RayFire for Unity 使用文档

RayFire for Unity 使用文档本文档基于 坦克项目Unity 2022实战集成经验整理所有坑点均已在项目实际复现并解决。一、插件概述RayFire 是 Unity 上一款专业级物理破碎与实时粉碎特效插件核心能力运行时无限次拆除/切片3D 对象编辑器预破碎提前生成碎片运行时仅实例化性能优异多种破碎算法Voronoi、Splinters、Slabs、Radial、Slices、Bricks、Voxels 等支持 Skinned Mesh可对带骨骼动画的角色/坦克进行破碎OpenFracture 不支持完整物理模拟碎片受重力、碰撞、爆炸力影响累积伤害系统内置 RFDamage可实现打几下才坍塌的效果二、核心组件组件作用RayfireRigid核心组件挂在可破碎物体上控制物理模拟与破碎行为RayfireShatter编辑器预破碎工具定义碎片形状与分布RayfireBomb爆炸物组件挂在空物体上产生范围爆炸力RayfireGun枪械组件挂在空物体上发射冲击射线RayfireActivator激活器激活 Inactive 物体进入物理模拟RayfireBlade切割器对 Rigid 物体进行平面切片RayfireConnectivity连通性组件模拟柱状结构局部破损后上部坍塌RayfireUnyielding固定区标记 Connectivity 集群中不参与破碎的区域RayfireMan全局管理器定义材质预设、碎片池等三、RayfireRigid 组件详解3.1 Initialization初始化方式选项说明By Method默认值需代码调用Initialize()才初始化At StartStart 时自动初始化推荐用于建筑物3.2 Main主设置Simulation Type模拟类型类型行为适用场景Dynamic受重力下落可被其他物体影响悬空物体、掉落碎片Sleeping冻结直到首次碰撞然后转为 Dynamic建筑物最常用避免初始下落Inactive冻结需被激活才转为 Dynamic需要触发激活的场景Kinematic用动画影响其他物体但自身不受影响移动平台、撞击锤Static完全不动仅与 Dynamic 物体交互地面、固定墙体Object Type对象类型类型说明Mesh单个物体用自身 MeshFilter 网格模拟Mesh Root空父物体自动给所有带网格的直接子物体添加 RigidSkinned Mesh破碎 SkinnedMesh角色/坦克Nested Cluster所有子物体作为一个整体凸体破碎时子物体独立飞散Connected Cluster类似 Nested但只取第一层子物体破碎按接触点局部脱落重要坑MeshRoot只处理直接子物体深层嵌套的子物体会被跳过。如模型是深层结构要么重组层级要么手动在每个部件上添加 RayfireRigid。Demolition Type破碎类型类型说明性能None不破碎-Runtime碰撞时实时生成碎片最慢低多边形适用Awake PrecacheAwake 时缓存碎片网格数据碰撞时创建 GameObject推荐平衡性能与内存Awake PrefragmentAwake 时预破碎所有碎片禁用等待触发内存占用高运行时最快Manual Prefab Precache手动缓存到预制体可保存为资产预制体场景推荐Manual Precache手动缓存不可存为预制体编辑器预生成Manual Prefragment手动预破碎编辑器预生成Reference Demolition用预设的引用物体替换破碎特殊场景重要坑使用RayfireShatter自定义碎片形状时Demolition Type必须设为 Awake Precache才能生效。3.3 Demolition破碎限制参数说明推荐值Solidity物体坚固度越低越易碎0 一碰就碎0.3~1Depth破碎深度递归次数0 无限1~2街机项目Time破碎后保护时间秒防止碎片刚生成就二次破碎3Size最小破碎尺寸小于此值不再破碎0.1~0.5Slice by Blade允许被 Blade 组件切割按需3.4 Damage累积伤害— 本项目核心参数说明推荐值Enable必须勾选才能累积伤害✅Max伤害阈值达到后自动 Demolish100子弹 damage30 时约打4发Current运行时自动累积不用手动设置-Collect收集伤害✅Multiplier伤害倍率1To Shards用于 ConnectedCluster⬜重要坑ApplyDamage内部先检查damage.en如果 Enable 没勾选伤害不会累积更不会触发破碎。3.5 Mesh Demolition → Fragments碎片参数参数说明推荐值Amount碎片数量10~30街机/ 50~200PC 高配Variation数量随机变化百分比10Depth Fade下一级深度的碎片数量倍数0.5Contact Bias接触点附近碎片更小更密集远处更大0.5~1Seed随机种子相同种子产生相同碎片按需Use Shatter使用 RayfireShatter 组件定义的碎片形状需配合 Awake PrecacheAdvanced 子区块本项目关键配置参数说明本项目值Clusterize集群化处理⬜Collider碎片碰撞体类型Mesh / Box / Sphere / NoneBox关键Size Filter小于此尺寸的碎片不加碰撞体0.1Remove Collinear移除共线顶点减少三角形✅重要坑默认 ColliderMesh 时薄壁/平面网格的碎片顶点数 coplanarVertLimitConvexHull 失败会报错Less than four valid vertices were found。必须改为 Box。3.6 Activation激活方式仅对Inactive模拟类型有效激活方式说明By Velocity速度超过阈值时激活By Offset位移超过阈值时激活By Damage伤害值超过阈值时激活By Activator被 RayfireActivator 组件激活By Impact被 RayfireGun 射中时激活By Connectivity失去与其他 Inactive 物体的连接时激活重要坑如果想让By Velocity等激活参数生效Demolition Type 必须设为 None否则会失效。四、基础使用流程流程 1运行时动态破碎最简单适用子弹/爆炸实时破坏建筑物1. 场景中放置 Cube或其他带网格物体 2. Add Component → RayfireRigid 3. 配置 - Simulation Type Sleeping - Object Type Mesh - Demolition Type Awake Precache推荐或 Runtime - Fragments → Amount 15 - Fragments → Advanced → Collider Box关键 - Damage → Enable ✅, Max 100 4. 运行场景用刚体物体撞击它即可破碎流程 2空父物体 多个子物体本项目建筑物方案适用复杂建筑物由多个 Mesh 组成1. 层级结构 Building空父物体挂 RayfireRigidObjectTypeMeshRoot ├─ Wall_01带 MeshFilter BoxColliderIs Triggerfalse ├─ Wall_02带 MeshFilter BoxColliderIs Triggerfalse └─ Pillar带 MeshFilter BoxColliderIs Triggerfalse 2. 父物体 RayfireRigid 配置 - Object Type Mesh Root - Simulation Type Sleeping - Demolition Type Awake Precache 或 Runtime - Physics → Collider Type Box - Damage → Enable ✅, Max 100 - Physics → Planar Check ⬜关闭否则薄壁网格不加碰撞体 3. 每个子物体必须有 ColliderBox Collider 推荐Mesh Collider 报错率高 4. 点击 Editor Setup 按钮可选 - 自动在每个直接子物体上添加子 RayfireRigid - 自动创建子物体 BoxCollider 5. 重要MeshRoot 自身不能 Demolish伤害必须施加在子物体的 RayfireRigid 上流程 3使用 Bomb 爆炸本项目爆破怪方案适用爆破怪、手雷、C4 等范围爆炸1. 可破碎物体按流程 1配置 RayfireRigid 2. 在爆炸点创建空 GameObjectAdd Component → RayfireBomb 3. 配置 RayfireBomb - Range 10爆炸半径 - Force 500爆炸力 4. 代码触发爆炸 bomb.Explode(0f); // 0 表示立即爆炸 5. 避免冲击玩家设置 Explosion Force Layer 仅含 Fracturable 层流程 4使用 Gun 射击本项目不需要RayfireGun子弹系统自行调用ApplyDamage累积伤害。1. 可破碎物体按流程 1配置 RayfireRigid 2. 在枪口位置创建空 GameObjectAdd Component → RayfireGun 3. 配置 RayfireGun - Range 100 - Force 300 - Radius 0.5冲击影响半径 4. 代码触发射击 gun.Shoot();流程 5编辑器预破碎性能最优适用性能敏感场景运行时仅实例化1. 选中物体Add Component → RayfireShatter 2. 配置 Shatter - Type Voronoi或其他碎片类型 - Amount 20 3. 点击 Shatter 按钮编辑器中生成碎片 4. 给碎片根物体添加 RayfireRigidDemolition Type None 5. 运行时通过代码触发rigid.DemolishObject();五、碎片形状类型RayfireShatter类型说明适用场景Voronoi沃罗诺伊图低多边形凸面碎片通用默认石头、混凝土Splinters木片状沿一个轴排列木材、木板Slabs石板状沿两个轴排列墙体、石板Radial径向碎片图案玻璃、圆盘Custom自定义点云分布精细控制Slices平面分割蛋糕式切片Bricks砖块状砖墙Voxels体素化方块风格Tets四面体配合胶合使用六、代码 API 速查usingRayFire;// 初始化Initialization By Method 时需要RayfireRigidrigidGetComponentRayfireRigid();rigid.Initialize();// 累积伤害达到 damage.max 后自动 Demolishrigid.ApplyDamage(damage,hitPosition,radius,hitCollider);// 触发破碎不经过伤害累积立即破碎rigid.DemolishObject();// 激活 Inactive 物体rigid.Activate();// 平面切片Vector3[]slicePlanesnewVector3[]{newVector3(0,1,0),newVector3(0,1,0),// 位置, 法线};rigid.AddSlicePlane(slicePlanes);// Bomb 爆炸RayfireBombbombGetComponentRayfireBomb();bomb.Explode(0f);// 0 立即爆炸0 延迟秒数// Gun 射击RayfireGungunGetComponentRayfireGun();gun.Shoot();6.1 ApplyDamage 重载说明重载适用场景ApplyDamage(damage, pos, radius, collider)完整版命中位置、影响半径、命中碰撞体仅对 ConnectedCluster 的 shard 级别有意义ApplyDamage(damage, pos, radius)简化版ApplyDamage(damage, pos)最简版对 MeshRoot/Mesh 类型的简单建筑物用最简版即可rigid.ApplyDamage(buildingDamage, transform.position, 0f)。七、常见坑与解决方案7.1 基础坑必读坑原因解决物体不破碎Demolition Type None改为 Awake Precache 或 RuntimeMesh Collider 不破碎Unity 物理限制换成 Box ColliderBy Velocity 不生效Demolition Type 非 None设为 NoneShatter 自定义形状不生效Demolition Type 不对必须设为 Awake Precache子物体错位下落Simulation Type Dynamic改为 Sleeping 或 Inactive碎片无限递归破碎Depth 0设为 1 或 2SkinnedMesh 无法破碎OpenFracture 不支持用 RayFire 的 Skinned Mesh 类型粉色材质URP 不兼容 Standard Shader替换为 URP/Lit预制体无法保存碎片网格Unity Mesh 不可序列化用 Manual Prefab Precache7.2 本项目实战踩坑点重点坑 1Mesh is not readable — Demolition type set to None日志RayFire Rigid: jctBld50C_btm_lod0 Mesh is not readable. Demolition type set to None.原因模型导入时未启用 Read/Write EnabledRayFire 强制将 Demolition Type 设为 None。解决Project 窗口选中模型文件Inspector → Model → 勾选Read/Write Enabled点击Apply本项目坑点模型常常以 LOD 形式存在*_lod0/*_lod1等每个 LOD 都要单独设置。坑 2had planar low poly mesh — Object can’t get Mesh Collider日志RayFire Rigid: jctBld50C_btm_lod0_fr_502 had planar low poly mesh. Object cant get Mesh Collider.原因Physics → Planar Check 默认开启。检测到薄壁/平面网格顶点数 coplanarVertLimit时把 Collider Type 设为 None导致后续 OnTriggerEnter / OnCollisionEnter 检测不到该物体。解决任选其一方案A推荐Physics → Type 设为Box方案BPhysics → 取消勾选Planar Check坑 3ConvexHull 失败 — Less than four valid vertices日志[Physics.PhysX] ConvexHullLib::cleanupVertices: Less than four valid vertices [Physics.PhysX] Failed to create Convex Mesh from source mesh 328.原因碎片太小顶点数 4无法生成 Convex MeshCollider。这是由Mesh Demolition → Fragments → Advanced → Collider默认值 Mesh 引起的。解决Mesh Demolition → Fragments → Advanced →Collider设为Box不是 Physics 区的 Type是 Fragments 子区块顺便设置Size Filter 0.1过滤掉过小碎片本项目坑点Physics 区的Type给原物体加的碰撞体和 Fragments 区的Collider给碎片加的碰撞体是两个独立配置。两个都要设为 Box 才能避免所有 ConvexHull 报错。坑 4MeshRoot 类型不响应 Demolish根因源码RFDemolitionMesh.cs:214限制if(scr.objectType!ObjectType.Meshscr.objectType!ObjectType.SkinnedMesh)returntrue;// MeshRoot 直接跳过不执行破碎场景子弹击中子物体 →GetComponentInParent找到父级 MeshRoot → 伤害累积到阈值 → 调用Demolish()→ MeshRoot 类型直接跳过 →不破碎。解决任选其一方案A推荐点击父物体 RayfireRigid 的Editor Setup按钮让 RayFire 自动在每个直接子物体上添加独立的 RayfireRigidObjectTypeMesh子弹直接命中子物体的 Rigid方案B代码中检测到 MeshRoot 时改为获取子物体自己的 Rigidif(rigid.objectTypeObjectType.MeshRoot){rigidother.GetComponentRayfireRigid();// 子物体自己的}坑 5子弹 Trigger 物体 Collider 触发不到根因Unity 物理规则——两个 Trigger 之间不会触发OnTriggerEnter必须一方是非 Trigger。解决子弹的 CapsuleCollider 保持Is Trigger true不要改建筑物子物体用BoxColliderIs Trigger falseRayFire 不会自动给子物体加非Trigger的 Collider坑 6Initialization By Method 导致死循环根因没有碰撞体 → 子弹检测不到建筑物 → ApplyDamage 不被调用 → Initialize() 不执行 → 碰撞体永远不创建 → 死循环解决Initialization 必须设为At Start让 Awake 时自动 Initialize 创建碰撞体。坑 7ExploderMonster 爆炸冲击玩家坦克根因RayfireBomb 的 mask 默认 -1所有层爆炸力会作用于所有带 Rigidbody 的对象包括玩家坦克。解决在子物体下挂RayfireBomb时将Explosion Force Layer设为仅含 Fracturable 层排除 Player 层。7.3 进阶坑坑 8运行时未受外力部分模型自动破碎原因使用 MeshCollider 时碎片连接处几乎必然发生碰撞导致自我破碎。解决在 RayfireRigid 中勾选Ignore Near让碎片之间不互相碰撞只有外力才会破碎。坑 9一运行物体直接掉下去原因Simulation Type 设为 Dynamic开局即判定为掉落。解决将 Simulation Type改为Inactive或Sleeping物体冻结在空中等待激活/碰撞。坑 10碰撞发生了碎片只位移不掉落原因没有设置激活条件碎片只是被推开但未进入 Dynamic 状态。解决在 Activation 中设置激活条件例如By Offset 0.2位移超过 0.2 米时激活掉落或其他激活方式By Velocity / By Damage / By Impact 等坑 11高楼建筑底部塌了上层浮空原因碎片之间没有连通性底部碎片掉落后上层碎片没有受力源。解决使用RayfireConnectivity组件给建筑物挂载 RayfireConnectivity默认设置即可在 RayfireRigid 中勾选By Connectivity激活方式这样碎块连接为一个整体底部塌陷时会带动上层坑 12使用 Connectivity 后整栋建筑一起被撞飞原因Connectivity 让所有碎块成为整体碰撞力传递到整栋建筑没有固定点。解决使用RayfireUnyielding组件设置地基在建筑物底部挂载 RayfireUnyielding设置 Size 定义地基范围地基区域固定不动其余部分受 Connectivity 约束7.4 高楼建筑坍塌完整方案1. 建筑物挂载 RayfireRigid - Simulation Type Inactive - Demolition Type Awake Precache - Activation → By Connectivity 勾选 2. 建筑物挂载 RayfireConnectivity - Clusterize 勾选 - Demolishable 勾选关键让集群倒塌时进一步破碎 3. 建筑物底部挂载 RayfireUnyielding - Size 调整为覆盖地基区域 4. 碰撞触发后效果 - 接触点局部碎裂 - 底部碎块掉落上层保持整体 - 上层倒塌撞地时进一步破碎Demolishable 生效 - 实现逐渐坍塌而非瞬间粉碎7.5 多个 RayfireRigid 物体重叠时互相碰撞场景桥梁有桥面钢筋和桥下桥墩多个独立模型互相穿插挂上 RayfireRigid 后立即触发碰撞。解决使用 Layer 隔离为不同 Rayfire 物体分配不同 Layer如RayfireStructure/RayfirePillarEdit → Project Settings → Physics中取消这两个 Layer 之间的碰撞勾选这样重叠的 Rayfire 物体互不影响只响应外力碰撞八、SkinnedMesh 使用注意事项8.1 选择正确的 ObjectType在 RayfireRigid 中必须将ObjectType设为SkinnedMesh枚举值为 2组件会自动检测并处理SkinnedMeshRenderer。8.2 破碎效果限制骨骼动画影响SkinnedMesh 的破碎效果不如普通 Mesh 理想骨骼动画会影响破碎后碎片的行为建议静止状态破碎在模型静止时触发破碎避免动画状态下破碎导致碎片位置异常8.3 性能开销SkinnedMesh 破碎计算量较大特别是运行时实时破碎建议限制碎片数量通过 RayfireRigid 的 Limitations 参数对于复杂模型考虑预破碎预制体8.4 材质与纹理确保 SkinnedMeshRenderer 的材质和纹理设置正确破碎后碎片会继承原始材质。8.5 替代方案推荐对于需要良好破碎效果的模型建议在 3D 软件中拆分为多个 Mesh 部件使用MeshRoot类型获得更好的破碎效果和性能九、与本项目集成现状9.1 子弹命中建筑物参考 [RTCTankBullet.cs](file:///d:/Projects/G320/UnityProject/G320/Assets/Packages/Physics%20Based%20Tank%20Controller/Scripts/RTCTankBullet.cs) 的TryFractureBuildingprivatevoidTryFractureBuilding(Colliderother){if(othernull)return;RayfireRigidrigidother.GetComponentRayfireRigid();if(rigidnull)rigidother.GetComponentInParentRayfireRigid();if(rigidnull)return;rigid.ApplyDamage(buildingDamage,transform.position,0f);}本项目建筑物配置配置项值Object TypeMesh RootSimulation TypeSleepingDemolition TypeAwake Precache / RuntimePhysics → TypeBoxPhysics → Planar Check⬜Fragments → Advanced → ColliderBoxFragments → Advanced → Size Filter0.1Damage → Enable✅Damage → Max100InitializationAt Start子弹配置buildingDamage 30打4发左右坍塌子弹 CapsuleColliderIs Trigger true建筑物子物体 BoxColliderIs Trigger false9.2 爆破怪自身爆炸参考 [ExploderMonster.cs](file:///d:/Projects/G320/UnityProject/G320/Assets/Scripts/Monster/ExploderMonster.cs)// TriggerSelfDestruction 中if(_rayfireRigid!null)_rayfireRigid.Initialize();if(_rayfireBomb!null){_rayfireBomb.strengthselfExplosionForce;_rayfireBomb.rangeexplodeRadius;_rayfireBomb.Explode(0f);}关键配置Explosion Force Layer 仅 Fracturable 层避免冲击玩家坦克Initialization At Start模型需要 Read/Write Enabled9.3 集成检查清单模型导入启用 Read/Write EnabledInitialization At StartPhysics → Type BoxPhysics → Planar Check ⬜Fragments → Advanced → Collider BoxFragments → Advanced → Size Filter 0.1Demolition Type Awake Precache 或 RuntimeDamage → Enable ✅, Max 0Simulation Type Sleeping建筑物/ Dynamic爆破怪子物体有 BoxCollider 且 Is Trigger falseMeshRoot 父物体已点击 Editor Setup或代码中处理 MeshRoot 跳过十、性能优化建议优先使用预破碎Awake Prefragment 或 Manual Prefragment运行时零计算开销限制 Depth设为 1 或 2避免碎片无限递归设置 Size 限制小于阈值的碎片不再破碎减少碎片数量使用 Sleeping 模式未碰撞时不参与物理计算碎片对象池RayfireMan 组件可配置碎片池复用简化碎片 Collider小碎片用BoxCollider 代替 Mesh Collider避免 ConvexHull 报错异步缓存Runtime Caching 设为 By Frames分帧生成碎片避免卡顿LOD 模型每个 LOD 都要单独设置 Read/Write Enabled十一、参考资源官方文档 - Rigid ComponentCSDN - 破碎插件 RayFire 的使用CSDN - Rayfire Rigid 组件参数含义CSDN - 使用 bomb 或 gun 摧毁物体CSDN - Activation By Velocity 不生效问题CSDN - unity Rayfire 破碎插件的踩坑点B站 - RayFire for Unity 教程视频B站专栏 - RayFire 使用心得CSDN - Rayfire Connectivity 组件