Class World

Namespace

Shard.Gameplay.Universe.World

Assembly

Shard.Gameplay.Universe.dll

Runs one ECS Store on its dedicated simulation thread.

public sealed class World : TickingThread, IAsyncDisposable

Inheritance

object

TickingThread

World

Implements

IAsyncDisposable

Inherited Members

TickingThread.DefaultTicksPerSecond

TickingThread.MaxTicksPerSecond

TickingThread.MinTicksPerSecond

TickingThread.CurrentTick

TickingThread.TicksPerSecond

TickingThread.IsRunning

TickingThread.IsOnTickThread

TickingThread.StartAsync()

TickingThread.StopAsync()

TickingThread.DisposeAsync()

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Universe manages the loaded Worlds. Each World controls Store access, startup, and shutdown; lifecycle, spatial, grid, and replication operations delegate to their separate runtime classes. Module asset catalogs and packet construction belong to their gameplay modules.

Properties

ChunkGrid

Chunk-grid leases and residency reports borrowed on this World's thread.

public WorldChunkGrid ChunkGrid { get; }

Property Value

WorldChunkGrid

Chunks

The world's chunks (generated on demand within the config bounds).

public ChunkStorage Chunks { get; }

Property Value

ChunkStorage

Config

Gets the loaded world configuration.

public WorldConfig Config { get; }

Property Value

WorldConfig

EntitySeed

Per-world seed the client uses for entity-visual determinism (sent via SetEntitySeed).

public int EntitySeed { get; }

Property Value

int

Grid

Spatial grid operations borrowed on this World's thread.

public WorldGrid Grid { get; }

Property Value

WorldGrid

IsIdle

Allows derived loops to reduce spin timing while still processing tasks and ticks.

protected override bool IsIdle { get; }

Property Value

bool

Name

Gets the stable world name used by the server runtime.

public string Name { get; }

Property Value

string

PlayerPackets

Gets the publisher for packet batches targeted at Players in this World.

public PlayerPacketPublisher PlayerPackets { get; }

Property Value

PlayerPacketPublisher

Players

Gets the current committed Players for this loaded World.

public WorldPlayerRegistry Players { get; }

Property Value

WorldPlayerRegistry

Replication

Replication connections and projections borrowed on this World's thread.

public WorldReplication Replication { get; }

Property Value

WorldReplication

Spatial

Spatial commands submitted synchronously on this World's thread for reconciliation.

public WorldSpatial Spatial { get; }

Property Value

WorldSpatial

SpatialQuery

Spatial view membership and queries borrowed on this World's thread.

public WorldSpatialQuery SpatialQuery { get; }

Property Value

WorldSpatialQuery

Storage

Gets storage information for the world save.

public WorldStorage Storage { get; }

Property Value

WorldStorage

Uuid

Gets the world UUID from the loaded configuration.

public Guid Uuid { get; }

Property Value

Guid

Methods

Compose(CompositionCallback, CompositionReason)

Configures members synchronously, then admits and publishes the composition.

public void Compose(CompositionCallback configure, CompositionReason reason = CompositionReason.Create)

Parameters

configure CompositionCallback

reason CompositionReason

Remarks

Requires immediate writable execution in this World's callback; nested compositions are rejected. Callback failure rolls back unpublished members and is rethrown, aggregated with any rollback failure. Admission rejection also rolls back. Publication failure is fatal and rethrown without rollback. Changes to existing entities or external resources are not transactional.

CreateEntity(EntityCreationCallback, CompositionReason)

Creates a primary entity and commits after synchronous configuration succeeds.

public Entity CreateEntity(EntityCreationCallback configure, CompositionReason reason = CompositionReason.Create)

Parameters

configure EntityCreationCallback

reason CompositionReason

Returns

Entity

Remarks

Requires immediate writable execution in this World's callback. Helpers may add members through the context. The returned Entity is borrowed only for the enclosing World callback. Identity and replication are optional; use Load explicitly when restoring members. Failure follows Compose: unpublished members roll back, while publication failure is fatal.

Delete(StableEntityId)

Permanently deletes the logical entity and retires its stable identity.

public bool Delete(StableEntityId id)

Parameters

id StableEntityId

Returns

bool

DeleteAsync(StableEntityId)

Queues deletion by stable ID and resolves it only inside the World callback.

public Task<bool> DeleteAsync(StableEntityId id)

Parameters

id StableEntityId

Returns

Task<bool>

DeleteAsync(WorldEntityReference)

Rejects a reference for another World before queuing stable-ID deletion.

public Task<bool> DeleteAsync(WorldEntityReference reference)

Parameters

reference WorldEntityReference

Returns

Task<bool>

DeleteEntity(Entity)

Deletes an entity borrowed inside this synchronous World callback.

public void DeleteEntity(Entity entity)

Parameters

entity Entity

DisposeAsyncCore()

Performs disposal once for the task published by DisposeAsync().

protected override Task DisposeAsyncCore()

Returns

Task

Remarks

Overrides must await this implementation and release derived resources in a finally block so every caller observes the same completion.

ExecuteAsync(Action<World>)

Executes synchronous Store work on the world thread.

