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

查看 212|回复 32
作者:tianhehechu   
我写了一个非常牛叉的东西,做梦笑醒了,不敢孤芳自赏,分享给 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 本地体验,预计近几天会修复该问题。

    [2026.07.06] 在线 Demo 页面 资源 404 的问题已修复,若仍然遇到,可清除页面缓存或使用其他浏览器打开。感谢大家的反馈。
            
       
       
       

    数据, 声明式, 引擎

  • franklioxygen   
    [2026.07.06] 在线 Demo 页面 资源 404 的问题已修复,若仍然遇到,可清除页面缓存或使用其他浏览器打开。感谢大家的反馈。
    tianhehechu
    OP
      
    Failed to load resource: the server responded with a status of 404 ()
    aoyi   
    @franklioxygen Demo 挂在 GitHub Pages ,试试魔法一下。
    senooo   
    Demo 什么都运行不出来
    Yasuke   
    Demo 什么都运行不出来 +1
    qrobot   
    有点想看做梦笑醒是什么样子,龇牙咧嘴吗?
    JiZhiDeboy   
    @tianhehechu Failed to load resource: the server responded with a status of 404 ()
    你先打磨一下在宣传吧。 别怪梯子的问题
    tianhehechu
    OP
      
    @tianhehechu 能访问 v2 肯定是挂着梯子的,另外提示的是 404 理解一下什么场景是出 404 ,跟梯子没有关系。
    tianhehechu
    OP
      
    @aoyi 正在修复这个问题,预计下午就能正常用了
    您需要登录后才可以回帖 登录 | 立即注册

    返回顶部