HYPNIC CORE

A deterministic, engine-independent execution and observation platform for AI-generated interactive worlds.

Most runtimes that execute generated 3D worlds are built on game engines whose variable-timestep, wall-clock loops make executions impossible to reproduce. HYPNIC CORE takes the opposite approach: a fixed-timestep, seeded, engine-independent simulation kernel where a session is fully described by (world, seed, input log) and replay is re-simulation — bit-identical in Node and in the browser. On top of that it adds reproducible observation, an explainable evidence pipeline, and a versioned agent-policy lifecycle.

It is the fourth and final project of the Hypnic ecosystem, which turns a photograph into an explorable, interactive world:

flowchart LR
  P["Photo / Video"] --> W["Hypnic Weaver<br/>(what does it look like?)"]
  W -->|WorldBundle| CORE["HYPNIC CORE<br/>(execute · observe · learn)"]
  W -.-> COH["COHERATION<br/>(what is it? how does it behave?)"]
  COH -->|KnowledgeBundle| CORE
  COH -->|specs| T["Teen's Hypnic<br/>(how is it built?)"]
  T -->|AssetBundle| CORE
  CORE -->|CandidateEvidence| COH
  CORE --> U(["A walkable, living world"])

The four projects communicate only through versioned contracts (WorldBundle, KnowledgeBundle, AssetBundle, and CORE's own RuntimeManifest, SessionRecord, ObservationEvent, CandidateEvidence, DatasetManifest). HYPNIC CORE never imports upstream code, and any world that conforms to the contracts runs with no runtime changes.

• Determinism. The simulation advances in fixed 60 Hz ticks driven by a single seeded RNG, with no wall-clock time inside the step. The same code runs headless in Node and in the browser and produces identical per-tick state hashes. A session is stored as its input log, not its frames — so any moment can be regenerated exactly.
• Contracts, not coupling. Each upstream project emits versioned JSON bundles; CORE validates them and assembles a world. Nothing calls into anything else's code. This is what lets four independent projects interoperate.
• Observe, don't steer. A read-only observation layer records interaction into reproducible, fully-attributed records. It never affects the simulation — turning it off changes nothing.
• Propose, don't decide. The learning pipeline turns observations into evidence packages and hands them to COHERATION; it never writes knowledge itself.

• Bit-exact determinism, verified in CI across Node and a headless browser.
• Engine-independent — a thin ECS kernel behind ports and adapters; the Three.js renderer is one swappable adapter, not the engine.
• Reproducible observation — records that re-simulate exactly.
• Explainable evidence — reproducible, auditable, k-anonymous evidence packages.
• Versioned agent lifecycle — train → freeze → sign → evaluate → approve → register, scored deterministically against a fixed reference suite.

npm install
npm run build
npm test

npm run core          # serves the browser runtime at http://127.0.0.1:5180

WASD / arrows to move. If Hypnic Weaver has exported a reconstructed world it loads automatically; otherwise a reference world is shown.

Run a world headlessly and see that it is deterministic:

import { produceEcosystemWorld } from '@hypnic-core/integration';
import { canonicalRun } from '@hypnic-core/runtime';

const world = produceEcosystemWorld();                       // a contract-valid world
const a = canonicalRun(world, { seed: '0xC0FFEE', ticks: 1200 });
const b = canonicalRun(world, { seed: '0xC0FFEE', ticks: 1200 });

console.log(a.finalHash === b.finalHash);  // true — identical every run, and identical in the browser

Run the whole ecosystem loop end-to-end (assemble → play → observe → evidence):

npm run core:demo

The projects connect through a shared folder of contract JSON (hypnic-exchange) — no shared database, no code dependency:

# Hypnic Weaver reconstructs a scene and exports a WorldBundle into the exchange:
python "../HYPNIC WEAVER/src/reconstruction/hypnic_core_exporter.py"

# HYPNIC CORE auto-loads the latest exported world, validates it, and runs it:
npm run load          # ✓ contracts valid, ✓ assembled, ✓ walkable

# ...or walk it in the browser:
npm run core          # http://127.0.0.1:5180

The four projects live side by side in the same folder. From HYPNIC CORE:

npm run weaver        # Hypnic Weaver   — React UI + backend
npm run teens         # Teen's Hypnic   — asset UI
npm run core          # HYPNIC CORE     — browser runtime
npm run coheration    # COHERATION      — knowledge engine (verify)
npm run all           # all four together

See ecosystem/README.md for per-project setup and how they connect.

contracts/              versioned contracts + validators (the ecosystem's coupling surface)
fixtures/               golden worlds used for development and tests
packages/
  kernel/               deterministic ECS kernel (fixed timestep, seeded RNG, event bus)
  runtime/              physics/character/scenario systems, world assembly, headless runner
  observation/          consent-gated capture, replay, robot ghost
  experience/           accounts, consent, attempts, world pool, ingest, data lifecycle
  robot/                sensors, policies, offline policy pipeline, benchmarks
  learning/             trajectory analysis → evidence generation
  adapter-render-three/ Three.js render adapter
integration/            conformance producers + the full-loop harness
apps/web-client/        the browser runtime
tools/                  research/benchmark tooling + the bundle validator
ecosystem/              launcher for running the four projects together

See ARCHITECTURE.md for the layered design, the determinism model, and the contract flow.

npm run build                                   # build all packages
npm test                                        # run all test suites
npm run typecheck -w @hypnic-core/web-client

MIT