08 · Change Detection¶
What it is¶
Change detection answers "which components were added or modified since a given moment?" Each component instance remembers when it was added and when it was last written, as a tick (a counter that only goes up). A system compares those ticks with the moment it last ran.
Why we need it¶
- R3 (network): replication sends only the components that changed since a client's last acknowledged state. Without change detection, the server would resend everything every tick.
- Rendering and other reactive work: only rebuild what changed (a sprite whose texture changed, a UI text whose score changed).
- Gameplay:
Added<Player>to run setup once when a player joins.
How others do it¶
| ECS | Mechanism | Granularity |
|---|---|---|
| Bevy | added and changed ticks per component instance; Mut<T> marks on mutable deref |
Per instance |
| flecs | Dirty state per table column (ecs_query_changed) |
Per table |
| Unity DOTS | Version number per chunk, bumped on write access | Per chunk |
| EnTT | Signals (on_update) when patch / replace is used |
Per call, opt-in |
| Unreal | Property dirty flags; Iris tracks dirty properties for replication | Per property |
Our choice¶
Per-instance ticks, as Bevy does. It is the most precise (per entity, per component), and it maps directly to "send this component of this entity".
How it works¶
Ticks¶
- The world has a change tick counter. It advances every time a system runs.
- Each pool stores, for each instance,
addedandchangedticks. - Each system remembers
lastRun, the world tick when it last ran.
| World tick | 100 | 101 | 102 |
|---|---|---|---|
| System running | movement |
collision, writes Position of e5 |
replication (its last run was tick 97) |
Position of e5 |
added 40, changed 40 | added 40, changed 101 | — |
At tick 102, replication sees Changed<Position> for e5 because 101 > 97 (its last run).
| Filter | True when |
|---|---|
Added<T> |
added > lastRun |
Changed<T> |
changed > lastRun (adding counts as changing) |
Mut<T>: detecting a write¶
template <typename T>
class Mut {
public:
[[nodiscard]] const T& get() const noexcept; ///< Read, does not mark changed.
[[nodiscard]] T* operator->() noexcept; ///< Write, marks changed.
[[nodiscard]] T& operator*() noexcept; ///< Write, marks changed.
private:
T* _value;
Tick* _changed;
Tick _currentTick;
};
A writable query term yields Mut<T>. Reading through get() is free; using -> or * stamps
changed = currentTick. So a system that iterates Query<Health> but only modifies the damaged
entities marks only those.
The type-erased world.getComponents().getMut(e, id) (used by Luau and the network) returns the value's bytes
(std::span<std::byte>) and marks on access, since it cannot know what the caller will do with them.
getComponents().getTicks(e, id) / getTicks<T>(e) return a ComponentTicks (added, changed) with
isAdded(lastRun, thisRun) and isChanged(lastRun, thisRun).
Wraparound¶
Ticks are 32-bit. At thousands of system runs per second they wrap after weeks, so ticks are compared
by age (isNewerThan(tick, lastRun, thisRun) compares thisRun - tick with thisRun - lastRun in
wrapping unsigned arithmetic), and old ticks are clamped (Bevy's approach):
world.advanceChangeTick(count = 1)moves the tick forward (the scheduler calls it once per system run) and, everykCheckTickThreshold(518 400 000) ticks, runsworld.checkChangeTicks().checkChangeTicks()moves every storedadded/changedtick older thankMaxChangeAge(2^32 − 1 − 2 × the threshold, about 3.26 billion) to exactly that age: it still compares as old, and its age can never wrap before the next check.- Ticks kept outside the world (a system's
lastRun, a client's acknowledged tick) are clamped by their owner withclampTick(tick, thisRun).
Comparisons stay correct as long as no system goes more than kMaxChangeAge ticks without running.
Replication's own "last run"¶
Replication does not use its system's lastRun; it keeps one tick per client: the tick of the last
snapshot that client acknowledged. "What to send to client A" = everything with changed newer than
A's acknowledged tick. A lost packet just makes the next delta larger. See
Replication.
Connections¶
- Uses: Pool (tick columns), World (tick counter).
- Used by: Queries (
Added,Changed,Mut<T>), Systems (lastRun), Replication.
Pitfalls¶
- Writing through
operator->to read.position->xon aMut<Position>counts as a write, even if the code only reads. Read withget()when nothing changes, or replication sends useless data. - Writes that bypass
Mut<T>. Any raw pointer write (in C++ or the bridge) must stamp the tick, or the change is never replicated. - Per-field changes. A tick says the component changed, not which field. Sending only changed fields needs a field mask (see the open question).
Open questions¶
- Track changes per field (a bitmask per instance) to send only changed fields, or always resend the whole component? (ECS + network)
- 32-bit ticks with clamping, or 64-bit and never clamp (8 more bytes per instance)? (ECS)