Table of Contents

Class WorldRuntime

Namespace
TileWorld.Engine.Runtime
Assembly
TileWorld.Engine.dll

Composes world data, editing rules, persistence hooks, and advanced tooling support behind a single gameplay-facing facade.

public sealed class WorldRuntime
Inheritance
WorldRuntime
Inherited Members

Remarks

Prefer this type as the stable entry point for gameplay code, editor tooling, and hosts. Lower-level runtime services are kept internal so external callers do not accidentally couple themselves to transient engine plumbing.

Constructors

WorldRuntime(WorldData, ContentRegistry)

Creates an in-memory world runtime without persistence options.

public WorldRuntime(WorldData worldData, ContentRegistry contentRegistry)

Parameters

worldData WorldData

The world data to own and mutate.

contentRegistry ContentRegistry

The content registry used to resolve tile definitions.

WorldRuntime(WorldData, ContentRegistry, WorldRuntimeOptions)

Creates a world runtime with optional persistence and auto-save behavior.

public WorldRuntime(WorldData worldData, ContentRegistry contentRegistry, WorldRuntimeOptions options)

Parameters

worldData WorldData

The world data to own and mutate.

contentRegistry ContentRegistry

The content registry used to resolve tile definitions.

options WorldRuntimeOptions

Optional persistence and auto-save configuration.

Properties

ContentRegistry

Gets the content registry used to resolve tile definitions referenced by the runtime.

public ContentRegistry ContentRegistry { get; }

Property Value

ContentRegistry

IsPersistenceEnabled

Gets a value indicating whether this runtime is currently backed by persistent world storage.

public bool IsPersistenceEnabled { get; }

Property Value

bool

Options

Gets the runtime options that control persistence and auto-save behavior.

public WorldRuntimeOptions Options { get; }

Property Value

WorldRuntimeOptions

Storage

Gets the storage backend when persistence is enabled.

public WorldStorage Storage { get; }

Property Value

WorldStorage

Remarks

This property is available for hosting and diagnostics scenarios. Gameplay code should usually prefer higher-level methods such as SaveWorld() and EnsureChunkLoaded(ChunkCoord).

WorldData

Gets the mutable world data owned by this runtime.

public WorldData WorldData { get; }

Property Value

WorldData

Methods

BreakTile(WorldTileCoord, TileBreakContext)

Breaks the foreground tile at the supplied coordinate using break semantics and validation rules.

public TileEditResult BreakTile(WorldTileCoord coord, TileBreakContext context)

Parameters

coord WorldTileCoord

The target world-tile coordinate.

context TileBreakContext

Break metadata and behavior flags.

Returns

TileEditResult

The outcome of the break attempt.

CanPlaceObject(WorldTileCoord, int, ObjectPlacementContext)

Evaluates whether an object placement would currently succeed.

public bool CanPlaceObject(WorldTileCoord anchorCoord, int objectDefId, ObjectPlacementContext context)

Parameters

anchorCoord WorldTileCoord

The logical object anchor coordinate.

objectDefId int

The object definition identifier to place.

context ObjectPlacementContext

Placement metadata and behavior flags.

Returns

bool

true when placement would currently succeed.

EnsureActiveAround(WorldTileCoord)

Ensures the active chunk set around the supplied world-tile coordinate.

public void EnsureActiveAround(WorldTileCoord center)

Parameters

center WorldTileCoord

The world-tile coordinate that should remain centered in the active set.

EnsureChunkLoaded(ChunkCoord)

Ensures that the chunk at the supplied coordinate is available in memory.

public Chunk EnsureChunkLoaded(ChunkCoord coord)

Parameters

coord ChunkCoord

The chunk coordinate to load or create.

Returns

Chunk

The loaded or newly created chunk.

Remarks

This method is intended for hosts, tooling, and controlled world bootstrap flows. Gameplay logic should usually access world state via tile-level APIs such as GetCell(WorldTileCoord, QueryOptions), PlaceTile(WorldTileCoord, ushort, TilePlacementContext), and BreakTile(WorldTileCoord, TileBreakContext).

