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/groups-and-tagsets.md
+4-18Lines changed: 4 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -44,7 +44,7 @@ Groups are the foundation of Trecs' performance model:
44
44
The tags you pass to `AddEntity<...>()` are a **filter**, not a label. Trecs picks the registered group whose tag set contains every tag you passed:
45
45
46
46
- One group matches → that's the target.
47
-
- Several match, but one matches your tags *exactly* → that one wins. (This is how partitioned templates let you target either side of a presence/absence partition by omitting the partition tag.)
47
+
- Several match → if one of them has *only* your tags and no extras, that one wins. (This is how partitioned templates let you target either side of a presence/absence partition by omitting the partition tag.)
// → {Enemy, Character}. Both groups contain Character, but this one matches exactly.
57
+
// → {Enemy, Character}. Only this group contains Enemy.
58
58
59
59
accessor.AddEntity<GameTags.Character>();
60
-
// → throws. Both groups contain Character and neither matches exactly.
60
+
// → throws. Both groups contain Character, and neither has Character on its own.
61
61
```
62
62
63
63
`AddEntity<Player>()` works because `Player` narrows to one group. `AddEntity<Character>()` doesn't — `Character` alone matches both, so you have to add `Player` or `Enemy` to disambiguate.
64
64
65
-
## TagSet vs GroupIndex
66
-
67
-
Trecs exposes two first-class handles for groups:
68
-
69
-
||`TagSet`|`GroupIndex`|
70
-
|---|---|---|
71
-
|**Role**| Stable identity for a tag combination | Runtime handle — a small array-indexable integer |
72
-
|**Representation**| 32-bit stable hash of the tag GUIDs | Sequential `ushort` assigned at world build time |
73
-
|**Serializable**| Yes — same value across runs | No — assignment depends on registration order |
|**How you get one**|`TagSet<GameTags.Player>.Value`, `TagSet.FromTags(...)`|`worldInfo.GetSingleGroupWithTags(tagSet)`, capture from slice, event callback |
76
-
77
-
Rule of thumb: to **store** the handle (component, disk, across sessions), use `TagSet`. To **use** it within a frame to reach into native storage, use `GroupIndex`.
78
-
79
65
## GroupSlices
80
66
81
67
`GroupSlices()` is a low-level iteration pattern that gives direct access to component buffers per group. It bypasses the per-entity abstraction and can be more efficient for bulk operations, but requires you to manage group-level access yourself.
`TagSet` is a stable hash, so it's safe to serialize — the same tag combination hashes to the same value across runs. Use it for save-game fields or network messages that name a group.
121
+
`TagSet` is a stable hash, so it's safe to serialize — the same tag combination hashes to the same value across runs.
0 commit comments