中文 | English

ThreeJSON Caller Guide

ThreeJSON is a Web3D JSON runtime built on top of Three.js. Instead of hand-writing large amounts of scene setup, render-loop, controls, lights, and mesh creation code, callers describe scenes and objects as configuration data. The ThreeJSON core then parses that configuration, creates the corresponding Three.js objects, starts the render loop, and updates declarative animations.

This handbook is written for library callers. It focuses on the scene pipeline under core/handler/ and general-purpose object builders under core/builder/ such as core/builder/modelBuilder.js. An ideal, non-mandatory view of builder / handler / runtime is in Design principles. The repository still contains some business-specific machine-room and cabinet code, but those parts are not the main focus of this handbook.

Contents

• Timeline, audio and media export: deterministic playback, dynamic clips, particle morphing, soundtracks and PNG/GIF/MP4/WebM output.

• Scene operations and AI tools: shared contracts, queries, spatial operations, preflight, undo, CLI/MCP and Editor pairing.

• Quick Start: create a minimal runnable scene with createSceneRuntime().

• JSON Format Guide: runtime config plus the JSON formats for boxes, spheres, groups, lines, info panels, scene text (objType: text), heatmaps, animated planes, and external models.

• Info panels guide: infoPanel / css3dPanel selection, per-type examples, and demo index.

• Business Domains and domains/: domainModelList, businessDomains, domain registration, and custom domains.

• Optional extensions and extensions/: PluginHost, JSON extensions containers, bundled references, and custom extension wiring.

• Core API: the most commonly used runtime APIs for callers (including createJsonScene and static asset base URLs).

• Tools and host apps: sysConfig / sceneConfig boundaries (editor, player, etc.).

• Runtime object mutation quickref: applyObjectChange / partial / snapshot / redeploy.

• Dynamic runtime batches: slot-backed GPU buffers, virtual runtime entities, frame-coalesced commits, and opt-in demand rendering.

• Complex meshes and progressive modeling: complete BufferGeometry, stable-ID control cages, modifiers, parametric/NURBS/Bezier/loft/sweep/SDF surfaces, mesh commands, and progressive AI refinement.

• Computable modeling and operators: parameterized graphs, built-in/custom/composite operators, incremental compilation, Workers, optional GPU, exact CAD/STEP and Editor/AI integration.

• Capabilities, Particle V2, and WebGPU/TSL: machine-readable capability truth, Physical materials, particles, optional WebGPU, TSL module policy, external-model material bindings, LOD, curves, and morph targets.

• Development: Node version, tests, AI verification, sync/async API naming.

• Terminology glossary: key concept pairs and short definitions (complements language policy).

• Scope: core vs extensions and canonical vs runtime overlays.

• Design principles: optional features, non-invasiveness, and separation of engine capability from host policy.

• Demo Pages: what each page under examples/html-demo/ and the repo root demonstrates.

• Scene load lifecycle: createJsonScene phase hooks and SDF text font preload (bilingual).

The default entry page at the repo root is ../index.html, which redirects to website/index.html. The tutorial index demo.html lets you switch between the examples/html-demo/ samples and integrated pages such as room-show.html, the scene editor, the scene player, and port-show.html.

npm Install (Optional)

The repository already provides a root ../package.json and the package name is threejson. When installing it into your own application, also install the peer dependencies so your bundler can resolve imports such as three from node_modules:

npm install threejson three @tweenjs/tween.js

Install html2canvas-pro, gifuct-js, fflate, three-bvh-csg + three-mesh-bvh, or troika-three-text only for the corresponding HTML-panel, GIF, archive, CSG, or SDF-text capability.

Prefer importing from the package root:

import { createSceneRuntime, deployMesh } from "threejson";

Before publishing to npm, you can still import directly from the cloned source path ../core/index.js. See the root ../package.json for the current package version and peer dependency range.

Recommended Usage

1. Use createSceneRuntime() to create the scene, camera, renderer, controls, lights, and the shared render loop.
2. Prepare object JSON descriptions.
3. Convert JSON objects into Three.js objects with deployMesh(), createGroup(), createLine2(), createHeatmap(), and similar helpers.
4. Call sceneRuntime.start() to start the shared render loop.

Minimal example:

import { createSceneRuntime, deployMesh } from "../core/index.js";

const sceneRuntime = createSceneRuntime({
  canvas: document.getElementById("canvasContainer"),
  config: {
    canvasWidth: window.innerWidth,
    canvasHeight: window.innerHeight,
    scene: { background: "#222222" },
    camera: { fov: 60, near: 0.1, far: 2500, position: { x: 220, y: 180, z: 280 } },
    renderer: { antialias: true, ratioRate: 1 },
    controls: { enableDamping: true, target: { x: 0, y: 40, z: 0 } },
    lights: [
      { type: "ambient", color: "#ffffff", intensity: 0.45 },
      { type: "directional", color: "#ffffff", intensity: 0.9, position: { x: 300, y: 400, z: 300 } }
    ],
    renderLoop: { autoResize: true, firstAutoResize: true }
  }
});

const boxJson = {
  name: "demo-box",
  objType: "box",
  geometry: { width: 100, height: 80, depth: 60 },
  position: { x: 0, y: 40, z: 0 },
  rotation: { rotationX: 0, rotationY: 0, rotationZ: 0 },
  scale: { scaleX: 1, scaleY: 1, scaleZ: 1 },
  material: {
    type: "standard",
    color: "#409eff"
  }
};

deployMesh(boxJson, sceneRuntime.scene);
sceneRuntime.start();

Running Notes

Running HTML in VS Code / Cursor

1. Open the project root in VS Code or Cursor.
2. Install the Live Server extension.
3. In the file explorer, right-click the .html file you want to preview and choose Open with Live Server.
4. Your browser will open the page over a local HTTP server.

Running HTML in WebStorm

1. Open the project in WebStorm.
2. In the project view, right-click the .html file you want to run and choose Run.

Other Notes

• Serve pages over a local static server instead of opening them with file://. ES modules, textures, and OBJ / GLTF loading usually require HTTP.
• The minimal runtime uses bare module specifiers such as three and @tweenjs/tween.js. Optional capability modules such as html2canvas-pro need an import-map entry only when that capability is used. With Vite or Webpack, installed packages are resolved from node_modules.
• Texture paths can use project-root paths such as /assets/textures/.... Pages inside examples/html-demo/ usually import engine modules from ../../core/....
• With npm install threejson: built-in domains and /assets/... paths in JSON try the active base first and fall back to jsDelivr @threejson/assets (see Static assets in api.md). Cloned-repo demos can still use assetsBase: "/assets" or setAssetsBaseUrl("/assets") for the local mount.
• rotationX, rotationY, and rotationZ use radians, not degrees.
• The engine stores the original JSON on userData.objJson, which is useful for later type checks, hiding, deletion, or business extensions.
• Start with examples/html-demo/track-00-runtime/00-03-friendly-full-scene.html and assets/json/sceneRuntimeBasic.json for a modern example.