Skip to main content

Module presentation

dotzuki_engine::overworld

Module presentation 

Source
Expand description

Overworld presentation-state machines — pure, frame-counted animation logic for the visual effects classic JRPGs implement as blocking animation routines. The renderer reads these each frame; the game’s update loop ticks them once per frame (freezing gameplay, mirroring the originals’ busy-wait structure).

Everything here is game-agnostic: states depend only on Direction, injected tuning data (spin facing order, elevator shake parameters), and frame counters. Sound cues are returned as typed enums (TeleportSpinSfx, EnterMapSpinSfx, ElevatorShakeSfx, ShipDepartureSfx); the game maps them to its own audio ids.

Covered effects:

Structs§

BoulderDustState
The 2×2 smoke-puff block kicked up when a pushed boulder slides one tile. The block is written once, anchored to the player’s map tile at push time (the animation outlives the push lockout, so the anchor must not track the player afterward), then runs BOULDER_DUST_STEPS steps of BOULDER_DUST_STEP_FRAMES frames each. Every step the block drifts 1px against the boulder’s slide direction and the sprite palette toggles, flashing two gray shades.
ElevatorShakeParams
Tuning for the elevator rumble: how many up/down iterations and how far the background scrolls each iteration.
ElevatorShakeState
Frame-driven elevator rumble: scrolls the background up/down by ±pixel_offset, iterations × 2 frames, a rattle cue each iteration, then a single arrival ding.
EnterMapSpinState
State of the arrival spin animation.
FishingAnimState
Frame-driven state of the rod animation. Constructed when a rod use passes the game’s eligibility gates; ticked once per frame by the update loop (which freezes gameplay while it runs); when Self::is_done the result text is queued.
ShipDepartureState
Frame-driven state of the ship-departure cutscene. Constructed when the game’s departure script fires; ticked once per frame by the update loop (freezing gameplay, matching the classic blocking structure). The renderer reads the scroll offset and puff positions; the game applies the ship erase + warp removal at the erase transition.
TeleportSpinState
State of the teleport / escape-item spin-out animation.
TileAnimState
Per-frame water/flower background-tile animation.

Enums§

ElevatorShakeSfx
Sound cues ElevatorShakeState::tick can request.
EnterMapSpinPhase
Phase of the arrival spin, the counterpart of TeleportSpinState: after a teleport-class warp arrival, the player descends from off the top of the screen, then spins in place.
EnterMapSpinSfx
Sound cues EnterMapSpinState::tick can request.
FishingAnimPhase
Phase of the player-side fishing rod animation.
ShipDeparturePhase
Phase of the ship-departure cutscene.
ShipDepartureSfx
Sound cues ShipDepartureState::tick can request.
TeleportSpinPhase
Phase of the leave-map spin animation.
TeleportSpinSfx
Sound cues TeleportSpinState::tick can request.
TileAnimKind
Which background tiles a tileset animates (the classic water-rotation / flower-frame system).

Constants§

BOULDER_DUST_STEPS
Number of animation steps of the boulder-dust puff.
BOULDER_DUST_STEP_FRAMES
Frames each dust step lasts.
ENTER_MAP_SPIN_DOWN_FRAMES
Total frames of the spin-down phase: 5 spins with 3-frame delays between (the last step ends immediately).
ENTER_MAP_SPIN_DOWN_STEPS
Number of 16px spin-down steps (from offscreen above to the standing position).
ENTER_MAP_SPIN_DOWN_STEP_DELAY
Frames between spin-down steps.
ENTER_MAP_SPIN_DOWN_STEP_PIXELS
Pixels the player sprite descends per spin-down step.
ENTER_MAP_SPIN_IN_PLACE_FRAMES
Total frames of the arrival spin-in-place phase: 8 spins whose delays are 0,1,…,7 (8 + (1+2+…+7)).
FISHING_ANIM_FRAMES
Total frames of the whole animation: 10 + 100 + 30 + 60.
FISHING_BUBBLE_FRAMES
Frames the “!” emotion bubble stays up.
FISHING_CAST_DELAY_FRAMES
Initial pause before the rod appears.
FISHING_ROD_OUT_FRAMES
Frames the rod stays out waiting for a bite.
FISHING_SHAKE_ITERATIONS
Shake iterations on a bite.
FISHING_SHAKE_STEP_FRAMES
Frames per shake iteration.
FLASH_WHITE_FRAMES
Frames of the all-palettes-white flash when a dark area is lit up.
SHIP_DEPARTURE_ERASE_FRAMES
Final pause after the ship is erased.
SHIP_DEPARTURE_INITIAL_PAUSE_FRAMES
Initial pause of the departure cutscene (after the departure music starts).
SHIP_DEPARTURE_ITERATION_FRAMES
Frames per iteration: 16 smoke-drift substeps × an 8-frame delay each.
SHIP_DEPARTURE_PUFF_DRIFT_PX_PER_SUBSTEP
Smoke-puff drift: every 8-frame substep all live puffs drift +2px right.
SHIP_DEPARTURE_PUFF_SPACING_PX
Smoke-puff spawn spacing: a new 2×2 puff block is emitted above the smokestack every iteration, 16px left of the previous one.
SHIP_DEPARTURE_PUFF_START_SCREEN_X
The first puff’s screen X at departure start.
SHIP_DEPARTURE_SCROLL_ITERATIONS
View-scroll iterations.
SHIP_DEPARTURE_SCROLL_PX_PER_ITERATION
Pixels the view scrolls east per iteration (the ship slides left).
SHIP_DEPARTURE_SMOKESTACK_TILE_X
The smokestack’s map position (tile units) — the puffs’ world anchor.
SHIP_DEPARTURE_SMOKESTACK_TILE_Y
SHIP_DEPARTURE_SUBSTEPS_PER_ITERATION
Substeps per iteration.
SHIP_DEPARTURE_SUBSTEP_FRAMES
Frames per drift substep.
SHIP_DEPARTURE_TOTAL_FRAMES
Total frames of the whole cutscene: 120 + 3 + 8×128 + 120.
SHIP_DEPARTURE_WATER_FILL_FRAMES
The water-fill commit (pushing the screen tile buffer’s water fill to the background). Kept for frame fidelity; the erase phase below is the visible ship removal.
SPIN_IN_PLACE_FRAMES
Total frames of the spin-in-place phase: 16+15+…+1.
SPIN_POST_DELAY_FRAMES
Extra frames after the spin-up when not on a warp pad.
SPIN_UP_STEPS
Number of 16px spin-up steps.
SPIN_UP_STEP_DELAY
Frames between spin-up steps.
SPIN_UP_STEP_PIXELS
Pixels the player sprite rises per spin-up step.