Skip to content

Commit 03b3392

Browse files
committed
Changed pausing-and-disabling-systems.md.
1 parent 53b66b9 commit 03b3392

1 file changed

Lines changed: 4 additions & 41 deletions

File tree

docs/advanced/pausing-and-disabling-systems.md

Lines changed: 4 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -24,21 +24,19 @@ public enum EnableChannel
2424
}
2525
```
2626

27-
Game-host / editor code calls these on a `WorldAccessor` (typically a long-lived `AccessorRole.Unrestricted` accessor created via `world.CreateAccessor(AccessorRole.Unrestricted)`):
27+
Game-host / editor code calls these on a `WorldAccessor`:
2828

2929
```csharp
3030
accessor.SetSystemEnabled(systemIndex, EnableChannel.User, false); // disable
3131
accessor.SetSystemEnabled(systemIndex, EnableChannel.User, true); // re-enable
3232
bool enabled = accessor.IsSystemEnabled(systemIndex, EnableChannel.User);
3333
```
3434

35-
`SetSystemEnabled` doesn't gate on `AccessorRole`, so any accessor can call it — but in practice you'll want a non-system `Unrestricted` accessor since channel toggles are host-side concerns.
36-
37-
Channel state defaults to "all enabled" at world init and is **not part of snapshot/restore or recording state**. Anything that sets a channel disable is responsible for re-applying it across world resets — `BundlePlayer` does this automatically when playback (re)starts.
35+
Channel state defaults to "all enabled" at world init and is **not part of snapshot/restore or recording state**. This is likely to cause desyncs.
3836

3937
## SetSystemPaused — deterministic pause
4038

41-
`SetSystemPaused` is a per-system flag that **is** part of serialized world state, so it survives snapshot/restore and round-trips through recording playback. Use it for any pause that affects the simulation and must replay identically.
39+
`SetSystemPaused` is a per-system flag that **is** part of serialized world state, so it survives snapshot/restore and round-trips through recording playback. Use it for any pause that affects the simulation and must replay identically (eg. pausing for UI menu popup).
4240

4341
Called from inside a system or from initialization code, via `WorldAccessor`:
4442

@@ -60,7 +58,7 @@ bool willRun = world.IsSystemEffectivelyEnabled(systemIndex);
6058

6159
## Building your own grouping
6260

63-
Trecs deliberately doesn't have a built-in `[SystemGroup]` concept. Instead, the framework exposes the per-system metadata you need to build whatever grouping makes sense for your game (also available on both `World` and `WorldAccessor`):
61+
Trecs deliberately doesn't have a built-in `[SystemGroup]` concept to do a bulk pause/unpause. Instead, the framework exposes the per-system metadata you need to build whatever grouping makes sense for your game (also available on both `World` and `WorldAccessor`):
6462

6563
```csharp
6664
int count = world.SystemCount;
@@ -70,41 +68,6 @@ SystemMetadata meta = world.GetSystemMetadata(systemIndex);
7068
// meta.DebugName — human-readable name
7169
```
7270

73-
A typical pattern: walk all systems once at init time, bucket their indices by some criterion the game cares about (a custom attribute, a type lookup, a config asset, anything), then drive `SetSystemPaused` or `SetSystemEnabled` calls against those buckets.
74-
75-
```csharp
76-
// One-time setup: collect indices of systems tagged "gameplay".
77-
var gameplayIndices = new List<int>();
78-
for (int i = 0; i < world.SystemCount; i++)
79-
{
80-
var meta = world.GetSystemMetadata(i);
81-
if (meta.System is IGameplaySystem)
82-
{
83-
gameplayIndices.Add(i);
84-
}
85-
}
86-
87-
// Later, when the pause overlay opens (called from a fixed-update system):
88-
foreach (var i in gameplayIndices)
89-
{
90-
accessor.SetSystemPaused(i, true);
91-
}
92-
```
93-
94-
The pause overlay's UI systems aren't in the gameplay bucket, so they keep running while the gameplay systems are paused.
95-
96-
## When to use which
97-
98-
- "I want to disable some systems while a debug menu is open" → `accessor.SetSystemEnabled(..., EnableChannel.User, false)`.
99-
- "I want to silence input systems while playing back a recording" → already done by `BundlePlayer` via `EnableChannel.Playback`. Don't reimplement.
100-
- "I want the editor to let me toggle systems for inspection" → already wired through the [Trecs Hierarchy window](../editor-windows/hierarchy.md) via `EnableChannel.Editor`.
101-
- "I want gameplay to pause when a UI overlay is up, and have that pause survive a save / replay deterministically" → `accessor.SetSystemPaused` from a Fixed-update system.
102-
- "I want a kill switch that doesn't need to replay deterministically" → `EnableChannel.User`. It won't show up in checksums or recordings.
103-
104-
## Threading
105-
106-
Both APIs are **main-thread only**. Neither is exposed on `NativeWorldAccessor`, so jobs cannot toggle systems. Reads and writes happen at main-thread sync points (between ticks, or inside a system's `Execute()`).
107-
10871
## Related
10972

11073
- [Accessor Roles](accessor-roles.md) — why `SetSystemPaused` requires a `Fixed`-role accessor and `SetSystemEnabled` doesn't.

0 commit comments

Comments
 (0)