Hylograph.Kernel.D3.Events

data SimulationEvent

Events that can occur during simulation lifecycle.

These types are primarily for Halogen integration via subscriptions. Internally, callbacks are invoked directly without constructing these values.

Usage with Halogen:

handleAction (SimEvent event) = case event of
  Tick -> liftEffect updateDOMPositions
  Started -> H.modify_ _ { simRunning = true }
  Stopped -> H.modify_ _ { simRunning = false }
  AlphaDecayed alpha -> when (alpha < 0.1) $ liftEffect doSomething

Constructors

• Tick
• Started
• Stopped
• AlphaDecayed Number

Instances

• Eq SimulationEvent
• Show SimulationEvent

type SimulationCallbacks = { onAlphaThreshold :: Ref (Number -> Effect Unit), onStart :: Ref (Effect Unit), onStop :: Ref (Effect Unit), onTick :: Ref (Effect Unit) }

Callbacks for simulation events.

All callbacks are stored in Refs to allow dynamic updates and to keep the tick loop allocation-free (no closures created per-tick).

The callbacks are Effect Unit rather than taking event data because:

1. Performance: No boxing/unboxing of event data in hot path
2. Simplicity: Consumers can read simulation state directly if needed
3. Flexibility: The consumer decides what data they need

defaultCallbacks :: Effect SimulationCallbacks

Create default callbacks (all no-ops).

Usage:

callbacks <- defaultCallbacks
Ref.write updateDOMPositions callbacks.onTick
sim <- createWithCallbacks config callbacks

onSimulationTick :: Effect Unit -> SimulationCallbacks -> Effect Unit

Set the tick callback.

WARNING: This callback runs 60x/second during simulation. Keep it fast! Avoid allocations, complex logic, or console.log.

Good:

onSimulationTick (updateGroupPositions nodes) callbacks

Bad:

onSimulationTick (do
  nodes <- Ref.read nodesRef  -- Extra ref read
  log "tick"                   -- Console I/O
  H.tell ...                   -- Halogen message (allocates)
) callbacks

onSimulationStart :: Effect Unit -> SimulationCallbacks -> Effect Unit

Set the start callback.

Called when simulation starts running or is reheated from stopped state. Safe to do heavier work here (only called occasionally).

onSimulationStop :: Effect Unit -> SimulationCallbacks -> Effect Unit

Set the stop callback.

Called when simulation stops (alpha < alphaMin). Safe to do heavier work here.

onAlphaDecay :: (Number -> Effect Unit) -> SimulationCallbacks -> Effect Unit

Set the alpha threshold callback.

Called when alpha crosses common thresholds: 0.5, 0.1, 0.01. The callback receives the new alpha value.

Useful for:

• Progressive rendering (show more detail as simulation settles)
• UI updates (e.g., hide "Simulating..." spinner)
• Analytics (track how long simulations run)