EnumerateEntities()

Enumerates all active prototype entities.

public IEnumerable<Entity> EnumerateEntities()

Returns

IEnumerable<Entity>

The active entities.

GetActiveChunks()

Enumerates the currently active chunk coordinates.

public IEnumerable<ChunkCoord> GetActiveChunks()

Returns

IEnumerable<ChunkCoord>

The active chunk coordinates.

GetCell(WorldTileCoord, QueryOptions)

Resolves a cell at the supplied world-tile coordinate.

public TileCell GetCell(WorldTileCoord coord, QueryOptions options = null)

Parameters

coord WorldTileCoord

The world-tile coordinate to inspect.

options QueryOptions

Optional query behavior overrides.

Returns

TileCell

The resolved cell, or Empty when no cell data is available.

GetObject(int)

Resolves an object instance by identifier.

public ObjectInstance GetObject(int objectInstanceId)

Parameters

objectInstanceId int

The object instance identifier to resolve.

Returns

ObjectInstance

The resolved object instance.

HasBackgroundWall(WorldTileCoord)

Returns whether the supplied coordinate contains a background wall.

public bool HasBackgroundWall(WorldTileCoord coord)

Parameters

coord WorldTileCoord

The world-tile coordinate to inspect.

Returns

bool

true when a background wall is present.

Initialize()

Transitions the runtime into the initialized state.

public void Initialize()

IsSolid(WorldTileCoord)

Returns whether the foreground tile at the supplied coordinate is solid.

public bool IsSolid(WorldTileCoord coord)

Parameters

coord WorldTileCoord

The world-tile coordinate to inspect.

Returns

bool

true when the foreground tile is solid.

LoadChunk(ChunkCoord)

Loads or creates a chunk and returns detailed source information.

public ChunkLoadResult LoadChunk(ChunkCoord coord)

Parameters

coord ChunkCoord

The chunk coordinate to load or create.

Returns

ChunkLoadResult

The detailed chunk load result.

PlaceObject(WorldTileCoord, int, ObjectPlacementContext)

Places an object instance into the world.

public ObjectPlacementResult PlaceObject(WorldTileCoord anchorCoord, int objectDefId, ObjectPlacementContext context)

Parameters

anchorCoord WorldTileCoord

The logical object anchor coordinate.

objectDefId int

The object definition identifier to place.

context ObjectPlacementContext

Placement metadata and behavior flags.

Returns

ObjectPlacementResult

The outcome of the placement attempt.

PlaceTile(WorldTileCoord, ushort, TilePlacementContext)

Places a foreground tile using placement semantics and validation rules.

public TileEditResult PlaceTile(WorldTileCoord coord, ushort tileId, TilePlacementContext context)

Parameters

coord WorldTileCoord

The target world-tile coordinate.

tileId ushort

The non-air tile identifier to place.

context TilePlacementContext

Placement metadata and behavior flags.

Returns

TileEditResult

The outcome of the placement attempt.

RemoveBackgroundWall(WorldTileCoord)

Removes the background wall at the supplied coordinate.

public bool RemoveBackgroundWall(WorldTileCoord coord)

Parameters

coord WorldTileCoord

The target world-tile coordinate.

Returns

bool

true when a background wall existed and was removed.

RemoveForegroundTile(WorldTileCoord)

Removes the foreground tile at the supplied coordinate without break validation.

public TileEditResult RemoveForegroundTile(WorldTileCoord coord)

Parameters

coord WorldTileCoord

The target world-tile coordinate.

Returns

TileEditResult

The outcome of the removal operation.

RemoveObject(int, bool)

Removes an object instance from the world.

public bool RemoveObject(int objectInstanceId, bool destroyed = true)

Parameters

objectInstanceId int

The object instance identifier to remove.

destroyed bool

Whether the removal should be treated as destruction.

Returns

bool

true when the object instance existed and was removed.

SaveWorld()

Persists metadata and all save-dirty chunks for the current world.

public int SaveWorld()

Returns

int

The number of chunk payloads written to storage.

