The Engine

Import

import { Engine } from "@snap-engine/core";

Basic Setup

import { Engine } from "@snap-engine/core";

const container = document.getElementById("engine-container");
const engine = new Engine();

if (container) {
  engine.element = container;
}

The element setter calls assignDom() internally.

engine.assignDom(container);

Svelte Setup

<script lang="ts">
  import { Engine } from "@snap-engine/core";

  const engine = new Engine();
</script>

<div bind:this={engine.element} class="engine-container"></div>

React Setup

import { useEffect, useRef } from "react";
import { Engine } from "@snap-engine/core";

export function EngineComponent() {
  const containerRef = useRef<HTMLDivElement>(null);
  const engineRef = useRef<Engine | null>(null);

  useEffect(() => {
    engineRef.current = new Engine();

    if (containerRef.current) {
      engineRef.current.element = containerRef.current;
    }

    return () => engineRef.current?.destroy();
  }, []);

  return <div ref={containerRef} className="engine-container" />;
}

Engine Events

engine.subscribeEvent("containerResized", "layout", ({ bounds }) => {
  console.log(bounds.width, bounds.height);
});

engine.unsubscribeEvent("containerResized", "layout");

Frame Controller

engine.frameController runs application controllers from SnapEngine’s shared requestAnimationFrame loop. Each callback runs synchronously at the start of the frame, while the engine is IDLE and before the READ_1 queue is snapshotted. Work queued by the callback can therefore participate in every stage of that same frame.

const controller = new AbortController();

const unsubscribe = engine.frameController.subscribe(
  ({ timestamp }) => {
    updateInteraction(timestamp);
  },
  { signal: controller.signal },
);

controller.abort(); // Removes the subscription.
unsubscribe(); // An explicit cleanup is also available.

timestamp is the timestamp supplied by the browser for that shared animation frame. Callbacks run in subscription order from a stable snapshot. A callback added during a tick starts on the next tick, while a callback removed or aborted before its turn is skipped.

Frame callbacks are synchronous and are not awaited. Keep frame-critical state changes inside the callback, and use object.schedule() for staged DOM reads and writes. A thrown error or a returned thenable rejection is reported without preventing later subscribers from running; a promise continuation cannot join the current frame.

The controller’s signal represents the Engine lifetime. engine.destroy() aborts it and removes all frame subscriptions before input listeners are torn down, so controllers that own an active gesture can perform terminal cleanup.

Feature Hooks

import { CollisionEngine } from "@snap-engine/core/collision";
import { DebugRenderer } from "@snap-engine/core/debug";

engine.enableAnimationEngine();
engine.setCollisionEngine(new CollisionEngine());
engine.setDebugRenderer(new DebugRenderer());
engine.disableDebug();

Public API