├── .editorconfig ├── .github ├── pull_request_template.md └── workflows │ └── ci.yml └── README.md /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*.xml] 4 | indent_style = space 5 | indent_size = 4 6 | -------------------------------------------------------------------------------- /.github/pull_request_template.md: -------------------------------------------------------------------------------- 1 | If you are adding or modifying an Auto Splitter, please fill out this checklist: 2 | - [ ] My Auto Splitter does not contain any malicious functionality and I'm entirely responsible for any damages myself. (Any kind of abuse in an Auto Splitter will result in an immediate ban.) 3 | - [ ] I am not replacing an existing Auto Splitter by a different author, or I have received permission from the author to replace the existing Auto Splitter. 4 | - [ ] The Auto Splitter has an open source license that allows anyone to fork and host it. 5 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | 3 | on: 4 | pull_request: 5 | 6 | jobs: 7 | build: 8 | runs-on: windows-2019 9 | 10 | steps: 11 | - name: Checkout LiveSplit 12 | uses: actions/checkout@v2 13 | with: 14 | submodules: recursive 15 | repository: LiveSplit/LiveSplit 16 | 17 | - name: Checkout commit 18 | uses: actions/checkout@v2 19 | with: 20 | path: autosplitters_xml 21 | 22 | - name: Move Auto Splitters XML 23 | run: mv -force autosplitters_xml/LiveSplit.AutoSplitters.xml . 24 | 25 | - name: Set up .NET environment 26 | uses: vrnobody/Setup-DotNetFrameworkEnv@v1.2.6 27 | 28 | - name: Install NuGet packages 29 | run: nuget restore LiveSplit\LiveSplit.sln 30 | 31 | - name: Build LiveSplit 32 | run: msbuild LiveSplit\LiveSplit.sln /verbosity:minimal /p:NoWarn=1591 /p:Configuration=Release 33 | 34 | - name: Run tests 35 | run: | 36 | & "vstest.console.exe" "LiveSplit/LiveSplit.Tests/bin/Release/LiveSplit.Tests.dll" 37 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Auto Splitters 2 | 3 | 4 | 5 | - [Features of an Auto Splitter](#features-of-an-auto-splitter) 6 | - [Game Time](#game-time) 7 | - [Automatic Splits](#automatic-splits) 8 | - [Automatic Timer Start](#automatic-timer-start) 9 | - [Automatic Resets](#automatic-resets) 10 | - [How an Auto Splitter works](#how-an-auto-splitter-works) 11 | - [Pointer Paths](#pointer-paths) 12 | - [The Auto Splitting Language - ASL](#the-auto-splitting-language---asl) 13 | - [State Descriptors](#state-descriptors) 14 | - [State objects](#state-objects) 15 | - [Actions](#actions) 16 | - [Timer Control](#timer-control) 17 | - [Script Management](#script-management) 18 | - [Action Variables](#action-variables) 19 | - [General Variables](#general-variables) 20 | - [Game Dependent](#game-dependent) 21 | - [Settings](#settings-1) 22 | - [Basic Settings](#basic-settings) 23 | - [Custom Settings](#custom-settings) 24 | - [Built-in Functions](#built-in-functions) 25 | - [Testing your Script](#testing-your-script) 26 | - [Debugging](#debugging) 27 | - [Sandboxed Auto Splitters](#sandboxed-auto-splitters) 28 | - [Adding an Auto Splitter](#adding-an-auto-splitter) 29 | - [Additional Resources](#additional-resources) 30 | 31 | 32 | 33 | LiveSplit has integrated support for Auto Splitters. An Auto Splitter can be one 34 | of the following: 35 | * A Script written in the Auto Splitting Language (ASL). 36 | * A WebAssembly module that uses the new cross-platform, sandboxed Auto 37 | Splitting Runtime. 38 | * A LiveSplit Component written in any .NET compatible language. 39 | * A third party application communicating with LiveSplit through the LiveSplit 40 | Server. 41 | 42 | LiveSplit can automatically download and activate Auto Splitters that are 43 | LiveSplit components, WebAssembly modules, or ASL scripts. 44 | 45 | Currently we recommend writing an ASL script, which has the most extensive 46 | support for all the features you might need. If you are feeling more 47 | adventurous, you can start looking into writing an auto splitter for the new 48 | cross-platform, sandboxed Auto Splitting Runtime 49 | [here](#sandboxed-auto-splitters). Sandboxed auto splitters are currently more 50 | limited, but they will become the main way to write auto splitters in the 51 | future. 52 | 53 | ## Features of an Auto Splitter 54 | 55 | An Auto Splitter can provide any of the following features: 56 | 57 | ### Game Time 58 | 59 | Game Time can either be Real Time without Loads or an actual Game Timer found in the game. This depends on the game and the speedrun community of that game. If the game has been run in Real Time for multiple years already, introducing a new timing method might not be worth it. 60 | 61 | ### Automatic Splits 62 | 63 | An Auto Splitter, as the name suggests, can also provide automatic splits to increase the accuracy of the individual segment and split times. An Auto Splitter might not necessarily implement Automatic Splits for every single split available since the runner might want to have some additional splits that are not supported by the Auto Splitter used. 64 | 65 | ### Automatic Timer Start 66 | 67 | Not every Auto Splitter automatically starts the timer. For some games, the Auto Splitter can't tell whether the runner just wants to start the game to practice something or actually wants to do a run. 68 | 69 | ### Automatic Resets 70 | 71 | An Auto Splitter can automatically reset the timer. This might be useful for games where going back to the main menu always means that the run is over. This is a bit dangerous though, as the runner might not have wanted to reset there. Think twice before implementing this functionality into your Auto Splitter. 72 | 73 | ## How an Auto Splitter works 74 | 75 | Auto Splitters can work in one or multiple of the following ways: 76 | * It can read the RAM, interpret the values, and toggle any of the actions described above based on these values. The RAM addresses might not always be the same. Therefore, the Auto Splitter might need to follow a so called *Pointer Path*. This is what most Auto Splitters do and what is directly supported by the Auto Splitting Language. 77 | * It can scan the game's RAM to find a value and toggle any of the actions based on these values. Doing a memory scan is slower than following a Pointer Path. 78 | * It can read the game's log files, parse them, and toggle actions based on those. This works, but is usually fairly delayed, which is why this isn't that great of a solution. 79 | * It can read the game's standard output stream. This only works if the game actually writes valuable information to the standard output, which is rare. Also, Steam prevents this method since in order to read the standard output, you need to start the game's process through the Auto Splitter, which Steam won't let you do. 80 | 81 | ### Pointer Paths 82 | 83 | A Pointer Path is a list of Offsets + a Base Address. The Auto Splitter reads the value at the base address and interprets the value as yet another address. It adds the first offset to this address and reads the value of the calculated address. It does this over and over until there are no more offsets. At that point, it has found the value it was searching for. This resembles the way objects are stored in memory. Every object has a clearly defined layout where each variable has a consistent offset within the object, so you basically follow these variables from object to object. 84 | 85 | *Cheat Engine* is a tool that allows you to easily find Addresses and Pointer Paths for those Addresses, so you don't need to debug the game to figure out the structure of the memory. 86 | 87 | ## The Auto Splitting Language - ASL 88 | 89 | The Auto Splitting Language is a small scripting language made specifically for LiveSplit Auto Splitters. It has a few advantages and disadvantages over normal Components. 90 | 91 | **Advantages:** 92 | * ASL Scripts are easy to maintain. 93 | * There's no need to update the Script for new LiveSplit versions. 94 | * No Visual Studio or any compiler is needed; you can write it in Notepad. 95 | 96 | **Disadvantages:** 97 | * Currently only provides Boolean settings in the GUI for the user to change. 98 | 99 | An ASL Script contains a State Descriptor and multiple [Actions](#actions) which contain C# code. 100 | 101 | ### State Descriptors 102 | 103 | The State Descriptor is the most important part of the script and describes which game process and which state of the game the script is interested in. This is where all of the Pointer Paths, which the Auto Splitter uses to read values from the game, are described. A State Descriptor looks like this: 104 | ``` 105 | state("PROCESS_NAME") 106 | { 107 | POINTER_PATH 108 | POINTER_PATH 109 | ... 110 | } 111 | ``` 112 | If the script needs to support multiple versions of the game, you can specify an optional version identifier: 113 | ``` 114 | state("PROCESS_NAME", "VERSION_IDENTIFIER") 115 | ... 116 | ``` 117 | 118 | The `PROCESS_NAME` is the name of the process the Auto Splitter should look for. The Script is inactive while it's not connected to a process. Once a process with that name is found, it automatically connects to that process. A Process Name should not include the `.exe`. Even advanced scripts that use other ways to access the game's memory require a State Descriptor to define which process LiveSplit is supposed to connect to. 119 | 120 | The optional `VERSION_IDENTIFIER` can be any arbitrary string you wish to use. Note that the script can define multiple State Descriptors for different processes/games. These optional features are extremely useful for emulators. 121 | 122 | `POINTER_PATH` describes a Pointer Path and has two ways to declare: 123 | ``` 124 | VARIABLE_TYPE VARIABLE_NAME : OFFSET, OFFSET, OFFSET, ...; 125 | VARIABLE_TYPE VARIABLE_NAME : "BASE_MODULE", OFFSET, OFFSET, OFFSET, ...; 126 | ``` 127 | 128 | The variable type `VARIABLE_TYPE` describes the type of the value found at the pointer path. It can be one of the following: 129 | 130 | | Type | Description | 131 | | ---------------- | -------------------------- | 132 | | sbyte | Signed 8-bit integer | 133 | | byte | Unsigned 8-bit integer | 134 | | short | Signed 16-bit integer | 135 | | ushort | Unsigned 16-bit integer | 136 | | int | Signed 32-bit integer | 137 | | uint | Unsigned 32-bit integer | 138 | | long | Signed 64-bit integer | 139 | | ulong | Unsigned 64-bit integer | 140 | | float | 32-bit IEEE floating-point | 141 | | double | 64-bit IEEE floating-point | 142 | | bool | Boolean | 143 | | string\ | String (e.g. string255) | 144 | | byte\ | Byte array (e.g. byte255) | 145 | 146 | The variable name `VARIABLE_NAME` can be any variable name you choose, describing what is found at the pointer path. The naming is up to you, but should be distinct from the other variable names. 147 | 148 | The optional base module name `BASE_MODULE` describes the name of the module the Pointer Path starts at. Every \*.exe and \*.dll file loaded into the process has its own base address. Instead of specifying the base address of the Pointer Path, you specify the base module and an offset from there. If this is not defined, it will default to the main (.exe) module. 149 | 150 | You can use as many offsets `OFFSET` as you want. They need to be integer literals, either written as decimal or hexadecimal. 151 | 152 | #### State objects 153 | 154 | The State Variables described through the State Descriptor are available through two State objects: `current` and `old`. The `current` object contains the current state of the game with all the up-to-date variables, while the `old` object contains the state of the variables at the last execution of the ASL Script in LiveSplit. These objects are useful for checking for state changes. For example, you could check if the last level of a game was a certain value and is now a certain other value, which might mean that a split needs to happen. 155 | 156 | LiveSplit's internal state is also available through the object `timer`. This is an object of the type [`LiveSplitState`](https://github.com/LiveSplit/LiveSplit/blob/master/LiveSplit/LiveSplit.Core/Model/LiveSplitState.cs) and can be used to interact with LiveSplit in ways that are not directly available through ASL. 157 | 158 | ### Actions 159 | 160 | After writing a State Descriptor, you can implement multiple actions such as splitting and starting the timer. These actions define the logic of the Auto Splitter based on the information described by the State Descriptor. An action looks like this: 161 | ``` 162 | ACTION_NAME 163 | { 164 | C# CODE 165 | } 166 | ``` 167 | 168 | You can think of Actions like functions that are automatically called by the ASL Component. These functions can only interact with each other or LiveSplit via the [special variables](#action-variables) the environment provides. 169 | 170 | All of the actions are optional and are declared by their name `ACTION_NAME` followed by a code block `CODE`. You trigger the action by returning a value. Returning a value is optional though; if no value is returned, the action is not triggered. Some actions are only executed while LiveSplit is connected to the process. 171 | 172 | Actions are implemented in C#. You can use C#'s documentation for any questions you may have regarding the syntax of C#. 173 | 174 | #### Timer Control 175 | 176 | These actions are repeatedly triggered while LiveSplit is connected to the game process. 177 | 178 | ##### Generic Update 179 | 180 | The name of this action is `update`. You can use this for generic updating. In each update iteration, this is run before the timer control actions, which e.g. means if you set a value in `vars` in `update` you can then access it in `start` on the same update cycle. 181 | 182 | Explicitly returning `false` will prevent the actions `isLoading`, `gameTime`, `reset`, `split`, and `start` from being run. This can be useful if you want to entirely disable the script under some conditions (e.g. for incompatible game versions). See [Order of Execution](#order-of-execution) for more information. 183 | 184 | ##### Automatic Timer Start 185 | 186 | The name of this action is `start`. Return `true` whenever you want the timer to start. Note that the `start` action will only be run if the timer is currently not running. 187 | 188 | ##### Automatic Splits 189 | 190 | The name of this action is `split`. Return `true` whenever you want to trigger a split. 191 | 192 | ##### Automatic Resets 193 | 194 | The name of this action is `reset`. Return `true` whenever you want to reset the run. 195 | 196 | Explicitly returning `true` will prevent the `split` action from being run. This can be useful in some cases, but may also cause issues for some scripts. See [Order of Execution](#order-of-execution) for more information. 197 | 198 | ##### Load Time Removal 199 | 200 | The name of this action is `isLoading`. Return `true` whenever the game is loading. LiveSplit's Game Time Timer will be paused as long as you return `true`. 201 | 202 | **NOTE**: Make sure the timer is set to "Game Time" in the layout! Failure to do so will cause the timer to keep running, as if `isLoading` had returned `false` or `isLoading` weren't triggered at all. 203 | 204 | ##### Game Time 205 | 206 | The name of this action is `gameTime`. Return a [`TimeSpan`](https://msdn.microsoft.com/en-us/library/system.timespan(v=vs.110).aspx) object that contains the current time of the game. You can also combine this with `isLoading`. If `isLoading` returns false, nothing, or isn't implemented, LiveSplit's Game Time Timer is always running and syncs with the game's Game Time at a constant interval. Everything in between is therefore a Real Time approximation of the Game Time. If you want the Game Time to not run in between the synchronization interval and only ever return the actual Game Time of the game, make sure to implement `isLoading` with a constant return value of `true`. 207 | 208 | ##### Order of Execution 209 | 210 | Understanding the order and conditions under which timer control actions are executed can help you avoid issues in your script where variables appear to be set improperly, actions appear to be skipped, and more. Every update iteration follows this process when running actions: 211 | 212 | 1. `update` will always be run first. There are no conditions on the execution of this action. 213 | 2. If `update` did not explicitly return `false` and the timer is currently either running or paused, then the `isLoading`, `gameTime`, and `reset` actions will be run. 214 | - If `reset` does not explicitly return `true`, then the `split` action will be run. 215 | 3. If `update` did not explicitly return `false` and the timer is currently not running (and not paused), then the `start` action will be run. 216 | 217 | ##### Events 218 | 219 | While a broader suite of events exist in LiveSplit, three are also available as ASL actions. The `onStart`, `onSplit` and `onReset` actions will be triggered when the timer is started, split, and reset respectively. 220 | 221 | #### Script Management 222 | 223 | ##### Script Startup 224 | 225 | The name of this action is `startup`. This action is triggered when the script is first loads. This is the place where you can put initialization that doesn't depend on being connected to the process and the only place where you can add [Custom Settings](#custom-settings). 226 | 227 | ##### Script Shutdown 228 | 229 | The name of this action is `shutdown`. This action is triggered whenever the script is entirely stopped, for example when the Auto Splitter is disabled, LiveSplit exits, the script path is changed or the script is reloaded (e.g. during development of the ASL script). 230 | 231 | ##### Script Initialization (Game Start) 232 | 233 | The name of this action is `init`. This action is triggered whenever a game process has been found according to the State Descriptors. This can occur more than once during the execution of a script (e.g. when you restart the game). This is the place to do initialization that depends on the game, for example detecting the game version. 234 | 235 | ##### Game Exit 236 | 237 | The name of this action is `exit`. This action is triggered whenever the currently attached game process exits. 238 | 239 | 240 | ### Action Variables 241 | 242 | Actions have a few hidden variables available. 243 | 244 | #### General Variables 245 | 246 | ##### vars 247 | A dynamic object which can be used to store variables. Make sure the variables are defined (for example in `startup` or `init`) before trying to access them. This can be used to exchange data between Actions. 248 | ``` 249 | init { vars.test = 5; } 250 | update { print(vars.test.ToString()); } 251 | ``` 252 | You can also store variables like this in `current` and the value will be in `old` on the next update. 253 | 254 | ##### version 255 | When you set `version` in `init`, the corresponding State Descriptor will be activated. When there is no State Descriptor corresponding to the `version`, the default one will be activated. 256 | 257 | The default is the first defined State Descriptor with no version specified, or the first State Descriptor in the file if there is none with no version specified. 258 | 259 | The string you set `version` to will also be displayed in the ASL Settings GUI. 260 | ``` 261 | state("game", "v1.2") 262 | { 263 | byte levelID : 0x9001; 264 | } 265 | state("game", "v1.3") 266 | { 267 | byte levelID : 0x9002; 268 | } 269 | init 270 | { 271 | if (modules.First().ModuleMemorySize == 0x123456) 272 | version = "v1.2"; 273 | else if (modules.First().ModuleMemorySize == 0x654321) 274 | version = "v1.3"; 275 | } 276 | update 277 | { 278 | if (version == "") return false; 279 | print(current.levelID.ToString()); 280 | } 281 | ``` 282 | 283 | ##### refreshRate 284 | Many actions are triggered repeatedly, by default approximately 60 times per second. You can set this variable lower to reduce CPU usage. This is commonly done in `startup` or `init`. 285 | ``` 286 | refreshRate = 30; 287 | ``` 288 | 289 | ##### settings 290 | Used to add and access [Settings](#settings-1). 291 | 292 | #### Game Dependent 293 | 294 | These variables depend on being or having been connected to a game process and are not available in the `startup` or `exit` actions and only partly available in `shutdown` (might be `null`). 295 | 296 | ##### current / old 297 | State objects representing the current and previous states. 298 | ``` 299 | split { return current.levelID != old.levelID; } 300 | ``` 301 | 302 | ##### game 303 | The currently connected [Process](https://msdn.microsoft.com/en-us/library/system.diagnostics.process%28v=vs.110%29.aspx) object. 304 | ``` 305 | update { if (game.ProcessName == "snes9x") { } } 306 | ``` 307 | 308 | ##### modules 309 | The modules of the currently connected process. Please use this instead of game.Modules! Use modules.First() instead of game.MainModule. 310 | 311 | ##### memory 312 | Provides a means to read memory from the game without using the State Descriptor. 313 | ``` 314 | vars.exe = memory.ReadBytes(modules.First().BaseAddress, modules.First().ModuleMemorySize); 315 | vars.test = memory.ReadValue(modules.First().BaseAddress + 0x9001); 316 | vars.test2 = memory.ReadString(modules.First().BaseAddress + 0x9002, 256); 317 | vars.test3 = new DeepPointer("some.dll", 0x9003, vars.test, 0x02).Deref(game); 318 | vars.test4 = memory.ReadString(modules.Where(m => m.ModuleName == "some.dll").First().BaseAddress + 0x9002, 256); 319 | ``` 320 | 321 | ### Settings 322 | 323 | ASL script settings are stored either with the Layout if you are using the Scriptable Auto Splitter component or with the Splits if you activated the script in the Splits Editor (so make sure to save your Layout or Splits accordingly when exiting LiveSplit if you changed settings). 324 | 325 | #### Basic Settings 326 | The Auto Splitter Settings GUI has some default settings to allow the user to toggle the actions `start`, `reset` and `split`. If the checkbox for an action is unchecked, the return value of that action is ignored (but the code inside the action is still executed). So for example if the checkbox for `start` is unchecked, returning `true` in the `start` action will have no effect. 327 | 328 | You can access the current value of the basic settings through the attributes `settings.StartEnabled`, `settings.ResetEnabled` and `settings.SplitEnabled`. This is only for informational purposes, for example if your script needs to do something depending on whether the action was actually performed or not, ignoring the return value is done automatically. 329 | 330 | Actions that are not present in the ASL script or empty will have their checkboxes disabled. 331 | 332 | #### Custom Settings 333 | 334 | You can define custom boolean settings for your script in the `startup` action and then access the setting values as configured by the user in the other actions. If you have custom settings defined, they will be shown in the GUI for the user to check/uncheck. They will appear in the same order you added them in the ASL script. 335 | 336 | ##### Basic usage 337 | 338 | You can define settings in the `startup` action by using the `settings.Add(id, default_value = true, description = null, parent = null)` method: 339 | 340 | ``` 341 | // Add setting 'mission1', enabled by default, with 'First Mission' being displayed in the GUI 342 | settings.Add("mission1", true, "First Mission"); 343 | 344 | // Add setting 'mission2', enabled by default, with 'mission2' being displayed in the GUI 345 | settings.Add("mission2"); 346 | 347 | // Add setting 'mission3', disabled by default, with 'mission3' being displayed in the GUI 348 | settings.Add("mission3", false); 349 | ``` 350 | 351 | You can access the current value of a setting in all actions other than `startup` by accessing `settings`: 352 | 353 | ```` 354 | // Do something depending on the value of the setting 'mission1' 355 | if (settings["mission1"]) { } 356 | ```` 357 | 358 | ##### Grouping settings 359 | If you want to organize the settings in a hierarchy, you can specify the `parent` parameter. Note that the `parent` has to be the `id` of a setting that you already added: 360 | 361 | ``` 362 | // Add setting 'main_missions' 363 | settings.Add("main_missions", true, "Main Missions"); 364 | 365 | // Add setting 'mission1', with 'main_missions' as parent 366 | settings.Add("mission1", true, "First Mission", "main_missions"); 367 | ``` 368 | 369 | Settings only return `true` (checked) when their `parent` setting is `true` as well. The user is unable to toggle settings that have their parent unchecked, and they will be grayed out to indicate they are disabled. 370 | 371 | Any setting can act as a `parent` setting, so you could for example do the following to go one level deeper (continuing from the last example): 372 | 373 | ``` 374 | // Add setting 'mission1_part1', with 'mission1' as parent 375 | settings.Add("mission1_part1", true, "First part of Mission 1", "mission1"); 376 | ``` 377 | 378 | The setting `mission1_part1` will only be enabled, when both `mission1` and `main_missions` are enabled. 379 | 380 | When the `parent` parameter is null or omitted, the setting will be added as top-level setting, unless `settings.CurrentDefaultParent` is set to something other than `null`: 381 | 382 | ``` 383 | // Add top-level setting 'main_missions' 384 | settings.Add("main_missions"); 385 | 386 | settings.CurrentDefaultParent = "main_missions"; 387 | 388 | // Add setting 'mission1', with the parent 'main_missions' 389 | settings.Add("mission1"); 390 | 391 | settings.CurrentDefaultParent = null; 392 | 393 | // Add top-level setting 'side_missions' 394 | settings.Add("side_missions"); 395 | ``` 396 | 397 | Using `settings.CurrentDefaultParent` can be useful when adding several settings with the same parent, without having to specify the parent every time. 398 | 399 | ##### Tooltips 400 | 401 | You can add a tooltip to settings that appears when hover over the setting in the GUI. This can be useful if you want to add a bit more information. After adding the setting, use `settings.SetToolTip(id, tooltip_text)` to set a tooltip: 402 | 403 | ``` 404 | settings.Add("main_missions", true, "Main Missions"); 405 | settings.SetToolTip("main_missions", "All main story missions, except Mission A and Mission B"); 406 | ``` 407 | 408 | ### Built-in Functions 409 | 410 | ##### print 411 | Used for debug printing. Use [DbgView](https://technet.microsoft.com/en-us/Library/bb896647.aspx) to watch the output. 412 | ``` 413 | print("current level is " + current.levelID); 414 | ``` 415 | 416 | ##### Other 417 | There are some advanced memory utilities not covered here. You can find them [here](https://github.com/LiveSplit/LiveSplit/blob/master/LiveSplit/LiveSplit.Core/ComponentUtil). 418 | 419 | ### Testing your Script 420 | 421 | You can test your Script by adding the *Scriptable Auto Splitter* component to your Layout. Right-click on LiveSplit and choose "Edit Layout..." to open the Layout Editor, then click on the Plus-sign and choose "Scriptable Auto Splitter" from the section "Control". You can set the Path of the Script by going into the component settings of the Scriptable Auto Splitter. To get to the settings of the component you can either double click it in the Layout Editor or go into to the Scriptable Auto Splitter Tab of the Layout Settings. Once you've set the Path, the script should automatically load and hopefully work. 422 | 423 | #### Debugging 424 | Reading debug output is an integral part of developing ASL scripts, both for your own debug messages which you can output with `print()` and any debug messages or error messages the ASL Component itself provides. 425 | 426 | The program [DebugView](https://technet.microsoft.com/en-us/sysinternals/debugview.aspx) can be used for a live view of debug output from the ASL Component. 427 | 428 | For errors, you can also check the Windows Event Logs, which you can find via: 429 | 430 | Control Panel ➞ Search for Event Viewer ➞ Open it ➞ Windows Logs ➞ Application ➞ Find the LiveSplit Errors 431 | 432 | Some might be unrelated to the Script, but it'll be fairly obvious which ones are caused by you. 433 | 434 | ## Sandboxed Auto Splitters 435 | 436 | It is also possible to provide an auto splitter as a WebAssembly module. These 437 | auto splitters get executed through the new Auto Splitter Runtime, which has 438 | several benefits: 439 | 1. The runtime is cross platform. It can run on Windows, macOS, and Linux. 440 | 2. The runtime is sandboxed. All auto splitters running on the new runtime are 441 | fully sandboxed and it's impossible for an auto splitter to harm the user. 442 | The user is also protected from the auto splitter crashing, which will not 443 | affect the timer itself. 444 | 3. The auto splitters can be written in many different languages, such as Rust, 445 | C, C++, JavaScript, TypeScript, Go, and more. 446 | 4. The runtime isn't tied to just LiveSplit and can be used with other timers or 447 | even run inside of the [Auto Splitting Runtime 448 | Debugger](https://github.com/CryZe/asr-debugger) which allows you to debug 449 | the auto splitters more easily. 450 | 451 | There is one downside to auto splitters written for the new runtime however. The 452 | fact that they are sandboxed and cross platform means that there may be certain 453 | functionality, that you may need for your auto splitter to work, that is not 454 | supported yet. 455 | 456 | Right now Rust is the language that has the best support. If you want to create 457 | an auto splitter using the new runtime, you can follow the instructions over 458 | here: [Rust Auto Splitter 459 | Template](https://github.com/LiveSplit/auto-splitter-template) 460 | 461 | If you need help writing an auto splitter for the new runtime, make sure to 462 | visit the `#auto-splitting-v2` channel in the [Speedrun Tool Development 463 | Discord](https://discord.gg/N6wv8pW). 464 | 465 | ## Adding an Auto Splitter 466 | 467 | If you implemented an Auto Splitter and want to add it to the Auto Splitters that are automatically being downloaded by LiveSplit, feel free to add it to the [Auto Splitters XML](./LiveSplit.AutoSplitters.xml). Just click the link, click the icon for modifying the file and GitHub will automatically create a fork, branch and pull request for you, which we can review and then merge in. 468 | 469 | **Any kind of abuse in an Auto Splitter will result in an immediate ban.** 470 | 471 | ## Additional Resources 472 | 473 | - [Speedrun Tool Development Discord](https://discord.gg/N6wv8pW) 474 | - [List of ASL Scripts](https://fatalis.pw/livesplit/asl-list/) to learn from, automatically created from the [Auto Splitters XML](./LiveSplit.AutoSplitters.xml) and filterable by different criteria 475 | - Example: [Simple Autosplitter with Settings](https://raw.githubusercontent.com/tduva/LiveSplit-ASL/master/AlanWake.asl) 476 | --------------------------------------------------------------------------------