Use DOTS Physics for Collisions

Code and workflows to update collisions that change material and destroy prefab entities using DOTS Physics
What will be developed on this page
We will update our project so that bullet collisions cause the material of the colliding entity to change and for the entity to be destroyed
Github branch link: https://github.com/moetsi/Unity-DOTS-Multiplayer-XR-Sample/tree/Updating-Bullets-to-Destroy​
​Join our Discord for more info​
Adding trigger events
First, some background:
We have mostly used .ForEach() and Job.WithCode() in this project. At their core, both of these interfaces run "jobs." When we implement our trigger events for bullet collisions we will also be using jobs, but some of the code will be using the core job interface. In some of the files we will be examining you can see the "job" struct.
Open the downloaded EntityComponentSystemSamples repo and navigate to Demos > 2. Setup > 2d. Events > Scripts > Stateful and Demos > 2. Setup > 2d. Events > 2d1. Triggers > Scripts
There are 6 files that we are going to base our bullet interactions on
in /2d. Events/Scripts/Stateful
1. IStatefulSimulationEvent.cs
2. StatefulSimulationEventBuffers.cs
3. StatefulTriggerEvent.cs
4. StatefulTriggerEventBufferAuthoring.cs
5. StatefulTriggerEventBufferSystem.cs
in /2d. Events/2d1. Triggers/Scripts
6. TriggerVolumeChangeMaterialAuthoring.cs
The first 5 files purpose is to take DOTS Physics TriggerEvents (which are stateless) and convert them to StatefulTriggerEvents. "Stateless" means that Unity Physics doesn't know what happened "before" ("before" = the previous "state"). So when 2 Physics bodies interact, there is no iterface to know if they "just" interacted this frame, or if they have already interacted. 
Classic MonoBehavior physics provided stateful methods like "OnTriggerEnter" and "OnTriggerStay" and "OnTriggerExit". The first 5 files in /2d. Events/Scripts/Stateful job is to provide the same type of functionality when using DOTS Physics. The ability to know when an interaction is Enter/Stay/Exit.
The states are defined in  IStatefulSimulationEvent.cs as an enum "StatefulEventState"
Undefined
Enter
Stay
Exit
StatefulTriggerEvent.cs defines the new StatefulTriggerEvent interface which is very similar to TriggerEvent but with the addition of the StatefulEventState
StatefulTriggerEventBufferAuthoring.cs is used to for Authoring and is meant to be placed on prefabs to provide it a component that can hold a buffer of StatefulTriggerEvents
StatefulSimulationEventBuffers.cs provides jobs used by StatefulTriggerEventBufferSystem.cs to convert TriggerEvents into StatefulEventStates and place them in the buffer provided by StatefulTriggerEventBufferAuthoring.cs
TriggerVolumeChangeMaterialAuthoring.cs uses StatefulTriggerEvents on the prefabs to change materials based on interactions
Let's take a deeper look into StatefulTriggerEventBufferSystem.cs to understand a bit more about Dependencies and scheduling. Unity Physics Upgrade guide for 0.7 can help us understand what is going on.
RegisterPhysicsRuntimeSystemReadOnly() and RegisterPhysicsRuntimeSystemReadWrite() (both registered as extensions of SystemBase) should be used to manage physics data dependencies instead of the old AddInputDependency() and GetOutputDependency() approach. Users should declare their UpdateBefore and UpdateAfter systems as before and additionally only call one of the two new functions in their system's OnStartRunning(), which will be enough to get an automatic update of the Dependency property without the need for manually combining the dependencies as before. Note that things have not changed if you want to read or write physics runtime data directly in your system's OnUpdate() - in that case, you still need to ensure that jobs from previous systems touching physics runtime data are complete, by completing the Dependency. Also note that BuildPhysicsWorld.AddInputDependencyToComplete() still remains needed for jobs that need to finish before any changes are made to the PhysicsWorld, if your system is not scheduled in between other 2 physics systems that will do that for you.
StatefulTriggerEventBufferSystem
This is the system that takes the intermediate results of the Solver (which are stateless) and assigns them state (enter, stay, and exit)
You can see that (following the instructions from the v0.7 upgrade guide) we are declaring when this system should be run, after running the StepPhysicsWorld and before EndFramePhysicsSystem
[UpdateInGroup(typeof(FixedStepSimulationSystemGroup))]
[UpdateAfter(typeof(StepPhysicsWorld))]
[UpdateBefore(typeof(EndFramePhysicsSystem))]
We also call RegisterPhysicsRuntimeSystemReadOnly() as described in the upgrade guide
    protected override void OnStartRunning()
    {
        base.OnStartRunning();
        this.RegisterPhysicsRuntimeSystemReadOnly();
    }
