TilemapComponent

Defined in: tilemap/src/TilemapComponent.ts:64

Component that renders a Tiled map using @pixi/tilemap.

Extends

• VisualComponent

Constructors

Constructor

new TilemapComponent(options): TilemapComponent

Defined in: tilemap/src/TilemapComponent.ts:83

Parameters

options

TilemapComponentOptions

Returns

TilemapComponent

Overrides

VisualComponent.constructor

Properties

container

readonly container: DisplayContainer

Defined in: tilemap/src/TilemapComponent.ts:67

---

data

readonly data: TilemapData

Defined in: tilemap/src/TilemapComponent.ts:68

---

entity

entity: Entity

Defined in: core/dist/index.d.ts:2716

Back-reference to the owning entity. Set by the engine when the component is added to an entity. Do not set manually.

Inherited from

VisualComponent.entity

---

fx

readonly fx: EffectsHost

Defined in: renderer/dist/index.d.ts:181

Component-scope effects host. .fx.addEffect(...) attaches a filter to this component’s render object; the effect is torn down automatically when the entity or component is destroyed. .fx.findEffect(definition) recovers the handle for the first matching effect after save/load.

Inherited from

VisualComponent.fx

---

keyPrefix

readonly keyPrefix: string | null

Defined in: tilemap/src/TilemapComponent.ts:72

Prefix used to derive auto-keys for entities spawned from objects.

---

layerName

readonly layerName: string

Defined in: renderer/dist/index.d.ts:174

Inherited from

VisualComponent.layerName

---

mapKey

readonly mapKey: string | null

Defined in: tilemap/src/TilemapComponent.ts:70

Asset path of this map, or null if constructed from a raw TiledMapData without one.

---

restorePriority

static restorePriority: number = 50

Defined in: tilemap/src/TilemapComponent.ts:65

Overrides

VisualComponent.restorePriority

---

updatePriority?

static optional updatePriority?: number

Defined in: core/dist/index.d.ts:2889

Class-level default for updatePriority: every instance runs at this priority unless its own updatePriority is written. Undeclared = 0. Subclasses inherit their base class’s value unless they declare their own. Declare it on a component whose behavior depends on running after (or before) a sibling, so the entity that adds it does not have to control the add order.

class BoundsClamp extends Component {
  static updatePriority = 10; // after the follow that moves the camera
}

Inherited from

VisualComponent.updatePriority

Accessors

alpha

Get Signature

get alpha(): number

Defined in: tilemap/src/TilemapComponent.ts:161

Set the container’s alpha (opacity).

Returns

number

Set Signature

set alpha(alpha): void

Defined in: tilemap/src/TilemapComponent.ts:156

Set the container’s alpha (opacity).

Parameters

alpha

number

Returns

void

Overrides

VisualComponent.alpha

---

blendMode

Get Signature

get blendMode(): BLEND_MODES

Defined in: renderer/dist/index.d.ts:209

Get the container’s blend mode.

Returns

BLEND_MODES

Set Signature

set blendMode(mode): void

Defined in: renderer/dist/index.d.ts:207

Set how the container combines with what is drawn beneath it.

Parameters

mode

BLEND_MODES

Returns

void

Inherited from

VisualComponent.blendMode

---

context

Get Signature

get context(): EngineContext

Defined in: core/dist/index.d.ts:2770

Access the EngineContext from the entity’s scene. Throws if the entity is not in a scene.

Returns

EngineContext

Inherited from

VisualComponent.context

---

effectiveEnabled

Get Signature

get effectiveEnabled(): boolean

Defined in: core/dist/index.d.ts:2740

Whether the component is actually running: enabled, on an active entity, and past onAdd. This is the state onEnable and onDisable track — read it when a method has to behave one way live and another way dormant.

Returns

boolean

Inherited from

VisualComponent.effectiveEnabled

---

enabled

Get Signature

get enabled(): boolean

Defined in: core/dist/index.d.ts:2732

Whether this component runs. Disabled components are skipped by ComponentUpdateSystem.

Writing this fires onEnable / onDisable when the effective state changes — enabled && entity.isActive. A component disabled here stays disabled through a setActive(false) / setActive(true) cycle on its entity.

Returns

boolean

Set Signature

