Hylograph.ForceEngine.Core

data ForceHandle

createManyBody :: ManyBodyConfig -> ForceHandle

Create a many-body (charge) force

createCollide :: CollideConfig -> ForceHandle

Create a collision force

createLink :: LinkConfig -> ForceHandle

Create a link force

createCenter :: CenterConfig -> ForceHandle

Create a centering force

createForceX :: ForceXConfig -> ForceHandle

Create an X positioning force

createForceY :: ForceYConfig -> ForceHandle

Create a Y positioning force

createRadial :: RadialConfig -> ForceHandle

Create a radial force

createManyBodyFiltered :: forall node. ManyBodyFilteredConfig node -> ForceHandle

Create a many-body force that only applies to nodes matching a predicate Useful for applying charge only to certain node types (e.g., tree parents)

createRadialFiltered :: forall node. RadialFilteredConfig node -> ForceHandle

Create a radial force that only applies to nodes matching a predicate

createCollideDynamic :: forall node. CollideDynamicConfig node -> ForceHandle

Create a collision force with dynamic radius per-node The radiusAccessor function is called for each node to determine collision radius Example: { radiusAccessor: \n -> n.r + 5.0, strength: 1.0, iterations: 1 }

createForceXDynamic :: forall node. ForceXDynamicConfig node -> ForceHandle

Create an X positioning force with dynamic target per-node The xAccessor function is called for each node to determine target X Useful for clustering (e.g., modules toward their parent package's X)

createForceYDynamic :: forall node. ForceYDynamicConfig node -> ForceHandle

Create a Y positioning force with dynamic target per-node

createLinkDynamic :: forall link. LinkDynamicConfig link -> ForceHandle

Create a link force with dynamic strength per-link The strengthAccessor function is called for each link to determine strength Useful for encoding link weight as force strength Example: { distance: 30.0, strengthAccessor: \link -> link.weight, iterations: 1 }

createForceXGrid :: Number -> ForceHandle

Create an X positioning force that reads node.gridX directly Much faster than createForceXDynamic because it avoids FFI callbacks. Nodes must have a gridX :: Number field.

createForceYGrid :: Number -> ForceHandle

Create a Y positioning force that reads node.gridY directly Much faster than createForceYDynamic because it avoids FFI callbacks. Nodes must have a gridY :: Number field.

createCollideGrid :: Number -> Number -> Int -> ForceHandle

Create a collision force that reads node.r directly Much faster than createCollideDynamic because it avoids FFI callbacks. Nodes must have an r :: Number field (radius). Parameters: padding, strength, iterations

initializeNodes :: forall r. Array (Record r) -> Effect Unit

Initialize nodes with indices and default velocities This mutates the nodes array to add index, vx, vy if missing

initializeForce :: forall r. ForceHandle -> Array (Record r) -> Effect ForceHandle

Initialize a force with nodes Must be called before applying the force

initializeLinkForce :: forall nodeRow linkRow. ForceHandle -> Array (Record nodeRow) -> Array (Record linkRow) -> Effect ForceHandle

Initialize a link force with nodes and links Link forces need both nodes and links

applyForce :: ForceHandle -> Number -> Effect Unit

Apply a single force This mutates vx/vy on the nodes the force was initialized with

applyForces :: Array ForceHandle -> Number -> Effect Unit

Apply multiple forces in sequence

integratePositions :: forall r. Array (Record r) -> Number -> Effect Unit

Integrate positions: apply velocity decay and update positions Call this once per tick after all forces have been applied

decayAlpha :: Number -> Number -> Number -> Number -> Number

Calculate new alpha value (the "cooling" step) Returns 0 if alpha falls below alphaMin

simulationTick :: forall r. { alpha :: Number, alphaDecay :: Number, alphaMin :: Number, alphaTarget :: Number, forces :: Array ForceHandle, nodes :: Array (Record r), velocityDecay :: Number } -> Effect Number

Complete simulation tick:

1. Apply all forces
2. Integrate positions
3. Return new alpha

type AnimationHandle = Effect Unit

Handle to a running animation (can be used to stop it)

startAnimation :: (Number -> Effect Boolean) -> Effect AnimationHandle

Start an animation loop The callback receives the current timestamp and should return whether to continue

stopAnimation :: AnimationHandle -> Effect Unit

Stop a running animation

attachDragWithReheat :: Array Element -> Effect Unit -> Effect Unit

Attach drag with a reheat callback

attachGroupDragWithReheat :: Array Element -> String -> Effect Unit -> Effect Unit

Attach drag to transformed group elements (like bubble packs)

Unlike attachDragWithReheat, this version takes a container selector to get pointer coordinates in the correct coordinate space. Use this when dragging <g> elements that have transform attributes.

Example:

-- For bubble packs inside a zoom group
attachGroupDragWithReheat packElements "#zoom-group" (Sim.reheat sim)

attachPinningDrag :: Array Element -> Effect Unit -> Effect Unit

Attach drag with toggle-pinning behavior

Unlike attachDragWithReheat, this version keeps nodes pinned after drag ends.

• First drag: pins the node where you drop it
• Subsequent drags: if you barely move (< 3px), unpins the node

This is useful for allowing users to "fix" certain nodes in place while letting others float freely in the simulation.

Example:

nodeElements <- getElementsByClassName "node"
attachPinningDrag nodeElements (Sim.reheat sim)

querySelectorElements :: String -> Effect (Array Element)

Query DOM elements by CSS selector

Returns all elements matching the given CSS selector. Useful for getting element references for drag behavior attachment.

Example:

nodeCircles <- querySelectorElements "#my-graph circle.node"
attachPinningDrag nodeCircles (Sim.reheat sim)

logNodes :: forall r. String -> Array (Record r) -> Effect Unit

Log node positions for debugging