liuyanghejerry/open-pokered/save-construction

save-construction — Building Save States

Three layers, pick per goal:

The assistant has no save-file propose tool — produce JSON in chat for the user to import, or walk them through the CLI below.

Layer 1: the editor Save tab

The Save activity edits a simplified snapshot (SaveDataSnapshot): player (name, rival, mapName, x/y, facing, money, coins, play time), badges (8 booleans, Boulder→Earth order), party (up to 6 × {species, level, currentHp, maxHp, moves[4], nickname}), items ({name, quantity}), and flags (name → bool). Import JSON accepts that shape; Export downloads it. Pair it with the Playtest activity to spawn the game at that state.

Layer 2: the full JSON snapshot

The game binary's own format (mirrors SaveData in crates/pokered-core/src/save/):

# .sav → editable JSON
cargo run --release --bin pokered-app -- export-snapshot --input pokered.sav -o snapshot.json
# import-snapshot dumps a .sav the same way (input required); there is no
# JSON → .sav write-back — load the JSON with `run --snapshot` below.
cargo run --release --bin pokered-app -- run --snapshot snapshot.json --skip-intro --warp PalletTown,10,14

Key fields:

• `game_data.position` — {map_id, x, y, x_block, y_block}; `player_direction` 4=Down 8=Up 2=Left 1=Right (original PLAYER_DIR bitmask, not sprite facing).
• `game_data.obtained_badges` — u8 bitfield, bit0=Boulder … bit7=Earth. (Badges are NOT event flags.)
• `game_data.player_money` (≤999999), `player_coins`, `game_data.bag.items` as [[itemId, qty], …] where itemId is the ItemId name string ("MasterBall", "RareCandy", … — the same ids as crates/pokered-data/data/items/*.json; the numeric byte order in data/items/item_list.json is 1=MasterBall, 2=UltraBall, 6=Bicycle, 40=RareCandy, with TMs at 0xC9+ and HMs at 0xC4+).
• `party` — up to 6 full Pokémon records: species (PascalCase), level, hp/max_hp/attack/defense/speed/special, type1/type2, moves (4 MoveId names — empty slots are "None"), pp[4], dv_bytes[2] (Atk/Spd high nybbles, Def/Spc low), stat_exp[5], total_exp, status, ot_id (0 = own), plus charmap-encoded nickname/ot_name byte arrays (0x50 = padding; see pokered_data::charmap).
• `game_data.event_flags` — the story flags: a 320-byte bitset (507 named flags in crates/pokered-data/src/event_flags.rs; the enum value IS the bit index). Flip bits, don't append:

import json
save = json.load(open('snapshot.json'))
flags = bytearray(save["game_data"]["event_flags"])
bit = 0x025                        # e.g. EVENT_GOT_POKEDEX — look the value up in event_flags.rs
flags[bit >> 3] |= 1 << (bit & 7)  # byte = bit >> 3, mask = 1 << (bit & 7)
save["game_data"]["event_flags"] = list(flags)
json.dump(save, open('snapshot.json', 'w'))

Common progression flags: EVENT_GOT_STARTER, EVENT_GOT_POKEDEX, EVENT_BEAT_BROCK/MISTY/LT_SURGE/…, EVENT_GOT_SS_TICKET, EVENT_BEAT_*_GYM_TRAINER_*. The enum in event_flags.rs is the source of truth.

Layer 3: live surgery via the debug server

cargo run --release --bin pokered-app --features debug-server -- run --headless --debug-port 9000 --skip-intro

JSON-lines over TCP (scripts/debug_drive.py is a minimal client):

from debug_drive import DebugClient
d = DebugClient(9000)
d.cmd(cmd="give_pokemon", species="Mewtwo", level=70)
d.cmd(cmd="give_item", item="MASTER_BALL", quantity=3)
d.cmd(cmd="set_flag", name="EVENT_BEAT_BROCK", value=True)
d.cmd(cmd="warp", map="CeruleanCity", x=14, y=8)
d.cmd(cmd="save")                      # persist from inside the running game
print(d.cmd(cmd="get_state")["data"])  # position, party, flags, dialogue, battle phase

Recipe: a save that exercises NEW content

To test-drive a new map / species / trainer (the other skills):

1. Export a template snapshot (or take one from a playthrough near the target).
2. Set position to a map adjacent to the new one (or warp in-game with --warp <NewMap>,x,y — the new map needs its Rust registration done, see the new-map skill; in the editor Playtest the runtime override covers it without a rebuild).
3. Put the new species in party (or plan to give_pokemon it live) with coherent stats: recompute max_hp/stats for its level from its baseStats, set total_exp on its growthRate curve, pp from the moves' base PP.
4. Set only the event flags your test needs — prefer the debug server's set_flag for iteration speed.

Gotchas

• script_flags was removed from SaveData — old snapshots carrying it still load, but those edits are silently dropped. Named flags = event_flags bitset only; runtime-only __OBJ_HIDDEN_*/__OBJ_SHOWN_* keys live outside the save (pokered.script_flags.json next to the native app).
• event_flags must stay a 320-byte array — the loader sizes it exactly (EVENT_FLAGS_SIZE).
• A party mon's hp may not exceed max_hp; keep moves/pp lengths at 4.
• charmap name fields are byte arrays, not strings — decode with pokered_data::charmap if you need to read them.