set enabled(value): void

Defined in: core/dist/index.d.ts:2733

Parameters

value

boolean

Returns

void

Inherited from

VisualComponent.enabled

---

heightPx

Get Signature

get heightPx(): number

Defined in: tilemap/src/TilemapComponent.ts:228

Map height in pixels.

Returns

number

---

mask

Get Signature

get mask(): MaskHandle | undefined

Defined in: renderer/dist/index.d.ts:241

The currently attached mask handle, if any. Useful after save/load to recover a handle whose caller-side reference went stale.

Returns

MaskHandle | undefined

Inherited from

VisualComponent.mask

---

renderObject

Get Signature

get renderObject(): DisplayContainer

Defined in: tilemap/src/TilemapComponent.ts:141

The underlying tilemap container.

Returns

DisplayContainer

Overrides

VisualComponent.renderObject

---

scene

Get Signature

get scene(): Scene

Defined in: core/dist/index.d.ts:2765

Access the entity’s scene. Throws if the entity is not in a scene. Prefer this over threading through this.entity.scene in component code.

Returns

Scene

Inherited from

VisualComponent.scene

---

tileHeight

Get Signature

get tileHeight(): number

Defined in: tilemap/src/TilemapComponent.ts:238

Tile height in pixels.

Returns

number

---

tileWidth

Get Signature

get tileWidth(): number

Defined in: tilemap/src/TilemapComponent.ts:233

Tile width in pixels.

Returns

number

---

tint

Get Signature

get tint(): number

Defined in: tilemap/src/TilemapComponent.ts:152

Set the container’s tint color.

Returns

number

Set Signature

set tint(color): void

Defined in: tilemap/src/TilemapComponent.ts:147

Set the container’s tint color.

Parameters

color

ColorSource

Returns

void

Overrides

VisualComponent.tint

---

updatePriority

Get Signature

get updatePriority(): number

Defined in: core/dist/index.d.ts:2758

Where this component runs among its siblings. ComponentUpdateSystem calls update / fixedUpdate on an entity’s components in ascending priority; equal priorities run in add order. Undeclared = 0, so a negative value runs before siblings that keep the default and a positive value runs after them. Writable at any time, before or after add(). Defaults to the class’s static updatePriority.

class Player extends Entity {
  setup() {
    this.add(new Mover());
    this.add(new Brain()).updatePriority = -1; // decides before Mover moves
  }
}

Returns

number

Set Signature

set updatePriority(value): void

Defined in: core/dist/index.d.ts:2759

Parameters

value

number

Returns

void

Inherited from

VisualComponent.updatePriority

---

visible

Get Signature

get visible(): boolean

Defined in: renderer/dist/index.d.ts:216

Get the requested visibility, whatever the entity’s activeness.

Returns

boolean

Set Signature

set visible(value): void

Defined in: renderer/dist/index.d.ts:214

Set the container’s visibility. Written while the entity is dormant, it is remembered and applied when the entity is activated.

Parameters

value

boolean

Returns

void

Inherited from

VisualComponent.visible

---

widthPx

Get Signature

get widthPx(): number

Defined in: tilemap/src/TilemapComponent.ts:223

Map width in pixels.

Returns

number

Methods

_applyEnabled()

_applyEnabled(effective): void

Defined in: core/dist/index.d.ts:2824

Internal

Force an effective-enabled transition, firing the hook on a flip. Used by Entity for teardown, where enabled and the entity’s activeness both still read true.

Parameters

effective

boolean

Returns

void

Inherited from

VisualComponent._applyEnabled

---

_refreshEnabled()

_refreshEnabled(): void

Defined in: core/dist/index.d.ts:2817

Internal

Recompute effective enabled-ness from enabled and the entity’s activeness, firing the hook on a flip.

Returns

void

Inherited from

VisualComponent._refreshEnabled

---

_runCleanups()

_runCleanups(): void

Defined in: core/dist/index.d.ts:2811

Internal

Run and clear all registered cleanups. Called by Entity.remove() and Entity._performDestroy() before onRemove/onDestroy.

Returns

void

Inherited from

VisualComponent._runCleanups

---

addCleanup()

protected addCleanup(fn): void

Defined in: core/dist/index.d.ts:2805