SetBackgroundWall(WorldTileCoord, ushort)

Writes a background wall directly to the world.

public bool SetBackgroundWall(WorldTileCoord coord, ushort wallId)

Parameters

coord WorldTileCoord

The target world-tile coordinate.

wallId ushort

The non-empty wall identifier to write.

Returns

bool

true when the write succeeds.

SetForegroundTile(WorldTileCoord, ushort)

Writes a non-air foreground tile directly to the world without placement validation.

public TileEditResult SetForegroundTile(WorldTileCoord coord, ushort tileId)

Parameters

coord WorldTileCoord

The target world-tile coordinate.

tileId ushort

The non-air tile identifier to write.

Returns

TileEditResult

The outcome of the write operation.

SetPlayerInput(int, float, bool)

Applies movement input to a player entity for the next update.

public void SetPlayerInput(int entityId, float moveAxis, bool jumpRequested)

Parameters

entityId int

The target player entity identifier.

moveAxis float

The horizontal movement axis in the range [-1, 1].

jumpRequested bool

Whether a jump should be attempted.

Shutdown()

Shuts down the runtime and performs final persistence when enabled.

public void Shutdown()

SpawnPlayer(Float2)

Spawns a controllable player prototype at the supplied world position in tile units.

public int SpawnPlayer(Float2 position)

Parameters

position Float2

The player spawn position in world tile units.

Returns

int

The created player entity identifier.

Subscribe<TEvent>(Action<TEvent>)

Subscribes to a runtime event stream.

public void Subscribe<TEvent>(Action<TEvent> handler)

Parameters

handler Action<TEvent>

The handler that should receive published events.

Type Parameters

TEvent

The event payload type to observe.

TryGetCell(WorldTileCoord, out TileCell, QueryOptions)

Attempts to resolve a cell at the supplied world-tile coordinate.

public bool TryGetCell(WorldTileCoord coord, out TileCell cell, QueryOptions options = null)

Parameters

coord WorldTileCoord

The world-tile coordinate to inspect.

cell TileCell

The resolved cell when available.

options QueryOptions

Optional query behavior overrides.

Returns

bool

true when the cell was resolved.

TryGetEntity(int, out Entity)

Attempts to resolve an entity by identifier.

public bool TryGetEntity(int entityId, out Entity entity)

Parameters

entityId int

The entity identifier to resolve.

entity Entity

The resolved entity when present.

Returns

bool

true when the entity exists.

TryGetLoadedChunk(ChunkCoord, out Chunk)

Attempts to resolve a chunk that is already loaded in memory.

public bool TryGetLoadedChunk(ChunkCoord coord, out Chunk chunk)

Parameters

coord ChunkCoord

The chunk coordinate to inspect.

chunk Chunk

The loaded chunk when present.

Returns

bool

true when the chunk is already loaded.

TryGetObject(int, out ObjectInstance)

Attempts to resolve an object instance by identifier.

public bool TryGetObject(int objectInstanceId, out ObjectInstance instance)

Parameters

objectInstanceId int

The object instance identifier to resolve.

instance ObjectInstance

The resolved object instance when present.

Returns

bool

true when the instance exists.

TryGetObjectAt(WorldTileCoord, out ObjectInstance)

Attempts to resolve an object instance occupying a world-tile coordinate.

public bool TryGetObjectAt(WorldTileCoord coord, out ObjectInstance instance)

Parameters

coord WorldTileCoord

The world-tile coordinate to inspect.

instance ObjectInstance

The resolved object instance when present.

Returns

bool

true when an object occupies the coordinate.

Unsubscribe<TEvent>(Action<TEvent>)

Unsubscribes a previously registered runtime event handler.

public void Unsubscribe<TEvent>(Action<TEvent> handler)

Parameters

handler Action<TEvent>

The handler to remove.

Type Parameters

TEvent

The event payload type to stop observing.

Update(FrameTime)

Advances runtime bookkeeping for the current frame, including auto-save checks.

public void Update(FrameTime frameTime)

Parameters

frameTime FrameTime

The frame timing snapshot supplied by the active host.