KSLCore/ksl.animation.emitters.agent/AgentAnimationCoordinator

AgentAnimationCoordinator

class AgentAnimationCoordinator(agentModel: AgentModel, overlays: OverlaySpec = ksl.animation.OverlaySpec.OFF) : AgentModel.AgentRegistryObserver(source)

Coordinates all per-agent animation for one AgentModel: it announces each agent (ksl.animation.AnimationEvent.AgentRegistered) and wires that agent's statechart (StatechartAnimationEmitter) and mailbox (MailboxAnimationEmitter) emitters. This is what the animation controller installs per agent model so a config-driven trace captures agent behavior, not just registrations.

Lifecycle:

attach registers this as the model's registry observer, so transient agents (created during the run) are wired as they register.
snapshotExistingAgents wires every already-registered agent; it must be called at replication start (when the sink is capturing), because permanent agents register at construction — before the controller attached — and are not re-announced by the observer.
detach unwires everything.

Each agent is wired at most once (tracked by identity), so calling snapshotExistingAgents every replication is safe.

Cleanup note: a mailbox observer is removed on detach; a statechart has no observer-removal API, so its observer remains attached but becomes a no-op once the controller restores the null sink. Multi-replication caveat: transient agents from earlier replications are not unwired between replications (their observers fire into the inactive sink and cost nothing once that replication is no longer captured).