SaveGame handle for the save editor bindings #446

Closed
opened 2026-10-31 08:15:32 +01:00 by jqueuniet · 0 comments
Owner

Follow-up to #440 and #443. The save editor bindings pass the whole dump in and out:

  • each edit parses and re-serializes the full dump: 4.1 MB on DOS sksave0.dat, 3.0 MB of it tile chains;
  • calls taking graphics.dat re-parse it, and in wasm copy its 8.6 MB first;
  • in wasm, the 4 MB string also crosses the JS boundary in and out per call;
  • options are positional (language), so adding one breaks signatures.

Measured natively on sksave0.dat:

call time where it goes
save_to_json_full 10.5 ms the dump itself
save_inventory_clear_json("cursor") 8.7 ms JSON parse and re-serialize, for one slot
save_inventory_json 4.7 ms mostly parsing the dump

Proposal

A SaveGame handle (wasm class, opaque FFI Dm2SaveGame *, Python class) holding the decoded full save, edited in place.

Construction:

  • new SaveGame(bytes, dungeon, graphics) replaces the decode of save_to_json_full, with the same checks: a mismatched dungeon is refused, and the rebuild must be byte-exact.
  • SaveGame.fromJson(json, dungeon, graphics) loads a full dump.

dungeon is a DungeonFile and graphics a GraphicsArchive. Only the map info the save needs is kept from the dungeon. Methods needing graphics.dat take the GraphicsArchive per call, as DungeonFile does: a wasm object cannot borrow another across calls.

Methods, each with a trailing options object:

Method Options Replaces
toJson() — save_to_json_full output
toBytes(graphics) — save_from_json_full
gameplay() / setGameplay(json) — edits of the dump's gameplay section (15 KB), so champion fields no longer move the record stream
inventory(graphics) language (en) save_inventory_json
container(loc, graphics) language (en) save_container_json
moveItem(src, dst), swapItems(a, b), copyItem(src, dst), clearItem(loc) — save_inventory_*
putInContainer(src, container, graphics), takeFromContainer(container, index, dst, graphics) — save_container_put / save_container_take
createItem(dst, item, graphics) — save_item_create
previewItem(dst, item, graphics) language (en) save_item_preview
fieldLimits() — save_field_limits_json, the variant taken from the save

Edits return nothing, and a refused edit leaves the save unchanged.

GraphicsArchive gains the two calls that only read graphics.dat:

  • itemCatalog({language}), replacing item_catalog_json;
  • skillTitle(skill, level, {language}), replacing skill_title_json.

These stay free: save_to_json, save_from_json and save_info_json (self-contained, bytes only, nothing to cache), and skill_level and skill_experience_for_level (pure arithmetic).

Naming: SaveGame avoids clashing with dm2_saves::SaveFile and the dm2_save_* C exports.

PRs:

  1. The GraphicsArchive methods.
  2. SaveGame, additive.
  3. Removal of the replaced free functions.

Acceptance

  • Outputs identical to the current functions for the same arguments.
  • An edit followed by inventory() is measurably faster than the dump round trip in wasm (numbers in the PR).
  • A refused edit changes nothing, covered by tests.
  • Adding an option changes no signature.

Out of scope

Editing tile chains, i.e. items on the dungeon floor.

https://claude.ai/code/session_01SnENBXnZbhNNrojZT5jbJ7

Follow-up to #440 and #443. The save editor bindings pass the whole dump in and out: - each edit parses and re-serializes the full dump: 4.1 MB on DOS `sksave0.dat`, 3.0 MB of it tile chains; - calls taking `graphics.dat` re-parse it, and in wasm copy its 8.6 MB first; - in wasm, the 4 MB string also crosses the JS boundary in and out per call; - options are positional (`language`), so adding one breaks signatures. Measured natively on `sksave0.dat`: | call | time | where it goes | |---|---|---| | `save_to_json_full` | 10.5 ms | the dump itself | | `save_inventory_clear_json("cursor")` | 8.7 ms | JSON parse and re-serialize, for one slot | | `save_inventory_json` | 4.7 ms | mostly parsing the dump | ## Proposal A `SaveGame` handle (wasm class, opaque FFI `Dm2SaveGame *`, Python class) holding the decoded full save, edited in place. **Construction:** - `new SaveGame(bytes, dungeon, graphics)` replaces the decode of `save_to_json_full`, with the same checks: a mismatched dungeon is refused, and the rebuild must be byte-exact. - `SaveGame.fromJson(json, dungeon, graphics)` loads a full dump. `dungeon` is a `DungeonFile` and `graphics` a `GraphicsArchive`. Only the map info the save needs is kept from the dungeon. Methods needing `graphics.dat` take the `GraphicsArchive` per call, as `DungeonFile` does: a wasm object cannot borrow another across calls. **Methods,** each with a trailing options object: | Method | Options | Replaces | |---|---|---| | `toJson()` | — | `save_to_json_full` output | | `toBytes(graphics)` | — | `save_from_json_full` | | `gameplay()` / `setGameplay(json)` | — | edits of the dump's `gameplay` section (15 KB), so champion fields no longer move the record stream | | `inventory(graphics)` | `language` (`en`) | `save_inventory_json` | | `container(loc, graphics)` | `language` (`en`) | `save_container_json` | | `moveItem(src, dst)`, `swapItems(a, b)`, `copyItem(src, dst)`, `clearItem(loc)` | — | `save_inventory_*` | | `putInContainer(src, container, graphics)`, `takeFromContainer(container, index, dst, graphics)` | — | `save_container_put` / `save_container_take` | | `createItem(dst, item, graphics)` | — | `save_item_create` | | `previewItem(dst, item, graphics)` | `language` (`en`) | `save_item_preview` | | `fieldLimits()` | — | `save_field_limits_json`, the variant taken from the save | Edits return nothing, and a refused edit leaves the save unchanged. **`GraphicsArchive` gains** the two calls that only read `graphics.dat`: - `itemCatalog({language})`, replacing `item_catalog_json`; - `skillTitle(skill, level, {language})`, replacing `skill_title_json`. **These stay free:** `save_to_json`, `save_from_json` and `save_info_json` (self-contained, bytes only, nothing to cache), and `skill_level` and `skill_experience_for_level` (pure arithmetic). **Naming:** `SaveGame` avoids clashing with `dm2_saves::SaveFile` and the `dm2_save_*` C exports. **PRs:** 1. The `GraphicsArchive` methods. 2. `SaveGame`, additive. 3. Removal of the replaced free functions. ## Acceptance - Outputs identical to the current functions for the same arguments. - An edit followed by `inventory()` is measurably faster than the dump round trip in wasm (numbers in the PR). - A refused edit changes nothing, covered by tests. - Adding an option changes no signature. ## Out of scope Editing tile chains, i.e. items on the dungeon floor. https://claude.ai/code/session_01SnENBXnZbhNNrojZT5jbJ7
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jqueuniet/dm2-tools#446
No description provided.