wasm: read and set the party position #483
Labels
No labels
area/ci-release
area/cli
area/docs
area/dungeon
area/ftl
area/graphics
area/gui
area/music
area/saves
area/tooling
port/amiga
port/dos
port/fm-towns
port/mac
port/pc98
port/sega-cd
priority/high
priority/low
priority/medium
type/bug
type/chore
type/docs
type/feature
type/research
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
jqueuniet/dm2-tools#483
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
SaveFileFull::party_positionandset_party_positionexist;SaveGameexposes neither.Wanted:
SaveGame.partyPosition()→{map, x, y, dir}andSaveGame.setPartyPosition(map, x, y, dir), throwing on a cell the party cannot stand on (wall, closed door, pit…), so callers need no walkability rules of their own. The web editor moves the party by clicking a cell of the live map, on any level.Facing caveat from
set_party_position: a newdirdoes not rotate the rank layout as an in-game turn does. A facing picker needs the ranks rotated with it, or the binding should rotate them.Design
Facing
The caveat on
set_party_positionis wrong. Each champion record holds its facing and its cell in the 2×2 layout: bytes0x1c(absdir) and0x1d(partypos), 2 bits each in the champion mask (DOS, Mac and Beta). An in-game turn adds the turn to both on every champion (skprojectROTATE_SQUAD, dm2macchamp_set_party_direction); writingplayer_diralone left them unturned, hence the flipped formation the oracle showed.set_party_positionwill rotate both bytes of each party member by(dir − player_dir) & 3. That fixes the CLI too.docs/formats/save-object-editability.mdgets its caveat corrected.Where the party may stand
Checked on the live dungeon (#482), so door states and creatures are current. Refused:
The first four rows are the engine's step rule (dm2mac
dungeon_square_blocks_movement, the pit fall test).My call on creatures: the engine lets the party share a tile with a creature flagged not solid (
0x8000in the executable's creature table, reached through graphics.dat). dm2-tools has no copy of that table, so every creature refuses. This costs ghost-type tiles; porting the table can lift it later.API
dm2-saves:SaveDump::party_position() -> (usize, u16, u16, Direction)andSaveDump::set_party_position(map_info, map, x, y, dir) -> Result<(), PartyEditError>: bounds, the tile rules, then the rotation and the position write. NewPartyEditError::Unstandable { map, x, y, why }.SaveFileFull::set_party_positiongains the rotation only; the tile rules need the live image, which works on a dump.dm2-convert:SaveGame::party_position()→{"map","x","y","dir"}JSON,set_party_position(map, x, y, dir); full saves only.partyPosition()/setPartyPosition(map, x, y, dir), FFI, Python.Tests
Party position for SaveGame Implementation Plan
Goal:
SaveGame.partyPosition()/setPartyPosition(map, x, y, dir), refusing tiles the party cannot stand on and turning the formation with the facing.Architecture: dm2-saves owns the rules: a champion turn helper shared by
SaveFileFullandSaveDump, and a standability check on the live dungeon image (SaveDump::live_dungeon, #482). dm2-convert wraps it onSaveGame; wasm, FFI and Python bind it.Tech Stack: Rust workspace, wasm-bindgen, cbindgen header, Python ctypes.
Spec: issue #483 and its design comment (#483 (comment)), local copy
scratch/483-party-position-design.md.Global Constraints
0x1c, cell at0x1d, values0..=3, same offsets for everyChampionLayout.(dir − player_dir) & 3, added mod 4 to both bytes of every champion record.{"map":u8,"x":u16,"y":u16,"dir":u8}, dir 0 N, 1 E, 2 S, 3 W.SaveGamerefuses aslevelLayoutdoes.cargo t; music untouched, socargo t-nomusicduring tasks.Review Focus
0x03).set_door_statebecomes standable.Task 1: Champion turn
Files:
crates/dm2-saves/src/party_edit.rs(set_party_position, doc comment)docs/formats/save-object-editability.md(§"Engine-behaviour caveats", first bullet)crates/dm2-saves/tests/party_position.rs(new)Interfaces:
Produces:
pub(crate) fn turn_champion(raw: &mut [u8], turn: u8)inparty_edit.rs(addsturnmod 4 toraw[0x1c]andraw[0x1d], each kept in0..=3). Needs apub(crate)mutable byte accessor onChampion(as_bytes_mut) if none exists.Step 1: Write the failing tests (DOS
sksave0.dat, and Mac first save; skip when fixtures absent,fixture_bytes!style)quarter_turn_rotates_formation: record(dir, cell)of each champion;set_party_positionto the current tile facing(d + 1) & 3; each champion's bytes are(dir + 1) & 3,(cell + 1) & 3.turn_back_is_identity: turn by 1 then back to the original facing; champion raw bytes equal the originals.same_facing_keeps_champions: same tile and facing; champion bytes unchanged.Step 2:
cargo test --profile fast -p dm2-saves --test party_position— Expected: the first two FAIL (bytes unchanged).Step 3: Implement
turn_champion; call it on every champion inSaveFileFull::set_party_positionbefore writingplayer_dir. Replace the doc comment's caveat with one line on the turn; rewrite the doc bullet: champion records keep facing and cell (0x1c,0x1d), the setter turns them as an in-game turn does. Drop the "deferred" pointer.Step 4: same command — Expected: PASS.
Step 5: commit
fix(saves): party facing turns the formation.Task 2: Standable tiles and
SaveDumppositionFiles:
crates/dm2-saves/src/party_edit.rscrates/dm2-saves/tests/party_position.rsInterfaces:
Consumes:
turn_champion;SaveDump::live_dungeon(&DungeonMapInfo) -> Result<Vec<u8>, JsonError>;Dungeon::parse,map_bodies[m].tile_at(x, y),Tile::decoded() -> TileAttr,Dungeon::iter_objects_on_tile,Oid::category.Produces:
PartyEditError::Unstandable { map: usize, x: u16, y: u16, why: &'static str }—"map {map} ({x},{y}): the party cannot stand on {why}";why∈"a wall","a map exit","a closed door","a closed trick wall","an open pit","stairs","an open teleporter","a creature".PartyEditError::Dump(JsonError)(#[from]) for live-image failures.impl SaveDump { pub fn party_position(&self) -> (usize, u16, u16, Direction); pub fn set_party_position(&mut self, map_info: &DungeonMapInfo, map: usize, x: u16, y: u16, dir: Direction) -> Result<(), PartyEditError> }— bounds asSaveFileFull, then the tile rules, then the turn on eachgameplay.champions[i].raw(base64 decode,turn_champion, encode), thensavegamebufferfields. A refusal leaves the dump unchanged.Step 1: Write the failing tests on the DOS
sksave0dump; each finds its tile by scanning the live image of the party's map (else any map) for the first tile matching the kind, skipping the test's assertion with a message if none exists:refuses_wall,refuses_closed_door(state 4),refuses_open_pit,refuses_stairs,refuses_open_teleporter,refuses_creature_tile— eachErr(Unstandable { why, .. })with the expectedwhy, and the dump's position and champions unchanged.opened_door_is_standable:set_door_stateopen on a closed door (astests/live_dungeon.rs::door_state_shows), thenset_party_positionthere succeeds.moves_to_floor: first empty floor tile;party_position()reads back(map, x, y, dir).dump_turns_formation: same assertions asquarter_turn_rotates_formation, on the dump.Step 2:
cargo test --profile fast -p dm2-saves --test party_position— Expected: compile FAIL (noSaveDump::set_party_position).Step 3: Implement.
fn standable(dungeon: &Dungeon, map, x, y) -> Result<(), &'static str>private inparty_edit.rs, onematchonTileAttrplus the creature scan.Step 4: same command — Expected: PASS.
Step 5: commit
feat(saves): party position on a dump, refusing unstandable tiles.Task 3:
SaveGameparty positionFiles:
crates/dm2-convert/src/save.rs,crates/dm2-convert/src/error.rscrates/dm2-convert/tests/save_game.rsInterfaces:
Consumes: Task 2's
SaveDumpmethods.Produces:
SaveGame::party_position(&self, _: &PositionOptions) -> Result<String, ConvertError>(position JSON) andSaveGame::set_party_position(&mut self, map: u8, x: u16, y: u16, dir: u8, _: &PositionOptions) -> Result<(), ConvertError>;PositionOptionsempty, asEditOptions.ConvertError::PartyEdit(#[from] PartyEditError).dir > 3→ConvertErrorviaPartyEditError(addBadDirection(u8)).Step 1: Write the failing tests:
party_position_round_trips(set to a floor tile, read back JSON,to_bytesthenSaveGame::newagain reads the same),party_position_refuses_wall,limited_save_refuses_party_position(both methods).Step 2:
cargo test --profile fast -p dm2-convert --test save_game party_position— Expected: compile FAIL.Step 3: Implement;
self.context()?first in both, aslevel_layout. Add to the module diagram line.Step 4: same command — Expected: PASS.
Step 5: commit
feat(convert): SaveGame party position.Task 4: Bindings
Files:
crates/dm2-wasm/src/wasm.rs,crates/dm2-wasm/README.md,crates/dm2-ffi/src/lib.rs,crates/dm2-ffi/include/dm2_tools.h,crates/dm2-ffi/tests/abi.rs,bindings/python/…(same files as #482'slevel_layout),bindings/python/tests/test_roundtrip.py,CHANGELOG.mdcrates/dm2-ffi/tests/abi.rs,test_roundtrip.pyInterfaces:
Produces: wasm
partyPosition(options?) -> string,setPartyPosition(map, x, y, dir, options?); FFIdm2_save_game_party_position(s, options, options_len) -> Dm2Buffer,dm2_save_game_set_party_position(s, map: u8, x: u16, y: u16, dir: u8, options, options_len) -> Dm2Buffer(empty on success, error buffer otherwise, as the existing setters); PythonSaveGame.party_position() -> dict,set_party_position(map, x, y, dir).Step 1: Write the failing tests: abi — read, set to the read position with
dirturned, read back; wall refused; nulls. Python — same read/set/read back and aDm2Erroron a wall.Step 2:
cargo test --profile fast -p dm2-ffianduv run --no-project --with pytest pytest bindings/python(envDM2_FFI_LIB=target/release/libdm2_ffi.so PYTHONPATH=bindings/python) — Expected: FAIL.Step 3: Implement; regenerate the header through
tests/header.rs's cbindgen as in #482; README row; CHANGELOG Unreleased → AddedSaveGame.partyPosition/setPartyPosition(#483) and Fixed: facing turns the formation.Step 4: same commands, plus wasm32
cargo check,cargo clippy --workspace -- -D warnings,cargo doc— Expected: PASS / clean.Step 5: commit
feat(bindings): SaveGame.partyPosition and setPartyPosition.