SAR

From P2SR Wiki

NeKz.jpg

Source Auto Record (SAR)


Source Auto Record is a Portal 2 plugin 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

SAR is very easy to install and use. To install, start by downloading your desired version from GitHub (Linked in the info box at the top).

Windows Firewall Issues

It's important to note that Windows often doesn't trust .dll files from GitHub. There is a chance that downloading this plugin will result in Windows Defender or other anti-virus programs automatically deleting the file. If this happens, you will need to manually add exceptions for the file in any directory you keep it in (more than likely the downloads folder and your portal2 folder).

Loading SAR in Portal 2

Portal 2 can load .dll (Windows) or .so (Linux) plugins through the console command plugin_load <name>. This command will search the default directory of \steamapps\common\Portal 2 and \steamapps\common\Portal 2\portal2, so place the plugin in one of those folders.

Notes

  • Ensure that SAR is installed in your actual install location. Be sure to check this by browsing local files through the Steam properties of the game.
  • It is recommended you add the plugin_load sar line to your Autoexec so that you will not need to reload the plugin every time you launch the game.
  • Portal 2 Speedrun Mod (P2SM) uses SAR for timing as well, but the mod reads from your base game install, so you do not need any special installation for SAR with P2SM. Just install SAR normally for Portal 2.

Configuring with Livesplit

.asl files are used to interface with LiveSplit, so using SAR with LiveSplit is fairly simple following these steps.

1. Create a new file called sar.asl (the folder does not matter as long as you can find it).

2. Copy and Paste the information from this link into the file, and save it.

3. Open LiveSplit with Portal 2 splits (splits can be found here).

4. Right-click and select Edit Layout.

5. Select the large + icon at the top left.

6. Go to Control.

7. Select Scriptable Auto Splitter and navigate to the file. (e.g. C:\Livesplit\Components\sar.asl)

8. Right click on LiveSplit, and hover "Compare Against", and select "Game Time".

Troubleshooting

  • Ensure all the option boxes in the Autosplitter's settings are checked (Start, Split & Reset).
  • LiveSplit sometimes needs to be ran as an admin on your machine to work. If it isn't updating, run it as an admin.
  • Attempting to run LiveSplit while it's still located in its original ZIP file will cause issues, be sure to extract.
  • Be sure to disable the Autosplitter built into Livesplit through the Edit Splits... tab. This will interfere with SAR's autosplitter.
  • Make sure your livesplit SAR.asl file is an .asl file, and not a text file, and try remaking the file to ensure there are no issues.
  • On fresh Windows installs, there can often be dependencies that aren't installed. If all steps have been followed, and SAR still isn't loading, check your device drivers, and install other applications that are common on Windows machines (can include other games). Try installing these dependencies:

Speedrun Timer

Note: as of SAR 1.12, the speedrun timer is now accurate in coop!

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 the Container Ride 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.

In fullgame runs, the timer offset used for the Container Ride save is 16868, so sar_speedrun_offset 16868.

Custom Categories

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

sar_speedrun_category_create <name>

sar_speedrun_category_remove <name>

sar_speedrun_category_rule_create <rulename> <type> [option=value]...

sar_speedrun_category_add_rule <category> <rulename>

sar_speedrun_category_remove_rule <category> <rulename>

Someone more knowledgeable than me please go into more depth about rule creation

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.

Loading Fixes

SAR contains several commands to improve loading times:

  • ui_loadingscreen_transition_time
  • ui_loadingscreen_fadein_time
  • ui_loadingscreen_mintransition_time
  • sar_disable_mat_snapshot_recompute
  • sar_disable_progress_bar_update
  • sar_loads_uncap
  • sar_loads_norender

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 1
  • 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_default_font_index
  • sar_hud_default_font_color
  • sar_hud_default_spacing
  • sar_hud_default_padding_x
  • sar_hud_default_padding_y

You can reorder HUD elements using sar_hud_default_order_top and sar_hud_default_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:

sar_hud_set_text 0 "Portal Funneling On"

alias "funnelingOff" "sv_player_funnel_into_portals 0; sar_hud_hide_text 0; alias funnelingChange funnelingOn"

alias "funnelingOn" "sv_player_funnel_into_portals 1; sar_hud_show_text 0; alias funnelingChange funnelingOff"

