如何在项目中通过 ESM 导入 PlayCanvas 内置的 playcanvas/scripts 脚本类并挂载到实体【免费下载链接】enginePowerful web graphics runtime built on WebGL, WebGPU, WebXR and glTF项目地址: https://gitcode.com/GitHub_Trending/en/enginePlayCanvas Engine 内置了一组可直接复用的Script类相机控制器、第一/第三人称控制器、标注、程序化天空、高斯泼溅辅助类等它们随playcanvasnpm 包一起发布但不包含在核心引擎 bundle 中——每个脚本类都要从自己的模块路径单独导入再通过实体的script组件挂载。本文以仓库中的 scripts/esm/README.md 和examples/src/examples/下的真实示例为基准给出一条可照抄的完整路径安装 → 导入 → 挂载 → 验证。准备条件npm 包与子路径导出scripts/esm/README.md明确说明这些脚本 ship inside theplaycanvasnpm package but arenotpart of the core engine bundle。也就是说不需要额外安装任何包playcanvas/scripts/*是 npm 包通过子路径导出暴露出来的。package.json 中的exports字段定义了这条映射./scripts/*: ./scripts/*这意味着import ... from playcanvas/scripts/esm/camera-controls.mjs会解析到包内scripts/esm/camera-controls.mjs。仓库当前包版本为2.23.0-beta.7且type: module。在你的项目中npm install playcanvas如果你的项目是 ESMtype: module或使用支持 ES module 的打包器Vite、esbuild 等这条导入可以直接写进代码无需为.mjs做额外转译配置。哪些脚本类可以这样导入内置脚本类位于 scripts/esm/ 目录按功能分目录组织camera/、gsplat/、sky/、vat/、xr/、parsers/另有若干顶层模块。README 列出的范围包括相机与角色控制器——orbit/fly/pan 相机控制、第一、第三人称控制器渲染辅助——基于 camera frame 的后处理、平面反射、shadow catcher、参考网格、程序化天空高斯泼溅——带 LOD 预设的流式 splat 加载、reveal 动画、shader 效果、天气、文字与图像 splatXR——会话生命周期、控制器、传送导航、物体操作与 3D 菜单标注——带 DOM 标签的 3D 热点。导入路径与文件一一对应例如来自examples/src/examples/中的真实 import脚本类模块路径CameraControlsplaycanvas/scripts/esm/camera-controls.mjsFirstPersonControllerplaycanvas/scripts/esm/first-person-controller.mjsThirdPersonControllerplaycanvas/scripts/esm/third-person-controller.mjsProceduralSkyplaycanvas/scripts/esm/sky/procedural-sky.mjsAnnotation,AnnotationManagerplaycanvas/scripts/esm/annotations.mjsVatCharactersplaycanvas/scripts/esm/vat/vat-characters.mjs注意引擎核心 APIVec3、Script、Entity等仍然从playcanvas导入只有脚本类走playcanvas/scripts/...两者不要混在一个 import 里。挂载步骤addComponent(script) script.createREADME 给出的最简挂载模式import { Vec3 } from playcanvas; import { CameraControls } from playcanvas/scripts/esm/camera-controls.mjs; entity.addComponent(script); entity.script.create(CameraControls, { properties: { focusPoint: new Vec3(0, 1, 0) } });三步缺一不可entity.addComponent(script)——先加 script 组件entity.script才能使用entity.script.create(脚本类, { properties })——传入类本身不是实例properties里给脚本的属性设初值脚本类内部标注了attribute的成员如CameraControls的enableFly、enableOrbit、focusDamping等都可以走properties传入README 说明这些属性 can be passed viapropertiesas above, or edited in the PlayCanvas Editor。examples/src/examples/camera/orbit.example.mjs展示了完整的真实用法并演示了第二种属性设置方式——创建后直接赋值const camera new Entity(); camera.addComponent(camera); camera.addComponent(script); camera.setPosition(start); app.root.addChild(camera); const cc /** type { CameraControls} */ (camera.script.create(CameraControls)); const sceneSize bbox.halfExtents.length(); Object.assign(cc, { focusPoint: bbox.center, enableFly: false, moveSpeed: 2 * sceneSize, moveFastSpeed: 4 * sceneSize, moveSlowSpeed: sceneSize });两种写法等价选择初值明确就用properties值依赖运行时计算如上例的sceneSize就取回script.create的返回值再Object.assign。一个最小可运行的自定义脚本示例如果你只是想验证挂载机制本身examples/src/examples/misc/esm-script.example.mjs用的就是一个极小的脚本类 examples/assets/scripts/misc/rotator.mjsimport { Script } from playcanvas; class Rotator extends Script { static scriptName rotator; /** * attribute */ angle 0; update(dt) { this.angle dt; this.entity.setLocalEulerAngles(this.angle * 10, this.angle * 20, this.angle * 30); } } export { Rotator };该示例中的挂载部分const box new Entity(cube); box.addComponent(render, { type: box }); box.addComponent(script); box.script.create(Rotator); app.root.addChild(box);场景运行后盒子持续旋转说明 script 组件的update(dt)每帧被驱动。结果验证挂载是否生效script.create返回脚本实例可以立即读取/设置属性如上例的Object.assign(cc, {...})或在其update中观察场景变化相机响应鼠标/手柄输入、盒子旋转。前置组件缺失CameraControls的构造函数会检查目标实体上的 camera 组件缺失时输出错误日志CameraControls: camera component not found见 scripts/esm/camera-controls.mjs。所以挂CameraControls的实体必须先addComponent(camera)。模式冲突告警同时禁用enableFly与enableOrbit时会输出CameraControls: both fly and orbit modes are disabled此时不会进入任何控制模式——调整属性时至少保留一个。限制与边界脚本类不属于核心 bundle只import playcanvas是拿不到它们的必须按模块路径单独导入不能写成import { CameraControls } from playcanvas。在仓库的 examples browser 环境下playcanvas/scripts/*被登记为共享引擎脚本模块当脚本组件需要的是运行时 URL 字符串而非 JS 导入时要用./scripts/...形式的路径见 examples/README.md 的 Example Modules 一节。在普通项目中直接用 ESM import 即可不需要这条 URL 规则。本文的挂载流程基于AppBase手动装配的componentSystems其中包含ScriptComponentSystem这也是各示例的统一做法createOptions.componentSystems里注册了RenderComponentSystem、CameraComponentSystem、LightComponentSystem、ScriptComponentSystem等见examples/src/examples/camera/orbit.example.mjs。如果你的项目已经能正常创建带 script 组件的实体则可跳过对这段装配的关注。【免费下载链接】enginePowerful web graphics runtime built on WebGL, WebGPU, WebXR and glTF项目地址: https://gitcode.com/GitHub_Trending/en/engine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
