SAR

Source Auto Record (SAR)

• GitHub Repo Latest Stable Release
• Latest Console Variables Latest cvars.md

Source Auto Record is a Portal 2 plugin originally developed by NeKz. The plugin is used by almost all Portal 2 speedrunners, and is highly recommended if you want to speedrun the game. It adds a wide variety of useful commands, and Quality of Life improvements that make running the game easier, and at times, more accurate.

How to install

Main Article: How to install plugins

1. Download either sar.dll or sar.so depending on whether you're on Windows or Linux respectively.
2. It is also recommended to download the sar.pdb file on Windows, as it expands on crash logs if Portal 2 were to crash.
3. Place the downloaded files into (steam installation)\steamapps\common\Portal 2.

Note: Portal 2 Speedrun Mod (P2SM) and other Sourcemods use SAR for timing as well, but these mods read from your base game install, so you do not need any special installation for SAR with P2SM. Just install SAR normally for Portal 2. However, full mods like Portal Stories: Mel require SAR to be installed manually.

Speedrun Timer

One of SAR's main uses is for timing runs. SAR will interface with LiveSplit (or other speedrun timing programs that support it), and automatically start/split/stop runs. This is done through the sar_speedrun category of commands. Most these commands are fairly self explanatory; the most important ones are below.

• sar_speedrun_category <name> - sets the category being run (affects how the run timing starts and stops). This only applies once you load a map.

• sar_speedrun_offset <ticks> - offsets the timer by a certain amount at the start of the run. Used, for instance, with Vault Save.

• sar_speedrun_time_pauses <0|1> - affects whether pauses are timed. You are allowed to omit pauses if you do not use them to gain an advantage.

• sar_speedrun_smartsplit <0|1> - enabled by default. Will prevent SAR from splitting on maps which you have previously entered in this run. Should be disabled in coop runs!

• sar_speedrun_reset - resets a run in preparation for another.

Custom Categories

SAR allows the creation of custom categories for speedruns based on entity inputs.

sar_speedrun_category_create <categoryname>
sar_speedrun_category_remove <categoryname>
sar_speedrun_category_rule_create <rulename> <type> [option=value]... <map=map> <action=action>
sar_speedrun_category_add_rule <categoryname> <rulename>
sar_speedrun_category_remove_rule <categoryname> <rulename>

There is a shorthand version of these commands used for creating MTriggers, which is

sar_speedrun_cc_start <categoryname> [map=map] [action=action]
sar_speedrun_cc_rule <rulename> <type> [option=value]... [action=action]
sar_speedrun_cc_finish

SAR comes packed with some default speedrun categories, and for Portal 2, this GitHub repository contains custom categories for every map in the game, for use in CM.

Rule Creation

Rule types:

• load - Rule triggers at the start of the level.

• zone <center=x,y,z> <size=x,y,z> <angle=degrees> - Rule triggers when any player enters the area specified by the center, size, and angle given. Size is on BOTH sides of the center, so the distance from the center to an edge is 1/2 of the given size.

• portal <center=x,y,z> <size=x,y,z> <angle=degrees> [portal=blue|orange] - Like a zone, except for portals instead of players.

• entity <targetname|classname=target> <inputname=input> [parameter=param] - Rule triggers on the input of a specified 'target' entity. See also: Entity inputs. Note that if the name, input, or parameter includes any of these characters (){}:', quotes must be put around the argument e.g. targetname=@glados inputname=RunScriptCode "parameter=Success()"

• fly - Rule triggers when a player leaves a funnel with the Crouch Flying Glitch.

• flags - Rule triggers when any player activates the CM flags.

• end - Rule ends when the map transitions to the next.

For any rule, the following options can be added:

• map - Specifies that this rule must occur on the map specified.

• action - Can be used to modify the timer. (start, force_start, stop, split, pause, resume)

• player - Specifies a certain player must trigger the rule. Player 0 is blue.

• after - Specifies that this rule must occur after the rule specified.

• ccafter - Same as after, except adds the category name to the beginning of the rule name. For use in the shorthand. e.g. "ccafter=Flags 1" in the category creation for Laser Crusher becomes "after=Laser Crusher - Flags 1"