Register a cleanup function to run when this component is removed or destroyed.

Parameters

fn

() => void

Returns

void

Inherited from

VisualComponent.addCleanup

---

afterRestore()

afterRestore(data): void

Defined in: tilemap/src/TilemapComponent.ts:209

Restore effects and masks after the tilemap is parented.

Parameters

data

TilemapComponentData

Returns

void

Overrides

VisualComponent.afterRestore

---

applyVisualOptions()

protected applyVisualOptions(options): void

Defined in: renderer/dist/index.d.ts:197

Apply the shared visible/tint/alpha/interactive options to renderObject. Call once from the subclass constructor, after the concrete Pixi object is created.

Parameters

options

VisualComponentOptions

Returns

void

Inherited from

VisualComponent.applyVisualOptions

---

clearMask()

clearMask(): void

Defined in: renderer/dist/index.d.ts:236

Detach and destroy the current mask, if any.

Returns

void

Inherited from

VisualComponent.clearMask

---

destroyOptions()

protected destroyOptions(): DestroyOptions

Defined in: tilemap/src/TilemapComponent.ts:443

Pixi destroy options passed to renderObject.destroy(). Default: undefined (Pixi’s own defaults). Override for a component whose destroy must cascade to children (SplitText’s per-segment display objects).

Returns

DestroyOptions

Overrides

VisualComponent.destroyOptions

---

findObject()

findObject(id): MapObject | undefined

Defined in: tilemap/src/TilemapComponent.ts:401

Find an object by its Tiled id. Searches every object layer.

Parameters

id

number

Returns

MapObject | undefined

---

findObjectByName()

findObjectByName(name): MapObject | undefined

Defined in: tilemap/src/TilemapComponent.ts:411

Find the first object with a matching name. Searches every object layer.

Parameters

name

string

Returns

MapObject | undefined

---

fixedUpdate()?

optional fixedUpdate(dt): void

Defined in: core/dist/index.d.ts:2863

Called every fixed timestep by the built-in ComponentUpdateSystem.

Parameters

dt

number

Fixed timestep in seconds, scaled by scene and entity timeScale.

Returns

void

Inherited from

VisualComponent.fixedUpdate

---

forEachObject()

forEachObject(layerName, fn): void

Defined in: tilemap/src/TilemapComponent.ts:371

Iterate every object on the given layer (or every layer if omitted), passing the auto-derived stable key alongside each object so callers can spawn entities with scene.spawn(Class, params, { key }).

Skips objects that don’t have a key prefix (component constructed from raw map: without mapKey or keyPrefix) — those callers should iterate getObjects directly.

Parameters

layerName

string | undefined

fn

(obj, key) => void

Returns

void

---

getAllObjects()

getAllObjects(): MapObject[]

Defined in: tilemap/src/TilemapComponent.ts:352

Flat list of every object across every object layer. Memoized — safe because parsed map data is immutable post-construction.

Returns

MapObject[]

---

getCollisionShapes()

getCollisionShapes(objectLayerName?): TilemapColliderConfig[]

Defined in: tilemap/src/TilemapComponent.ts:294

Extract physics-agnostic collision shapes from object layers.

Parameters

objectLayerName?

string

Returns

TilemapColliderConfig[]

---

getObjectGroups()

getObjectGroups(objectLayerName?): MapObjectGroup[]

Defined in: tilemap/src/TilemapComponent.ts:323

Objects grouped strictly by object layer and class.

Parameters

objectLayerName?

string

Returns

MapObjectGroup[]

---

getObjects()

getObjects(objectLayerName?): Record<string, MapObject[]>

Defined in: tilemap/src/TilemapComponent.ts:302

Objects grouped by class ?? name. Use getObjectGroups when the source layer must be preserved.

Parameters

objectLayerName?

string

Returns

Record<string, MapObject[]>

---

getProperty()

getProperty<T>(obj, name): T | undefined

Defined in: tilemap/src/TilemapComponent.ts:421

Read a typed custom property from any tilemap data that has properties.

Type Parameters

T

T = unknown

Parameters

obj

HasProperties

name

string

Returns

T | undefined

---

getPropertyArray()

getPropertyArray<T>(obj, name): T[]

