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.

EnsureActiveForTileArea(RectI, int)

Ensures that chunks covering a world-tile area remain active, with optional extra chunk padding.

public void EnsureActiveForTileArea(RectI tileBounds, int activePaddingInChunks = 0)

Parameters

tileBounds RectI

The world-tile area that should remain synchronously active.

activePaddingInChunks int

The number of extra chunk rings that should remain active around the area.

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.

GetBiomeId(WorldTileCoord)

Resolves the derived biome identifier at a world-tile coordinate.

public int GetBiomeId(WorldTileCoord coord)

Parameters

coord WorldTileCoord

The world-tile coordinate to inspect.

Returns

int

The derived biome identifier for the coordinate.

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.

GetLightLevel(WorldTileCoord)

Resolves the derived single-channel light level at a world-tile coordinate.

public byte GetLightLevel(WorldTileCoord coord)

Parameters

coord WorldTileCoord

The world-tile coordinate to inspect.

Returns

byte

The light level in the range 0..15.

GetLiquidState(WorldTileCoord)

Resolves liquid information at a world-tile coordinate.

public LiquidState GetLiquidState(WorldTileCoord coord)

Parameters

coord WorldTileCoord

The world-tile coordinate to inspect.

Returns

LiquidState

The resolved liquid state, or None when no liquid is present.

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.

IsWithinWorldBounds(WorldTileCoord)

Returns whether the supplied world-tile coordinate falls inside the world's optional vertical bounds.

public bool IsWithinWorldBounds(WorldTileCoord coord)

Parameters

coord WorldTileCoord

The world-tile coordinate to inspect.

Returns

bool

true when the coordinate is within the configured world bounds.

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.

RemoveLiquid(WorldTileCoord)

Removes liquid from a world cell.

public bool RemoveLiquid(WorldTileCoord coord)

Parameters

coord WorldTileCoord

The world-tile coordinate to clear.

Returns

bool

true when the clear operation succeeded.

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.

SetLiquid(WorldTileCoord, byte, byte)

Writes liquid values directly to a world cell.

public bool SetLiquid(WorldTileCoord coord, byte liquidType, byte liquidAmount)

Parameters

coord WorldTileCoord

The world-tile coordinate to update.

liquidType byte

The liquid type identifier. Use 0 only when liquidAmount is 0.

liquidAmount byte

The liquid amount in the range 0..255.

Returns

bool

true when the write succeeded.

SetPlayerHeldLightLevel(int, byte)

Sets the held-light contribution for a player-controlled entity.

public void SetPlayerHeldLightLevel(int entityId, byte lightLevel)

Parameters

entityId int

The target player entity identifier.

lightLevel byte

The held-light level in the range 0..15.

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.

TryGetBiomeDef(WorldTileCoord, out BiomeDef)

Attempts to resolve the biome definition at a world-tile coordinate.

public bool TryGetBiomeDef(WorldTileCoord coord, out BiomeDef biomeDef)

Parameters

coord WorldTileCoord

The world-tile coordinate to inspect.

biomeDef BiomeDef

The resolved biome definition when registered.

Returns

bool

true when a registered biome definition was resolved.

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.

TryGetLightLevel(WorldTileCoord, out byte)

Attempts to resolve the derived single-channel light level at a world-tile coordinate.

public bool TryGetLightLevel(WorldTileCoord coord, out byte level)

Parameters

coord WorldTileCoord

The world-tile coordinate to inspect.

level byte

The resolved light level when available.

Returns

bool

true when the containing chunk is available and a light value could be resolved.

TryGetLiquid(WorldTileCoord, out byte, out byte)

Attempts to resolve liquid information at a world-tile coordinate.

public bool TryGetLiquid(WorldTileCoord coord, out byte liquidType, out byte liquidAmount)

Parameters

coord WorldTileCoord

The world-tile coordinate to inspect.

liquidType byte

The resolved liquid type identifier when a liquid is present.

liquidAmount byte

The resolved liquid amount in the range 0..255.

Returns

bool

true when a liquid is present in the cell.

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.