README: Freshen up

Author: nosoop

README.md

@@ -4,54 +4,81 @@ A SourceMod extension that provides:
 - An easy way for plugins to validate and patch platform-specific address locations with a game
 configuration file.
 - A new handle type for plugins to allocate / free their own memory blocks.
+- Additional memory-related utilities.
 
-## Origin
+The extension comes bundled with `sourcescramble_manager`, a helper plugin that reads gamedata
+file names and patch names from a config file, then loads them all in.  For those simple patches
+that don't need further configuration other than being toggled on.
+
+## Installation
+
+This is the installation process for end-users.
+
+1.  Download and unpack the latest release (`package.zip` for Windows, `package.tar.gz` for
+Linux) into your game directory.
+2.  Install `sourcescramble_manager.smx` into your SourceMod installation's `plugins/`
+directory.
 
-I just got really tired of writing plugin boilerplate for good, clean, memory patching
-shenanigans.  I've written a number of them for public / private purposes, and they've been
-generally a pain.
+There are two ways patches can be applied:
 
-[This is the most recent one I've written.][bot-collide]  The problems that stand out to me are:
+- managed patches, where `sourcescramble_manager.smx` handles installation / uninstallation in
+a set-and-forget fashion; these are installed by adding a configuration entry in
+`configs/sourcescramble/`
+- unmanaged patches, where another plugin (usually by the patch author) performs the patching
 
-1.  Hardcoded, platform-specific patch payload.
-2.  No verification on bytes to be patched (what if a game update modifies the function?).
-3.  Reverting the patch would have to be manually implemented.
+It's up to the developer of each patch to provide instructions on how to install them.
+Regardless, all patches do require a game configuration file installed in `gamedata/`.
 
-[bot-collide]: https://gist.github.com/nosoop/08774339937179d0022a541b05b51c8c
+## Origin
+
+This was originally just dedicated to memory patching.  I had a number of gripes with existing
+solutions like [Memory Patcher][], [No Thriller Taunt][], and one-off plugins for this purpose:
 
-SourceMod's built-in memory access functions are very powerful, but also very primitive.
-Additionally, there is no method to access arbitrary sections of the game config file, so a
-pure-SourcePawn implementation would force developers to either:
+1.  Plugins either hardcode the solution in the plugin, or use some custom conventions in their
+game config file (solutions I've seen / written myself use either pollute the `Keys` section or
+do their own config parsing with `SMCParser`).
+2.  There is no verification on bytes to be patched (what if a game update modifies the
+function?).
+3.  Reverting the patch would have to be manually implemented.  Some plugins neglect to do this.
 
-* Load and parse the config separate from `LoadGameConfigFile` with an `SMCParser` or similar.
-I've written this myself as a standalone include file, and there's still a decent amount of
-manual management that needed doing for every plugin I wrote using it.
-* Have them place the required information in separate "Keys" section entries with particular
-naming conventions.  This is what [Memory Patcher][] and [No Thriller Taunt][] do.
+Writing it as an extension allows it to:
+
+1.  Leverage SourceMod's game configuration parsing logic.  No need to reparse the file, and
+this provides a uniform convention for patches.
+2.  Use the SourceMod handle system; this allows for managed cleanup and provides a relatively
+nice API for developers to work with.
 
 [Memory Patcher]: https://forums.alliedmods.net/showthread.php?p=2617543
 [No Thriller Taunt]: https://forums.alliedmods.net/showthread.php?t=171343
 
-Both solutions (which are the ones that I can think of) are fairly cumbersome.
+## Developer usage
 
-The extension comes bundled with `sourcescramble_manager`, a helper plugin that reads gamedata
-file names and patch names from a config file, then loads them all in.  For those simple patches
-that don't need further configuration other than being toggled on.
+There are a number of things provided with this extension:
+
+- Memory patches, which are a game config-dedicated section that allows a plugin to safely
+overwrite and restore the contents of a memory location.
+- Memory blocks, which provide a Handle type to allocate memory.
+- Address-of natives.
 
-## Memory patching usage
+Developing with this extension is intended for power users that are already getting their hands
+dirty with server internals.  Most developers do not need this kind of flexibility.
 
-### Writing patches
+### Memory patches
 
-This assumes you have a decent enough understanding of x86 assembly.  I mean, why else would you
-be writing one?
+Memory patches allow developers to declare a byte payload to be written to memory.
+
+#### Creating new patches
+
+Since patches generally operate on machine code, you'll need to be familiar with that to write
+patches.
 
 A new `MemPatches` section is added at the same level of `Addresses`, `Offsets`, and
 `Signatures` in the game configuration file.  An example of a section is below:
 
 ```
 "MemPatches"
 {
-	// this patch makes buildings solid to TFBots
+	// this patch makes buildings solid to TFBots by forcing certain code paths
 	"CTraceFilterObject::ShouldHitEntity()::TFBotCollideWithBuildings"
 	{
 		"signature" "CTraceFilterObject::ShouldHitEntity()"
@@ -73,33 +100,37 @@ A new `MemPatches` section is added at the same level of `Addresses`, `Offsets`,
 
 A few things are present:
 
-* A subsection.  The name of the section will be the name used when getting a `MemoryPatch`
+- A subsection.  The name of the section will be the name used when getting a `MemoryPatch`
 handle with `MemoryPatch.CreateFromConf()`.
-* A function `signature` name referencing the name of a signature in a `Signatures` section
+- A function `signature` name referencing the name of a signature in a `Signatures` section
 somewhere else in the game config file.
-* The `offset` to patch.  Hexadecimal notation is supported with the `h` suffix, for easy
+- The `offset` to patch.  Hexadecimal notation is supported with the `h` suffix, for easy
 referencing in IDA or similar.
-* `patch` (required) and `verify` (optional) Hex strings (`\x01\x02\x03` or `01 02 03` formats
+- `patch` (required) and `verify` (optional) Hex strings (`\x01\x02\x03` or `01 02 03` formats
 supported) indicating the byte payload and a signature to match against at the previously
 mentioned offset.
+	- `verify` signatures can use `\x2A` to indicate wildcards, same as SourceMod.
 
-### Automatically applying patches
+Any values written on top of an applied patch will be reverted back when the patch is removed.
 
-Add a key / value pair to `configs/sourcescramble_manager.cfg`, where the key and value
-correspond to a gamedata file and patch name, respectively.
+#### Automatically applying patches
 
-Alternatively, you can add your own config files to `configs/sourcescramble/`, making it easy
-for end-users to install without having to edit the base config file.
+Once you've created a game configuration file that gets stored in `gamedata/`, you can apply it
+in "managed" mode.
+
+Create a new config file in `configs/sourcescramble/`, following the same format as
+`configs/sourcescramble_manager.cfg`.  Key / value pairs should correspond to a gamedata file
+and patch name, respectively.
 
 Reload the plugin using `sm plugins reload sourcescramble_manager` to reload the patches.
 No reload command is built-in, because the plugin intentionally leaks and doesn't keep track of
 handles.  (The extension automatically disables patches when the handle is deleted, which
 happens when the owning plugin is unloaded or reloaded.)
 
-### Manually applying patches
+#### Manually applying patches
 
 For more complex cases (e.g., scoped hook memory patches or potentially dynamic patch
-modifications), you'll have to write your own plugin.
+modifications), you'll have to write your own plugin to patch / unpatch the memory as desired.
 
 This should be fairly self-explanatory:
 
@@ -117,10 +148,12 @@ if (!patch.Validate()) {
 
 // ...
 
+// restore the bytes that were in place when the patch was enabled
+// any writes on top of the patched area are also wiped
 patch.Disable();
 ```
 
-## Memory blocks
+### Memory blocks
 
 A `MemoryBlock` is a `calloc`-allocated chunk of memory that can be accessed with
 `StoreToAddress` and `LoadFromAddress` (indirectly via wrapped helper methods).
@@ -129,6 +162,8 @@ Some patches I've dealt with operate on fixed locations in memory (e.g., floatin
 operations that don't take immediate values), so with this I can point to the `MemoryBlock`
 address space and put in whatever I need.
 
+It's also a useful way of allocating structures for things like `SDKCall`s.
+
 Basic use of the API:
 
 ```sourcepawn
@@ -142,3 +177,23 @@ Address pFloatBlock = block.Address;
 // frees the 4 bytes that was allocated
 delete block;
 ```
+
+### Address-of natives
+
+New to Source Scramble 0.6.x, this allows a plugin to get the address of one of its own
+variables (`cell_t` or `char[]`).
+
+This replaces certain use cases of memory blocks; you can now point to an existing variable in
+the plugin's memory space in cases when you need to read a float value or more granular control
+in things like DHooks to send a fixed buffer.
+
+```sourcepawn
+float g_flValue;
+
+Address pFloatLocation = GetAddressOfCell(g_flValue);
+// patch an indirect load or whatever with the address of that float value
+
+g_flValue = 0.75; // changes are reflected instantly wherever this memory location is referenced
+```
+
+Of course, this is all use-at-your-own-risk.