authoring_routes.md

Route JSON

Routes are configured using a JSON file and use "events" generated by SwiftSplit.

Here's an example for Old Site Any%:

{
    "useFileTime": false,
    "reset": "leave 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 section for more on that.

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:

• 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 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).

Events

Leave events are triggered by restarting the chapter, returning to the map, or using "Save and Quit"

Chapter start/end events

• enter chapter - Triggered when any chapter is entered
• leave chapter - Triggered when leaving any chapter
• complete chapter - Triggered when any chapter is completed
• enter chapter <n> - Triggered when chapter <n> is entered
• leave chapter <n> - Triggered when leaving chapter <n>
• complete chapter <n> - Triggered when chapter <n> is completed
• A-side specific:
  • enter a-side - Triggered when any A-side is entered
  • leave a-side - Triggered when leaving any A-side
  • complete a-side - Triggered when completing any A-side
  • 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 - Triggered when any B-side is entered
  • leave b-side - Triggered when leaving any B-side
  • complete b-side - Triggered when completing any B-side
  • 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 - Triggered when any C-side is entered
  • leave c-side - Triggered when leaving any C-side
  • complete c-side - Triggered when completing any C-side
  • 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

The ExtendedSplits.zip file included in this repository is an Everest mod that exposes additional data to SwiftSplit, in particular it provides SwiftSplit with the full area SID

Extended Events (Everest)

Chapter numbers for custom maps are dynamically allocated by Everest, so if you want area-specific events (enter chapter 1 vs. enter chapter) you can add the ExtendedSplits mod, which SwiftSplit will use to emit variants of all the relevant events using the Area SID instead of area number.

• enter chapter '<sid>' - Triggered when the given chapter is entered
• leave chapter '<sid>' - Triggered when leaving the given chapter
• complete chapter '<sid>' - Triggered when the given chapter is completed
• A-side specific:
  • enter a-side '<sid>' - Triggered when the given chapter's A-side is entered
  • leave a-side '<sid>' - Triggered when leaving the given chapter's A-side
  • complete a-side '<sid>' - Triggered when the given chapter's A-side is completed
• B-side specific:
  • enter b-side '<sid>' - Triggered when the given chapter's B-side is entered
  • leave b-side '<sid>' - Triggered when leaving the given chapter's B-side
  • complete b-side '<sid>' - Triggered when the given chapter's B-side is completed
• C-side specific:
  • enter c-side '<sid>' - Triggered when the given chapter's C-side is entered
  • leave c-side '<sid>' - Triggered when leaving the given chapter's C-side
  • complete c-side '<sid>' - Triggered when the given chapter's C-side is completed
• Collectables
  • collect chapter '<sid>' cassette - Triggered when the cassette in the specified chapter is collected
  • collect chapter '<sid>' heart - Triggered when the heart gem in the specified chapter is collected

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. Generally you'll want to define an event that happens right before you leave, then the leave event. This ensures that resetting any time outside that window will trigger a proper reset.

Here's what the RTM for the 1A heart might look like:

"reset": "leave chapter",
"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 reset the run. Any attempt to reset the run will just result in progressing through the route.