We can see in StatefulTriggerEventBufferSystem's OnUpdate() that we also follow the note from the v0.7 upgrade guide that "if you want to read or write physics runtime data directly in your system's OnUpdate() - in that case, you still need to ensure that jobs from previous systems touching physics runtime data are complete, by completing the Dependency"
        Dependency = new StatefulEventCollectionJobs.CollectTriggerEvents
        {
            TriggerEvents = currentEvents
        }.Schedule(m_StepPhysicsWorld.Simulation, Dependency);
We schedule a StatefulEventCollectionJobs.CollectTriggerEvents job (which itself we define as dependent on  StepPhysicsWorld.Simulation) and add the resulting dependency to StatefulTriggerEventBufferSystem's OnUpdate() job
That means this system is dependent on the results of that system to perform its operations
This makes sense because we need to grab the results of the Solver (which occurs during StepPhysicsWorld.Simulation) to get the trigger events
Otherwise we would be trying to convert TriggerEvents to StatefulTriggerEvents before the TriggerEvents have been calculated (no good! can't convert something that doesn't exist yet!)
You can see the requirements for for TriggerEvents to be transformed to StatefulTriggerEvents and stored in a Dynamic Buffer at the top of StatefulSimulationEventBuffers.cs
1) 'Raise Trigger Events' option of the 'Collision Response' on PhysicsShapeAuthoring on the entity that should raise trigger events
2) Add a StatefulTriggerEventBufferAuthoring component to that entity
3) If this is desired on a Character Controller, tick "RaiseTriggerEvents" on CharacterControllerAuthoring (and skip (1) and (2))
We already chose "Raise Trigger Events" on our bullet prefab so we are set there, and we will add StatefulTriggerEventBufferAuthoring on the bullet
​
Now take a look at TriggerVolumeChangeMaterialAuthoring.cs
Taking a look at TriggerVolumeChangeMaterialAuthoring from Unity DOTS Physics sample repo
This file also has an implementation of the IConvertGameObjectToEntity interface
This adds the "TriggerVolumeChangeMaterial" Component (defined at the top of the file) to the converted GameObject
It will grab whatever GameObject we drag onto the public field "ReferenceGameObject" in TriggerVolumeChangeMaterialAuthoring and set it as the ReferenceEntity field of the TriggerVolumeChangeMaterial Component
Or, if the public field is left null,  IConvertGameObjectToEntity will set the reference entity as the GameObject too
This ReferenceEntity is used further down to reset the material to the same material as the ReferenceEntity
Let's keep moving down the file...
TriggerVolumeChangeMaterialSystem
There are a couple of decorators at the top of the file
[UpdateInGroup(typeof(FixedStepSimulationSystemGroup))]
FixedStepSimulationSystemGroup is the system group we reviewed in the previous section
[UpdateAfter(typeof(StatefulTriggerEventBufferSystem))]
StatefulTriggerEventBufferSystemis the system from the previous file we just reviewed
This makes sense because we want to perform our actions in the simulation and after we have created our stateful triggers
This makes sense because we need the stateful triggers produced by TriggerEventConversionSystem to exist if we want to act on them
Now, in the OnUpdate() is where we find the code that causes the material to change
Taking a look at TriggerVolumeChangeMaterialAuthoring
By taking a look at the code that runs when shapes stop intersecting, you can see the purpose of the ReferenceEntity field
The ReferenceEntity's RenderMesh is used
Once the intersection stops, the RenderMesh is set equal to the ReferenceEntity's RenderMesh
This is why the ball turns back to its original color in the sample
We are going to update this code so that when a bullet first intersects with any entity, the other entity will have its material changed to the same material as the bullet
"On exit" we will add a DestroyTag to the entity
We do not need the "ReferenceEntity" because we will not be changing material back on exit. Instead, we will be able to remove TriggerVolumeChangeMaterial and TriggerChangeMaterialAndDestroyAuthoring
Now, let's implement:
Copy and paste the 5 files from /2d. Events/Scripts/Stateful to /ScriptsAndPrefabs
1. IStatefulSimulationEvent.cs
2. StatefulSimulationEventBuffers.cs
3. StatefulTriggerEvent.cs
4. StatefulTriggerEventBufferAuthoring.cs
5. StatefulTriggerEventBufferSystem.cs
as well as 3 additional files (these are used for CollisionEvents which we are not concerned with but are also referenced by our systems so they are necessary)
6. StatefulCollisionEvent.cs
7. StatefulCollisionEventBufferAuthoring.cs
8. StatefulCollisionEventBufferSystem.cs
With these 8 files we have what we need to create StatefulEventTriggers on our prefabs 💪
​
Now let's make some modifications to TriggerVolumeChangeMaterialAuthoring.cs so that bullets change the color of the Asteroid when they intersect and that the Asteroid is given a DestroyTag when the bullet exists.
Create ChangeMaterialAndDestroySystem and paste the code snippet below into ChangeMaterialAndDestroySystem.cs:
using Unity.Collections;
using Unity.Entities;
using Unity.Jobs;
using Unity.Physics.Stateful;
using Unity.Rendering;
using UnityEngine;
​
//We did not need the ReferenceEntity so we deleted the IConvertGameObjectToEntity interface
//and the TriggerVolumeChangeMaterial component
​
[UpdateInGroup(typeof(FixedStepSimulationSystemGroup))]
[UpdateAfter(typeof(StatefulTriggerEventBufferSystem))]
public partial class ChangeMaterialAndDestroySystem : SystemBase
{
    private EndFixedStepSimulationEntityCommandBufferSystem m_CommandBufferSystem;
​
    private EntityQueryMask m_NonTriggerMask;
​
    protected override void OnCreate()
    {
        m_CommandBufferSystem = World.GetOrCreateSystem<EndFixedStepSimulationEntityCommandBufferSystem>();
        m_NonTriggerMask = EntityManager.GetEntityQueryMask(
            GetEntityQuery(new EntityQueryDesc
            {
                None = new ComponentType[]
                {
                    typeof(StatefulTriggerEvent)
                }
            })
        );
    }
​
    protected override void OnUpdate()
    {
        var commandBuffer = m_CommandBufferSystem.CreateCommandBuffer();
​
        // Need this extra variable here so that it can
        // be captured by Entities.ForEach loop below
        var nonTriggerMask = m_NonTriggerMask;
​
        Entities
            .WithName("ChangeMaterialOnTriggerEnter")
            .WithoutBurst()
            .ForEach((Entity e, ref DynamicBuffer<StatefulTriggerEvent> triggerEventBuffer) =>
            {
                for (int i = 0; i < triggerEventBuffer.Length; i++)
                {
                    var triggerEvent = triggerEventBuffer[i];
                    var otherEntity = triggerEvent.GetOtherEntity(e);
​
                    // exclude other triggers and processed events
                    if (triggerEvent.State == StatefulEventState.Stay || !nonTriggerMask.Matches(otherEntity))
                    {
                        continue;
                    }
​
                    if (triggerEvent.State == StatefulEventState.Enter)
                    {
                        var volumeRenderMesh = EntityManager.GetSharedComponentData<RenderMesh>(e);
                        var overlappingRenderMesh = EntityManager.GetSharedComponentData<RenderMesh>(otherEntity);
                        overlappingRenderMesh.material = volumeRenderMesh.material;
​
                        commandBuffer.SetSharedComponent(otherEntity, overlappingRenderMesh);
                    }
                    //The following is what happens on exit
                    else
                    {
                        commandBuffer.AddComponent(otherEntity, new DestroyTag {});
                    }
                }
            }).Run();
​
        m_CommandBufferSystem.AddJobHandleForProducer(Dependency);
    }
}
Next, open the Bullet prefab and add StatefulTriggerEventBufferAuthoring
Navigate to SampleScene, reimport ConvertedSubScene
Hit "play" and shoot around
Adding StatefulTriggerEventBufferAuthoring and ChangeMaterialAndDestroySystem 
Woo hoo! We have a working collision trigger system 👍
In our testing we found that occasionally it is necessary to "Reimport All" assets for the changes to take  (go to "Assets" then select "Reimport All")
The changing of material is... underwhelming
Let's update the Bullet prefab to have a Red material
In the Asset folder, right-click, choose "Create", select "Material" and name it "Red"
Select the Red material, go to Base Map in the Inspector, and change it to a red color and save
Select the Bullet prefab and change the Mesh Renderer material to Red
Hit save, navigate to SampleScene, and reimport the ConvertedSubScene
Updating the Bullet prefab to be red
Now hit "play" and checkout the difference
Shooting red bullets to destroy asteroids
Now it's a bit more exciting, right?! 😬
Remember, the purpose of this gitbook is to give a "how" of using Unity's DOTS packages, not to make an exciting game 🥺
We now know how to make collisions using DOTS Physics
We navigated through DOTS Physics samples to find a sample that matched our needs
We checked out the sample scene to get an idea of the different components
We read through Physics Samples to get an idea of what changes we wanted to make
We copied 8 files needed to create StatefulEventTriggers and created ChangeMaterialAndDestroySystem in our project
We added the StatefulTriggerEventBufferAuthoring to our Bullet prefab and updated the prefab to be red
Github branch link: 
git clone https://github.com/moetsi/Unity-DOTS-Multiplayer-XR-Sample/
git checkout 'Updating-Bullets-to-Destroy'
​Join our Discord for more info​
Unity DOTS Physics - Previous
Use DOTS Physics for Prefabs, Players, and Bullets
Next - Unity DOTS NetCode
Intro to DOTS NetCode
Last modified 11mo ago