When using the shorthand and a rule's map or action is not specified, it is inherited from the category. Every rule requires an action and a map.

e.g. (Laser Crusher)

sar_speedrun_cc_start "Laser Crusher" map=mp_coop_laser_crusher action=split
sar_speedrun_cc_rule "Start" load action=force_start
sar_speedrun_cc_rule "End Hop" zone center=2630.95,-1135.87,80.33 size=77.85,287.33,161.4 angle=0
sar_speedrun_cc_rule "End Trigger Blue" entity targetname=team_door-team_proxy inputname=OnProxyRelay1
sar_speedrun_cc_rule "End Trigger Orange" entity targetname=team_door-team_proxy inputname=OnProxyRelay3
sar_speedrun_cc_rule "Flags 1" flags
sar_speedrun_cc_rule "Flags 2" flags "ccafter=Flags 1" action=stop
sar_speedrun_cc_finish

In this example, all rules except Start and Flags 2 inherit the action split from the category, and all rules inherit the map.

Entity Inputs

Note: This command exists for category creation purposes. It is not allowed in runs, and is therefore cheat protected.

Almost all events that occur in Source games are dictated by certain 'inputs' to entities in the map. For example, whenever the Blue robot gets near an exit door, the door receives the entity input OnProxyRelay1, which triggers a sound and lights up Blue's side of the indicator above the door. Many speedrun categories make use of these entity inputs as rules. In order to assist creation of these categories, you can toggle sar_show_entinp <0|1>. This will show the entity inputs, and the tick they occurred on, in the developer console.

Demo Recording

If you are recording demos (for run verification or analysis), the command sar_autorecord 1 will automatically begin recording a new demo every level load or restart. Make sure to start recording demos at the start of your run with record demoname, and stop recording after the timer stops with stop.

Demo Prefix

