Add separate guide for authoring routes

thecodewarrior · thecodewarrior · commit d91d3128f007 · 2021-06-19T22:38:30.000-07:00
diff --git a/README.md b/README.md
@@ -44,91 +44,23 @@ Launching and using SwiftSplit is fairly simple, with only three broad steps.
 Safari doesn't like the way SwiftSplit communicates with LiveSplit One, so LiveSplit stalls when trying to connect.
 
 ### Firefox - Mostly compatible
-If you only have one display, Firefox will slow down the LiveSplit One tab, causing it to record incorrect times.
-If you keep the LiveSplit window open on a second display this isn't an issue.
+Unless you can keep LiveSplit open and visible, Firefox will slow down the LiveSplit One tab, causing it to record 
+incorrect times. If you keep the LiveSplit window open on a second display this isn't an issue.
 
 ### Chrome - Compatible
 Chrome doesn't seem to have the same optimization as Firefox, which in this case is a good thing. If you're using 
 Firefox and your splits are coming out wrong, try with Chrome and see if that fixes it.
 
 ## Pre-made splits
-Pre-made splits and route JSON files for Any% and the B-sides can be found [here](https://github.com/thecodewarrior/SwiftSplit/tree/master/example).
-The `.lss` files can be imported directly into LiveSplit One and the corresponding `.json` files can be loaded into SwiftSplit.
-
-# Route JSON
-Routes are configured using a JSON file and use "events" generated by SwiftSplit. They consist of a reset event and a 
-list of route events. SwiftSplit expects route events in a specific order and triggers splits on those events. The reset
-event can trigger at any point during the route and will reset the run. If the next event in the route is itself the 
-reset event, that will take priority and the run won't be reset. This can be used to implement returning to map into
-your route.
-
-Here's an example for Old Site Any%:
-```json
-{
-    "useFileTime": false,
-    "reset": "reset chapter",
-    "route": [
-        "start chapter 2 ## Start",
-        "d8 > d3 ## - Mirror",
-        "3x > 3 ## Intervention",
-        "10 > 2 ## - Escape",
-        "13 > end_0 ## Awake",
-        "complete chapter 2"
-    ]
-}
-```
-
-## Events
-Events are triggered when SwiftSplit observes a change in the game state, which is checked 30 times every second. A 
-single state change frequently causes multiple events, generally with differing levels of specificity. 
-
-Note that the *exact* text of an event is important. Spaces and capitalization have to match, with a couple additions:
-- Inserting an exclamation point (`!`) at the beginning of an event will cause that event to not trigger a split. This 
-  can be useful when your route passes between two screens multiple times but you only want one split. 
-- Anything after `##` will be trimmed off. This can be useful for explaining events.
-- Any event entries that start with `#` will be ignored, allowing you to "comment out" events.
-
-SwiftSplit has an "Event Stream" panel that displays events as they are triggered, which can be useful when creating 
-route files. (You can copy the text out of the panel to paste directly into the route file too).
-
-### Chapter start/end events
-- `leave chapter` - Triggered when leaving any chapter (either by restarting the chapter, returning to the map, or
-  using "Save and Quit")
-- `leave chapter <n>` - Triggered when leaving chapter `<n>`
-- `start chapter` - Triggered when any chapter is started
-- `start chapter <n>` - Triggered when chapter `<n>` is started
-- `complete chapter` - Triggered when any chapter is completed
-- `complete chapter <n>` - Triggered when chapter `<n>` is completed
-- **A-side specific:**
-  - `start a-side <n>` - Triggered when chapter `<n>`'s A-side is started
-  - `leave a-side <n>` - Triggered when leaving chapter `<n>`'s A-side
-  - `complete a-side <n>` - Triggered when chapter `<n>`'s A-side is completed
-- **B-side specific:**
-  - `start b-side <n>` - Triggered when chapter `<n>`'s B-side is started
-  - `leave b-side <n>` - Triggered when leaving chapter `<n>`'s B-side
-  - `complete b-side <n>` - Triggered when chapter `<n>`'s B-side is completed
-- **C-side specific:**
-  - `start c-side <n>` - Triggered when chapter `<n>`'s C-side is started
-  - `leave c-side <n>` - Triggered when leaving chapter `<n>`'s C-side
-  - `complete c-side <n>` - Triggered when chapter `<n>`'s C-side is completed
-
-### Screen transition event
-- `<from screen> > <to screen>` - Triggered when transitioning between two screens (you can find the screen IDs by
-  enabling debug and hovering over the screen in the map editor.)
-
-### Collectable events
-- **Cassettes:**
-  - `cassette` - Triggered when any cassette is collected
-  - `chapter <n> cassette` - Triggered when the cassette in the specified chapter is collected
-  - `<n> total cassettes` - Triggered when a cassette is collected. `<n>` is the total number of cassettes collected in
-    the current file
-- **Heart Gems:**
-  - `heart` - Triggered when any heart gem is collected
-  - `chapter <n> heart` - Triggered when the heart gem in the specified chapter is collected
-  - `<n> total hearts` - Triggered when a heart gem is collected. `<n>` is the total number of heart gems collected in 
-    the current file
-- **Strawberries:**
-  - `strawberry` - Triggered when any strawberry is collected
-  - `<n> chapter strawberries` - Triggered when a total of `<n>` strawberries are collected in a chapter
-  - `<n> file strawberries` - Triggered when a total of `<n>` strawberries are collected in the file
+You can get pre-made splits from the [examples directory](https://github.com/thecodewarrior/SwiftSplit/tree/master/example).
+Included are:
+- Full-game
+  - Any%
+- IL (chapters 1–9)
+  - Any%
+  - B-side
+  - C-side
+- Icons (chapters, berry, and celeste mountain) for use as split icons
+For each of these the `.lss` file can be imported directly into LiveSplit One and the corresponding `.json` files can 
+be loaded into SwiftSplit. 
 
diff --git a/SwiftSplit/CelesteSplitter.swift b/SwiftSplit/CelesteSplitter.swift
@@ -214,33 +214,29 @@ class CelesteSplitter {
             events.append(Event(
                 .normal("collect cassette", specificity: 0),
                 .normal("collect chapter \(new.chapter) cassette", specificity: 0),
-                .normal("collect \(new.fileCassettes) total cassettes", specificity: 0),
+                .normal("\(new.fileCassettes) total cassettes", specificity: 0),
                 // compat:
                 .legacy("cassette"),
-                .legacy("chapter \(new.chapter) cassette"),
-                .legacy("\(new.fileCassettes) total cassettes")
+                .legacy("chapter \(new.chapter) cassette")
             ))
         }
         if new.chapterHeart && !old.chapterHeart {
             events.append(Event(
                 .normal("collect heart", specificity: 0),
                 .normal("collect chapter \(new.chapter) heart", specificity: 0),
-                .normal("collect \(new.fileHearts) total hearts", specificity: 0),
+                .normal("\(new.fileHearts) total hearts", specificity: 0),
                 // compat:
                 .legacy("heart"),
-                .legacy("chapter \(new.chapter) heart"),
-                .legacy("\(new.fileHearts) total hearts")
+                .legacy("chapter \(new.chapter) heart")
             ))
         }
         if new.chapterStrawberries > old.chapterStrawberries {
             events.append(Event(
                 .normal("collect strawberry", specificity: 0),
-                .normal("collect \(new.chapterStrawberries) chapter strawberries", specificity: 0),
-                .normal("collect \(new.fileStrawberries) file strawberries", specificity: 0),
+                .normal("\(new.chapterStrawberries) chapter strawberries", specificity: 0),
+                .normal("\(new.fileStrawberries) file strawberries", specificity: 0),
                 // compat:
-                .legacy("strawberry"),
-                .legacy("\(new.chapterStrawberries) chapter strawberries"),
-                .legacy("\(new.fileStrawberries) file strawberries")
+                .legacy("strawberry")
             ))
         }
         return events
@@ -342,7 +338,7 @@ class RouteEvent {
     }
     
     private static let pattern = try! NSRegularExpression(
-        pattern: #"^(!)?\s*(.*?)\s*(##.*)?$"#
+        pattern: #"^\s*(!)?\s*(.*?)\s*(#.*)?$"#
     )
 }
 
diff --git a/authoring_routes.md b/authoring_routes.md
@@ -0,0 +1,115 @@
+# Route JSON
+Routes are configured using a JSON file and use "events" generated by SwiftSplit. 
+
+Here's an example for Old Site Any%:
+```json
+{
+    "useFileTime": false,
+    "reset": "reset chapter",
+    "route": [
+        "enter chapter 2 # Start",
+        "d8 > d3 # - Mirror",
+        "3x > 3 # Intervention",
+        "10 > 2 # - Escape",
+        "13 > end_0 # Awake",
+        "complete chapter 2"
+    ]
+}
+```
+
+A route consists of a "reset" event and a list of "route" events. SwiftSplit expects route events in a specific order
+and triggers splits on those events. The reset event can trigger at any point during the route and will instruct
+LiveSplit to reset the run. There are mechanisms in place to allow leaving a chapter mid-run (either via Save and Quit
+or Return to Map). See the [Expected Resets](#expected-resets) section for more on that.
+
+## Events
+Events are triggered when SwiftSplit observes a change in the game state, which is checked 30 times every second. A 
+single event may have multiple variants, generally with differing levels of specificity (e.g. `leave chapter`, 
+`leave chapter 1`, and `leave a-side 1`).
+
+Note that the *exact* text of an event is important. Spaces and capitalization have to match, with a couple additions:
+- Whitespace *around* an event doesn't matter. (e.g. `"leave chapter"` is equivalent to `"    leave chapter "`)
+- Inserting an exclamation point (`!`) at the beginning of an event will cause that event to be "silent" and not trigger 
+  a split. This can be useful for situations like [expected resets](#expected-resets).
+- Anything after `#` will be trimmed off. This can be useful for explaining events.
+- If after applying the previous two rules the event is empty, it's simply ignored. (e.g. `! # comment` will be ignored)
+
+SwiftSplit has an "Event Stream" panel that displays events as they are triggered, which can be useful when creating 
+route files. (You can copy the text out of the panel to paste directly into the route file).
+
+### Chapter start/end events
+- `leave chapter` - Triggered when leaving any chapter (either by restarting the chapter, returning to the map, or
+  using "Save and Quit")
+- `leave chapter <n>` - Triggered when leaving chapter `<n>`
+- `enter chapter` - Triggered when any chapter is entered
+- `enter chapter <n>` - Triggered when chapter `<n>` is entered
+- `complete chapter` - Triggered when any chapter is completed
+- `complete chapter <n>` - Triggered when chapter `<n>` is completed
+- **A-side specific:**
+  - `enter a-side <n>` - Triggered when chapter `<n>`'s A-side is entered
+  - `leave a-side <n>` - Triggered when leaving chapter `<n>`'s A-side
+  - `complete a-side <n>` - Triggered when chapter `<n>`'s A-side is completed
+- **B-side specific:**
+  - `enter b-side <n>` - Triggered when chapter `<n>`'s B-side is entered
+  - `leave b-side <n>` - Triggered when leaving chapter `<n>`'s B-side
+  - `complete b-side <n>` - Triggered when chapter `<n>`'s B-side is completed
+- **C-side specific:**
+  - `enter c-side <n>` - Triggered when chapter `<n>`'s C-side is entered
+  - `leave c-side <n>` - Triggered when leaving chapter `<n>`'s C-side
+  - `complete c-side <n>` - Triggered when chapter `<n>`'s C-side is completed
+
+### Screen transition event
+- `<from screen> > <to screen>` - Triggered when transitioning between two screens (you can find the screen IDs by
+  enabling debug and hovering over the screen in the map editor.)
+
+### Collectable events
+- **Cassettes:**
+  - `collect cassette` - Triggered when any cassette is collected
+  - `collect chapter <n> cassette` - Triggered when the cassette in the specified chapter is collected
+  - `<n> total cassettes` - Triggered when a cassette is collected. `<n>` is the total number of cassettes collected in
+    the current file
+- **Heart Gems:**
+  - `collect heart` - Triggered when any heart gem is collected
+  - `collect chapter <n> heart` - Triggered when the heart gem in the specified chapter is collected
+  - `<n> total hearts` - Triggered when a heart gem is collected. `<n>` is the total number of heart gems collected in 
+    the current file
+- **Strawberries:**
+  - `collect strawberry` - Triggered when any strawberry is collected
+  - `<n> chapter strawberries` - Triggered when a total of `<n>` strawberries are collected in a chapter
+  - `<n> file strawberries` - Triggered when a total of `<n>` strawberries are collected in the file
+
+## Return to Map & Save and Quit
+
+Without the proper route file, both of these count as resetting a chapter. It's impossible for SwiftSplit to tell the 
+difference between a reset, return to map, or save and quit. To get around this, you can define in your route where
+leaving the chapter is *expected.* 
+
+Here's what the reset for the 1A might look like:
+```json
+"route": [
+    "enter chapter 1 # Start",
+    "5 > 6 # Crossing",
+    "!collect heart",
+    "!leave chapter",
+    "9 > 9b # Chasm",
+    "complete chapter 1"
+]
+```
+
+The reason we put `!collect heart` before `!leave chapter` is because any time that SwiftSplit is waiting for you to 
+leave the chapter *you can not automatically reset the run.* Any attempt to restart the run will just result in 
+progressing through the route. By putting the collect heart event before the leave chapter event we make sure that 
+SwiftSplit only starts waiting for the leave event right before we do it. 
+
+For restarting after collecting berries you'd want to have two events: one when you enter the room you'll save and quit
+in, and the next when you collect the berry:
+
+```json
+"route": [
+    "...",
+    "!a00 > a03",
+    "!collect strawberry",
+    "!leave chapter",
+    "..."
+]
+```
