From 0ca9e9261658602a421f009793307d044aa3da63 Mon Sep 17 00:00:00 2001
From: Marcus Huderle <huderlem@gmail.com>
Date: Thu, 15 Aug 2024 09:01:51 -0500
Subject: [PATCH] Update README

---
 README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/README.md b/README.md
index bec0f06..b5c22a2 100644
--- a/README.md
+++ b/README.md
@@ -35,6 +35,7 @@ View the [Changelog](https://github.com/huderlem/poryscript/blob/master/CHANGELO
   * [Comments](#comments)
   * [Constants](#constants)
   * [Scope Modifiers](#scope-modifiers)
+  * [AutoVar Commands](#autovar-commands)
   * [Compile-Time Switches](#compile-time-switches)
   * [Optimization](#optimization)
   * [Line Markers](#line-markers)
@@ -720,6 +721,65 @@ The top-level statements have different default scopes. They are as follows:
 | `mart` | Local |
 | `mapscripts` | Global |
 
+## AutoVar Commands
+Some scripting commands always store their result in the same variable. For example, `checkitem` always stores its result in `VAR_RESULT`. Poryscript can simplify working with these commands with a concept called "AutoVar" commands.
+
+*Without* using an AutoVar, a script would be written like this:
+```
+checkitem(ITEM_ROOT_FOSSIL)
+if (var(VAR_RESULT) == TRUE) {
+    // player has the Root Fossil
+}
+```
+
+However, AutoVars can be used *inside* the condition, which helps streamline the script:
+```
+if (checkitem(ITEM_ROOT_FOSSIL) == TRUE) {
+    // player has the Root Fossil
+}
+```
+
+AutoVars can be used ***anywhere*** a `var()` operator can be used.  e.g. `if` conditions, `switch` statements--any boolean expression!
+
+### Defining AutoVar Commands
+AutoVar commands are fully configurable with the `command_config.json` file.  Use the `-cc` command line parameter to specifying the location of that config.
+
+There are two types of AutoVar commands:
+1. Implicit
+    - The stored var is defined in the config file, and is not present in the authored script.
+    - Examples: `checkitem`, `getpartysize`, `random`
+2. Explicit
+    - The stored var is provided as part of the command, and the config file stores the 0-based index of the command that specifies the stored var.
+    - Examples: `specialvar`, `checkcoins`
+
+Let's take a look at the example config file:
+```json
+// command_config.json
+{
+    "autovar_commands": {
+        "specialvar": {
+            "var_name_arg_position": 0
+        },
+        "checkitem": {
+            "var_name": "VAR_RESULT"
+        },
+    ...
+}
+```
+
+With the above config, a script could be written like so:
+```
+if (checkitem(ITEM_POKEBLOCK_CASE)) {
+    if (specialvar(VAR_RESULT, GetFirstFreePokeblockSlot) != -1 && 
+        specialvar(VAR_RESULT, PlayerHasBerries)
+    ) {
+        msgbox("Great! You can use the Berry Blender!)
+    }
+} else {
+    msgbox("You don't have a Pokeblock case!")
+}
+```
+
 ## Compile-Time Switches
 Use the `poryswitch` statement to change compiler behavior depending on custom switches. This makes it easy to make scripts behave different depending on, say, the `GAME_VERSION` or `LANGUAGE`. Any content that does not match the compile-time switch will not be included in the final output. To define custom switches, use the `-s` option when running `poryscript`.  You can specify multiple switches, and each key/value pair must be separated by an equals sign. For example: