Animate transitions and bring the office to life

[williamthorsen]

Problem

The OfficeScene generates TransitionPlan objects with ordered animation instructions (walk, state_change, fade_in, fade_out, artifact_appear, artifact_deliver) — but discards them and teleports all entities to their new positions. The office is static. This issue makes it alive.

Context

• Parent: Implement office visualization with React canvas and animation #307
• Depends on: Replace geometric placeholders with tileset rendering #310 (tileset rendering — need sprites before animating them)
• Design skill: .agents/skills/office-game-feel/SKILL.md — movement timing, state machines, attention guidance, Excalibur patterns
• Facility architecture: packages/factory/docs/visions/facility-architecture.md — orchestrator heartbeat, agent states, artifact lifecycle

The transition planner already produces everything needed:

• Waypoint sequences with corridor routing through doorways
• 150ms stagger between simultaneous transitions
• Transition types matching the facility architecture's state machines

Solution

1. Transition playback engine

Wire OfficeScene to consume TransitionPlan instead of calling applyFullState(). Process transitions respecting their delayMs stagger. Dispatch each transition type to a handler. Centralize all animation timing, speed, opacity, and scale constants in a single constants module for easy tuning.

2. Walk animation

Animate walk transitions along waypoint sequences using Excalibur action queues. Target speed: 3-4 tiles/second. Update character sprite facing direction to match movement direction between waypoints. Use idle sprites with directional slide (walk cycle sprite sheets are a future cosmetic upgrade that won't require code changes).

3. Orchestrator heartbeat

The orchestrator's errand pattern (desk → doorway → destination → pause → doorway → desk) is state-driven: the orchestrator walks only when the transition planner produces a walk transition from phase changes. No autonomous idle patrol loop.

4. State change animations

• state_change: Brief visual cue at current position (opacity pulse)
• fade_in / fade_out: Opacity transitions for agent appearances/departures
• artifact_appear: Pop-in with scale bounce at agent position
• artifact_deliver: Slide to delivery surface with settle

Overlapping updates

When a new status arrives while animations are playing, interrupt: cancel in-progress animations, snap entities to final positions, then start the new transition batch.

Out of scope (follow-up ticket)

• Thought bubbles (HTML overlays with cycling messages)
• Time indicators (colored pips showing phase elapsed time)
• HUD toggle (ambient/standard/detailed display density modes)

Acceptance criteria

• Transitions play as animations instead of teleporting
• Orchestrator walks between zones with visible errand pattern
• Agent state changes have brief visual cues
• Agents and orchestrator face the correct direction during movement
• Artifacts animate (appear, deliver) rather than snap into existence
• New status arriving mid-animation interrupts cleanly without visual glitches
• All animation constants (speeds, durations, opacities, scales) are centralized in a single tweakable constants module
• Healthy progress looks calm; problems draw attention

Depends on

• Replace geometric placeholders with tileset rendering #310 (tileset rendering)

Guided by

.agents/skills/office-game-feel/SKILL.md

[williamthorsen]

Insights from #311 implementation

Excalibur v0.32 API confirmations:

• callMethod() is available in the action queue and works for scheduling callbacks between action steps. The plan flagged this as a risk (the catwalk visualization doesn't use it), but it was functional for scheduling direction-update callbacks between moveTo segments.

• scaleTo() accepts vec for both target and speed parameters as expected. No workaround needed — the plan's fallback to onPreUpdate with manual elapsed-time tracking was unnecessary.