UISurface

Defined in: ui/src/UISurface.ts:27

Mounts a UI tree on an entity: entity.add(new UISurface({...})). Owns the tree’s root UIPanel element (exposed as root) and provides builder methods (.text(), .button(), .panel()) for constructing it. Layout is driven by UILayoutSystem each frame.

Extends

• Component

Constructors

Constructor

new UISurface(opts?): UISurface

Defined in: ui/src/UISurface.ts:42

Parameters

opts?

UISurfaceOptions

Returns

UISurface

Overrides

Component.constructor

Properties

_anchor

readonly _anchor: Anchor | undefined

Defined in: ui/src/UISurface.ts:35

Internal

---

_layer

readonly _layer: string | undefined

Defined in: ui/src/UISurface.ts:37

Internal

---

_offset

readonly _offset: object

Defined in: ui/src/UISurface.ts:36

Internal

x

x: number

y

y: number

---

_positioning

readonly _positioning: "anchor" | "transform"

Defined in: ui/src/UISurface.ts:38

Internal

---

entity

entity: Entity

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

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

Inherited from

Component.entity

---

root

readonly root: UIPanel

Defined in: ui/src/UISurface.ts:34

Root element of the mounted UI tree — a UIPanel created with this component and destroyed by it in onDestroy. Same instance for the component’s whole lifetime; after onDestroy it is destroyed (its destroy() is idempotent) and must not be re-added elsewhere.

---

inspectExclude?

static optional inspectExclude?: readonly string[]

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

Own fields and getters the Inspector leaves out of this component’s reflected state. Use it for bulk data that is not worth a diagnostic copy — a parsed tilemap, a large lookup table. Lists merge down the class chain, so a subclass adds to its base class’s exclusions.

class TilemapComponent extends VisualComponent {
  static inspectExclude = ["data"];
}

Inherited from

Component.inspectExclude

---

updatePriority?

static optional updatePriority?: number

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

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

Component.updatePriority

Accessors

container

Get Signature

get container(): DisplayContainer

Defined in: ui/src/UISurface.ts:53

The PixiJS Container of the root panel.

Returns

DisplayContainer

---

context

Get Signature

get context(): EngineContext

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

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

Returns

EngineContext

Inherited from

Component.context

---

effectiveEnabled

Get Signature

get effectiveEnabled(): boolean

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

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

Component.effectiveEnabled

---

enabled

Get Signature

get enabled(): boolean

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

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:3235

Parameters

value

boolean

Returns

void

Inherited from

Component.enabled

---

scene

Get Signature

get scene(): Scene

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

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

Component.scene

---

updatePriority

Get Signature

get updatePriority(): number

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

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:3261

Parameters

value

number

Returns

void

Inherited from

Component.updatePriority

---

visible

Get Signature

get visible(): boolean

Defined in: ui/src/UISurface.ts:117

Whether the mounted UI tree is visible. Reads back what you set, even while the entity is dormant and the tree is hidden.

Returns

boolean

Set Signature

set visible(v): void

Defined in: ui/src/UISurface.ts:121

Parameters

v

boolean

Returns

void

Methods

_applyEnabled()

_applyEnabled(effective): void

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

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

Component._applyEnabled

---

_isTornDown()

_isTornDown(): boolean

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

Internal

Internal: true once this component has been removed or its entity destroyed. Components are terminal — Entity.add uses this to reject re-attaching an instance whose cleanups and onDestroy already ran.

Returns

boolean

Inherited from

Component._isTornDown

---

_markTornDown()

_markTornDown(): void

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

Internal

Internal: mark this component torn down. Called by Entity.remove() and Entity._performDestroy() after onDestroy runs.

Returns

void

Inherited from

Component._markTornDown

---

_refreshEnabled()

_refreshEnabled(): void

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

Internal

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

Returns

void

Inherited from

Component._refreshEnabled

---

_runCleanups()

_runCleanups(onError?): void

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

Internal

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

Parameters

onError?

(error) => void

Returns

void

Inherited from

Component._runCleanups

---

addCleanup()

protected addCleanup(fn): void

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

Register a cleanup function to run when this component is removed or destroyed, before onDestroy. Use it for what listen, listenScene and listenBus do not cover, such as an unsubscribe from a custom emitter.

Parameters

fn

() => void

Returns

void

Inherited from