Defined in: tilemap/src/TilemapComponent.ts:426

Read an indexed property bag (name[0], name[1], …) as an array.

Type Parameters

T

T = unknown

Parameters

obj

HasProperties

name

string

Returns

T[]

---

getTileAt()

getTileAt(worldX, worldY, layerName?): number | null

Defined in: tilemap/src/TilemapComponent.ts:260

Returns the tile id at a world position, accounting for the entity Transform and each layer’s own draw offset. Returns null if the position is outside every layer or the tile is empty.

A tileset’s tileoffset is not reversed here: it moves where a tile’s image is drawn, not which cell the tile occupies, and one layer can mix tilesets that offset differently. So a tile from an offset tileset answers at its cell, which is where its collision and neighbours are, rather than under the part of the image that overhangs. A tile image that does not match the grid is the same case: it sits on its cell’s bottom edge, and the cells its image reaches into answer with whatever they hold themselves.

Tiled’s flip bits are stripped, so the id compares against a tileset’s numbering whichever way the tile faces. Read them from the raw layer data with readTileGid when orientation matters.

Parameters

worldX

number

worldY

number

layerName?

string

Returns

number | null

---

inspectRender()

inspectRender(): object

Defined in: renderer/dist/index.d.ts:248

Derived render facet for the Inspector — world-space bounds and the component’s own (local, non-inherited) visible flag, computed on demand from the live render object. Not part of serialize(); see computeRenderFacet for the bounds coordinate space.

Returns

bounds

bounds: { height: number; width: number; x: number; y: number; } | null

Axis-aligned bounding box of the component’s geometry, in world space (the same coordinate space the Inspector reports for entity.transform — pixels, before camera/viewport projection). Measured from the geometry itself, so a sized-but-hidden object still reports its real box; null means there is no measurable geometry at all (an empty Graphics, a zero-area object), NOT that the object is hidden. Read RenderFacetSnapshot.visible for the hidden/shown state.

visible

visible: boolean

The component’s own (local, non-inherited) visibility flag at snapshot time. A hidden ancestor (e.g. a parent/layer container set invisible) is NOT folded in — read the relevant parent separately if you need the fully resolved on-screen state.

Inherited from

VisualComponent.inspectRender

---

listen()

protected listen<T>(entity, token, handler): void

Defined in: core/dist/index.d.ts:2797

Subscribe to events on any entity, auto-unsubscribe on removal.

Type Parameters

T

T

Parameters

entity

Entity

token

EventToken<T>

handler

(data) => void

Returns

void

Inherited from

VisualComponent.listen

---

listenScene()

protected listenScene<T>(token, handler): void

Defined in: core/dist/index.d.ts:2803

Subscribe to scene-level events, auto-unsubscribe on removal. Handlers fire for bubbled entity events (entity = source) and scene.emit events (entity = undefined).

Type Parameters

T

T

Parameters

token

EventToken<T>

handler

(data, entity?) => void

Returns

void

Inherited from

VisualComponent.listenScene

---

objectKey()

objectKey(obj): string

Defined in: tilemap/src/TilemapComponent.ts:391

Auto-derived stable key for an object: <keyPrefix>#object:<id>.

Parameters

obj

MapObject

Returns

string

---

onAdd()

onAdd(): void

Defined in: tilemap/src/TilemapComponent.ts:165

Returns

void

Overrides

VisualComponent.onAdd

---

onDestroy()

onDestroy(): void

Defined in: tilemap/src/TilemapComponent.ts:447

Returns

void

Overrides

VisualComponent.onDestroy

---

onDisable()

onDisable(): void

Defined in: renderer/dist/index.d.ts:251

Called when the component stops being effectively enabled — enabled went false, the entity (or an ancestor) was deactivated, or the component is being removed or destroyed. Put live resources to sleep here; the component is reused afterwards, so do not free anything onEnable cannot rebuild.

Returns

void

Inherited from

VisualComponent.onDisable

---

onEnable()

onEnable(): void

Defined in: renderer/dist/index.d.ts:250

Called when the component becomes effectively enabled — enabled is true and the entity is active. Fires right after onAdd() for a component added to an active entity, and again on every later flip. Bring live resources back online here (unpause a sound, show a display object, re-enable a physics body). Game-state reset does not belong here: the hook sees whatever state the component held while dormant.

