Feature: deferred board rebuild + BFS movement path animation

Units now animate before their nodes are rebuilt:

Deferred rebuild
- _schedule_rebuild(state, delay) uses a Tween to hold off _rebuild_units
  until animations finish; a new state cancels and replaces the pending rebuild
- POST_ANIM_SECS (1.2s) delay for attack / damaged / dying one-shots
- Hand and HUD update immediately; only the board is delayed

BFS movement animation
- _bfs_path() does 4-directional BFS avoiding other units' old positions
- _animate_unit_move() tweens the StaticBody3D through each grid step
  (EASE_IN_OUT / TRANS_SINE, 0.28s per cell) while playing the Moving loop
- Returns to Idle automatically when the tween finishes
- rebuild delay = max(move duration, POST_ANIM_SECS if damage played)
- Model load callback skips position reset if a move tween owns the body

Housekeeping
- _play_damage_animations now returns bool (triggered any anim?)
- _update_prev_state() replaces HP/pos tracking that was in _rebuild_units
- _rebuild_units kills all in-flight move tweens before destroying nodes

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
This commit is contained in:
dingo
2026-03-15 19:22:50 -04:00
co-authored by Claude Happy
parent 038f736926
commit f524cb9782
+177 -20
View File
@@ -156,7 +156,18 @@ var _unit_def_ids : Dictionary = {} # instanceId → card definition ID string
# ── Animation / facing state ───────────────────────────────────────────────────
var _local_is_p1 : bool = false # true when Auth.user_id == playerOneAccountId
var _prev_unit_hp : Dictionary = {} # instanceId → int, HP from last rebuild
var _prev_unit_hp : Dictionary = {} # instanceId → int, HP snapshot for damage detection
var _prev_unit_pos: Dictionary = {} # instanceId → Vector2i, position snapshot for move detection
var _move_anims : Dictionary = {} # instanceId → Tween (active movement tweens)
# Delayed rebuild: when animations need time to play we don't destroy unit nodes immediately.
var _pending_rebuild : Dictionary = {} # latest state waiting for the delayed rebuild
var _rebuild_tween : Tween = null
## Seconds per grid step when animating unit movement along the BFS path.
const MOVE_STEP_SECS : float = 0.28
## How long to hold after one-shot animations (attack / damaged / dying) before rebuilding.
const POST_ANIM_SECS : float = 1.2
## Animation name aliases: maps the canonical lower-case action to fallback track names.
## The AnimationPlayer track list is matched case-insensitively against each entry.
@@ -533,12 +544,19 @@ func _update_tile_affinity(x: int, y: int, affinity: String) -> void:
# ── Unit meshes ───────────────────────────────────────────────────────────────
func _rebuild_units(state: Dictionary) -> void:
# Kill any in-flight movement tweens before destroying nodes.
for iid : String in _move_anims:
var t := _move_anims[iid] as Tween
if t != null: t.kill()
_move_anims.clear()
for c in _units_root.get_children(): c.queue_free()
_unit_meshes.clear()
_unit_bodies.clear()
_anim_players.clear()
_unit_def_ids.clear()
_prev_unit_hp.clear()
# _prev_unit_hp and _prev_unit_pos are updated in _update_prev_state,
# called immediately in _on_state_updated — do NOT clear them here.
var my_id := Auth.user_id
for player: Dictionary in state.get("players", []):
var is_mine : bool = str(player.get("accountId", "")).to_lower() == my_id.to_lower()
@@ -549,12 +567,6 @@ func _rebuild_units(state: Dictionary) -> void:
for unit: Dictionary in player.get("field", []):
if unit.get("position") != null:
_add_unit_mesh(unit, color, not is_mine)
# Store HP for damage detection on next state update.
for unit: Dictionary in ([arch] + player.get("field", [])):
if unit.is_empty(): continue
var iid := str(unit.get("instanceId", ""))
if not iid.is_empty():
_prev_unit_hp[iid] = int(unit.get("currentHealth", 0))
func _add_unit_mesh(unit: Dictionary, team_color: Color, is_enemy: bool = false) -> void:
@@ -654,9 +666,9 @@ func _add_unit_mesh(unit: Dictionary, team_color: Color, is_enemy: bool = false)
model_node.rotation_degrees = Vector3(0, 180, 0)
# Position model so its local origin sits at the body's position.
# Models should be authored with their base (foot) at y = 0.
# Adjust the body back down so the model base lands on the tile surface.
b.position = wp + Vector3(0, 0.5, 0)
# Skip reset if a move tween is driving this body — it controls position.
if not _move_anims.has(iid):
b.position = wp + Vector3(0, 0.5, 0)
b.add_child(model_node)
_unit_meshes[iid] = model_node
@@ -758,10 +770,11 @@ func _play_unit_anim(iid: String, action: String, loop: bool = false) -> void:
## Detect HP decreases and unit deaths vs previous state, and fire animations.
## Called just before _rebuild_units so animations play on the existing nodes.
func _play_damage_animations(state: Dictionary) -> void:
## Returns true if any animation was triggered (used to decide rebuild delay).
func _play_damage_animations(state: Dictionary) -> bool:
if _prev_unit_hp.is_empty():
return
return false
var played := false
var seen_iids : Dictionary = {}
for player: Dictionary in state.get("players", []):
for unit: Dictionary in ([player.get("archSpirit", {})] + player.get("field", [])):
@@ -772,10 +785,145 @@ func _play_damage_animations(state: Dictionary) -> void:
seen_iids[iid] = true
if new_hp < old_hp:
_play_unit_anim(iid, "damaged")
played = true
# Units that vanished this update → play dying.
for iid: String in _prev_unit_hp:
if not seen_iids.has(iid):
_play_unit_anim(iid, "dying")
played = true
return played
## Update _prev_unit_hp and _prev_unit_pos from the given state snapshot.
## Call immediately when a new state arrives so the next state update has
## correct baselines, independent of when the delayed rebuild fires.
func _update_prev_state(state: Dictionary) -> void:
_prev_unit_hp.clear()
_prev_unit_pos.clear()
for player: Dictionary in state.get("players", []):
var arch := player.get("archSpirit", {})
for unit: Dictionary in ([arch] + player.get("field", [])):
if unit.is_empty(): continue
var iid := str(unit.get("instanceId", ""))
if iid.is_empty(): continue
_prev_unit_hp[iid] = int(unit.get("currentHealth", 0))
var pd = unit.get("position")
if pd is Dictionary and not (pd as Dictionary).is_empty():
_prev_unit_pos[iid] = Vector2i((pd as Dictionary).get("x", 0),
(pd as Dictionary).get("y", 0))
## 4-directional BFS on the game grid.
## blocked: Dictionary[Vector2i → true] of impassable tiles;
## the destination 'to' is always reachable regardless.
## Returns the path steps NOT including 'from', including 'to'.
## Falls back to [to] if no path found (shouldn't happen on a connected grid).
func _bfs_path(from: Vector2i, to: Vector2i, blocked: Dictionary) -> Array[Vector2i]:
if from == to:
return []
var bw := Game.board_width()
var bh := Game.board_height()
var DIRS : Array[Vector2i] = [Vector2i(1,0), Vector2i(-1,0), Vector2i(0,1), Vector2i(0,-1)]
var visited : Dictionary = {from: true}
# Queue entries: [pos: Vector2i, path: Array[Vector2i]]
var queue : Array = [[from, []]]
while not queue.is_empty():
var front = queue.pop_front()
var cur : Vector2i = front[0]
var path : Array[Vector2i] = front[1]
for d : Vector2i in DIRS:
var nxt := cur + d
if nxt.x < 0 or nxt.x >= bw or nxt.y < 0 or nxt.y >= bh:
continue
if visited.has(nxt):
continue
if blocked.has(nxt) and nxt != to:
continue
visited[nxt] = true
var new_path : Array[Vector2i] = path.duplicate()
new_path.append(nxt)
if nxt == to:
return new_path
queue.append([nxt, new_path])
return [to] # fallback: direct jump
## Animate a single unit moving from from_coord to to_coord along a BFS path.
## blocked: tiles occupied by other units (their old positions).
## Returns the total tween duration in seconds.
func _animate_unit_move(iid: String, from_coord: Vector2i, to_coord: Vector2i,
blocked: Dictionary) -> float:
var body := _unit_bodies.get(iid) as StaticBody3D
if not is_instance_valid(body):
return 0.0
var path := _bfs_path(from_coord, to_coord, blocked)
if path.is_empty():
return 0.0
var duration := path.size() * MOVE_STEP_SECS
# Cancel any existing move tween for this unit.
if _move_anims.has(iid) and _move_anims[iid] != null:
(_move_anims[iid] as Tween).kill()
# Play the looping move animation.
_play_unit_anim(iid, "moving", true)
# Tween the body through each grid step, preserving its current Y.
var body_y := body.position.y
var tween := create_tween()
tween.set_ease(Tween.EASE_IN_OUT)
tween.set_trans(Tween.TRANS_SINE)
for step : Vector2i in path:
var wp := _coord_to_world(step.x, step.y)
tween.tween_property(body, "position", Vector3(wp.x, body_y, wp.z), MOVE_STEP_SECS)
# Return to Idle once movement finishes.
tween.tween_callback(func() -> void:
_move_anims.erase(iid)
_play_unit_anim(iid, "idle", true))
_move_anims[iid] = tween
return duration
## Detect position changes vs _prev_unit_pos and start move animations.
## Returns the maximum movement duration across all movers (seconds).
func _play_move_animations(state: Dictionary) -> float:
if _prev_unit_pos.is_empty():
return 0.0
# Build the set of blocked tiles from old unit positions.
var blocked : Dictionary = {}
for prev_iid : String in _prev_unit_pos:
blocked[_prev_unit_pos[prev_iid]] = true
var max_dur := 0.0
for player: Dictionary in state.get("players", []):
var arch := player.get("archSpirit", {})
for unit: Dictionary in ([arch] + player.get("field", [])):
if unit.is_empty(): continue
var iid := str(unit.get("instanceId", ""))
var pd = unit.get("position")
if not (pd is Dictionary) or (pd as Dictionary).is_empty(): continue
var new_coord := Vector2i((pd as Dictionary).get("x", 0),
(pd as Dictionary).get("y", 0))
if not _prev_unit_pos.has(iid): continue
var old_coord : Vector2i = _prev_unit_pos[iid]
if old_coord == new_coord: continue
# Mover has left its old tile — unblock it for BFS.
blocked.erase(old_coord)
var dur := _animate_unit_move(iid, old_coord, new_coord, blocked)
max_dur = maxf(max_dur, dur)
return max_dur
## Schedule a delayed call to _rebuild_units.
## Cancels any previous pending rebuild. If delay <= 0 rebuilds synchronously.
func _schedule_rebuild(state: Dictionary, delay: float) -> void:
_pending_rebuild = state
if _rebuild_tween != null:
_rebuild_tween.kill()
_rebuild_tween = null
if delay <= 0.0:
_rebuild_units(state)
return
_rebuild_tween = create_tween()
_rebuild_tween.tween_callback(func() -> void:
_rebuild_tween = null
_rebuild_units(_pending_rebuild)).set_delay(delay)
# ── Highlights ────────────────────────────────────────────────────────────────
@@ -1992,11 +2140,11 @@ func _on_state_updated(state: Dictionary) -> void:
_update_tile_affinity(c.get("x", 0), c.get("y", 0),
tile.get("resolvedAffinity", "Void"))
# Play damage/death animations on existing unit nodes before the rebuild
# destroys them. These play for one frame — enough for a flash effect and
# as a foundation for a future deferred-rebuild architecture.
_play_damage_animations(state)
_rebuild_units(state)
# ── Fire animations on existing nodes before rebuild destroys them ────────
var move_dur : float = _play_move_animations(state)
var dmg_played : bool = _play_damage_animations(state)
# ── Immediate UI update (hand / HUD don't need to wait for animations) ────
var hand := Game.get_hand()
print("[GameScreen] state phase=", state.get("phase","?"),
" my_player_found=", not Game.get_my_player().is_empty(),
@@ -2005,6 +2153,16 @@ func _on_state_updated(state: Dictionary) -> void:
_rebuild_hand(hand)
_update_hud(state)
# ── Update position/HP tracking now so the next state update is correct ───
_update_prev_state(state)
# ── Schedule delayed board rebuild to let animations finish ───────────────
var delay := move_dur
if dmg_played:
delay = maxf(delay, POST_ANIM_SECS)
_schedule_rebuild(state, delay)
# ── Selection preservation (immediate — highlights are tile overlays) ──────
# After a state update, preserve hand-card and unit selections where possible.
# A state push from the server (e.g. opponent action, draw echo) must not
# silently clear tile highlights that the player just set up.
@@ -2028,7 +2186,6 @@ func _on_state_updated(state: Dictionary) -> void:
_:
# Unit selected, sacrifice, ability — clear these on any state change
# because unit positions / health / eligibility may have changed.
print("This is firing")
_set_mode(Mode.NONE)
# Auto-draw.