World

Remarks

A world is not thread-safe and does not pretend to be. Structural change — creating, destroying, adding, removing — happens on the main thread or through a CommandBuffer played back at a sync point; reads and component writes parallelise across chunks under the scheduler's read/write declarations. A lock here would make every one of those cost something to buy safety in a case the design already rules out.

⚠ That sentence was not true of a managed component until #1198. A managed component's chunk cell is a handle into a store the world owns, and the read path used to take the row a slot when it had none — so two workers reading the same component type in different chunks shared a free list and an array resize, which is precisely the case the paragraph above says the design rules out. Read``1 and TryGet``1 now resolve a managed cell without writing one; writing a managed component still touches the store, and that is a write, declared as one.

Worlds are numbered, and the number is in every entity handle, so passing an entity from the editor's world to the play world is caught rather than silently addressing whatever shares the slot.

Fields and properties (9)

• public short Id

  Which world this is. Present in every entity handle it hands out.

• public string Name

  An optional name, for diagnostics and for the editor's world list.

• public int EntityCount

  How many entities are alive.

• public uint Version

  The version writes are stamped with. A system advances it at its sync point, and a query with a change filter compares against the value it last saw.

• public int StructuralVersion

  Bumped whenever an archetype is created, so a query knows its matched set may be stale without re-testing every archetype's mask.

• public IReadOnlyList<Archetype> Archetypes

  The archetypes that exist, in creation order.

• public Archetype EmptyArchetype

  The archetype a bare entity with no components lives in.

• public bool IsDisposed

  Whether Dispose has been called.

• public const bool EventsEnabled

  Whether the structural-change events are raised by this build.

Events (5)

• public Action<Entity>? EntityCreated

  An entity now exists. Raised before any of its components are announced.

• public Action<Entity>? EntityDestroyed

  An entity is about to stop existing. Its components are still readable.

• public Action<Entity, ComponentTypeId>? ComponentAdded

  A component has been added, and its value is readable.

• public Action<Entity, ComponentTypeId>? ComponentRemoved

  A component is about to be removed, and its value is still readable.

• public Action<Entity, ComponentTypeId>? ComponentSet

  A component has been overwritten through Set``1.

Methods (31)

• public World(string name = "World")

  Creates a world and gives it the lowest free id.

• public static World? Find(short id)

  The world with an id, if it is still alive.

• public uint AdvanceVersion()

  Moves the version forward, so writes from here on are distinguishable from writes before.

• public Entity Create()

  Creates an entity with no components.

• public Entity Create<T0>(in T0 component0)

  Creates an entity with one component.

• public Entity Create<T0, T1>(in T0 component0, in T1 component1)

  Creates an entity with two components.

• public Entity Create<T0, T1, T2>(in T0 component0, in T1 component1, in T2 component2)

  Creates an entity with three components.

• public Entity Create<T0, T1, T2, T3>(in T0 component0, in T1 component1, in T2 component2, in T3 component3)

  Creates an entity with four components.

• public Entity Create(Archetype archetype)

  Creates an entity directly in an archetype, which is what bulk instantiation wants.

• public bool CanRecreate(Entity entity)

  Whether TryRecreate would give this exact handle back.

• public bool TryRecreate(Entity entity, Archetype archetype)

  Creates an entity with a handle a destroyed one used to have.

• public Query Query(QueryDescription description)

  The query for a description, with its matched archetypes remembered.

• public ChunkSequence Chunks(QueryDescription description, uint since = 0)

  The chunks matching a description.

• public void CreateMany(Archetype archetype, Span<Entity> created)

  Creates a run of entities in one archetype.

• public void CopyComponentsFrom(Entity target, World source, Entity sourceEntity)

  Copies every component the target's archetype has from another entity, which may be in another world.

• public Archetype ArchetypeOf(ReadOnlySpan<ComponentTypeId> componentTypes)

  The archetype for a set of component types, creating it if this is the first ask.

• public bool IsAlive(Entity entity)

  Whether a handle still names a live entity of this world.

• public void Destroy(Entity entity)

  Destroys an entity and frees its slot for reuse.

• public Archetype ArchetypeOf(Entity entity)

  The archetype an entity is in.

• public bool Has<T>(Entity entity)

  Whether an entity has a component, tags included.

• public ref T Get<T>(Entity entity)

  A reference to a component, for writing. Marks the chunk's column as changed at the current Version.

• public ref readonly T Read<T>(Entity entity)

  A reference to a component, for reading. Does not mark anything as changed.

• public bool TryGet<T>(Entity entity, out T? value)

  Reads a component if the entity has one.

• public void Set<T>(Entity entity, in T value)

  Overwrites a component the entity already has.

• public void Add<T>(Entity entity, in T value)

  Adds a component, moving the entity to the archetype that has it.

• public void Add<T>(Entity entity)

  Adds a component zeroed — the usual way to add a tag.

• public void AddDefault<T>(Entity entity) where T : struct, IDefaultComponent<T>

  Adds a component holding what its type declares a fresh one should hold.

• public void Remove<T>(Entity entity)

  Removes a component, moving the entity to the archetype without it.

• public void Clear()

  Destroys every entity, keeping the archetypes and their chunk memory.

• public void Dispose()

  Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

• public override string ToString()

  Renders the name, entity count and archetype count.

Used by (509, showing 40)

• AiVillageGameAiVillage
• ArenaMultiplayer
• ArenaThirdPersonShooter
• CharacterAnimationThirdPersonShooter
• DecisionLogAiVillage
• GameClientMultiplayer
• GameServerMultiplayer
• IntruderSystemAiVillage
• LocalMatchMultiplayer
• OrbitSystemEcsStressTest
• PbrShowcaseGamePbrShowcase
• PlayerRigThirdPersonShooter
• ProgramEcsStressTest
• SliceResolverNetworkSoak
• SoakNetworkSoak
• ThirdPersonShooterGameThirdPersonShooter
• VillageAiVillage
• VillageTestsAiVillage.Agent.Tests
• Vixen_Samples_Multiplayer_CombatantReplicatorMultiplayer
• Vixen_Samples_Multiplayer_VitalsReplicatorMultiplayer
• WeaponFireThirdPersonShooter
• ConstraintStageBenchmarksVixen.Benchmarks.Animation
• CrowdBenchmarksVixen.Benchmarks.Animation
• WorldBenchmarksVixen.Benchmarks.Ecs
• AgentContextVixen.Ai
• AgentTargetVixen.Ai.Nodes
• AiDebugChannelVixen.Ai
• AiDebugChannelTestsVixen.Ai.Tests
• AiDiagnosisExitCriteriaTestsVixen.Ai.Tests
• AiFocusVixen.Ai.Nodes
• AiGameplayDebuggerVixen.Ai.Diagnostics
• AiSchedulingTestsVixen.Ai.Tests
• AiSnapshotTestsVixen.Ai.Tests
• AiSnapshotsVixen.Ai
• AiSystemVixen.Ai
• AiSystemTestsVixen.Ai.Tests
• AiSystemTreeTestsVixen.Ai.Tests
• AllNetworkedSourceVixen.Net
• AnimationSystemVixen.Animation
• ArchetypeVixen.Ecs