You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/advanced/pausing-and-disabling-systems.md
+4-41Lines changed: 4 additions & 41 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -24,21 +24,19 @@ public enum EnableChannel
24
24
}
25
25
```
26
26
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`:
`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.
38
36
39
37
## SetSystemPaused — deterministic pause
40
38
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).
42
40
43
41
Called from inside a system or from initialization code, via `WorldAccessor`:
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`):
64
62
65
63
```csharp
66
64
intcount=world.SystemCount;
@@ -70,41 +68,6 @@ SystemMetadata meta = world.GetSystemMetadata(systemIndex);
70
68
// meta.DebugName — human-readable name
71
69
```
72
70
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
-
vargameplayIndices=newList<int>();
78
-
for (inti=0; i<world.SystemCount; i++)
79
-
{
80
-
varmeta=world.GetSystemMetadata(i);
81
-
if (meta.SystemisIGameplaySystem)
82
-
{
83
-
gameplayIndices.Add(i);
84
-
}
85
-
}
86
-
87
-
// Later, when the pause overlay opens (called from a fixed-update system):
88
-
foreach (variingameplayIndices)
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
-
108
71
## Related
109
72
110
73
-[Accessor Roles](accessor-roles.md) — why `SetSystemPaused` requires a `Fixed`-role accessor and `SetSystemEnabled` doesn't.
0 commit comments