public Task ExecuteAsync(Action<World> callback)

Parameters

callback Action<World>

Returns

Task

Remarks

Use this as the submission path to world-owned ECS state. The callback must not keep Store-owned handles for later use

ExecuteAsync<T>(Func<World, T>)

Executes synchronous Store work on the world thread and returns its result.

public Task<T> ExecuteAsync<T>(Func<World, T> callback)

Parameters

callback Func<World, T>

Returns

Task<T>

Type Parameters

T

Remarks

Use this as the submission path to world-owned ECS state. The callback must not keep Store-owned handles for later use

Expire(StableEntityId)

Runs expiry hooks and then requests ordinary deletion.

public bool Expire(StableEntityId id)

Parameters

id StableEntityId

Returns

bool

ExpireAsync(StableEntityId)

Queues expiry by stable ID and resolves it only inside the World callback.

public Task<bool> ExpireAsync(StableEntityId id)

Parameters

id StableEntityId

Returns

Task<bool>

ForEach(Query, Action<Entity>)

Visits resident query matches while deferring structural changes until iteration ends.

public void ForEach(Query query, Action<Entity> callback)

Parameters

query Query

callback Action<Entity>

Remarks

Use this helper for lifecycle calls inside queries. Raw Query.Each locks native tables without deferring deletion.

GetStoreDiagnostics()

Gets a point-in-time diagnostics snapshot for the owned Store.

public StoreDiagnostics GetStoreDiagnostics()

Returns

StoreDiagnostics

IsModuleEnabledAsync(string)

Gets runtime module activation on the world thread.

public Task<bool> IsModuleEnabledAsync(string moduleId)

Parameters

moduleId string

Returns

Task<bool>

LookupEntity(StableEntityId)

Looks up a stable ID during the current synchronous World callback.

public StableEntityLookup LookupEntity(StableEntityId id)

Parameters

id StableEntityId

Returns

StableEntityLookup

LookupEntityAsync(StableEntityId)

Resolves a stable ID inside a queued synchronous World callback.

public Task<StableEntityLookup> LookupEntityAsync(StableEntityId id)

Parameters

id StableEntityId

Returns

Task<StableEntityLookup>

OnShutdown()

Runs once on the loop thread after the tick loop exits.

protected override void OnShutdown()

OnStart()

Runs once on the loop thread before the start task completes.

protected override void OnStart()

OpenComposition(CompositionReason)

Opens an immediate writable composition with explicit commit or rollback authority. Deferred, readonly and staged execution are unsupported. Cross-thread callers can enter the callback through ExecuteAsync; calling it within a system does not change that system's execution context.

public CompositionUnit OpenComposition(CompositionReason reason)

Parameters

reason CompositionReason

Returns

CompositionUnit

OpenTransaction()

Opens a synchronous transaction owned by this world's tick thread.

public Transaction OpenTransaction()

Returns

Transaction

Exceptions

InvalidOperationException

Thrown when called off the world thread or while the world is not running.

PublishModulePackets(string, IReadOnlyList<IToClientPacket>)

Publishes a module-owned packet batch from this world's current Store callback.

public void PublishModulePackets(string moduleId, IReadOnlyList<IToClientPacket> packets)

Parameters

moduleId string

packets IReadOnlyList<IToClientPacket>

ReportPipelineFailure(Exception)

Retains the first root, stops further inbox work, and rethrows it at the next safe tick boundary.

public void ReportPipelineFailure(Exception exception)

Parameters

exception Exception

SetModuleEnabledAsync(string, bool)

Changes runtime module activation on the world thread.

public Task<bool> SetModuleEnabledAsync(string moduleId, bool enabled)

Parameters

moduleId string

enabled bool

Returns

Task<bool>

Whether the activation profile changed.

SetTicksPerSecondAsync(int)

Queues a runtime TPS change onto the world thread.

public Task SetTicksPerSecondAsync(int ticksPerSecond)

Parameters

ticksPerSecond int

Returns

Task

Tick(float)

Runs one measured tick on the loop thread.

protected override void Tick(float deltaSeconds)

Parameters

deltaSeconds float

TryGetNetworkEntityId(Entity, out NetworkEntityId)

Reads the network identity of an entity borrowed inside this World callback.

public bool TryGetNetworkEntityId(Entity entity, out NetworkEntityId id)

Parameters

entity Entity

id NetworkEntityId

Returns

bool

TryGetStableEntityId(Entity, out StableEntityId)

Reads the stable identity of an entity borrowed inside this World callback.

public bool TryGetStableEntityId(Entity entity, out StableEntityId id)

Parameters

entity Entity

id StableEntityId

Returns

bool

Unload(StableEntityId)

Unloads the entity while preserving its stable identity.

public bool Unload(StableEntityId id)

Parameters

id StableEntityId

Returns

bool

UnloadAsync(StableEntityId)

Queues unload by stable ID and resolves it only inside the World callback.

public Task<bool> UnloadAsync(StableEntityId id)

Parameters

id StableEntityId

Returns

Task<bool>

UnloadEntity(Entity)

Unloads an entity borrowed inside this synchronous World callback.

public void UnloadEntity(Entity entity)

Parameters

entity Entity