manual: working on command design (#34)

* add a few commands

* update some commands

* add ITEM_PARSE

manual/ITEM_PARSE.md

@@ -0,0 +1,25 @@
+Item specifier:
+
+```
+ItemListForAdd    -> NumberedItem+
+ItemListForRemove -> AllableItem+
+ItemListForArea   -> InfableItem+
+NumberedItem  -> NUMBER Item
+InfableItem   -> NumOrInf Item
+AllableItem   -> NumOrAll Item
+NumOrInf      -> NUMBER | "infinite"
+NumOrAll      -> NUMBER | "all"
+Item          -> ItemName ItemMeta?
+ItemMeta      -> [ ItemMetaEntry (OpComma ItemMetaEntry)* ]
+ItemMetaEntry -> ItemMetaKey (OpAssign ItemMetaValue)?
+ItemMetaKey   -> WORD
+ItemMetaValue -> WORD | NUMBER | BOOL
+ItemName      -> WORD+ | < WORD >
+
+ItemSlot      -> ( OpSlotSpec "slot" NUMBER )
+
+OpSlotSpec    -> "from" | "in" | "to"
+
+OpAssign      -> = | :
+OpComma       -> ,
+```

manual/Taskfile.yml

@@ -6,7 +6,7 @@ tasks:
     cmds:
       - task: build
       - mdbook watch &
-      - live-server book -p 8081
+      - live-server book -p 8081 {{.CLI_ARGS}}
 
   build:
     desc: (Re-)build the book

manual/book.toml

@@ -1,5 +1,4 @@
 [book]
-
 authors = ["Pistonight"]
 language = "en"
 multilingual = false
@@ -8,5 +7,18 @@ title = "The IST Simulator Manual"
 
 [output.html]
 site-url = "/manual/"
+default-theme = "frappe"
+preferred-dark-theme = "frappe"
 smart-punctuation = true
 git-repository-url = "https://github.com/Pistonite/botw-ist"
+additional-css = [
+    "./theme/mdbook-admonish.css",
+    "./theme/catppuccin.css", 
+    "./theme/catppuccin-admonish.css"
+]
+
+[preprocessor]
+
+[preprocessor.admonish]
+command = "mdbook-admonish"
+assets_version = "3.0.2" # do not edit: managed by `mdbook-admonish install`

manual/src/SUMMARY.md

@@ -1,3 +1,10 @@
 # Summary
 
 - [Chapter 1](./chapter_1.md)
+- [Scopes](./scope.md)
+  - [Game Scope]()
+  - [Inventory Scope]()
+  - [Dialog Scope]()
+- [Actions](./action.md)
+  - [`get`](./action/get.md)
+- [Commands]()

manual/src/action.md

@@ -0,0 +1,3 @@
+# Actions
+
+Actions map to actions you can do in the game

manual/src/action/get.md

@@ -0,0 +1,6 @@
+# Get 
+
+## Syntax
+```
+
+```

manual/src/chapter_1.md

@@ -1,3 +1,50 @@
 # Chapter 1
 
 This is a placeholder...
+Test 2 3 4 5 6 7 8 9 10
+
+```rust
+fn main() {
+    println!("Hello, World!");
+}
+```
+
+```admonish info
+Test
+```
+
+```admonish note
+Test
+```
+
+```admonish warning
+Test
+```
+
+```admonish danger
+Test
+```
+
+```admonish tip
+Test
+```
+
+```admonish important
+Test
+```
+
+```admonish caution
+Test
+```
+
+```admonish error
+Test
+```
+
+```admonish hint
+Test
+```
+
+```admonish attention
+Test
+```

manual/src/scope.md

@@ -0,0 +1,97 @@
+# Scopes
+
+Scope is a concept that the simulator runtime uses to enforce
+the validity of the setup, and automatically update
+different parts of the simulation. For example:
+
+- You cannot use an item while talking to a NPC
+- GDT Inventory is synced when closing inventory
+- If the game crashes, you can't do anything until you restart it
+
+Currently, there are three scopes in the simulator:
+- Game Scope: The game is running, and the player has control of Link
+- Inventory Scope: The player is looking at the inventory (pressed `+`)
+- Dialog Scope: The player doesn't have control of Link (for example, talking to an NPC)
+
+## Automatic Scope Management
+For the most part, scopes are managed automatically by the simulator runtime
+based on the command, so you don't have to worry about them. 
+
+For example,
+consider the following script
+
+```
+get 1 apple
+eat 1 apple
+get 1 wood
+```
+
+At first, the simulation state is not in any scope.
+To get an item, you must have control of Link, so the `get` action requires `game, !paused` scope, so the simulator automatically
+activate the `game` scope by starting a new game.
+
+The next `eat` action requires `game, inventory` scope because you need
+to be in the inventory to eat an item. The simulator infers
+that you want to pause the game to eat the item, so it automatically
+activates the `inventory` scope.
+
+Finally, the last `get` action requires the game to be not paused,
+so the simulator automatically deactivates the `inventory` scope to allow
+the action to be performed.
+
+## Manual Scope Management
+Certain actions like `pause` can be used to change the scope manually.
+When the scope is activated manually, the simulator will not automatically
+change the scope until the manual scope is deactivated.
+
+For example, consider the following script, which is the same as above except
+that it manually pauses the game before `eat`
+```
+get 1 apple
+pause
+eat 1 apple
+get 1 wood # Error!
+```
+
+Now the simulator will not automatically deactivate the `inventory` scope
+for `get 1 wood`. Instead, it will give an error saying you cannot get new 
+item while paused.
+
+## Scope Conflict
+Another error that the scope system checks for is conflicting scopes.
+For example, you cannot access inventory while talking to an NPC.
+This is implemented by you cannot activate `inventory` scope 
+while the `dialog` scope is active.
+
+The following script is valid:
+```
+sell 1 apple
+eat 1 apple
+```
+Here, `sell` activates the `dialog` scope, and `eat` deactivates it to
+activate the `inventory` scope.
+
+However, if you manually activate the `inventory` scope before `sell`,
+you will have an error because the `dialog` scope cannot be automatically
+activated while `inventory` scope is in use.
+
+```
+talk-to shopkeeper
+sell 1 apple
+eat 1 apple # Error!
+```
+
+## Crashes
+Most commands require the `game` scope, which can be automatically activated.
+The only exception is when the game crashes. In this case, you must
+manually activate the `game` scope with an action like `new-game` or `reload`
+
+## Testing
+Scope can be tested using the `!assert-scope` command. The special `not-paused`
+keyword can be used to test that `game` is the top-level scope
+
+```
+!assert-scope game
+!assert-scope inventory
+!assert-scope game not-paused
+```