From c11c30a0626e45855e84f8ebd543f72ec99e8bc9 Mon Sep 17 00:00:00 2001 From: Ted Wollman <25165500+TheTedder@users.noreply.github.com> Date: Wed, 21 Jun 2023 18:44:22 -0400 Subject: [PATCH 01/12] Update README.md --- README.md | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 62 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 1fec0f1..43c94b6 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,69 @@ Welcome! --- -##### Third Party Notice +## Third Party Notice This repository is not responsible for scripts malfunctioning due to issues that are not caused by asl-help. We reserve the right to immediately close any issues which report problems out of our control. Instead, please either open an issue in the repository of the script's creator, or ask a question in the [Speedrun Tool Development Discord server](https://discord.gg/cpYsxz7). + +## Purpose +Asl-help was created to aid autosplitter authors in writing scripts for games that use the mono framework, specifically the Unity fork. It is packaged as a .NET framework library that can be loaded at runtime from an autosplitter script, and uses codegen to allow for the creation of more streamlined, human-readable, and update-resilient pointer paths. + +## Usage +### Devopment Setup +Download the `asl-help` file located in the `lib` directory of this repository and place it in LiveSplit's components folder. This is only necessary for development—the file will be downloaded automatically for end users, provided that you configure your autosplitter correctly (see below). +### Loading Asl-Help +Use the following snippet to load the asl-help binary in your autosplitter. This and the following examples will assume that the game runs on the Unity engine. +```cs +startup { + Assembly.Load(File.ReadAllBytes("Components/asl-help")).CreateInstance("Unity"); +} +``` +### TryLoad +All pointers must be declared inside of a function that is assigned to the `TryLoad` member of the auto-generated `Helper` variable. This should be done inside the `init` block. If this function returns `true`, then asl-help has been successfully initialized. +```cs +init { + vars.Helper.TryLoad = (Func)(mono => { + // Declare your pointers here. + return true; + }); +``` +Because the `mono` variable is scoped to the anonymous function, it cannot be accessed outside of the function. Do not store a reference to it that could outlive said function. +### Pointers +Pointers in asl-help are declared with the following syntax inside of the TryLoad function. +```cs +vars.Helper["WatcherName"] = mono["ClassName"].Make("FieldName", offset1, offset...); +``` +`WatcherName` is the name that will be used to access the MemoryWatcher. +`ClassName` is the name of the class that owns the field that is to be accessed. +`Type` is the datatype of the value that is to be read from memory. +`FieldName` is the name of a **static** field on the class. It can also be replaced by a number representing that field's offset in the static field table. Asl-help will print all the static fields of any classes used to the debug output, wich can be used to ensure the name of the field matches said output. +`offset`, `offset2`, etc. are optional additional pointer offsets that work just like a normal pointer declaration. +### Accessing Pointers +The value of pointers declared this way can be accessed just like pointers declared in the state block: using `current` and `old`. Alternatively, the MemoryWatchers themselves can be accessed from the `vars.Helper` variable. +```cs +// The following two lines are equivalent. +return current.Level != old.Level; +return vars.Helper["Level"].Current != vars.Helper["Level"].Old; +``` +### Inheritance +Sometimes, a class's parent class has a static field that must be accessed. This is very common when dealing with singletons, which are often implemented like so: +```cs +abstract class Singleton { + static T instance; +} + +class Manager : Singleton { + // other fields +} +``` +To access a field like this, specify a number indicating how many classes in the inheritance tree to go up when declaring the pointer. +```cs +vars.Helper["Manager"] = mono["Manager", 1].Make("instance"); +``` +### Publishing +When publishing an autosplitter that depends on asl-help, add the following to the autosplitter's entry in the master XML document inside of the `` tag to ensure that it will be automatically downloaded along with the script. +```xml +https://github.com/just-ero/asl-help/raw/main/lib/asl-help +``` From 121b5304eeee8f411368009ea68d04170344bf94 Mon Sep 17 00:00:00 2001 From: Ted Wollman <25165500+TheTedder@users.noreply.github.com> Date: Thu, 22 Jun 2023 17:54:18 -0400 Subject: [PATCH 02/12] Move third party notice to the bottom. --- README.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 43c94b6..81387bb 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,6 @@ # asl-help Welcome! ---- -## Third Party Notice -This repository is not responsible for scripts malfunctioning due to issues that are not caused by asl-help. -We reserve the right to immediately close any issues which report problems out of our control. - -Instead, please either open an issue in the repository of the script's creator, or ask a question in the [Speedrun Tool Development Discord server](https://discord.gg/cpYsxz7). - ## Purpose Asl-help was created to aid autosplitter authors in writing scripts for games that use the mono framework, specifically the Unity fork. It is packaged as a .NET framework library that can be loaded at runtime from an autosplitter script, and uses codegen to allow for the creation of more streamlined, human-readable, and update-resilient pointer paths. @@ -68,3 +61,9 @@ When publishing an autosplitter that depends on asl-help, add the following to t ```xml https://github.com/just-ero/asl-help/raw/main/lib/asl-help ``` +--- +## Third Party Notice +This repository is not responsible for scripts malfunctioning due to issues that are not caused by asl-help. +We reserve the right to immediately close any issues which report problems out of our control. + +Instead, please either open an issue in the repository of the script's creator, or ask a question in the [Speedrun Tool Development Discord server](https://discord.gg/cpYsxz7). \ No newline at end of file From 74e5e2d29ae4a761e682508b18545c4eabbe4bcb Mon Sep 17 00:00:00 2001 From: Ted Wollman <25165500+TheTedder@users.noreply.github.com> Date: Thu, 22 Jun 2023 17:54:29 -0400 Subject: [PATCH 03/12] Add newlines before headings. --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index 81387bb..ce7b13e 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ Asl-help was created to aid autosplitter authors in writing scripts for games th ## Usage ### Devopment Setup Download the `asl-help` file located in the `lib` directory of this repository and place it in LiveSplit's components folder. This is only necessary for development—the file will be downloaded automatically for end users, provided that you configure your autosplitter correctly (see below). + ### Loading Asl-Help Use the following snippet to load the asl-help binary in your autosplitter. This and the following examples will assume that the game runs on the Unity engine. ```cs @@ -14,6 +15,7 @@ startup { Assembly.Load(File.ReadAllBytes("Components/asl-help")).CreateInstance("Unity"); } ``` + ### TryLoad All pointers must be declared inside of a function that is assigned to the `TryLoad` member of the auto-generated `Helper` variable. This should be done inside the `init` block. If this function returns `true`, then asl-help has been successfully initialized. ```cs @@ -24,6 +26,7 @@ init { }); ``` Because the `mono` variable is scoped to the anonymous function, it cannot be accessed outside of the function. Do not store a reference to it that could outlive said function. + ### Pointers Pointers in asl-help are declared with the following syntax inside of the TryLoad function. ```cs @@ -34,6 +37,7 @@ vars.Helper["WatcherName"] = mono["ClassName"].Make("FieldName", offset1, `Type` is the datatype of the value that is to be read from memory. `FieldName` is the name of a **static** field on the class. It can also be replaced by a number representing that field's offset in the static field table. Asl-help will print all the static fields of any classes used to the debug output, wich can be used to ensure the name of the field matches said output. `offset`, `offset2`, etc. are optional additional pointer offsets that work just like a normal pointer declaration. + ### Accessing Pointers The value of pointers declared this way can be accessed just like pointers declared in the state block: using `current` and `old`. Alternatively, the MemoryWatchers themselves can be accessed from the `vars.Helper` variable. ```cs @@ -41,6 +45,7 @@ The value of pointers declared this way can be accessed just like pointers decla return current.Level != old.Level; return vars.Helper["Level"].Current != vars.Helper["Level"].Old; ``` + ### Inheritance Sometimes, a class's parent class has a static field that must be accessed. This is very common when dealing with singletons, which are often implemented like so: ```cs @@ -56,11 +61,13 @@ To access a field like this, specify a number indicating how many classes in the ```cs vars.Helper["Manager"] = mono["Manager", 1].Make("instance"); ``` + ### Publishing When publishing an autosplitter that depends on asl-help, add the following to the autosplitter's entry in the master XML document inside of the `` tag to ensure that it will be automatically downloaded along with the script. ```xml https://github.com/just-ero/asl-help/raw/main/lib/asl-help ``` + --- ## Third Party Notice This repository is not responsible for scripts malfunctioning due to issues that are not caused by asl-help. From 7ec08445f6f444153bae50ed01b77b858fb88ffe Mon Sep 17 00:00:00 2001 From: Ted Wollman <25165500+TheTedder@users.noreply.github.com> Date: Thu, 22 Jun 2023 17:56:33 -0400 Subject: [PATCH 04/12] Restore level 5 heading for the third party notice. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ce7b13e..9fd5a1c 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,7 @@ When publishing an autosplitter that depends on asl-help, add the following to t ``` --- -## Third Party Notice +##### Third Party Notice This repository is not responsible for scripts malfunctioning due to issues that are not caused by asl-help. We reserve the right to immediately close any issues which report problems out of our control. From a698f8ebbaf46d6aec778bf14311e29c65bfbf9d Mon Sep 17 00:00:00 2001 From: Ted Wollman <25165500+TheTedder@users.noreply.github.com> Date: Thu, 22 Jun 2023 17:58:47 -0400 Subject: [PATCH 05/12] Change spelling and capitalization on some terms. --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 9fd5a1c..22d994e 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,14 @@ Welcome! ## Purpose -Asl-help was created to aid autosplitter authors in writing scripts for games that use the mono framework, specifically the Unity fork. It is packaged as a .NET framework library that can be loaded at runtime from an autosplitter script, and uses codegen to allow for the creation of more streamlined, human-readable, and update-resilient pointer paths. +asl-help was created to aid auto splitter authors in writing scripts for games that use the Mono framework, specifically the Unity fork. It is packaged as a .NET Framework library that can be loaded at runtime from an auto splitter script, and uses code generation to allow for the creation of more streamlined, human-readable, and update-resilient pointer paths. ## Usage ### Devopment Setup Download the `asl-help` file located in the `lib` directory of this repository and place it in LiveSplit's components folder. This is only necessary for development—the file will be downloaded automatically for end users, provided that you configure your autosplitter correctly (see below). ### Loading Asl-Help -Use the following snippet to load the asl-help binary in your autosplitter. This and the following examples will assume that the game runs on the Unity engine. +Use the following snippet to load the asl-help binary in your auto splitter. This and the following examples will assume that the game runs on the Unity engine. ```cs startup { Assembly.Load(File.ReadAllBytes("Components/asl-help")).CreateInstance("Unity"); @@ -35,7 +35,7 @@ vars.Helper["WatcherName"] = mono["ClassName"].Make("FieldName", offset1, `WatcherName` is the name that will be used to access the MemoryWatcher. `ClassName` is the name of the class that owns the field that is to be accessed. `Type` is the datatype of the value that is to be read from memory. -`FieldName` is the name of a **static** field on the class. It can also be replaced by a number representing that field's offset in the static field table. Asl-help will print all the static fields of any classes used to the debug output, wich can be used to ensure the name of the field matches said output. +`FieldName` is the name of a **static** field on the class. It can also be replaced by a number representing that field's offset in the static field table. asl-help will print all the static fields of any classes used to the debug output, wich can be used to ensure the name of the field matches said output. `offset`, `offset2`, etc. are optional additional pointer offsets that work just like a normal pointer declaration. ### Accessing Pointers @@ -63,7 +63,7 @@ vars.Helper["Manager"] = mono["Manager", 1].Make("instance"); ``` ### Publishing -When publishing an autosplitter that depends on asl-help, add the following to the autosplitter's entry in the master XML document inside of the `` tag to ensure that it will be automatically downloaded along with the script. +When publishing an auto splitter that depends on asl-help, add the following to the auto splitter's entry in the master XML document inside of the `` tag to ensure that it will be automatically downloaded along with the script. ```xml https://github.com/just-ero/asl-help/raw/main/lib/asl-help ``` From 94a8594afadc356c85292fe694050921c74c9558 Mon Sep 17 00:00:00 2001 From: Ted Wollman <25165500+TheTedder@users.noreply.github.com> Date: Thu, 22 Jun 2023 17:59:58 -0400 Subject: [PATCH 06/12] Fix typo. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 22d994e..9d7257c 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ Welcome! asl-help was created to aid auto splitter authors in writing scripts for games that use the Mono framework, specifically the Unity fork. It is packaged as a .NET Framework library that can be loaded at runtime from an auto splitter script, and uses code generation to allow for the creation of more streamlined, human-readable, and update-resilient pointer paths. ## Usage -### Devopment Setup +### Development Setup Download the `asl-help` file located in the `lib` directory of this repository and place it in LiveSplit's components folder. This is only necessary for development—the file will be downloaded automatically for end users, provided that you configure your autosplitter correctly (see below). ### Loading Asl-Help From 4fb3fc88983b63c1822a150267715887828c2399 Mon Sep 17 00:00:00 2001 From: Ted Wollman <25165500+TheTedder@users.noreply.github.com> Date: Thu, 22 Jun 2023 18:01:48 -0400 Subject: [PATCH 07/12] Change writing style and treat "auto splitter" as two words. Co-authored-by: Ero <56401411+just-ero@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9d7257c..eaeb320 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ asl-help was created to aid auto splitter authors in writing scripts for games t ## Usage ### Development Setup -Download the `asl-help` file located in the `lib` directory of this repository and place it in LiveSplit's components folder. This is only necessary for development—the file will be downloaded automatically for end users, provided that you configure your autosplitter correctly (see below). +Download the `asl-help` file located in the `lib` directory of this repository and place it in LiveSplit's components folder. This is only necessary for development — the file will be downloaded automatically for end users, provided that you configure your auto splitter correctly (see below). ### Loading Asl-Help Use the following snippet to load the asl-help binary in your auto splitter. This and the following examples will assume that the game runs on the Unity engine. From 12abe6148336f397fab4c55d5056ad7bf0d800fa Mon Sep 17 00:00:00 2001 From: Ted Wollman <25165500+TheTedder@users.noreply.github.com> Date: Thu, 22 Jun 2023 18:08:09 -0400 Subject: [PATCH 08/12] Link directly to the relevant section. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index eaeb320..a9d1813 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ asl-help was created to aid auto splitter authors in writing scripts for games t ## Usage ### Development Setup -Download the `asl-help` file located in the `lib` directory of this repository and place it in LiveSplit's components folder. This is only necessary for development — the file will be downloaded automatically for end users, provided that you configure your auto splitter correctly (see below). +Download the `asl-help` file located in the `lib` directory of this repository and place it in LiveSplit's components folder. This is only necessary for development — the file will be downloaded automatically for end users, provided that you configure your autosplitter correctly (see [Publishing](#publishing)). ### Loading Asl-Help Use the following snippet to load the asl-help binary in your auto splitter. This and the following examples will assume that the game runs on the Unity engine. @@ -62,7 +62,7 @@ To access a field like this, specify a number indicating how many classes in the vars.Helper["Manager"] = mono["Manager", 1].Make("instance"); ``` -### Publishing +### Publishing {#publishing} When publishing an auto splitter that depends on asl-help, add the following to the auto splitter's entry in the master XML document inside of the `` tag to ensure that it will be automatically downloaded along with the script. ```xml https://github.com/just-ero/asl-help/raw/main/lib/asl-help From 0e1169facb7ca279263ca86d624c1400f01841f8 Mon Sep 17 00:00:00 2001 From: Ted Wollman <25165500+TheTedder@users.noreply.github.com> Date: Thu, 22 Jun 2023 18:08:26 -0400 Subject: [PATCH 09/12] Change one last instance of "autosplitter." --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a9d1813..bd84ad2 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ asl-help was created to aid auto splitter authors in writing scripts for games t ## Usage ### Development Setup -Download the `asl-help` file located in the `lib` directory of this repository and place it in LiveSplit's components folder. This is only necessary for development — the file will be downloaded automatically for end users, provided that you configure your autosplitter correctly (see [Publishing](#publishing)). +Download the `asl-help` file located in the `lib` directory of this repository and place it in LiveSplit's components folder. This is only necessary for development — the file will be downloaded automatically for end users, provided that you configure your auto splitter correctly (see [Publishing](#publishing)). ### Loading Asl-Help Use the following snippet to load the asl-help binary in your auto splitter. This and the following examples will assume that the game runs on the Unity engine. From ea447be3b04ef6e5a2f51c7006442aad5c0402c4 Mon Sep 17 00:00:00 2001 From: Ted Wollman <25165500+TheTedder@users.noreply.github.com> Date: Thu, 22 Jun 2023 18:10:47 -0400 Subject: [PATCH 10/12] Remove erroneous header id. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bd84ad2..cd182ca 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ To access a field like this, specify a number indicating how many classes in the vars.Helper["Manager"] = mono["Manager", 1].Make("instance"); ``` -### Publishing {#publishing} +### Publishing When publishing an auto splitter that depends on asl-help, add the following to the auto splitter's entry in the master XML document inside of the `` tag to ensure that it will be automatically downloaded along with the script. ```xml https://github.com/just-ero/asl-help/raw/main/lib/asl-help From dfb10aba855d646550be335a5097e06cbbfa3300 Mon Sep 17 00:00:00 2001 From: Ted Wollman <25165500+TheTedder@users.noreply.github.com> Date: Thu, 22 Jun 2023 18:11:46 -0400 Subject: [PATCH 11/12] Add missing closing brace. Co-authored-by: Ero <56401411+just-ero@users.noreply.github.com> --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index cd182ca..b8c62c0 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,7 @@ init { // Declare your pointers here. return true; }); +} ``` Because the `mono` variable is scoped to the anonymous function, it cannot be accessed outside of the function. Do not store a reference to it that could outlive said function. From 1f3a89e2d031ff50492ad594e49456b24b6f9c06 Mon Sep 17 00:00:00 2001 From: Ted Wollman <25165500+TheTedder@users.noreply.github.com> Date: Fri, 23 Jun 2023 15:31:50 -0400 Subject: [PATCH 12/12] Use the MonoHelper overloads for making pointers. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b8c62c0..576357e 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ Because the `mono` variable is scoped to the anonymous function, it cannot be ac ### Pointers Pointers in asl-help are declared with the following syntax inside of the TryLoad function. ```cs -vars.Helper["WatcherName"] = mono["ClassName"].Make("FieldName", offset1, offset...); +vars.Helper["WatcherName"] = mono.Make("Classname", "FieldName", offset1, offset...); ``` `WatcherName` is the name that will be used to access the MemoryWatcher. `ClassName` is the name of the class that owns the field that is to be accessed.