Returns

void

Inherited from

VisualComponent.onEnable

---

onRemove()?

optional onRemove(): void

Defined in: core/dist/index.d.ts:2851

Called when the component is removed from an entity.

Returns

void

Inherited from

VisualComponent.onRemove

---

resolveRef()

resolveRef(obj, propName): MapObject | undefined

Defined in: tilemap/src/TilemapComponent.ts:434

Resolve a Tiled object-reference property to the actual object. Auto-collects across every layer so callers don’t have to.

Parameters

obj

HasProperties

propName

string

Returns

MapObject | undefined

---

resolveRefArray()

resolveRefArray(obj, propName): MapObject[]

Defined in: tilemap/src/TilemapComponent.ts:439

Same as resolveRef, but for indexed object-reference arrays.

Parameters

obj

HasProperties

propName

string

Returns

MapObject[]

---

restoreVisual()

protected restoreVisual(data): void

Defined in: renderer/dist/index.d.ts:227

Restore effects and mask from a snapshot’s shared fields. Call from the subclass’s afterRestore, after the render object is parented.

Parameters

data

Pick<VisualComponentData, "effects" | "mask">

Returns

void

Inherited from

VisualComponent.restoreVisual

---

serialize()

serialize(): TilemapComponentData | null

Defined in: tilemap/src/TilemapComponent.ts:190

Return a JSON-serializable snapshot of this component’s state. Used by the save system.

Returns

TilemapComponentData | null

Overrides

VisualComponent.serialize

---

serializeVisual()

protected serializeVisual(): VisualComponentData

Defined in: renderer/dist/index.d.ts:222

Serialise the shared layer/visible/tint/alpha/blendMode/interactive/ effects/mask fields. Subclasses spread this into their own Data object alongside their own-specific fields (texture key, text, anchor, …).

Returns

VisualComponentData

Inherited from

VisualComponent.serializeVisual

---

service()

protected service<T>(key): T

Defined in: core/dist/index.d.ts:2787

Lazy proxy-based service resolution. Can be used at field-declaration time:

readonly input = this.service(InputManagerKey);

The actual resolution is deferred until first property access.

Type Parameters

T

T extends object

Parameters

key

ServiceKey<T>

Returns

T

Inherited from

VisualComponent.service

---

setMask()

setMask(factory): MaskHandle

Defined in: renderer/dist/index.d.ts:234

Attach a mask to this component’s render object, replacing any existing mask. Returns a handle for inverse toggling, redraw (graphicsMask), or removal. The mask is torn down automatically when the component is destroyed.

Parameters

factory

MaskFactory

Returns

MaskHandle

Inherited from

VisualComponent.setMask

---

sibling()

protected sibling<C>(cls): C

Defined in: core/dist/index.d.ts:2795

Lazy proxy-based sibling component resolution. Can be used at field-declaration time:

readonly anim = this.sibling(AnimatedSpriteComponent);

The actual resolution is deferred until first property access.

Type Parameters

C

C extends Component

Parameters

cls

ComponentClass<C>

Returns

C

Inherited from

VisualComponent.sibling

---

update()

update(deltaSeconds): void

Defined in: tilemap/src/TilemapComponent.ts:181

Advance the tile-animation clock. ComponentUpdateSystem supplies time already scaled by the scene and the entity, and skips paused scenes, so a paused game freezes its tilemaps and timeScale slows them.

Parameters

deltaSeconds

number

Returns

void

Overrides

VisualComponent.update

---

use()

protected use<T>(key): T

Defined in: core/dist/index.d.ts:2778

Resolve a service by key, cached after first lookup. Scene-scoped values (registered via scene._registerScoped) take precedence over engine scope. A key declared with scope: "scene" that falls back to engine scope emits a one-shot dev warning — almost always signals a missed beforeEnter hook.

Type Parameters

T

T

Parameters

key

ServiceKey<T>

Returns

T

Inherited from

VisualComponent.use

---

fromSnapshot()

static fromSnapshot(data): TilemapComponent

Defined in: tilemap/src/TilemapComponent.ts:213

Parameters

data

TilemapComponentData

Returns

TilemapComponent