Entity Facades

Move, display, animate, and order existing entities through focused Runtime controls.

Capability checks

A facade controls one part of an entity. Sprite, animation, shader, and render-order facades operate on capabilities the entity already has; they do not turn an arbitrary entity into a fully configured renderable or animated entity.

When you are unsure what an entity contains, use exists() on facades that provide it:

if (player.sprite().exists()) {
    player.sprite().setAlpha(0.8f);
}

Other facades expose a query suited to their domain, such as spatial().enabled() or light().hasPoint(). The particle facade also provides exists() to test whether an emitter is currently present.

Transform

Use transform() to position, move, rotate, scale, or set the origin of an entity.

player.transform()
      .setPosition(120f, 64f)
      .moveBy(4f, 0f)
      .setScale(2f)
      .setRotationRad(0.5f)
      .setOrigin(16f, 24f);

Transform setters can establish a standalone transform when the entity does not already have one.

Sprite

Use sprite() to change an existing sprite’s asset, visibility, tint, alpha, size, and repeat settings.

if (player.sprite().exists()) {
    player.sprite()
          .setAssetId(42)
          .setVisible(true)
          .setTint(1f, 1f, 1f, 1f)
          .setAlpha(0.9f)
          .setSize(32f, 48f);
}

Configure horizontal and vertical repeat with setRepeat(...), and query the settings with repeatsX() and repeatsY():

if (player.sprite().exists()) {
    player.sprite().setRepeat(true, false);
}

Repeat applies to axis-aligned, non-animated sprites. A rotated sprite falls back to one draw, and animated sprites do not render as repeated sprites.

Animation

Use animation() to control an animated entity:

if (player.animation().exists()) {
    player.animation()
          .play("run")
          .setLoop(true)
          .setFps(12f);
}

The facade can play, pause, stop, or restart playback; choose a clip; control looping, FPS, and playback time; and query whether the animation is playing, looping, or finished.

An entity that owns more than one animation can switch by name or play a clip from another owned animation:

player.animation().setAnimation("hero-combat");
player.animation().play("hero-combat", "attack");

The full animation registration and ownership rules belong in the Animations API guide.

Particles

Use particles() to control a particle emitter attached to an entity:

player.particles()
      .setEffect("particles/dust.p", "main")
      .setLooping(true)
      .restart();

Current controls include play(), pause(), resume(), restart(), stop(), setLooping(...), and setAutoStart(...). Use isPaused() and isLooping() to query playback.

A replacement effect must already be prepared for the scene. See Runtime Availability.

Shader

Use shader() to select a registered shader and set its custom float values:

if (player.shader().exists()) {
    player.shader()
          .use("water")
          .setFloat("u_time", time)
          .setFloat("u_strength", 0.5f);
}

The custom uniforms currently exposed by this facade are float values. You can query, remove, or clear those values with getFloat(...), hasFloat(...), removeFloat(...), and clearFloats().

Light

light() provides read-only checks for point-light and cone-light capabilities:

if (player.light().hasPoint()) {
    // This entity has a point light.
}

Use hasCone() for a cone light.

Spatial

Use spatial() to configure the vertical volume Pixscape uses when an entity participates in 2.5D ordering.

player.spatial()
      .enable()
      .setVolume(0f, 32f);

boolean spatiallyOrdered = player.spatial().participatesInRenderOrder();

The facade provides enabled(), enable(), and disable(), along with altitude and height getters and setters. Calling enable() records the entity’s Spatial height settings, but does not by itself guarantee effective Spatial ordering. Use participatesInRenderOrder() to check the current result.

See Spatial API for layer and tiled Spatial controls.

Layer and z-index

Use renderOrder() to move an entity to another scene layer or change its local z-order from gameplay code:

EntityRef enemy = api.entities().requireName("Enemy");

enemy.renderOrder()
     .layerIndex(4)
     .zIndex(10);

To change both values together:

enemy.renderOrder().set(4, 10);

The rules are:

layerIndex(...) uses an exported numerical scene layer index and preserves the current z-index.
zIndex(...) preserves the current layer. Valid values are -32768 through 32767, inclusive.
set(layerIndex, zIndex) changes both values as one operation.

renderOrder() changes an entity that already participates in Pixscape’s normal scene rendering. Check renderOrder().exists() when the entity’s capabilities are uncertain.

Layer and z-index control normal scene placement. Spatial actors are still ordered by Pixscape’s Spatial rules where Spatial applies; changing z-index does not replace or enable Spatial ordering.