The JSON is the world.

1. Define a world

A world contains reusable assets, bounded areas, entities and prefabs, actor input bindings, camera state, simulation settings, and serializable runtime state. The format identifier is jsoncraft/2.

{
  "format": "jsoncraft/2",
  "id": "hello-world",
  "assets": { "marker": { "primitive": "sculpture" } },
  "areas": {
    "main": {
      "size": [20, 20],
      "entities": {
        "hello": {
          "components": {
            "render": { "asset": "marker", "color": "#78906f" },
            "spin": { "rate": [0, 18, 0] },
            "text": { "value": "Hello from JSON." }
          }
        }
      }
    }
  },
  "camera": { "area": "main", "position": [0, 6] }
}

Open the JSON Schema ↗. Structural validation is followed by semantic checks for references, inheritance, hierarchy, component versions, geometry, and runtime invariants.

2. Mount it in the browser

Give the container a height, load a world or exported project, and wait for required assets. The renderer uses an isolated shadow root and scoped controls.

<div id="world" style="height:480px"></div>
<script type="module">
  import { mountWorld } from './jsoncraft.js';

  const project = await fetch('./project.json').then(r => r.json());
  const view = mountWorld(document.querySelector('#world'), project.world, {
    resources: project.resources,
    onInteraction(detail) {
      console.log(detail.action, detail.result);
    },
    onError(error) {
      console.error(error);
    }
  });

  await view.ready;
</script>

Download the browser engine ↓. Export project.json from the playground, or supply your own valid world JSON directly.

3. Update the live world

The engine does not prescribe sockets, polling, databases, or agent frameworks. Once your application has changed JSON, choose the update level that matches your state ownership.

// Atomic edits to the current engine.
view.engine.apply({
  baseRevision: view.engine.revision,
  operations: [
    { type: 'entity.update', area: 'main', id: 'hello',
      patch: { state: { active: true } } }
  ]
});

// Replace state in the same engine and component registry.
view.engine.load(nextCheckpoint, {
  baseRevision: view.engine.revision
});

// Replace the mounted engine with another complete world.
await view.load(nextWorld, { preserveView: true });

apply() is atomic and supports revision, tick, state-token, entity-version, and idempotency checks. view.load() cancels captured input and keeps the mount's current resources, base URL, and registry; remount when those dependencies change.

4. Interactions and behavior

Built-in components cover rendering, bodies, vehicle/walk/fly controls, input, spin, text, interactions, and proximity triggers. JSON actions are link, portal, increment, toggle, set, append, and event.

Pointer, keyboard, or touch activation invokes the selected action. The host receives { target, entity, action, result } through onInteraction and the bubbling jsoncraft:interact event. Without a callback, the mount displays a safe built-in content card.

The built-in trigger is proximity-based and supports once, cooldown, and an optional actor. Fixed-tick jobs support wait, move, apply, and invoke. render.when provides state-driven visibility. World JSON never installs arbitrary JavaScript; custom components are trusted host implementations registered separately.

5. Assets and portability

Native world geometry has two forms: editable mesh.parts and detailed model.data triangles. The playground imports OBJ, static glTF/GLB, triangle JSON, voxel JSON, and shape-parts JSON into those forms. Imported model hosts are not runtime dependencies.

Images and web destinations may remain links. Relative resources can come from an exported project resource map. Remote browser fetches omit credentials and require CORS. The runtime also retains direct linked-model support for compatibility and advanced integrations.

Export formats: standalone HTML contains the runtime, world, imported geometry, and owned resources; ZIP contains a static site; project JSON stores { world, resources }. Engine snapshots contain world state only, not project resources.

6. Browser lifecycle

The complete browser handle also exposes engine, element, focus, load, select, setMode, setTool, setTransformMode, setSnap, flushCameraChanges, project, frameView, gizmoHandles, and getStats.

7. Current limits

Static models support up to 32,000 triangles, 96,000 vertices, and 256 material colors. Source glTF must be static; animation and skinning are rejected. Rich textures, transparency, and double-sided materials are simplified when converted to editable world geometry.

Detailed JSON can exceed browser local-storage quotas, so exported projects are the durable authoring copy. See beta status and verified limitations for current browser and physical-device coverage.