Timers are used in different ways in video games such as to allow the players to fast forward in strategy games, or to be used by systems for computations like damage per minute type of effect, and much more. In my experiment project using Unity’s pure ECS, I needed a timer for setting how long an NPC will be on idle.
In this quick tutorial I’ll show you how I implemented this timer system. As usual, there are references at the end of the blog for further reading. Enjoy!
The Timer Component Tag
Let’s start with the Timer tag that we will add to the entities that we want the timer system to affect. Keep in mind that we will be implementing a generic system later that will take this timer tag as the system’s data type. The tag will look like this:
public struct Timer<T> : IComponentData where T : struct {
// Note that we don't reset the values here since
// we will remove this component when we're done anyways
public float ElapsedTime;
public float TargetDuration;
public Timer(float targetDuration) : this() {
SetDuration(targetDuration);
}
public bool IsDone {
get {
return this.ElapsedTime >= this.TargetDuration;
}
}
private void SetDuration(float targetDuration) {
this.ElapsedTime = 0;
this.TargetDuration = targetDuration;
}
}
I admit that this code looks weird because we introduce a type T, but never use it anywhere in the struct. But, this will help us differentiate the different timer systems later. This is done this way as a workaround to the fact that we can’t inherit structs and structs can’t derive from classes.
The Generic Timer System
For the system, we’ll implement a generic timer system. This will allow us to extend the timer system and have different timers for different parts of the game (such as animations, idle, game speed, etc.). This is what it looks like in code:
public class TimerBaseSystem<T> : SystemBase where T : struct, IComponentData {
private EntityQuery timerQuery;
private EntityCommandBufferSystem entityCommandBufferSystem;
private const float TIME_SCALE = 1f;
/// <summary>
/// We set the TimeScale as virtual so that subclasses can have their own timescales if needed.
/// A use case for this is for faster speeds or faster enemies in strategy games.
/// </summary>
protected virtual float TimeScale {
get {
return TIME_SCALE;
}
}
/// <summary>
/// This is the scaled time - applying the Timescale to the delta time.
/// </summary>
private float ScaledTime {
get {
return this.Time.DeltaTime * this.TimeScale;
}
}
protected override void OnCreate() {
base.OnCreate();
this.entityCommandBufferSystem = this.World.GetOrCreateSystem<EntityCommandBufferSystem>();
// The main idea here is that everything that has the Timer tag of type T will only be processed
this.timerQuery = this.EntityManager.CreateEntityQuery(
ComponentType.ReadWrite<Timer<T>>()
);
}
protected override void OnUpdate() {
UpdateTimerJob job = new UpdateTimerJob {
EntityTypeHandle = GetEntityTypeHandle(),
TimerTypeHandle = GetComponentTypeHandle<Timer<T>>(),
CurrentTimeInterval = this.ScaledTime,
CommandBuffer = this.entityCommandBufferSystem.CreateCommandBuffer().AsParallelWriter()
};
this.Dependency = job.ScheduleParallel(this.timerQuery, this.Dependency);
this.entityCommandBufferSystem.AddJobHandleForProducer(this.Dependency);
}
// BURST IT!!! YAAS!
[BurstCompile]
private struct UpdateTimerJob : IJobChunk {
[ReadOnly]
public EntityTypeHandle EntityTypeHandle;
[ReadOnly]
public float CurrentTimeInterval;
public ComponentTypeHandle<Timer<T>> TimerTypeHandle;
public EntityCommandBuffer.ParallelWriter CommandBuffer;
public void Execute(ArchetypeChunk chunk, int chunkIndex, int firstEntityIndex) {
NativeArray<Entity> entities = chunk.GetNativeArray(this.EntityTypeHandle);
NativeArray<Timer<T>> timers = chunk.GetNativeArray(this.TimerTypeHandle);
for (int i = 0; i < entities.Length; ++i) {
Timer<T> timer = timers[i];
timer.ElapsedTime += this.CurrentTimeInterval;
if (timer.IsDone) {
int sortKey = firstEntityIndex + i;
this.CommandBuffer.RemoveComponent<Timer<T>>(sortKey, entities[i]);
}
timers[i] = timer;
}
}
}
}
Now, if you want to extend the timer system – say, you want another one with a faster timescale, it will look like this:
public struct FastTimeScaleTag : IComponentData {
}
public class FastTimeScaleTimerSystem : TimerBaseSystem<FastTimeScaleTag> {
protected override float TimeScale {
get {
return 2f;
}
}
}
We first create a new tag that we will then use as the type for the new timer system. Then inside the timer system, we override the TimeScale and set it higher (faster) than the default 1 inside the base class.
A caveat however, if you run this now, you will get an ArgumentException error. This is because in ECS, all ComponentTypes should be known during compile time. To remedy this you can create a separate file, say AssemblyInfo.cs and add the following:
[assembly: RegisterGenericComponentType(typeof(Timer<NormalTimeScaleTag>))]
[assembly: RegisterGenericComponentType(typeof(Timer<FastTimeScaleTag>))]
You can also add this in the TimerBaseSystem class right after declaring your using directives if that is more convenient for you.
To further make it easier to track all the timer systems, we can make a separate system group for all the timers. Then update our timer systems inside that group.
// Depending on your use case, you can choose when your timers should update
[UpdateBefore(typeof(EndSimulationEntityCommandBufferSystem))]
public class TimerSystemsGroup : ComponentSystemGroup {
}
[UpdateInGroup(typeof(TimerSystemsGroup))]
public class TimerBaseSystem<T> : SystemBase where T : struct, IComponentData {
// Rest of the timer system code
}
Now, we are almost set. We just need to add the timer tags to our entities. My use case for this timer is for how long an NPC should wait (be idle) before moving. That said adding the components for me would look something like:
// This will make the NPC wait for 3 seconds at a normal time scale.
// More or less 3 seconds in real life.
this.CommandBuffer.AddComponent(firstEntityIndex, npcEntity,
new Timer<NormalTimeScaleTag>(3f)
);
// This will make the NPC move earlier than the one above with a
// faster timescale which is twice of the normal time scale
// which is about 1.5 seconds in real life.
this.CommandBuffer.AddComponent(firstEntityIndex, npcEntity,
new Timer<FastTimeScaleTag>(3f)
);
To demonstrate this I made the following setup:
- Two NPCs with different time scales (1f and 2f), but the same idle wait time of 3 seconds; and,
- A MovementSystem that would move the two NPCs after waiting
And it looks something like this (note that timing might differ since I just captured this with a screen to gif tool):
And there you have it. For further improvement, I’m thinking of adding a query in the base system that the subclasses can override, so that other parts of the game can get the scaled time from any respective timer systems. I already got it working and if you want to read more about query systems, Marnel from Squeaky Wheel wrote a simple query system. He made a better version of that system that doesn’t involve boxing but I can’t seem to find a reference about it online, maybe soon.
If you have questions you can reach me via Twitter or Instagram – That’s all for now and see you in the next one!
References:
- The source of this idea is by Spy-Shifty in Unity Forums
- Generic Components workaround
P.S. It took a lot longer for me to release this blog because of something great happening soon – Academia: School Simulator is releasing in just a couple of weeks and boy are we nervous in Squeaky Wheel. Please check it out on Steam and let us know what you think. Thank you again, have a good one, and stay safe!
Neil Mark Corre 