Skip to content
T1KTheOneKit

t1k:unity:dots-combat:physics

FieldValue
Moduledots-combat
Version2.3.8
Efforthigh
Tools—

Keywords: collision, DOTS, physics, rigidbody

How to invoke

Section titled “How to invoke”
/t1k:unity:dots-combat:physics

Unity DOTS Physics

Section titled “Unity DOTS Physics”

Skill Purpose

Section titled “Skill Purpose”

This skill provides a complete reference for Unity Physics 1.4.5 in ECS/DOTS. To implement any physics feature, consult the relevant reference file listed below before writing code.

Prerequisite: dots-ecs skill (ISystem, Baker, SystemAPI, ECB patterns).

When This Skill Triggers

Section titled “When This Skill Triggers”
  • “add physics to entity”, “rigid body”, “PhysicsCollider”, “PhysicsVelocity”
  • “raycast”, “spherecast”, “collider cast”, “distance query”, “overlap”
  • “collision event”, “trigger event”, “OnCollision”, “OnTrigger”
  • “physics joint”, “hinge”, “ball socket”, “prismatic”, “motor”
  • “PhysicsShape”, “PhysicsBody”, “bake physics”, “physics authoring”
  • “FixedStepSimulationSystemGroup”, “PhysicsSimulationGroup”

Quick Reference

Section titled “Quick Reference”
TopicReference File
Components, collider factory, entity creation, collision filters, compound colliderscomponents-setup-guide.md
Raycasting, sphere/box casts, point distance, overlap, batched queriesqueries-raycasting-guide.md
Collision events, trigger events, stateful enter/stay/exit eventsevents-guide.md
Joints, motors, forces, impulses, PhysicsCustomTagsjoints-forces-guide.md
Baking, custom bakers, PhysicsStep config, system orderingauthoring-config-guide.md
Advanced queries — custom collectors, compound collider casts, query optimizationqueries-advanced-guide.md

Terminology

Section titled “Terminology”
  • DOTS — Data-Oriented Technology Stack
  • ECS — Entity Component System
  • ECB — EntityCommandBuffer

Key Conventions

Section titled “Key Conventions”
  • Namespace: DOTSAI.Physics
  • Static body: LocalTransform + LocalToWorld + PhysicsCollider + PhysicsWorldIndex
  • Dynamic body: add PhysicsVelocity + PhysicsMass + PhysicsDamping + PhysicsGravityFactor
  • To query physics world, use SystemAPI.GetSingleton<PhysicsWorldSingleton>() in OnUpdate only
  • To receive collision events, set collider Collision Response = Raise Collision Events
  • To receive trigger events, set collider Collision Response = Raise Trigger Events
  • To modify a shared collider blob at runtime, call MakeUnique before writing
  • System ordering: run before PhysicsSystemGroup to read broadphase; after PhysicsSimulationGroup to handle events
  • PhysicsVelocity.Angular is in local body space
  • At least one body in a joint pair must have PhysicsVelocity
  • Do not add PhysicsVelocity to static bodies

Performance Rules

Section titled “Performance Rules”
  • Always Burst-compile physics systems — [BurstCompile] on struct and methods
  • Use CollisionWorld.CastRay (DOTS Physics) — never UnityEngine.Physics.Raycast (managed, can’t see SubScene-baked colliders)
  • Batch queries when possible — use NativeArray<RaycastInput> with CollisionWorld.CastRay overloads for multiple rays
  • Use CollisionFilter to narrow ray/overlap scope — reduces broadphase checks
  • Cache PhysicsWorldSingleton at the start of OnUpdate — avoid multiple GetSingleton calls
  • System ordering matters — read physics state BEFORE PhysicsSystemGroup; handle events AFTER PhysicsSimulationGroup
  • Use [ReadOnly] CollisionWorld in parallel jobs — physics world is read-only after step
  • Avoid MakeUnique in hot paths — it copies the entire blob. Do it once during setup, not every frame

Common Gotchas

Section titled “Common Gotchas”
IssueFix
Events not firingCollider Collision Response must be set to raise events
GetSingleton failsCall in OnUpdate, not OnCreate
Collider changes lostCall MakeUnique before modifying shared blob
Joint has no effectAt least one body must have PhysicsVelocity
Static body movesRemove PhysicsVelocity from static bodies
Stale query dataUse [UpdateBefore(typeof(PhysicsSystemGroup))]
Custom PhysicsBodyAuthoring missingImport “Custom Physics Authoring” sample from Package Manager
Classic raycasts miss SubScene entitiesUse DOTS CollisionWorld.CastRay, not UnityEngine.Physics.Raycast

Simulation Pipeline (from Unity Physics docs)

Section titled “Simulation Pipeline (from Unity Physics docs)”
1. Physics World Building  → CollisionWorld + DynamicsWorld from entity components
2. Broadphase Detection    → bounding volume pair identification
3. Narrowphase Detection   → actual contacts and penetration depth
4. Constraint Solver       → collision response + joint constraints → velocity updates
5. Integration             → advance bodies by timestep
6. Export                  → write positions/orientations to entities

CollisionFilter Quick Reference

Section titled “CollisionFilter Quick Reference”
// Two colliders interact when: (A.BelongsTo & B.CollidesWith) != 0 AND (B.BelongsTo & A.CollidesWith) != 0
new CollisionFilter
{
    BelongsTo    = 1u << layerIndex,  // which layer(s) this collider is on
    CollidesWith = 1u << otherLayer,  // which layer(s) to interact with
    GroupIndex   = 0                  // positive = force collide, negative = force ignore (same pair)
}

Documentation

Section titled “Documentation”