Component.addCleanup

---

addElement()

addElement(child): void

Defined in: ui/src/UISurface.ts:96

Append an arbitrary UIElement (e.g. UIImage, UIProgressBar, UICheckbox) as the last child. Prefer the .text(), .button(), and .panel() builders for those element types — they’re shorter.

Parameters

child

UIElement

Returns

void

---

button()

button(label, opts): UIButton

Defined in: ui/src/UISurface.ts:77

Add a button element.

Parameters

label

string

opts

Omit<UIButtonProps, "children">

Returns

UIButton

---

destroy()

destroy(): void

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

End this component’s life on its own — the same as entity.remove(SomeClass), without having to name its own class from inside itself, which breaks under subclassing.

Returns

void

Inherited from

Component.destroy

---

fixedUpdate()?

optional fixedUpdate(dt): void

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

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

Component.fixedUpdate

---

insertElementBefore()

insertElementBefore(child, before): void

Defined in: ui/src/UISurface.ts:109

Insert child immediately before before in the root panel’s child list. Falls back to append if before isn’t a current child.

Parameters

child

UIElement

before

UIElement

Returns

void

---

listen()

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

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

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

Component.listen

---

listenBus()

protected listenBus<K>(event, handler): void

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

Subscribe to an engine EventBus event, auto-unsubscribe on removal. Throws when the entity is not in a scene, like listenScene.

Type Parameters

K

K extends keyof EngineEvents

Parameters

event

K

handler

(data) => void

Returns

void

Inherited from

Component.listenBus

---

listenScene()

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

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

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

Component.listenScene

---

onAdd()

onAdd(): void

Defined in: ui/src/UISurface.ts:134

Called when the component is added to an entity. Validate dependencies here — a service, a sibling component, a render layer — and throw when one is missing. The throw is attributed to this component, recorded in Inspector.getErrors().callbackErrors, and rethrown, so it reaches the caller of entity.add() unchanged.

Returns

void

Overrides

Component.onAdd

---

onDestroy()

onDestroy(): void

Defined in: ui/src/UISurface.ts:170

Called when the component is destroyed (entity destroyed or component removed).

Returns

void

Overrides

Component.onDestroy

---

onDisable()

onDisable(): void

Defined in: ui/src/UISurface.ts:130

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

Overrides

Component.onDisable

---

onEnable()

onEnable(): void

Defined in: ui/src/UISurface.ts:126

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

Overrides

Component.onEnable

---

panel()

panel(opts?): UIPanel

Defined in: ui/src/UISurface.ts:82

Add a nested child panel.

Parameters

opts?

UIPanelProps

Returns

UIPanel

---

removeElement()

removeElement(child): void

Defined in: ui/src/UISurface.ts:101

Remove a previously added element. No-op if the element isn’t a child.

Parameters

child

UIElement

Returns

void

---

scrollView()

scrollView(opts?): UIScrollView

Defined in: ui/src/UISurface.ts:87

Add a nested scrollable viewport.

Parameters

opts?

UIScrollViewProps

Returns

UIScrollView

---

service()

protected service<T>(key): T

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

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

Component.service

---

setPointerHandlers()

setPointerHandlers(handlers): void

Defined in: ui/src/UISurface.ts:67

Set the root panel’s pointer / hover handlers (onHover, onPointerOver, onPointerOut) after construction — forwarded to root. (update() can’t double as the prop setter here: on a Component it’s the per-frame lifecycle hook the engine calls.) Like the element update, a present key replaces that handler and an absent key leaves it intact, so a partial setPointerHandlers({ onHover }) won’t drop the others. Handy for wiring attachTooltip: surface.setPointerHandlers({ onHover: tip.setActive }).

Parameters

handlers

PointerEventProps

Returns

void

---

sibling()

protected sibling<C>(cls): C

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

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

Component.sibling

---

text()

text(content, style?): UIText

Defined in: ui/src/UISurface.ts:72

Add a text element.

Parameters

content

string

style?

Partial<TextStyleOptions>

Returns

UIText

---

update()?

optional update(dt): void

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

Called every frame by the built-in ComponentUpdateSystem.

Parameters

dt

number

Frame delta in seconds, scaled by scene and entity timeScale.

Returns

void

Inherited from

Component.update

---

use()

protected use<T>(key): T

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

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

Component.use