v4.0 · ABI major 4 · npc-ffi

API Reference

npc-ffi is the only outward-facing crate. 65+ exported symbols — all listed here grouped by category with stability tiers and return codes. The canonical header is npc-ffi/include/npc_engine.h; the frozen contract is npc-ffi/abi/stable-contract.txt.

Stability tiers

Stable — no breaking change within ABI major 4. Experimental — no guarantees, may change. Deprecated symbols are omitted from this page.

Common Return Codes

Code	Meaning
`0`	Success (ingress: enqueued on primary channel)
`1`	Success with warning (ingress: primary saturated, enqueued on overflow)
`-1`	JSON parse error or null pointer
`-2`	Engine not initialized / buffer too small (egress: message not dropped)
`-3`	Queue empty
`-4`	Agent not found
`-5`	Bundle I/O error
`-6`	Corrupt bundle (BLAKE3 mismatch)
`-7`	Unsupported bundle version (`LegacyBundleFormat`)
`-97`	Re-entrancy guard triggered (debug builds only)

Lifecycle

Symbol	Stability	Description
`npc_engine_init(config_json)`	Stable	Initialize engine from config JSON. Returns opaque `EngineHandle*` or `NULL` on error.
`npc_engine_shutdown(handle)`	Stable	Drain the WAL writer thread, flush, then free all engine state. Safe to call with `NULL`.
`npc_engine_version(buf, buf_len)`	Stable	Write the engine semver string (e.g. `"4.0.0"`) into `buf`. Returns bytes written.
`npc_engine_abi_major()`	Stable	Returns the ABI major version as `uint32_t`. Currently `4`.

Ingress

Symbol	Stability	Description
`npc_engine_record_event(handle, event_json)`	Stable	Enqueue a game event. Non-blocking. Returns `0` (primary) or `1` (overflow).

Egress

Symbol	Stability	Description
`npc_engine_peek_action_size(handle)`	Stable	Return the byte size of the next pending action, or `0` if the queue is empty. Always call before pop.
`npc_engine_pop_action(handle, buf, buf_len)`	Stable	Pop the next action into `buf`. Returns bytes written, `-2` if buf is too small (message NOT dropped), `-3` if queue is empty.

Tick

Symbol	Stability	Description
`npc_engine_tick(handle, now_seconds)`	Stable	Advance simulation by one world tick. `now_seconds` is real wall time; the engine converts to game-time delta internally.

Proximity & Tier Control

Symbol	Stability	Description
`npc_engine_set_proximity(handle, agent_id_json, distance, now_seconds)`	Stable	Update agent-to-player distance. The engine handles FS/SS hysteresis and promotion caps.
`npc_engine_set_region(handle, region_json)`	Stable	Set the active region for settlement streaming and partial bundle load.

Snapshots & Subscriptions

Symbol	Stability	Description
`npc_engine_snapshot_agent(handle, agent_id_json, buf, buf_len)`	Stable	Return a JSON snapshot of a single agent's current state (needs, mood, tier, location).
`npc_engine_snapshot_relationships(handle, agent_id_json, buf, buf_len)`	Stable	Return a JSON array of all relationship edges for an agent.
`npc_engine_subscribe_agent(handle, agent_id_json)`	Stable	Subscribe to state-change events for an agent. Changes appear in the action queue as `HostAction::AgentUpdate`.
`npc_engine_unsubscribe_agent(handle, agent_id_json)`	Stable	Remove subscription for an agent.

Scenes & Conversations

Symbol	Stability	Description
`npc_engine_request_player_dialog(handle, agent_id_json, utterance_json)`	Stable	Initiate or continue a player↔NPC dialog. Enqueues a `PlayerDialog`-priority cloud call.
`npc_engine_cancel_dialog(handle, scene_id_json)`	Stable	Cancel an in-flight dialog stream and record partial usage.
`npc_engine_peek_stream_chunk_size(handle)`	Stable	Return size of the next incremental dialog stream chunk, or `0`.
`npc_engine_pop_stream_chunk(handle, buf, buf_len)`	Stable	Pop the next stream chunk (token delta). Same peek-then-pop contract as `pop_action`.
`npc_engine_open_scene(handle, scene_json)`	Stable	Open a multi-agent scene with declared participants, intents, and topics.
`npc_engine_close_scene(handle, scene_id_json)`	Stable	Close a scene. Atomically updates relationships, beliefs, and commitments.

Bundles & Persistence

Symbol	Stability	Description
`npc_engine_export_bundle(handle, path)`	Stable	Drain WAL, flush, export NPCB v17 bundle. Returns `0`, or `-5/-6/-7` on error.
`npc_engine_import_bundle(handle, path)`	Stable	Import a bundle into the engine's store. Readable versions: 16, 17.
`npc_engine_export_repro_bundle(handle, path, ticks, tick_seconds)`	Stable	Capture a full RPRO repro bundle for bug reproduction.

WorldPacks & Modding

Symbol	Stability	Description
`npc_engine_resolve_world(handle, packs_json)`	Stable	Resolve and load a list of WorldPack paths into the engine's world model.
`npc_engine_install_pack(handle, url_with_hash, buf, buf_len)`	Stable	Download, verify (Blake3), and install a pack from a URL. Returns installed pack id into `buf`. Returns `-2` on buffer too small without partial install.

Metrics & Diagnostics

Symbol	Stability	Description
`npc_engine_peek_metrics(handle, buf, buf_len)`	Stable	Return JSON engine metrics — budget remaining, circuit breaker state, FS agent count, tick timing.
`npc_engine_peek_agent_budget(handle, agent_id_json, buf, buf_len)`	Stable	Return per-agent budget state JSON.

Decision Hooks (v3.6)

Symbol	Stability	Description
`npc_engine_register_decision_hook(handle, seam, callback, user_data)`	Experimental	Register a C callback to override a policy seam decision. Pass `NULL` callback to unregister.
`npc_engine_decision_hook_registered(handle, seam)`	Experimental	Returns `1` if a hook is registered for the seam, `0` otherwise.
`npc_engine_decision_hook_fallback_count(handle, seam)`	Experimental	Returns the number of times the engine fell back to its default for this seam (hook failures).