Class Universe

Namespace

Shard.Gameplay.Universe

Assembly

Shard.Gameplay.Universe.dll

Owns the loaded gameplay worlds for a server instance.

public sealed class Universe : IAsyncDisposable

Inheritance

object

Universe

Implements

IAsyncDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

World load, unload, and disposal are serialized through one lifecycle gate. The first admitted load attempt freezes the Store definition registry before composing its candidate. The same immutable definitions are then reused by every later world, even when that first attempt fails. Disposal synchronously seals world publication and clears both lookup indexes before waiting for the lifecycle gate.

Fields

DefaultWorldName

Default world name used when server config does not provide one.

public const string DefaultWorldName = "default"

Field Value

string

Properties

LoadedWorldNames

Gets a snapshot of loaded world names.

public IReadOnlyCollection<string> LoadedWorldNames { get; }

Property Value

IReadOnlyCollection<string>

LoadedWorldUuids

Gets a snapshot of loaded world UUIDs.

public IReadOnlyCollection<Guid> LoadedWorldUuids { get; }

Property Value

IReadOnlyCollection<Guid>

Models

Model store used to build a joining player's avatar after assets are available.

public IModelStore? Models { get; set; }

Property Value

IModelStore

SolidBlockId

Gets the block ID used to fill solid terrain voxels. The host resolves it from the active biome material. It defaults to the placeholder value when the material is unavailable.

public ushort SolidBlockId { get; set; }

Property Value

ushort

TerrainDensityFactory

Builds the world's terrain density from its seed using the Hytale v2 generator assets. When null, the world uses the placeholder heightmap.

public Func<long, Density?>? TerrainDensityFactory { get; set; }

Property Value

Func<long, Density>

WorldDefaults

World asset defaults used by join weather/environment; set once assets are available.

public IWorldDefaults? WorldDefaults { get; set; }

Property Value

IWorldDefaults

Methods

AddPlayerAsync(PlayerJoinStart, CancellationToken)

Adds an authenticated player to a loaded world and installs its gameplay endpoint.

public Task<Player> AddPlayerAsync(PlayerJoinStart start, CancellationToken cancellationToken)

Parameters

start PlayerJoinStart

cancellationToken CancellationToken

Returns

Task<Player>

The exact Player whose initial world binding committed.

Remarks

Failure runs exact runtime and avatar rollback. Cancellation applies only until global Player publication.

DisposeAsync()

Unloads and disposes every world owned by the universe.

public ValueTask DisposeAsync()

Returns

ValueTask

Remarks

The first caller synchronously prevents further world publication and captures all currently loaded worlds. Every caller observes the same cached completion. Disposal attempts every captured world before reporting an AggregateException containing any failures.

Get()

Get a instance of Universe

public static Universe Get()

Returns

Universe

LoadInitialWorldsAsync(string?, CancellationToken)

Loads worlds required during server boot.

public Task LoadInitialWorldsAsync(string? defaultWorldName = "default", CancellationToken cancellationToken = default)

Parameters

defaultWorldName string

cancellationToken CancellationToken

Returns

Task

Remarks

This is the future hook for loading saved worlds before creating the default fallback.

LoadWorldAsync(string, WorldConfig?, WorldStorage?)

Creates, starts, and registers a world using the frozen Store definitions.

public Task LoadWorldAsync(string name, WorldConfig? config = null, WorldStorage? storage = null)

Parameters

name string

config WorldConfig

storage WorldStorage

Returns

Task

Remarks

The lifecycle gate prevents concurrent definition application during first load and keeps publication ordered with unload and disposal. A failed candidate is disposed without being published; freezing is not rolled back.

TryGetWorld(Guid, out World?)

Attempts to resolve a loaded world by UUID.

public bool TryGetWorld(Guid uuid, out World? world)

Parameters

uuid Guid

world World

Returns

bool

TryGetWorld(string, out World?)

Attempts to resolve a loaded world by name.

public bool TryGetWorld(string name, out World? world)

Parameters

name string

world World

Returns

bool

UnloadWorldAsync(string)

Unloads and disposes a world by name.

public Task<bool> UnloadWorldAsync(string name)

Parameters

name string

Returns

Task<bool>