Embedding & bridges

Entelechy runs as programs of its own (the CLI, the Player) or inside another. Every bridge is a client of the public contracts and nothing more: the Host’s file formats and the creation protocol. Nothing in the Rust workspace depends on them.

The C ABI: in your own process

libentelechy_ffi is behind the C header entelechy.h: a host opens a scene from a path or from files it hands in, evaluates it under its own input, reads an output in place (no copy), and sends protocol lines through entelechy_request.

cargo build --release -p entelechy-ffi
cc bridges/c/hello.c -Icrates/interface/ffi/include -Ltarget/release -lentelechy_ffi -o /tmp/entelechy-hello
LD_LIBRARY_PATH=target/release /tmp/entelechy-hello examples/text/scene.esn jit      # Linux
DYLD_LIBRARY_PATH=target/release /tmp/entelechy-hello examples/text/scene.esn jit    # macOS

Real output on the Linux machine that built these docs:

entelechy 0.0.2-rc.3
picture 192 x 88, 4 words a pixel, schema f,f,f,f, pixels 1
pixel (12, 9) = 0.09 0.10 0.13
publish: {"id":null,"ok":{"generation":24,"id":"scene.back@1"}}
pixel (12, 9) = 0.30 0.10 0.10

hello.c opens a scene, evaluates it, reads the picture where it lies in Host memory (RGBA floats), publishes a new Kernel through the protocol, and reads again — the pixel changed.

Main functions:

Function	Does
`entelechy_open(scene, backend, library)`	opens a scene; NULL on failure, why in `entelechy_open_error()`
`entelechy_open_files(files, scene, backend)`	opens from files the host hands in (`entelechy_files_put`)
`entelechy_open_replay(files, replay, backend)`	opens a replay
`entelechy_evaluate(session, input)`	evaluates a frame under the host’s input; `entelechy_report` reads the report
`entelechy_output(session, name, field)`	reads an output Field in place
`entelechy_node(session, node, port, field)`	reads a node’s port
`entelechy_allow(session, allowance)`	grants a Host permission as `--allow` does
`entelechy_request(session, line)`	sends one protocol line, returns its answer
`entelechy_play_*`	drives it as a Player (keys, pointer, pads, frames, sound)
`entelechy_close(session)`	closes

The static libentelechy_ffi.a links the same way. Any language with a C FFI (Python’s ctypes, C#, Zig, or a native host extension) binds it; the header documents each pointer’s lifetime.

WebAssembly

From a release:

wasmtime run --dir . entelechy-<version>-wasm32-wasip1.wasm replay examples/ant/tests/ant.replay --backend cpu
cd entelechy-<version>-web && node bridges/web/serve.mjs   # then http://127.0.0.1:7789/bridges/web/play.html?scene=examples/voxel/scene.esn

From the source:

cargo build --release -p entelechy --target wasm32-wasip1
cargo build --release -p entelechy-ffi --target wasm32-unknown-unknown
wasm-bindgen --target web --keep-lld-exports --no-typescript --out-dir target/page \
  target/wasm32-unknown-unknown/release/entelechy_ffi.wasm
node bridges/web/serve.mjs     # then http://127.0.0.1:7789/bridges/web/index.html

Under WASI, entelechy runs scenes on the interpreter and serve answers on stdin and stdout.
In a page, Entelechy is the C ABI with wasm-bindgen’s glue: its documents are files the page hands in, its JIT writes WebAssembly the page loads, and its GPU backend runs on the browser’s WebGPU (Chrome and Edge 137 and later). play.html is the Player in a page, ?scene= or ?replay=.

Bridges

Bridge	Connects by	Notes
`bridges/c`	the in-process C ABI	`hello.c` above
`bridges/web`	WebSocket (`--listen`)	a page: connect, `evaluate` + `read` (PPM) frame after frame, keys and pointer, list and edit Kernels; opened from a file it needs `--allow-origin null`
External host bridge	TCP socket	A host-app client: `EntelechyClient` (`open`, `request`, `close`, PPM and Field decoders), a control that is a session’s window, a control per graph param
DCC tool bridge	files + socket	A DCC add-on: pushes the active mesh as scene assets (`.vertices.field`, `.triangles.field`, `.albedo.png`); with Live on, editing the mesh changes the window; turns z-up / y-up axes; pushes rigs

entelechy player examples/voxel/scene.esn --serve --listen 127.0.0.1:7788 --allow-origin null   # web
entelechy serve examples/fluid/scene.esn --backend jit --listen 127.0.0.1:7788                   # host
entelechy player examples/mesh/parts/model/scene.esn --serve --listen 127.0.0.1:7788             # dcc

cargo test -p entelechy --test bridges runs them where their tools are installed.