ThreeJSON 横空出世：一个 JSON 驱动、AI 友好的开源 3D 引擎（基于 Three.js）

我写了一个非常牛叉的东西，做梦笑醒了，不敢孤芳自赏，分享给 V 友们同乐。

一句话介绍：ThreeJSON 支持使用 JSON 文本描述构建 3D 场景的一切。

本项目使用 MIT 协议开源。

GitHub 仓库地址： https://github.com/nnrj/threejson

Demo 页面： https://nnrj.github.io/threejson/

Npm： https://www.npmjs.com/package/threejson

可使用 VSCode 打开后，用 Live Sever 插件打开其中的 示例 html 页面体验。

ThreeJSON 的哲学浓缩成四句话：
Scene as Data —— 场景即数据
Runtime as Engine —— 运行时即引擎
Domain as Extension —— 业务域即扩展
Agent as Operator —— Agent 即操作者

说人话就是：

你负责描述世界，AI 负责创造和修改世界，ThreeJSON 渲染和运行世界。

目前项目已开源，欢迎 V 友 们围观、试玩、提 Issue 。

[开始念经]

ThreeJSON 是一个 JSON 驱动的 Three.js 声明式场景运行时与 Web3D 引擎。它不是对 Three.js 的简单 API 包装或替代品，而是建立了一条完整的数据驱动链路：场景描述 统一解析 → 对象创建 → 场景装配 → 实时运行 → 增量修改 → 场景持久化。

通过将 3D 场景抽象为结构化数据，ThreeJSON 解耦了业务逻辑与底层渲染，让开发者无需重复编写冗长的初始化代码，即可高效构建复杂的 3D 交互世界。

核心架构与技术特性

1. 规范真源：JSON 为王 (Single Source of Truth)

在 ThreeJSON 中，JSON 是场景的唯一规范真源。

• 双模 JSON 支持：兼容易于机器生成、流水线处理和 AI 消费的“标准 JSON”，以及便于人类阅读、手写和局部微调的“用户友好 JSON”（加载时自动归一化）。


• 双层运行结构：每个由运行时创建的对象都会保留其原始 JSON 描述符。形成“JSON 负责规范与持久化，Object3D 负责高性能实时运行”的双层结构。物理引擎或游戏循环对 Object3D 的实时修改，可随时增量同步并导出为普通文件、数据库记录或 .tjz 资源压缩包。

2. 完备的声明式对象与组件体系

内置丰富的声明式对象，支持位置、旋转、缩放、材质、纹理、动画和事件的完整参数化配置：

• 几何与网格：盒体、球体、平面、圆环、圆柱、圆锥、线条、Group 等。


• 高级与多媒体组件：3D 文字、CSS3D 面板、信息面板、高级粒子系统、热力图等。


• 外部资产与原生混配：高效加载外部 3D 模型（如 glTF/FBX ），并支持接入 Native 原生对象。

3. 高效的对象管理与运行时变更

• 扁平化对象检索：内置高效的管理体系，支持通过 threeJsonId、uuid、refName 或 name 快速定位对象。上层系统无需遍历复杂的 Three.js 树状场景树，即可在 systemBucket 或自定义分类桶中实现毫秒级查改。


• 增量状态更新（不重载场景）：提供精细化的运行时变更 API 。修改位置、替换材质、动态显隐或调整纹理等操作均为增量原子操作，极为适合数字孪生、大屏监控和实时控制场景。

4. 动态交互、动画与扩展机制

• 双轨动画系统：既支持在 JSON 中直接声明旋转、位移、浮动等轻量行为（由统一渲染循环驱动），也支持通过 Three.js AnimationMixer 完美承接外部 glTF 模型内嵌的复杂骨骼与机械动画。


• 声明式事件系统：允许在 JSON 描述符中直接定义鼠标/键盘交互、内置 action 、自定义 DSL 甚至外部 JavaScript 脚本，实现从“静态展示”到“动态世界”的跨越。


• 业务域（ Domain ）扩展机制：核心层保持绝对纯粹，通过 handler 与 registry 机制向外延伸。开发者可针对“机房”、“港口”、“园区”、“工厂”等垂直数字孪生领域，自定义专属的模型组装方式、API 钩子和视觉规范。

面向 AI 与 Agent 的下一代设计

ThreeJSON 为大语言模型（ LLM ）和自主 Agent 提供了天然契合的 3D 场景表达方式。AI 不必尝试去生成晦涩且容易出错的 Three.js 源码，只需输出高度结构化的场景 JSON 。Agent 可以通过稳定的对象 ID 、JSON Patch 、动态命令接口和运行时变更为场景注入智能。

其核心设计哲学可完美概括为：

Scene as Data + Runtime as Engine + Domain as Extension + Agent as Operator

当前（ 2026 年 7 月 6 日），GitHub Pages 页面加载不出场景，可在 Clone 本地体验，预计近几天会修复该问题。