GDevelop 的 ThreeAddons 构建与升级指南为游戏引擎生成经典脚本形式的 Three.js 运行时依赖【免费下载链接】GDevelop Open-source, cross-platform 2D/3D/multiplayer game engine designed for everyone.项目地址: https://gitcode.com/GitHub_Trending/gd/GDevelop导读本文聚焦 GDevelop 仓库中 SharedLibs/ThreeAddons 这一构建子项目讲解它如何把现代 ESM 形态的 Three.js 及官方 addons 打包成游戏引擎运行时GDJS/Runtime所需的经典脚本classic script暴露全局变量并给出完整的构建、复制与版本升级流程。读完本文你将掌握three.js与ThreeAddons.js两个运行时产物的生成原理、涉及的 Rollup 打包配置、升级 Three.js 时需要同步修改的多个版本声明位置以及引擎侧如 3D 模型加载实际消费这些全局命名空间的方式从而可以独立完成该子项目的重建与版本维护。一、这个子项目解决什么问题GDevelop 的 JavaScript 游戏引擎运行时GDJS/Runtime所依赖的脚本是经典脚本classic scripts它们通过暴露全局变量来提供能力而不是 ES modules。这意味着运行时里的pixi.js、three.js、ThreeAddons.js都是往全局命名空间塞东西的普通脚本。而 Three.js 官方自r160之后不再提供这种经典构建此前的build/three.min.js/build/three.js等 UMD/全局构建被移除只以 ES modules 形式发布。因此 GDevelop 需要在自己的仓库里从 npm 的three包出发自己打出一份引擎运行时能直接script引用的全局脚本。SharedLibs/ThreeAddons就是为此而存在的构建子项目它产出两个文件产物暴露的全局命名空间内容落点three.jsTHREE完整 Three.js 库直接写入GDJS/Runtime/pixi-renderers/three.jsThreeAddons.jsTHREE_ADDONSGDevelop 用到的 Three.js addons 合集加载器、控制器、后处理……先生成到dist/ThreeAddons.js需手动复制到GDJS/Runtime/pixi-renderers/ThreeAddons.js从源码结构看rollup.config.js 中明确注释了这一动机Three.js 在 r160 之后停止提供经典脚本构建所以改在这里自行打包且产物要与pixi.js一样作为设置全局变量的普通脚本被引擎使用。二、产物与消费方引擎如何依赖这两个全局构建产物最终位于 GDJS/Runtime/pixi-renderers/与pixi.js、layer-pixi-renderer.ts等同目录共存。引擎侧对这两个全局的直接消费可以从以下文件得到源码级确认GDJS/Runtime/Model3DManager.ts3D 模型管理器直接用THREE_ADDONS.GLTFLoader与THREE_ADDONS.DRACOLoader加载 GLTF/GLB 模型this._loader new THREE_ADDONS.GLTFLoader()并用THREE.Group、THREE.BoxGeometry、THREE.MeshBasicMaterial等构造占位网格资源缓存的类型为THREE_ADDONS.GLTF。GDJS/Runtime/types/global-three-addons.d.ts为THREE_ADDONS全局命名空间声明了类型列出了GLTFLoader、GLTF、DRACOLoader、SkeletonUtils、TransformControls、SelectionBox、EffectComposer、OutlinePass、RenderPass、ShaderPass、SMAAPass、OutputPass、UnrealBloomPass、BrightnessContrastShader、ColorCorrectionShader、HueSaturationShader、ExposureShader等导出方便 TypeScript 侧对全局做类型检查。后处理post-processing、3D 场景调试等还会在 layer-pixi-renderer.ts 与编辑器相关脚本如 InGameEditor.tsx中引用这些全局。也就是说THREE承担底层三维数学与渲染THREE_ADDONS承担 GLTF 加载、骨骼处理、变换控制、多通道后处理等高层能力。三、源码结构一个入口、两个打包目标构建子项目的源码非常精简核心只有三个文件SharedLibs/ThreeAddons/ ├── src/ │ ├── index.ts # addons 的汇总入口THREE_ADDONS 的导出清单 │ └── three.ts # 整个 Three.js 库的再导出入口THREE ├── package.json # 依赖与构建脚本 ├── rollup.config.js # 双目标打包配置 └── README.md1.src/three.ts产出THREEthree.ts 内容只有一行export * from three并注释说明重新导出整个 Three.js 库以便把它打包成一个暴露THREE全局的经典脚本。2.src/index.ts产出THREE_ADDONSindex.ts 是 addons 的汇总清单逐条从本地拷贝的官方examples/jsm源码中再导出。当前打包进来的 addons 包括加载器loadersGLTFLoader、DRACOLoader控制器与交互controls / interactiveTransformControls、SelectionBox骨骼/几何工具utilsSkeletonUtils后处理管线postprocessingEffectComposer、RenderPass、OutlinePass、ShaderPass、SMAAPass、OutputPass、UnrealBloomPass着色器shadersBrightnessContrastShader、HueSaturationShader、ExposureShader这些 addons 的源码位于 src/examples/jsm/是从 Three.js 官方仓库的examples/jsm目录拷贝而来。注意 README.md 明确说明这些源码以 MIT 协议授权与 Three.js 本体一致可放心随仓库分发与修改。3.rollup.config.js双目标输出rollup.config.js 定义了两个打包任务任务一输入src/three.tsformat: iifename: THREE同时输出两个文件——开发用的./dist/three.js带 sourcemap和引擎运行时用的../../GDJS/Runtime/pixi-renderers/three.js不带 sourcemap。也就是说构建 three.js 时产物会直接被写入运行时目录无需手动复制。任务二输入src/index.tsformat: umdname: THREE_ADDONS并把three声明为externalglobals: { three: THREE }仅输出./dist/ThreeAddons.js。因为 addons 依赖 Three.js 本体UMD 打包时引用全局THREE即可。两个任务都启用了rollup/plugin-node-resolve把threenpm 包解析进来与rollup/plugin-terser压缩。四、构建与更新运行时文件按照 README.md 的说明重建流程是两条命令npm install npm run build其中npm run build等价于rollup -c见 package.json 的 scripts 定义。构建完成后GDJS/Runtime/pixi-renderers/three.js直接被重新生成Rollup 配置里写死了这个输出路径dist/ThreeAddons.js生成在子项目目录下如果 addons 有变更需要手动复制到GDJS/Runtime/pixi-renderers/ThreeAddons.js。这是因为 three.js 的重建完全由仓库内代码决定而 addons 的输出是否进入运行时需要维护者根据变更范围人工判断README 因此强调to be copied manually ... if the addons changed。本地依赖与构建脚本速览package.json 中与构建相关的关键信息运行时依赖为空three只是devDependencies构建期使用产物自包含核心 devDependenciesthree0.160.0、rollup^2.66.1、rollup/plugin-node-resolve^13.1.3、rollup/plugin-terser^0.4.0、prettier2.1.2附带两个格式检查脚本formatprettier --write src/**/*.ts与check-formatprettier --list-different src/**/*.ts用于保持src下 TypeScript 源码风格统一。五、升级 Three.js 的完整操作清单当需要把运行时使用的 Three.js 升级到新版本时README.md 给出了一套四个步骤的标准流程这里结合仓库实际逐一展开1. 同步三处版本声明不要漏主版本修改 SharedLibs/ThreeAddons/package.json 中的three版本当前为0.160.0。类型声明同步修改 GDJS/package.json 中的types/three当前同样为0.160.0保证引擎 TypeScript 侧的类型与运行时实际使用的库版本一致。编辑器依赖同步修改 newIDE/app/package.json 中的three版本使 IDE编辑器侧的 Three.js 依赖也保持一致。README 特别强调这三处必须保持同步否则可能出现编辑器里看的类型/行为与运行时实际跑的库不一致的问题。2. 更新src/examples中的 addons 源码从 Three.js 官方仓库的最新examples/jsm中把SharedLibs/ThreeAddons/src/examples/下对应文件loaders、controls、postprocessing、shaders、utils 等更新为最新实现确保 addons 与新的 Three.js 核心 API 兼容。3. 重新构建并复制产物执行npm run build然后按第四节说明处理产物three.js已自动写入运行时目录若 addons 有变更将dist/ThreeAddons.js手动复制到GDJS/Runtime/pixi-renderers/ThreeAddons.js。4. 适配引擎代码并跑测试升级后 Three.js 可能引入破坏性 API 变更如渲染器、材质、后处理接口的调整需要逐一适配游戏引擎代码主要涉及GDJS/Runtime/下引用THREE/THREE_ADDONS的文件随后运行 GDJS 测试套件GDJS/tests验证 3D 相关行为没有回归。六、源码级佐证引擎内部如何消费这两个全局3D 模型加载Model3DManagerGDJS/Runtime/Model3DManager.ts 是最典型的消费方用THREE_ADDONS.GLTFLoader与THREE_ADDONS.DRACOLoader配合完成 GLTF/GLB 的解析DRACO 压缩模型需要draco/解码器见 GDJS/Runtime/pixi-renderers/draco/用THREE.Group、THREE.BoxGeometry、THREE.MeshBasicMaterial构造加载失败/占位用的无效模型模型资源缓存类型是THREE_ADDONS.GLTF加载结果通过getModel(resourceName)提供给渲染器。类型声明桥global-three-addons.d.tsGDJS/Runtime/types/global-three-addons.d.ts 通过declare global { namespace THREE_ADDONS { export { ... } } }把 addons 的类型注入全局命名空间与运行时ThreeAddons.js暴露的全局保持一一对应使得引擎源码能够获得完整的类型检查与补全。运行时中的配套文件最终运行时目录里与 Three.js 相关的还有layer-pixi-renderer.ts3D 场景渲染与后处理效果的挂载点以及InGameEditor相关脚本编辑器内 3D 变换控制、物体选择等依赖TransformControls与SelectionBox它们共同构成了 GDevelop 3D 能力的运行时闭环。从这些文件的使用方式可以推断THREE_ADDONS打包内容的选择不是随意的而是精确对应引擎 3D 功能的实际需求清单。结语SharedLibs/ThreeAddons是 GDevelop 3D 功能链路中承上启下的一环上游它把 ESM 形态的 Three.js 生态翻译成引擎能直接加载的经典脚本下游它的产物THREE/THREE_ADDONS被 Model3DManager.ts 等运行时模块稳定消费。维护者在升级 Three.js 时只需牢记三处版本同步 addons 源码更新 重建并复制 引擎适配与测试这条完整链路即可安全完成迭代。【免费下载链接】GDevelop Open-source, cross-platform 2D/3D/multiplayer game engine designed for everyone.项目地址: https://gitcode.com/GitHub_Trending/gd/GDevelop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
GDevelop 的 ThreeAddons 构建与升级指南：为游戏引擎生成经典脚本形式的 Three.js 运行时依赖
GDevelop 的 ThreeAddons 构建与升级指南为游戏引擎生成经典脚本形式的 Three.js 运行时依赖【免费下载链接】GDevelop Open-source, cross-platform 2D/3D/multiplayer game engine designed for everyone.项目地址: https://gitcode.com/GitHub_Trending/gd/GDevelop导读本文聚焦 GDevelop 仓库中 SharedLibs/ThreeAddons 这一构建子项目讲解它如何把现代 ESM 形态的 Three.js 及官方 addons 打包成游戏引擎运行时GDJS/Runtime所需的经典脚本classic script暴露全局变量并给出完整的构建、复制与版本升级流程。读完本文你将掌握three.js与ThreeAddons.js两个运行时产物的生成原理、涉及的 Rollup 打包配置、升级 Three.js 时需要同步修改的多个版本声明位置以及引擎侧如 3D 模型加载实际消费这些全局命名空间的方式从而可以独立完成该子项目的重建与版本维护。一、这个子项目解决什么问题GDevelop 的 JavaScript 游戏引擎运行时GDJS/Runtime所依赖的脚本是经典脚本classic scripts它们通过暴露全局变量来提供能力而不是 ES modules。这意味着运行时里的pixi.js、three.js、ThreeAddons.js都是往全局命名空间塞东西的普通脚本。而 Three.js 官方自r160之后不再提供这种经典构建此前的build/three.min.js/build/three.js等 UMD/全局构建被移除只以 ES modules 形式发布。因此 GDevelop 需要在自己的仓库里从 npm 的three包出发自己打出一份引擎运行时能直接script引用的全局脚本。SharedLibs/ThreeAddons就是为此而存在的构建子项目它产出两个文件产物暴露的全局命名空间内容落点three.jsTHREE完整 Three.js 库直接写入GDJS/Runtime/pixi-renderers/three.jsThreeAddons.jsTHREE_ADDONSGDevelop 用到的 Three.js addons 合集加载器、控制器、后处理……先生成到dist/ThreeAddons.js需手动复制到GDJS/Runtime/pixi-renderers/ThreeAddons.js从源码结构看rollup.config.js 中明确注释了这一动机Three.js 在 r160 之后停止提供经典脚本构建所以改在这里自行打包且产物要与pixi.js一样作为设置全局变量的普通脚本被引擎使用。二、产物与消费方引擎如何依赖这两个全局构建产物最终位于 GDJS/Runtime/pixi-renderers/与pixi.js、layer-pixi-renderer.ts等同目录共存。引擎侧对这两个全局的直接消费可以从以下文件得到源码级确认GDJS/Runtime/Model3DManager.ts3D 模型管理器直接用THREE_ADDONS.GLTFLoader与THREE_ADDONS.DRACOLoader加载 GLTF/GLB 模型this._loader new THREE_ADDONS.GLTFLoader()并用THREE.Group、THREE.BoxGeometry、THREE.MeshBasicMaterial等构造占位网格资源缓存的类型为THREE_ADDONS.GLTF。GDJS/Runtime/types/global-three-addons.d.ts为THREE_ADDONS全局命名空间声明了类型列出了GLTFLoader、GLTF、DRACOLoader、SkeletonUtils、TransformControls、SelectionBox、EffectComposer、OutlinePass、RenderPass、ShaderPass、SMAAPass、OutputPass、UnrealBloomPass、BrightnessContrastShader、ColorCorrectionShader、HueSaturationShader、ExposureShader等导出方便 TypeScript 侧对全局做类型检查。后处理post-processing、3D 场景调试等还会在 layer-pixi-renderer.ts 与编辑器相关脚本如 InGameEditor.tsx中引用这些全局。也就是说THREE承担底层三维数学与渲染THREE_ADDONS承担 GLTF 加载、骨骼处理、变换控制、多通道后处理等高层能力。三、源码结构一个入口、两个打包目标构建子项目的源码非常精简核心只有三个文件SharedLibs/ThreeAddons/ ├── src/ │ ├── index.ts # addons 的汇总入口THREE_ADDONS 的导出清单 │ └── three.ts # 整个 Three.js 库的再导出入口THREE ├── package.json # 依赖与构建脚本 ├── rollup.config.js # 双目标打包配置 └── README.md1.src/three.ts产出THREEthree.ts 内容只有一行export * from three并注释说明重新导出整个 Three.js 库以便把它打包成一个暴露THREE全局的经典脚本。2.src/index.ts产出THREE_ADDONSindex.ts 是 addons 的汇总清单逐条从本地拷贝的官方examples/jsm源码中再导出。当前打包进来的 addons 包括加载器loadersGLTFLoader、DRACOLoader控制器与交互controls / interactiveTransformControls、SelectionBox骨骼/几何工具utilsSkeletonUtils后处理管线postprocessingEffectComposer、RenderPass、OutlinePass、ShaderPass、SMAAPass、OutputPass、UnrealBloomPass着色器shadersBrightnessContrastShader、HueSaturationShader、ExposureShader这些 addons 的源码位于 src/examples/jsm/是从 Three.js 官方仓库的examples/jsm目录拷贝而来。注意 README.md 明确说明这些源码以 MIT 协议授权与 Three.js 本体一致可放心随仓库分发与修改。3.rollup.config.js双目标输出rollup.config.js 定义了两个打包任务任务一输入src/three.tsformat: iifename: THREE同时输出两个文件——开发用的./dist/three.js带 sourcemap和引擎运行时用的../../GDJS/Runtime/pixi-renderers/three.js不带 sourcemap。也就是说构建 three.js 时产物会直接被写入运行时目录无需手动复制。任务二输入src/index.tsformat: umdname: THREE_ADDONS并把three声明为externalglobals: { three: THREE }仅输出./dist/ThreeAddons.js。因为 addons 依赖 Three.js 本体UMD 打包时引用全局THREE即可。两个任务都启用了rollup/plugin-node-resolve把threenpm 包解析进来与rollup/plugin-terser压缩。四、构建与更新运行时文件按照 README.md 的说明重建流程是两条命令npm install npm run build其中npm run build等价于rollup -c见 package.json 的 scripts 定义。构建完成后GDJS/Runtime/pixi-renderers/three.js直接被重新生成Rollup 配置里写死了这个输出路径dist/ThreeAddons.js生成在子项目目录下如果 addons 有变更需要手动复制到GDJS/Runtime/pixi-renderers/ThreeAddons.js。这是因为 three.js 的重建完全由仓库内代码决定而 addons 的输出是否进入运行时需要维护者根据变更范围人工判断README 因此强调to be copied manually ... if the addons changed。本地依赖与构建脚本速览package.json 中与构建相关的关键信息运行时依赖为空three只是devDependencies构建期使用产物自包含核心 devDependenciesthree0.160.0、rollup^2.66.1、rollup/plugin-node-resolve^13.1.3、rollup/plugin-terser^0.4.0、prettier2.1.2附带两个格式检查脚本formatprettier --write src/**/*.ts与check-formatprettier --list-different src/**/*.ts用于保持src下 TypeScript 源码风格统一。五、升级 Three.js 的完整操作清单当需要把运行时使用的 Three.js 升级到新版本时README.md 给出了一套四个步骤的标准流程这里结合仓库实际逐一展开1. 同步三处版本声明不要漏主版本修改 SharedLibs/ThreeAddons/package.json 中的three版本当前为0.160.0。类型声明同步修改 GDJS/package.json 中的types/three当前同样为0.160.0保证引擎 TypeScript 侧的类型与运行时实际使用的库版本一致。编辑器依赖同步修改 newIDE/app/package.json 中的three版本使 IDE编辑器侧的 Three.js 依赖也保持一致。README 特别强调这三处必须保持同步否则可能出现编辑器里看的类型/行为与运行时实际跑的库不一致的问题。2. 更新src/examples中的 addons 源码从 Three.js 官方仓库的最新examples/jsm中把SharedLibs/ThreeAddons/src/examples/下对应文件loaders、controls、postprocessing、shaders、utils 等更新为最新实现确保 addons 与新的 Three.js 核心 API 兼容。3. 重新构建并复制产物执行npm run build然后按第四节说明处理产物three.js已自动写入运行时目录若 addons 有变更将dist/ThreeAddons.js手动复制到GDJS/Runtime/pixi-renderers/ThreeAddons.js。4. 适配引擎代码并跑测试升级后 Three.js 可能引入破坏性 API 变更如渲染器、材质、后处理接口的调整需要逐一适配游戏引擎代码主要涉及GDJS/Runtime/下引用THREE/THREE_ADDONS的文件随后运行 GDJS 测试套件GDJS/tests验证 3D 相关行为没有回归。六、源码级佐证引擎内部如何消费这两个全局3D 模型加载Model3DManagerGDJS/Runtime/Model3DManager.ts 是最典型的消费方用THREE_ADDONS.GLTFLoader与THREE_ADDONS.DRACOLoader配合完成 GLTF/GLB 的解析DRACO 压缩模型需要draco/解码器见 GDJS/Runtime/pixi-renderers/draco/用THREE.Group、THREE.BoxGeometry、THREE.MeshBasicMaterial构造加载失败/占位用的无效模型模型资源缓存类型是THREE_ADDONS.GLTF加载结果通过getModel(resourceName)提供给渲染器。类型声明桥global-three-addons.d.tsGDJS/Runtime/types/global-three-addons.d.ts 通过declare global { namespace THREE_ADDONS { export { ... } } }把 addons 的类型注入全局命名空间与运行时ThreeAddons.js暴露的全局保持一一对应使得引擎源码能够获得完整的类型检查与补全。运行时中的配套文件最终运行时目录里与 Three.js 相关的还有layer-pixi-renderer.ts3D 场景渲染与后处理效果的挂载点以及InGameEditor相关脚本编辑器内 3D 变换控制、物体选择等依赖TransformControls与SelectionBox它们共同构成了 GDevelop 3D 能力的运行时闭环。从这些文件的使用方式可以推断THREE_ADDONS打包内容的选择不是随意的而是精确对应引擎 3D 功能的实际需求清单。结语SharedLibs/ThreeAddons是 GDevelop 3D 功能链路中承上启下的一环上游它把 ESM 形态的 Three.js 生态翻译成引擎能直接加载的经典脚本下游它的产物THREE/THREE_ADDONS被 Model3DManager.ts 等运行时模块稳定消费。维护者在升级 Three.js 时只需牢记三处版本同步 addons 源码更新 重建并复制 引擎适配与测试这条完整链路即可安全完成迭代。【免费下载链接】GDevelop Open-source, cross-platform 2D/3D/multiplayer game engine designed for everyone.项目地址: https://gitcode.com/GitHub_Trending/gd/GDevelop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考