Live swap (--watch and the Player)

Entelechy’s core experience: the world keeps running while its laws and structure change. Three ways to try it locally.

1. run --watch

entelechy run examples/grayscale/scene.esn --out output.ppm --watch

Save the scene or any document it uses: Kernels whose text changed republish and what they affect runs again. A Kernel that does not compile is reported and the previous version keeps running. A real session (with examples/grayscale copied to gw/):

watching gw/kernels/gradient.ent, gw/kernels/grayscale.ent, gw/kernels/pixelate.ent, gw/scene.esn; edit a document and save
rejected gw/kernels/grayscale.ent:8:59: `nope` is not defined        ← a deliberate mistake: refused
scene loaded
evaluated in 51.856µs: executed [], reused 2 -> gw.png              ← nothing changed; the old version runs
scene loaded
evaluated in 1.30081ms: executed [gray+source, blocks], reused 0 -> gw.png   ← fixed, and amount set to 0.5

Under --watch the scene’s clock is the seconds since it started, so a scene using time() keeps moving.

2. The Player

entelechy player examples/life/scene.esn

The Player opens a scene in a window and keeps it live; a changed Kernel compiles off the frames and swaps in when ready. It takes run’s --library, --input, --output, --backend, --memory, --work, --small, --allow and --grant, and:

Flag	What it does
--scale <n>, --window <w>x<h>	initial magnification and size
--no-audio	leaves the sound card closed
--show-while-building	opens the window before the device has built what only shows, drawing on the processor meanwhile
--hold-pointer	locks and hides the system cursor once clicked
--folder <name,...>	lets Cmd+O choose a folder for those directory inputs/outputs, allowed what --folder-allow says
--replay <file>	plays a replay in the window
--serve, --listen <host:port>, --allow-origin <origin>	serve the creation protocol from the window

Keys:

Key	What it does
F5	resets state
F6	cycles the preview through the nodes
F8	holds the scene’s time; F9 or F7 steps it
F10	shows the frame’s data: frame, cpu, wait, gpu, nodes, memory, the nodes that waited for the device, the busiest nodes

A gamepad is keys too: the D-pad and left stick are the arrows, South Z, East X, Start Enter, Select Escape. Every other key is the scene’s.

Note

Building entelechy-player on Linux needs libudev and pkg-config. Without a window, use run --watch or render.

3. replay --watch

entelechy replay tests/*.replay --watch

Plays again only the replays a change reaches, each computing only what changed — tests beside you as you write.

What happens to state?

When a Kernel is replaced, state read through <~ (what the last frame committed) is kept; if the new version changes a state port’s layout, migrate names a Kernel that converts the old state, otherwise the state restarts from its initial source and the evaluation says so. See Graph & state and Hot swap & validation.