图形学3D渲染游戏开发【免费下载链接】runtimeA typescript interactive engine, support 2D, 3D, animation, physics, built on WebGL and glTF.项目地址https://gitcode.com/gh_mirrors/ru/runtime点击查看免费下载galacean/engine-physics-physx是 Galacean Engine一款基于 WebGL 与 glTF 的 TypeScript 互动引擎中提供真实感物理模拟的可选插件底层封装了 NVIDIA PhysX 引擎的 Web 运行时。读完本文你将掌握该插件的安装与导入方式、PhysX 的 WebAssembly/JavaScript 双运行时机制、物理系统的初始化路径以及碰撞体、刚体、材质、关节与触发事件等核心 API 的使用与源码级实现原理。包安装与导入方式按照包文档README的说明通过 npm 安装插件npm install galacean/engine-physics-physx安装后可以整体导入命名空间也可以按需导入单个类// 整体导入 import * as PHYSICS_PHYSX from galacean/engine-physics-physx; // 或按需导入单个类 import { PhysXPhysics } from galacean/engine-physics-physx;从 package.json 可以看到该包的关键元信息包名为galacean/engine-physics-physx当前仓库内版本为1.6.13采用 MIT 协议产物入口包含dist/main.jsmain、dist/module.jsmodule、dist/browser.jsbrowser以及types/index.d.ts类型声明发布时会将dist/**、libs/**、types/**打进产物其中libs/目录在仓库中对应 libs/physx.release.js、libs/physx.release.downgrade.js 与 libs/physx.release.wasm 这三个 PhysX Web 运行时文件这也解释了为什么自定义运行时 URL 时通常会指向这些文件见下文“自定义运行时地址”一节。galacean/engine以peerDependencies形式声明意味着该插件需要宿主项目同时安装引擎主包。快速上手初始化物理系统README 给出的最简使用流程如下传入画布创建引擎然后用PhysXPhysics初始化物理管理器最后驱动引擎运行。// Create engine by passing in the HTMLCanvasElement id and adjust canvas size const engine await WebGLEngine.create({ canvas: canvas-id }); // Initialize physics manager with PhysXPhysics. engine.physicsManager.initialize(PhysXPhysics); // ...... // Run engine. engine.run();除此之外仓库的端到端测试用例 e2e/case/physx-customUrl.ts 展示了另一种更完整的接入姿势——在WebGLEngine.create时直接通过physics选项传入一个PhysXPhysics实例并指定运行时 URLWebGLEngine.create({ canvas: canvas, physics: new PhysXPhysics(PhysXRuntimeMode.Auto, { wasmModeUrl: ../physx.release.js, javaScriptModeUrl: ../physx.release.downgrade.js }) }).then((engine) { // 后续创建刚体、碰撞体、注册 onTriggerEnter/onTriggerExit 等事件 });该用例中同时演示了 PhysX 后端下的典型玩法为StaticCollider添加isTrigger true的BoxColliderShape、为DynamicCollider设置isKinematic true的SphereColliderShape再通过自定义Script覆写onTriggerEnter / onTriggerExit实现触发事件回调。运行时模式WebAssembly 优先、JavaScript 降级PhysX 的 Web 版提供了两种分发形态PhysXRuntimeMode.ts 中以枚举定义了三种选择策略export enum PhysXRuntimeMode { /** Use webAssembly mode first, if WebAssembly mode is not supported, roll back to JavaScript mode. */ Auto, /** WebAssembly mode. */ WebAssembly, /** JavaScript mode. */ JavaScript }Auto默认值优先使用 WebAssembly 模式不支持时自动回退到纯 JavaScript 模式WebAssembly强制 wasm 模式对应physx.release.jsphysx.release.wasmJavaScript强制降级模式对应physx.release.downgrade.js。检测与加载逻辑位于 PhysXPhysics.ts 的initialize()中。当运行在Auto模式时源码会先构造一个最小 wasm 模块0x00 0x61 0x73 0x6d ...魔数头并用WebAssembly.Module/WebAssembly.Instance探测能力确认支持后加载 wasm 版脚本否则加载降级版脚本if (typeof WebAssembly object typeof WebAssembly.instantiate function) { const wasmModule new WebAssembly.Module(Uint8Array.of(0x0, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00)); if (wasmModule instanceof WebAssembly.Module) return new WebAssembly.Instance(wasmModule) instanceof WebAssembly.Instance; }随后通过动态注入script标签加载对应脚本脚本就绪后再调用全局的window.PHYSX()获得 PhysX 运行时对象。整个initialize()使用内部状态机Uninitialized / Initializing / Initialized做幂等保护重复调用会直接复用同一个 Promise不会重复注入脚本。自定义运行时地址PhysXPhysics构造函数支持通过runtimeUrls覆盖默认下载地址constructor(runtimeMode: PhysXRuntimeMode PhysXRuntimeMode.Auto, runtimeUrls?: PhysXRuntimeUrls)从 PhysXPhysics.ts 可以看到接口定义interface PhysXRuntimeUrls { /*** The URL of PhysXRuntimeMode.WebAssembly mode. */ wasmModeUrl?: string; /*** The URL of PhysXRuntimeMode.JavaScript mode. */ javaScriptModeUrl?: string; }若不传runtimeUrls构造函数会回退到两个默认 CDN 地址mdn.alipayobjects.com域名下的physx.release.js与physx.release.downgrade.js。在实际项目中更常见的做法是把 PhysX 运行时文件如libs/physx.release.js、libs/physx.release.downgrade.js随站点一起部署然后像 e2e/case/physx-customUrl.ts 那样显式传入相对路径避免运行时依赖外部 CDN 的可用性与版本。初始化链路Foundation 到 Physics 的构建过程脚本加载完成后PhysXPhysics._init() 会按 PhysX 官方推荐的顺序搭建整套基础设施const version physX.PX_PHYSICS_VERSION; const defaultErrorCallback new physX.PxDefaultErrorCallback(); const allocator new physX.PxDefaultAllocator(); const pxFoundation physX.PxCreateFoundation(version, allocator, defaultErrorCallback); const tolerancesScale new physX.PxTolerancesScale(); const pxPhysics physX.PxCreatePhysics(version, pxFoundation, tolerancesScale, false, null); physX.PxInitExtensions(pxPhysics, null);即读取运行时版本 → 创建默认错误回调与默认内存分配器 →PxCreateFoundation建立基础层 → 创建PxTolerancesScale容差标度 →PxCreatePhysics建立物理核心 →PxInitExtensions初始化扩展。这些对象分别缓存在实例字段中destroy()时按逆序释放PxCloseExtensions→ release physics/foundation → 删除 allocator、tolerancesScale 与错误回调保证 wasm 侧资源不泄漏。PhysXPhysics 工厂方法全景PhysXPhysics实现了galacean/engine-design包中的IPhysics接口接口定义位于 packages/design/src/physics/ 目录是引擎物理抽象与 PhysX 后端的适配层。它提供了一组工厂方法用于创建物理世界中的各类对象工厂方法返回对象底层实现createPhysicsManager()PhysXPhysicsManagerPhysXPhysicsManager.ts维护触发事件映射表_eventMapcreatePhysicsScene(...)PhysXPhysicsScene创建PxScene接收 contact/trigger 回调createStaticCollider(position, rotation)PhysXStaticCollider静态碰撞体createDynamicCollider(position, rotation)PhysXDynamicCollider内部调用pxPhysics.createRigidDynamic(transform)createCharacterController()PhysXCharacterController角色控制器createPhysicsMaterial(...)PhysXPhysicsMaterial由 staticFriction/dynamicFriction/bounciness/两个 combine 模式构成createBoxColliderShape/createSphereColliderShape/createPlaneColliderShape/createCapsuleColliderShape各类*ColliderShape碰撞形状见 src/shape/ 目录createFixedJoint/createHingeJoint/createSpringJoint各类*Joint约束关节见 src/joint/ 目录此外还提供了碰撞层查询/设置getColliderLayerCollision(layer1: number, layer2: number): boolean setColliderLayerCollision(layer1: number, layer2: number, isCollide: boolean): void它们直接代理到 wasm 运行时的getGroupCollisionFlag / setGroupCollisionFlag用于配置两个碰撞层之间是否发生碰撞。碰撞体一侧的层设置则体现在 PhysXCollider.ts 的setCollisionLayer中通过setGroup(this._pxActor, layer)把 actor 归入指定组。物理场景重力、接触与触发回调PhysXPhysicsScenePhysXPhysicsScene.ts实现了IPhysicsScene接口是 PhysX 场景与引擎回调之间的桥梁。构造时会注册一个PxSimulationEventCallback把 PhysX 的原生事件转发给引擎侧回调接触事件onContactBegin → onContactEnter、onContactEnd → onContactExit、onContactPersist → onContactStay参数为ICollision触发事件onTriggerBegin / onTriggerEnd以碰撞体唯一 ID 的有序对(index1, index2)形式传递内部通过PhysXPhysicsManager._eventMap维护触发状态事件以DisorderedArray 对象池_eventPool的方式零分配复用。场景构造中还初始化了射线检测用的PxRaycastHit与PxQueryFilterData过滤标志为STATIC | DYNAMIC | PRE_FILTER即射线同时可命中静态与动态刚体并走预过滤逻辑。重力则由setGravity(value)直接代理到this._pxScene.setGravity(value)。动态碰撞体力、速度、CCD 与休眠PhysXDynamicCollider.ts 封装了PxRigidDynamic的核心能力是刚体物理中最常用的 API 集合运动学量getLinearVelocity / setLinearVelocity、getAngularVelocity / setAngularVelocity。注意源码中角速度做了角度/弧度互转PhysX 使用弧度引擎侧接口使用角度例如setAngularVelocity内部先MathUtil.degreeToRadian再写入 actor刚体参数setMass、setMassAndUpdateInertia、setCenterOfMass、setInertiaTensor、setMaxAngularVelocity、setMaxDepenetrationVelocity、setSleepThreshold、setSolverIterations、setLinearDamping / setAngularDamping力的施加addForce(force)、addTorque(torque)分别代理到PxRigidDynamic.addForce / addTorque运动学刚体setIsKinematic(true)会打开PxRigidBodyFlag.eKINEMATIC标志此时用move(positionOrRotation, rotation?)设置setKinematicTarget逐帧插值运动——e2e 用例中的运动球体即采用此模式休眠控制sleep()、isSleeping()、wakeUp()自由度锁定setConstraints(flags)代理到setRigidDynamicLockFlags可锁定平移/旋转自由度重力开关setUseGravity(value)通过PxActorFlag.eDISABLE_GRAVITY控制。文件顶部还定义了连续碰撞检测CCD模式枚举setCollisionDetectionMode会映射到对应的PxRigidBodyFlagexport enum CollisionDetectionMode { Discrete, // 关闭 CCD Continuous, // 对静态网格开启 CCDeENABLE_CCD ContinuousDynamic, // 对静态 动态几何开启eENABLE_CCD_FRICTION ContinuousSpeculative // 预测式 CCDeENABLE_SPECULATIVE_CCD }对于高速小物体如子弹从源码结构看应将其collisionDetectionMode设为连续类模式以避免单帧位移超过自身尺寸而穿透薄墙。碰撞体的通用能力增删形状、同步世界变换、设置碰撞层、销毁位于基类 PhysXCollider.tsaddShape / removeShape负责把物理形状 attach/detach 到 actor 并同步场景内的形状集合setWorldTransform以setGlobalPose(..., true)更新 actor 位姿。物理材质与碰撞层PhysXPhysicsMaterialPhysXPhysicsMaterial.ts描述碰撞时摩擦与弹性的处理方式构造函数接收五个参数并调用pxPhysics.createMaterial(staticFriction, dynamicFriction, bounciness)创建底层材质参数含义对应 PhysX APIstaticFriction静摩擦系数setStaticFrictiondynamicFriction动摩擦系数setDynamicFrictionbounciness弹性恢复系数setRestitutionfrictionCombine两材质摩擦的合并模式setFrictionCombineModebounceCombine两材质弹性的合并模式setRestitutionCombineMode合并模式由文件内CombineMode枚举定义Average取平均、Minimum取较小值、Multiply相乘等用于决定两个碰撞物体接触时以哪个材质的参数为准。在 e2e 用例中材质的用法是直接在碰撞形状上修改默认材质属性例如physicsBox.material.staticFriction 0.1; physicsBox.material.dynamicFriction 0.2; physicsBox.material.bounciness 1;碰撞层方面PhysXPhysics.setColliderLayerCollision(layer1, layer2, isCollide)配合碰撞体的setCollisionLayer可以构建层与层之间的碰撞矩阵e2e 测试 e2e/case/physx-collision-group.ts 即围绕该能力展开。端到端验证截图回归测试该插件的行为验证主要依靠仓库根目录下的 Playwright 端到端测试。e2e/case/ 中提供了多个 PhysX 用例physx-collision.ts基础碰撞场景physx-collision-group.ts碰撞分组layer 碰撞矩阵physx-customUrl.ts自定义运行时 URL 的完整接入示例含触发事件与运动学刚体对应的参考截图存放在 e2e/fixtures/originImage/ 下如Physics_physx-collision.jpg、Physics_physx-collision-group.jpg、Physics_physx-customUrl.jpg截图比对逻辑见 e2e/utils/screenshot.ts。这些用例与参考图共同构成了该插件“可复现、可回归”的事实依据任何对galacean/engine-physics-physx的改动都可以通过运行 e2e 截图比对来验证渲染与物理行为是否与基线一致。小结与参考路径包文档packages/physics-physx/README.md核心适配层packages/physics-physx/src/PhysXPhysics.ts、PhysXPhysicsScene.ts、PhysXDynamicCollider.ts、PhysXPhysicsMaterial.ts、PhysXCollider.ts碰撞形状packages/physics-physx/src/shape/关节约束packages/physics-physx/src/joint/运行时文件packages/physics-physx/libs/物理抽象接口定义packages/design/src/physics/端到端用例与基线截图e2e/case/physx-collision.ts、e2e/fixtures/originImage/。需要说明的是该插件与仓库内的galacean/engine-physics-litepackages/physics-lite/面向不同性能需求——PhysX 后端提供刚体动力学、CCD、关节等完整物理能力适合需要真实物理模拟的场景接入前请确认部署环境能加载 PhysX 运行时脚本wasm 或降级 js并在目标浏览器中验证 WebAssembly 支持情况。赞分享图形学3D渲染游戏开发【免费下载链接】runtimeA typescript interactive engine, support 2D, 3D, animation, physics, built on WebGL and glTF.项目地址https://gitcode.com/gh_mirrors/ru/runtime点击查看免费下载相关推荐Galacean Engine Physics-Lite 轻量级物理模块安装、初始化、触发器与碰撞检测实现剖析Galacean Engine Physics Lite 轻量级物理模块安装、初始化、触发器与碰撞检测实现剖析 本篇基于仓库中 packages/physic图形学3D渲染游戏开发探索未来交互的奥秘Galacean Engine探索未来交互的奥秘Galacean Engine Galacean Engine是一个专为现代Web和移动设备设计的高性能实时交互引擎。它采用组件系统设计追图形学3D渲染游戏开发Galacean Runtimegalacean/engine 纯代码开发实践与聚合包构建机制解析Galacean Runtimegalacean/engine 纯代码开发实践与聚合包构建机制解析 本篇技术文章基于 Galacean Engine 的聚合图形学3D渲染游戏开发上一篇如何让任意窗口永远保持在最前面AlwaysOnTop窗口置顶工具完全指南下一篇在电脑上玩Switch游戏Ryujinx从零到流畅运行的完整路径创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考