@wity-ai/rkf-player

Headless temporal driver for wity-rkf.

wity-rkf is state-primary — a document is a pure function f(doc, state) → ComputedFrame. rkf-core stays pure; rkf-player turns that pure function into a running machine: it owns the mutable state, advances it over ticks and events, and schedules elastic (self-resetting) variables. Analogous to scene-player over scene-core and graph-player over graph-headless.

Presentation-agnostic — wire any renderer to the frame event.

Install

npm install @wity-ai/rkf-player @wity-ai/rkf-core @wity/graph-headless

Usage

import { parse, setGraphProvider, setXmlParser } from '@wity-ai/rkf-core';
import * as graph from '@wity/graph-headless';
import { RkfPlayer } from '@wity-ai/rkf-player';

setGraphProvider(graph);
setXmlParser(new DOMParser());          // Node.js only

const doc = parse(knowledgeXml);        // a <wity-knowledge> document

const player = new RkfPlayer({ interval: 120 });
player.on('frame', ({ frame, state, changed }) => {
  render(frame);                        // frame.marks, frame.controls, frame.envs, …
  // `changed` = { vars, gates } that differ from the previous frame — for partial re-render
});

player.load(doc);                       // resets to initial state, emits first frame
player.play();                          // start the tick loop
player.set('running', true);            // external port (control) input
player.dispatch('click');               // fire a named event
player.pause();
player.stop();                          // reset to initial state

API

new RkfPlayer({ interval })

interval — ms between ticks (default 120, the RKF clock default).

load(docOrGraph, initialState?)

Load a document from parse(). Resets state to the document's initial state (or the provided override) and emits the first frame.

play() / pause() / stop()

Start / stop the tick loop. stop() also resets state to initial.

tick()

Advance one tick event manually — use this to drive the machine from your own requestAnimationFrame loop instead of play().

dispatch(event)

Fire a named event. Applies every transform whose on matches (or is unset) and whose trigger holds.

set(varId, value)

Set a variable from an external control (an rkf-port), then emit a frame.

getState()

Return a copy of the current state.

Events

Event	Payload
loaded	{ doc }
frame	{ frame, state, changed: { vars, gates } }
playback:started / playback:paused / playback:stopped	{}

Isomorphic

Uses setInterval for the tick clock (Node.js and browser). For render-synced ticking, drive tick() from your own requestAnimationFrame loop instead of play().