The command sar_record_prefix can be used to timestamp or prepend text to recorded demo names. e.g. sar_record_prefix "demo/%Y-%m-%d_%H-%M-%S_" will put demos in the demo folder, and have Year, Month, Day, Hour, Minute, Second prefixed to it. e.g. demo/2021-06-01_19-23-50_fullgame.dem (fun trivia, that's the build time of SAR 1.12.3)

Loading Fixes

SAR contains several commands to improve loading times:

ui_loadingscreen_transition_time <0|1>
ui_loadingscreen_fadein_time <0|1>
ui_loadingscreen_mintransition_time <0|0.5>
sar_disable_mat_snapshot_recompute <0|1>
sar_disable_progress_bar_update <0|1>
sar_loads_uncap <0|1>
sar_loads_norender <0|1>

To make using these easier, there is one unified command to set all of them to preset values.

sar_fast_load_preset <preset>

The following presets exist:

• none - disables all loading fixes

• normal - enables most loading fixes, but retains loading screen and progress bar rendering

• sla - enables all loading fixes which do not affect SLA

• full - enables all loading fixes

The full preset is generally recommended for most runners.

CM Leaderboard

SAR can disable the leaderboard popup at the start of the map in challenge mode. It is allowed in all singleplayer CM levels.

Note: Not recommended for use in coop, as it can cause issues with the start of the level, and potentially invalidate your run.

sar_disable_challenge_stats_hud <0|1>

HUDs

SAR adds many optional HUDs on top of the base game, including the "SAR HUD", input HUD (ihud), portal HUD (lphud), vphysics HUD (vphys_hud), and more.

SAR HUD

SAR's main HUD is effectively a more extensible version of cl_showpos, displaying useful information in a simple text form somewhere on your screen. It allows for displaying arbitrary text; higher precision on position and angle values; demo and session timers; customizable fonts and position; and more. Elements of this HUD are enabled and tweaked through the sar_hud_xxxx commands. For instance, sar_hud_position and sar_hud_angles will display your position and angle like cl_showpos does. To replicate the behaviour of cl_showpos 1, run the following commands:

sar_hud_velocity 4
sar_hud_position 2
sar_hud_angles 2
sar_hud_precision 2

You can customize the color, font, and spacing of the SAR HUD using these commands:

• sar_hud_font_index

• sar_hud_font_color

• sar_hud_spacing

• sar_hud_x

• sar_hud_y

You can reorder HUD elements using sar_hud_order_top and sar_hud_order_bottom.

The SAR HUD also allows you to write arbitrary text on the screen. A line of text is added with sar_hud_set_text <id> <text>; for example, sar_hud_set_text 0 "Portal Funneling: ON" will set the piece of text with ID 0 to "Portal Funneling: ON". Pieces of text can then be shown or hidden from the HUD using sar_hud_show_text <id> and sar_hud_hide_text <id>. For instance, this config provides a portal funneling toggle alias named "funnelingChange" which displays this text when funneling is enabled:

Changing the value of portal funneling is banned in all categories other than CM.

sar_hud_set_text 0   "Portal Funneling: ON"
sar_hud_set_text 1   "Portal Funneling: OFF"
alias "funnelingOff" "sv_player_funnel_into_portals 0; sar_hud_hide_text 0; sar_hud_show_text 1; alias funnelingChange funnelingOn"
alias "funnelingOn"  "sv_player_funnel_into_portals 1; sar_hud_show_text 0; sar_hud_hide_text 1; alias funnelingChange funnelingOff"
funnelingOn
bind <key> funnelingChange

The command sar_hud_set_text_color <id> <hex color> can be used to change the color of the arbitrary text values. Furthermore, the color can be changed inline by using #<hex code>. e.g:

alias "funnelingOff" "sv_player_funnel_into_portals 0; sar_hud_set_text 0 Portal Funneling: #55FF55ON;  alias funnelingChange funnelingOn"
alias "funnelingOn"  "sv_player_funnel_into_portals 1; sar_hud_set_text 0 Portal Funneling: #FF5555OFF; alias funnelingChange funnelingOff"
funnelingOn
bind <key> funnelingChange

You can also add a grey background to the SAR HUD using sar_hud_bg <0|1>.

Input HUD

Another commonly used HUD is the input HUD (ihud). This is a HUD element which displays a subset of your inputs to the game on a keyboard overlay. It is made up of 3 presets:

• sar_ihud_preset normal - Displays WASD movement as well as jump, duck, use, and the portal shots.

• sar_ihud_preset normal_mouse - Same as above, but also has a display of your mouse movement.

• sar_ihud_preset tas - Displays two analog displays of your current move direction and look direction, as well as jump, duck, use, and the portal shots. This is helpful when TASing or when playing with controller.

Once set up with a preset, the ihud can be extensively modified using the command sar_ihud_modify <element|all> [property=value]....

This HUD can be used to see inputs in demos, which can be useful when learning movement.

Portal HUD

The Least Portals HUD shows how many portals you've shot in total across a play session. It is toggled using sar_lphud <0|1>, and its portal count can be reset using sar_lphud_set 0. The LP HUD accurately accounts for save loads and other level changes, so is useful in category extensions like 100 Portals.

Vphys HUD

Note: This HUD exists for routing purposes. It is not allowed in runs, and is therefore cheat protected.

The vphys HUD displays some physics information on-screen. It is useful for routers and those trying to understand various glitches in the game; it shows the states of your physics hitboxes, your current funnel handle and count, etc. It can be toggled using sar_vphys_hud <0|1>.

Ghosts

SAR includes support for ghosts: models that appear in-game to represent the position of another player. There are two kinds of ghosts: demo ghosts and network ghosts. Demo ghosts follow the path of a player defined by a demo file, whereas network ghosts represent the real-time position of another player on the same map, and are generally best suited to longer races (e.g. fullgame).

Setting Up

Demo ghosts are very simple to use. The command ghost_set_demo [demo] <id> will add a ghost using the given demo file. If specified, the ghost will be created with the given ID (replacing it if it already exists). There is also ghost_set_demos, which works similarly, but will automatically continue with successive demo files (demo_2, demo_3 etc). Once your ghosts are set up, you can start then with ghost_start. If you need to set a delay before ghosts start, you can set a per-ghost offset with ghost_offset [offset] [id].

Network ghosts are similarly simple. First, you should set a name with ghost_name [name]; this is the name you will be shown as to other people connected to the server. Then, run ghost_connect [server] [port] with the server address and port the host has given you.

Other Ghost Commands

There are many more commands affecting the appearance and behavior of ghosts.

• ghost_delete_by_ID <id> - delete the demo ghost with the given ID.

• ghost_delete_all - delete all demo ghosts.

• ghost_recap - list all current demo ghosts.

• ghost_reset - reset all demo ghosts ready for restarting.

• ghost_TCP_only <0|1> - for network ghosts, send all position data over TCP rather than UDP. This is slower, but more reliable, so may be useful if you have an unreliable Internet connection.

• ghost_update_rate <ms> - the number of milliseconds between sending out position updates to the ghost server. The default value, 50, is generally recommended, but can be tweaked if necessary.

• ghost_disconnect - disconnect from the current ghost server.

• ghost_name <name> - change what your name appears as to others on the ghost server.

• ghost_message <msg> - send a chat message to the ghost server.

• ghost_height <height> - set the amount to vertically offset ghosts by.

• ghost_transparency <0-255> - set the opacity of ghost models, where 0 is completely transparent and 255 is completely opaque.

• ghost_text_offset <height> - set the amount to vertically offset ghost names by.

• ghost_show_advancement <0|1> - set whether to display a message in chat when ghosts move between levels.

• ghost_proximity_fade <0-2000> - how far you need to be from ghost models before they start fading out, to prevent them from blocking your view. The default is 200.

• ghost_show_name <0|1> - set whether to display ghosts' names above their models.

• ghost_type <0|1|2> - sets how ghosts render for you. In type 0, ghosts simply render as plain red triangles. In type 1, ghosts render as entities with models (see ghost_prop_model). In type 2, ghosts render as red triangles, with small portal guns. See also: Run Legitimacy.

• ghost_prop_model <model> - for demo ghosts, sets the model that all ghosts use (if ghost_type is 1). For network ghosts, set the model you appear as to other people (if their ghost_type is 1). Contains autocompletions for some common models.

Run Legitimacy

Ghosts themselves are not banned from runs. However, some aspects and uses of them are considered illegitimate.

• ghost_type 0 and 1 are legal in runs. Type 2 is not allowed because it adversely effects demos.

• You may not use a ghost to gain any advantage. This includes, but is not limited to, using the positions of other ghosts for lineups, or using ghost_sync to perform pause abuse (e.g. checking coordinates). Any runs submitted to speedrun.com or the CM leaderboards which in any way abuse ghosts can and will be rejected or removed.

Server

To use network ghosts, a "ghost server" must be hosted. The server is cross-platform (works on both Windows and Linux); it can be found on GitHub. To use it, set a port in the settings (the default is 53000) and, if necessary (behind NAT), forward this port on TCP and UDP.

Alternatively to setting up your own server, you can use our website which will host it for you.

The server can trigger a countdown for all connected clients, and can run commands before and after the countdown (for instance, running load vault after the countdown for a fullgame race). Note that the countdown will not work for clients in the menu; they must all be in-game.

Config+

Config+ is the name for a number of SAR commands allowing more complex configurations. More advanced use of this functionality is often referred to as Config++ or C++.

seq

The seq command takes an arbitrary number of commands as arguments, and runs them all one tick after another. For instance:

seq "say 1" "say 2" "say 3"

This will output 1 to the chat, then one tick later 2, then one tick later 3.

hwait

The hwait <ticks> <command> command runs a command after a specified number of ticks. Unlike seq, these timers run even on the menus.

cond

The second command is cond. This command allows you to only run a command in certain conditions.

cond [condition] [command]

This can be used, for instance, to automatically apply execs for different categories or levels; as an example, the condition "map=mp_coop_start & !orange" will succeed only when you run it in Calibration as blue. Conditions work as follows:

• ?<variable>=<value> checks whether the svar <variable> is equal to the value on the right side. (e.g. the condition ?yes=1 will run if the svar 'yes' is set to 1). You can also use ?<variable> on the right side (e.g. ?foo=?bar will run if the svars 'foo' and 'bar' are the same). Originally, this syntax was var:<variable>=<value>, but the newer syntax is favored because of the 'breakset.'

• #<cvar>=<value> checks whether the cvar <cvar> is equal to the value on the right side. (e.g. the condition #sv_cheats=1 will run if the cvar 'sv_cheats' is set to 1). You can also use #<cvar> on the right side. Alternatively, you can also use cvar:<cvar>.

• %<string>=<value> checks whether the literal string <string> is equal to the value on the right side. (e.g. the condition %map=?variable will run if the svar 'variable' is equal to 'map'.

• game=<game_name> checks whether you are playing a certain Source game. Currently supported games are Portal 2 (portal2), Aperture Tag (aptag), Portal Stories: Mel (mel), Thinking With Time Machine (twtm), Portal Reloaded (reloaded), and Portal 2 Speedrun Mod (srm). Any other game is recognized as other. You can also use ?<variable> on the right side here.

• map=<map_name> checks whether you are in a certain map. You can also use ?<variable> on the right side here.

• prev_map=<map_name> checks the last map you were in. You can also use ?<variable> on the right side here.

• steamid=<steam32id> checks for specific partner Steam32 ID. You can also use ?<variable> on the right side here. Use sar_get_partner_id in Co-Op to retrieve your partner's Steam32 ID.

• same_map checks whether the current map is the same as the previous map

• coop checks whether you are in coop

• orange checks whether you are playing as orange (P-Body)

• cm checks whether you are in Challenge Mode

• workshop checks whether you are currently in a map from the workshop

• menu checks whether you are currently in the menu

• ! is logical NOT; if put before a condition, it inverts it (e.g. the condition !orange will run unless you are playing as orange)

• & is logical AND; it chains conditions, requiring both to be true (e.g. coop & !orange will only run if you are playing as blue in coop)

• | is logical OR; it chains conditions, requiring at least one to be true (e.g. map=sp_a1_intro1 | map=sp_a1_intro2 will run in both Container Ride and Portal Carousel)

• Parentheses () can be used to group expressions

For example, the following condition would run an exec when run in a coop map as orange:

cond "coop & orange" "exec coop_orange"

Another relevant command is conds, which does the same but in a sort of if-else manner. It will run the command for the first condition that is truthy.

conds [<condition> <command>]... [else]

For example, conds "coop & orange" "exec coop_orange" "coop" "exec coop_blue" "exec singleplayer" will exec the relevant file for your role. You can chain as many statements as you like.

sar_on_ Events

The sar_on_ family of commands are used to register commands to be run on certain events. These commands will pass all successive arguments to the command given; this means you do not need to quote the command given.

• load - to be run on session start
• session_end - to be run on session end
• exit - to be run on game exit
• demo_start - to be run when demo playback starts
• demo_stop - to be run when demo playback stops
• flags - to be run when CM flags are hit
• coop_reset_done - to be run when coop reset is completed
• coop_reset_remote - to be run when coop reset run remotely
• coop_spawn - to be run on coop spawn
• config_exec - to be run on config.cfg exec
• tas_start - to be run when TAS script playback starts
• tas_end - to be run when TAS script playback ends
• pb - to be run when auto-submitter detects PB
• not_pb - to be run when auto-submitter detects not PB

You can chain this with cond to make conditional execs as follows:

sar_on_load cond "coop & orange" exec coop_orange

svars

Configurable variables called 'svars,' or 'SAR variables,' allow you to read the values of cvars into variables. You can set an svar using svar_set <svar> <value>, read the console output of a command with svar_capture <svar> <command>, or read the value of a cvar with svar_from_cvar <svar> <cvar>. You can then do arithmetic on these variables using the following commands:

• svar_add <svar> <svar|value> - Adds the value of the right side to the svar.

• svar_sub <svar> <svar|value> - Subtracts the value of the right side from the svar.

• svar_mul <svar> <svar|value> - Multiplies the svar by the value of the right side.

• svar_div <svar> <svar|value> - Divides the svar by the value of the right side.

• svar_mod <svar> <svar|value> - Returns the remainder when dividing the svar by the value of the right side.

For each of the above commands, there is an equivalent svar_f<...> command that uses floating point arithmetic rather than integer, i.e. svar_fadd <svar> <svar|value>. You can see what an svar is set to using svar_get <svar>. There are also the following commands for operating on a single svar:

• svar_floor <svar> - Rounds down the value of the svar to the nearest integer.

• svar_round <svar> - Rounds the value of the svar to the nearest integer.

• svar_ceil <svar> - Rounds up the value of the svar to the nearest integer.

• svar_abs <svar> - Sets the value of the svar to its absolute value. e.g. -17.2 => 17.2, 31 => 31

• svar_substr <svar> <from> [length] - Sets the value of the svar to its substring. From starts at 0. A negative from value means from the end of the svar.

Note: If a cvar is set to 1.000000 (by incrementvar for example) and you use svar_from_cvar on it, you can coerce this value to be 1 by doing svar_add <svar> 0.

SAR Functions

sar_function is a command that allows you to make commands that can be dynamically filled with svars and passed arguments. The $ character is used to get svars or args. $1 will be replaced with the first argument given to the command, and this works up to $63. Similarly, $+1 will be replaced by all arguments after and including argument 1. $variable will be replaced with the value of the svar variable. Additionally, $- will expand to nothing, to be used as a separator between substitutions and text e.g. $variable$-hello, and $' will expand to ", for use in nested quotes. $# will be replaced with the number of arguments provided. Finally, $$ will expand to $. This substitution (excluding $1 - $63 and $+1 - $+63) can be done inline with the sar_expand command. $# will expand to -1 when using sar_expand.

Some examples:

// pass arguments to the function
sar_function print echo "$1"
print "Hello World!"                // prints "Hello World!" to the console.

// the function can read svars
sar_function print echo "$variable"
svar_set variable "Hello World!"
print                               // prints "Hello World!" to the console.

These functions are one of the main reasons SARtris is possible.

Common Mistakes

There are a few common mistakes that users make when writing Config+ commands.

• You must quote conditions that contain breakset characters. cond var:yes=1 echo hi should be cond "var:yes=1" echo hi or cond ?yes=1 echo hi

What are more mistakes people make? I don't know because I'm so smart B)

Freecam

SAR allows you to freely control the in-game camera using commands, much like in demos. The camera can be separated from the player using sar_cam_control 1 (only works if playing a demo OR with cheats enabled). Then, the camera can be manipulated using the following commands:

sar_cam_setpos <x> <y> <z>
sar_cam_setang <pitch> <yaw> [roll]
sar_cam_setfov <fov>
sar_cam_reset

Drive Mode

As well as the above commands, the camera can also be controlled in drive mode. This is very similar to drive mode demos, but contains several extra features. Whilst holding left click, the camera can be controlled as follows:

• Move the mouse to look around.

• Use WASD to move around.

• Hold left shift to speed up or left ctrl to slow down.

• Hold right click and move mouse left and right to change camera roll.

• Hold right click and move mouse up and down to change FOV.

Drive mode can be toggled using sar_cam_drive <0|1>

Cinematic Mode

In demos only, the camera can be given a specific path to follow for a cinematic view.

• sar_cam_path_setkf <frame> <x> <y> <z> <pitch> <yaw> <roll> <fov> - adds a path keyframe. Parameters default to the current frame and position if not given.

• sar_cam_path_remkf <frame> - removes the given keyframe.

• sar_cam_path_showkfs - list all the current keyframes.

• sar_camera_control 2 - puts the camera into cinematic mode to follow the set path.

Misc. Commands

• sar_about - Gives information about the currently installed version of SAR. Make sure you're up to date!

• sar_update [release|pre|canary] [exit|restart] [force] - Checks if SAR is up-to-date, and if not, updates it. If force is given, it will always reinstall, even if it may be a downgrade.

• sar_clear_lines - Removes drawn drawline lines (like the ones used to practice moonshot).

Credits

• NeKz : Original creator of SAR
• Krzyhau : TASTools developer and responsible for fixing a memory leak
• Blenderiste09, Mlugg : Past maintainers of SAR
• AMJ, Krzyhau : Current maintainers of SAR
• A number of other people have helped contribute, find a list here