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 > 2d1. Triggers > Scripts
In this folder there are 2 files we are going to base our bullet interactions on
DynamicBufferTriggerEventAuthoring
TriggerVolumeChangeMaterialAuthoring
Open DynamicBufferTriggerEventAuthoring and checkout through the code to get an understanding of what it does
Navigating to DynamicBufferTriggerEventAuthoring in the Unity Physics sample repo
This file has a few key components
EventOverlapState
StatefulTriggerEvent
ExcludeFromTriggerEventConversion
TriggerEventConversionSystem
DynamicBufferTriggerEventAuthoring
EventOverlapState
These are the "states" a trigger can be
EventOverlapState.Enter, when 2 bodies are overlapping in the current frame, but they did not overlap in the previous frame
EventOverlapState.Stay, when 2 bodies are overlapping in the current frame, and they did overlap in the previous frame
EventOverlapState.Exit, when 2 bodies are NOT overlapping in the current frame, but they did overlap in the previous frame
StatefulTriggerEvent
This is the actual stateful trigger event being stored in a dynamic buffer
Provides some methods like "GetOtherEntity"
So when we have a trigger event (like we will when our bullet passes through an asteroid) we can call "GetOtherEntity" to reference the asteroid (and in our case, add a DestroyTag to it)
ExcludeFromTriggerEventConversion
This is a Tag that is used for CharacterControllers to exclude it from adding trigger events to the dynamic buffer
Not important for this gitbook, but still good to know
TriggerEventConversionSystem
This is a hardcore system that takes the intermediate results of the Solver (which are stateless) and assigns them state (enter, stay, and exit)
In order for TriggerEvents to be transformed to StatefulTriggerEvents and stored in a Dynamic Buffer, you must:
1) Tick "IsTrigger" on PhysicsShapeAuthoring on the entity that should raise trigger events
2) Add a DynamicBufferTriggerEventAuthoring 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 DynamicBufferTriggerEventAuthoring on the bullet
We can see in TriggerEventConversionSystem's OnUpdate() that the system takes the FinalSimulationJobHandle of the StepPhysicsWorld as a dependency
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 to get the trigger events
Near the bottom we can see CollectTriggerEventJob which implements the ITriggerEventsJob interface (mentioned in the previous section)
DynamicBufferTriggerEventAuthoring
An implementation of the IConvertGameObjectToEntity interface
When we place this script on a GameObject, it creates "stateful" trigger events from the stateless triggers created by DOTS Physics
In short, if you put the DynamicBufferTriggerEventAuthoring on a prefab, it will create a dynamic buffer of stateful triggers on the entity. This is why it is highly recommended to look through Unity DOTS Physics samples; making this type of script completely on your own would not be very fun 👎
Now take a look at TriggerVolumeChangeMaterialAuthoring
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
TriggerEventConversionSystem is the system fro the previous file we just reviewed, DynamicBufferTriggerEventAuthoring
This makes sense because we want to perform our actions in the simulation and after we have created our stateful triggers
We can see at the beginning of the OnUpdate() that TriggerVolumeChangeMaterialSystem has a dependency on the output of TriggerEventConversionSystem, so the dependencies combine
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:
We are going to create DynamicBufferTriggerEventAuthoring in our project and an updated TriggerVolumeChangeMaterialAuthoring called ChangeMaterialAndDestroySystem
Create DynamicBufferTriggerEventAuthoring and paste the code snippet below into DynamicBufferTriggerEventAuthoring.cs:
1
using Unity.Entities;
2
using Unity.Jobs;
3
using Unity.Physics;
4
using Unity.Physics.Systems;
5
using UnityEngine;
6
using Unity.Collections;
7
using Unity.Burst;
8
using System;
9
using Unity.Assertions;
10
using Unity.Mathematics;
11
12
namespace Unity.Physics.Stateful
13
{
14
// Describes the overlap state.
15
// OverlapState in StatefulTriggerEvent is set to:
16
// 1) EventOverlapState.Enter, when 2 bodies are overlapping in the current frame,
17
// but they did not overlap in the previous frame
18
// 2) EventOverlapState.Stay, when 2 bodies are overlapping in the current frame,
19
// and they did overlap in the previous frame
20
// 3) EventOverlapState.Exit, when 2 bodies are NOT overlapping in the current frame,
21
// but they did overlap in the previous frame
22
public enum EventOverlapState : byte
23
{
24
Enter,
25
Stay,
26
Exit
27
}
28
29
// Trigger Event that is stored inside a DynamicBuffer
30
public struct StatefulTriggerEvent : IBufferElementData, IComparable<StatefulTriggerEvent>
31
{
32
internal EntityPair Entities;
33
internal BodyIndexPair BodyIndices;
34
internal ColliderKeyPair ColliderKeys;
35
36
public EventOverlapState State;
37
public Entity EntityA => Entities.EntityA;
38
public Entity EntityB => Entities.EntityB;
39
public int BodyIndexA => BodyIndices.BodyIndexA;
40
public int BodyIndexB => BodyIndices.BodyIndexB;
41
public ColliderKey ColliderKeyA => ColliderKeys.ColliderKeyA;
42
public ColliderKey ColliderKeyB => ColliderKeys.ColliderKeyB;
43
44
public StatefulTriggerEvent(Entity entityA, Entity entityB, int bodyIndexA, int bodyIndexB,