funnelingOn

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 enabled using the sar_ihud variable, which can be given one of several values:

  • sar_ihud 0 - disable the HUD entirely
  • sar_ihud 1 - show WASD movement
  • sar_ihud 2 - show all of the above, as well as duck, jump, and use
  • sar_ihud 3 - show all of the above, as well as attack and attack2 (portal shots)
  • sar_ihud 4 - show all of the above, as well as speed and reload (not generally used in Portal 2)

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 behaviour 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 about 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. NOTE: for a run to be legitimate, you must use ghost type 0; see the "Run Legitimacy" section below.
  • 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.

As of 1.12.2 ghost_type 0 and 1 are legal in runs. On any previous version of SAR it must be set to 0, because of the fact that ghosts otherwise affect demos. Additionally, 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 iVerb 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 (working on both Windows and Linux); it can be found on Blenderiste's GitHub. To use it, set a port in the settings (the default is 53000) and, if neccesary (behind NAT), forward this port on TCP and UDP.

The server can trigger a countdown for all connected clients, and can run commands before and after the countdown (for instance, running load containerridesave 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 three SAR commands allowing more complex configurations.

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.

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 run only when you load into Calibration as blue. Conditions work as follows:

  • map=map_name checks whether you are in a certain map
  • prev_map=map_name checks the last map you were in
  • 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
  • ! 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"

sar_on_load

The last command is sar_on_load. This is used to register a command to be run on every map load. This command will pass all successive arguments to the command given; this means you do not need to quote the command given. You can chain this with cond to make conditional execs as follows:

sar_on_load cond "coop & orange" "exec coop_orange"

MTrigger

MTrigger is a feature allowing you to make custom splits in a map, allowing you to track your times in runs or in demos.

Adding/Removing triggers

To make these splits, you have to create triggers by using one of the following two commands:

The first command is of the following form:

sar_mtrigger_add <id> <A.x> <A.y> <A.z> <B.x> <B.y> <B.z> [angle].

This command will create a "zone" trigger; a cuboid which will trigger when the player passes through it. You can also place them by aiming at points in the map by using the sar_mtrigger_place <id> command. Triggers can be rotated with sar_mtrigger_rotate <id> <angle>.

The second command is of the following form:

sar_mtrigger_add <id> <entity> <input>

This command will create an "entity" trigger, which triggers whenever the given input is executed for the entity with the given targetname.

Examples:

sar_mtrigger_add 1 38.28 479.59 1104.03 49.72 539.14 1195.38 45 will create a zone trigger with an ID of 1 at the specified coordinates and rotated by 45°.

sar_mtrigger_add podium_collapse_push_brush Enable will create an entity trigger that will watch the Enable input of the podium_collapse_push_brush entity in Portal Gun.

You can delete the triggers by using the sar_mtrigger_delete <id> or sar_mtrigger_delete_all commands.

Once the triggers are placed, you have to set the runner's name with sar_mtrigger_name <name>.

You can now play the map. As soon as you trigger an entity or zone trigger, the game will display your split time in the chat with the syntax <name> -> <split time> (time since last split). It also adds this time to a CSV file; we'll get to that in a bit.

Normal usage of this is to set your own name while you're grinding a chamber and change it to the corresponding runner's name when playing a demo.

To reset the splits results, use the sar_mtrigger_reset command.

Exporting

Once you're done with grinding or with demo playback, you might want to export the results. Before doing that, you have to set the sar_mtrigger_header variable. sar_mtrigger_header will be the header of the CSV file; for instance:

sar_mtrigger_header "Name,Ground trigger,Portal gun,Office".

Once these variables are set, you can export the file with sar_mtrigger_export_stats <filename>, filename being the path to the file. It will export a .csv in your Portal 2 folder with the header you set, and all the times you recorded.

You can also export the triggers, either to save them or to share them to someone. To do that, use the command sar_mtrigger_export_triggers <filename>. This will export a CFG file with all the commands to automatically generate the triggers. You can then place it in your Portal2/portal2/cfg folder and type exec <filename> to re-create the triggers.

Miscellaneous

  • sar_mtrigger_show_chat <0|1> - display split times in the chat
  • sar_mtrigger_draw <0|1> - show the zone triggers (requires sv_cheats 1)

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_clear_lines - Removes drawn drawline lines (like the ones used to practice moonshot).

Credits

  • NeKz : Creator of SAR
  • Blenderiste09, Krzyhau, mlugg : Random guys that modified the plugin