Field batch 1 readability follow-ups (bridge decision tree, bridge-shaped API, accessor names) #46

New issue

Open

opened 2026-11-03 02:56:37 +00:00 by Gatchan · 0 comments

Gatchan commented

2026-11-03 02:56:37 +00:00

Owner

From the independent readability review of PR #35 (2026-11-03), items left for later (not blocking the merge):

UpdateObjFrame bridge repeats the game's decision tree (core/port/field_bridge.c ~264-290): use a bridge-local path enum + one switch; factor the repeated entry checks (8-bit A with B=0, 16-bit indexes, field pages) into one prv_field_entry_ok(). Watch the bridge:game ratio (#38 should cut it).
Public API shaped by the bridge: field_objects.h exports 8 functions, the game needs 2; field_scroll_speed likewise. Group them under a "helpers also used by the bridge" comment or accept as convention; field_object_walk_step int + out-parameter could be one return value.
Accessor names from the disassembly vocabulary (re/ram_map.toml): field_bg_scroll_carry -> scroll overflow, field_objects_map_ptr -> map cell, scratch accessors (field_obj_frame_facing_base, field_obj_frame_anim_offset, field_scroll_step) get a scratch_ prefix so game code does not use them as state.

From the independent readability review of PR #35 (2026-11-03), items left for later (not blocking the merge): 1. `UpdateObjFrame` bridge repeats the game's decision tree (`core/port/field_bridge.c` ~264-290): use a bridge-local path enum + one `switch`; factor the repeated entry checks (8-bit A with B=0, 16-bit indexes, field pages) into one `prv_field_entry_ok()`. Watch the bridge:game ratio (#38 should cut it). 2. Public API shaped by the bridge: `field_objects.h` exports 8 functions, the game needs 2; `field_scroll_speed` likewise. Group them under a "helpers also used by the bridge" comment or accept as convention; `field_object_walk_step` int + out-parameter could be one return value. 3. Accessor names from the disassembly vocabulary (`re/ram_map.toml`): `field_bg_scroll_carry` -> scroll overflow, `field_objects_map_ptr` -> map cell, scratch accessors (`field_obj_frame_facing_base`, `field_obj_frame_anim_offset`, `field_scroll_step`) get a `scratch_` prefix so game code does not use them as state.

Gatchan added this to the Phase 2 - field ports milestone

2026-11-03 02:56:37 +00:00

Gatchan added the

task

tools

labels

2026-11-03 02:56:37 +00:00

Gatchan referenced this issue

2026-11-03 07:27:28 +00:00

Field ports batch 1: WRAM-only leaves (timers, object order, scroll, object frames) #32