OverlaySpec

@Serializable

data class OverlaySpec(val velocities: Boolean = false, val forces: Boolean = false, val flowField: Boolean = false, val plannedPaths: Boolean = false, val markerPulses: Boolean = false, val vectorSampleInterval: Double? = null, val agentSubset: List<String> = emptyList())(source)

Opt-in "agent debugging / teaching" overlays (G10–G12): they record internal computation that drives agent behavior — velocity/force vectors, the flow-field gradient, and planned routes — rather than the observable state the base animation already shows. All flags default off, so a normal run pays zero cost. These are the capture gates (whether the trace contains the data); the viewer has its own display toggles (whether it draws the data), so a captured overlay can be shown/hidden without re-running.

Volume note: the per-step overlays (velocity/force) are the only heavy ones; vectorSampleInterval and agentSubset keep them bounded. The flow field is a one-time per-replication snapshot; paths are occasional.

Constructors

OverlaySpec

constructor(velocities: Boolean = false, forces: Boolean = false, flowField: Boolean = false, plannedPaths: Boolean = false, markerPulses: Boolean = false, vectorSampleInterval: Double? = null, agentSubset: List<String> = emptyList())