Story mods

A story mod adds events to the original stages. On a given turn, when someone is shot down, when two characters fight, when Persuade is chosen and so on, it plays the lines you wrote, has characters join or leave, or sets story variables so that the original story afterwards takes another branch. The game decides when an event fires. You write only the conditions and what happens, and you need not know the original event tables. No original event is changed or pushed out.

Installing and managing packages is in Mod packages: installing and making them. Version 0.5.3 or later is needed.

The complete example is “Master Asia Lives”, with its source in config/recomp/mods/master-asia. On the Independence Army route’s “Death Match! Showdown on Lantau Island (Part 2)” and the OZ route’s “Fist of Despair and Sorrow (Part 2)”, once Domon has talked with Master Asia in battle he can persuade him. With 50 kills or more Master Asia withdraws and joins after the stage.

What a package holds

yourname.story/
  mod.json
  story/
    <any name>.json   story scripts, as many as you like
  data/
    pilots.json       numbers to change as well, if needed (see Number mods)

When the package is packed (tools/mods/pack.py), the story scripts in story/ are compiled into the form the game reads. A mistake is reported with the event and the item it is in.

Writing events

{
  "schema": "srw64.story.v1",
  "events": [
    {
      "id": "persuade",
      "scene": 129,
      "when": { "persuade": { "by": 4, "target": 18 } },
      "if": { "vars": { "131": 0 }, "kills": { "4": 50 } },
      "do": [
        { "say": 4, "text": { "ja": "「師匠！」", "zh-Hans": "“师父！”", "en": "“Master!”" } },
        { "say": 18, "mode": 2, "text": { "ja": "「……」", "zh-Hans": "“……”", "en": "“...”" } },
        { "leave": 18 },
        { "set": { "131": 3 } }
      ]
    },
    {
      "id": "joins",
      "scene": 129,
      "when": { "after": "end" },
      "if": { "fired": ["persuade"] },
      "do": [ { "join": { "pilot": 18, "unit": 27 } } ]
    }
  ]
}

Each event has:

By default each event fires once per stage. The game keeps track, in the suspend save too, so you need not set variables to stop a replay as the original events do.

Pilot and unit numbers are in the pilot and unit tables of Number mods.

when

When an original event is due at the same moment it runs first, and yours is looked at on the next check. Events after the opening, setup or ending cannot repeat.

if

When the character is not on the player’s roster, neither kills nor kills_below holds.

Success and failure lines. Write two events for the same moment with conditions that exclude each other, and the game picks the one that holds. In the example, enough kills means success and too few plays the refusal:

{ "id": "persuade", "when": { "persuade": { "by": 4, "target": 18 } },
  "if": { "vars": { "131": 0 }, "kills": { "4": 50 }, "not_fired": ["refused"] }, "do": [] },
{ "id": "refused", "when": { "persuade": { "by": 4, "target": 18 } },
  "if": { "vars": { "131": 0 }, "kills_below": { "4": 50 } }, "do": [] }

The refusal fires only once and the success needs not_fired: refused, so after a refusal neither holds in that stage. Persuade leaves the menu and the story goes as it was. To let the player try again, give the refusal "repeat": true and drop the success’s not_fired.

Across stages: flags

fired covers one stage and is cleared for the next. To let a later stage know what happened, write "set_flags": ["name"] on the event (lower-case letters, digits, _ and -, up to 32 characters). The flag is set when the event has run. Flags belong to your package alone and have nothing to do with the original story variables. They follow the suspend and intermission saves and are cleared only by a new game.

{ "id": "persuade", "scene": 129, "set_flags": ["persuaded"], "when": { "persuade": { "by": 4, "target": 18 } }, "do": [] },
{ "id": "comes-along", "scene": 81, "when": { "after": "opening" },
  "if": { "roster": { "pilots": [18] }, "flags": ["persuaded"] },
  "do": [ { "say": 18, "text": { "ja": "「ドモン、遅れを取るでないぞ！」", "en": "“Domon, don't fall behind!”" } } ] }

The roster is checked as well because the original story or another event may take him off the roster later. With the flag alone he would speak even when he is gone.

do

Lines. text must have ja. Other languages left out show the Japanese (Traditional Chinese falls back to Simplified). A line holds up to 200 characters and the reader pages it itself, so do not write <STOP>. Write the quotation marks yourself, as the original lines have them: 「」 in Japanese and Traditional Chinese, “ ” in Simplified Chinese and English. mode is how the original dialogue shows the line: on the map usually 0 for the player and 2 for the enemy, and on the world map 0 and 1 alternate top and bottom.

The level on joining follows the original rule, the stage’s base level (from the average of the player’s top 15). "level": {"offset": 3} adds to it or takes from it, and "level": {"like": 4} gives character 4’s level at the moment of joining. SP, abilities, skills and spirits come from the original by level. To change the base values use data/pilots.json (enemy characters often have no SP or spirits; the example adds SP).

Things to know

• Original events read only the original variables. To stop an original event or make it play another part, change the variable it checks. In the example, persuasion sets 131 = 3, and the original ending plays Master Asia’s farewell only when 131 is 1 or 2.
• A unit leaving (leave) does not fire the original shot-down event. What the original does after the defeat (in the example, Wong arriving and the victory condition opening up) your events must do themselves.
• Before moving a storyline to another stage, read that stage’s original events: which variable the conversation sets, what follows a defeat, and which variables the ending event plays which parts by. The example’s OZ-route events were adapted from scene 137’s.
• Flags are kept beside the saves (story-state/ in the saves/ folder), not in the save files themselves. Take a save to another emulator or delete that folder, and the flags are gone, so events across stages will not fire. Events within one stage are not affected.
• Story mods do not run in custom campaign stages (campaign/).

Checking and packing

python3 tools/mods/story.py compile story/master.json -o out.json

python3 tools/mods/pack.py yourname.story -o build/mods

The first compiles one story script so you can see the commands each event becomes. The second packs the package and checks it by the game’s rules. A package the game cannot read is reported in the log as SRW64_STORY_MOD_PROBLEM.

The repository’s docs/guide/story-mods/ folder has the full format and the scene table, which you can hand to an AI assistant to write story scripts from your ideas.