Sprites API

Spawn and control sprite entities from scene assets.

Use api.sprites() to create a sprite from an asset that is available for the current scene.

SpritesAPI sprites = api.sprites();

Spawn a sprite

Spawn by exported asset name:

SpriteRef coin = api.sprites().spawn("coin", 120f, 64f)
        .scale(2f)
        .alpha(0.9f);

Or spawn by Pixscape asset ID:

SpriteRef coin = api.sprites().spawn(42, 120f, 64f);

The coordinates are the initial world position. Both overloads return a SpriteRef, which can move, scale, rotate, tint, change shader, or remove the created entity:

coin.position(160f, 64f)
        .scale(2f, 1.5f)
        .rotationRad(0.25f)
        .tint(1f, 0.8f, 0.3f, 1f)
        .shader("outline");

coin.remove();

Use entity() when another Runtime API needs an EntityRef, or transform(), sprite(), and shader() for their complete controls.

Change the displayed asset

The sprite facade can change an existing sprite to another available asset:

coin.sprite().setAssetId(43);

Use setAsset(assetId, atlasTag) when you also need to select an atlas tag. A blank tag means main.

If the replacement asset is unavailable, the call throws IllegalArgumentException and the previous sprite remains unchanged. Sprite facade methods control an existing complete sprite; they do not turn an arbitrary entity into a sprite.

Visibility, size, and tint

coin.sprite()
        .setVisible(true)
        .setSize(32f, 32f)
        .setTint(1f, 1f, 1f, 0.8f);

Color channels are clamped to 0..1.

Repeat a sprite

Repeat can be enabled independently on the X and Y axes:

SpriteRef background = api.sprites().spawn("ground", 0f, 0f);

background.sprite()
        .setSize(1024f, 512f)
        .setRepeat(true, true);

Repeat is intended for non-animated, axis-aligned sprites. A rotated sprite renders normally as one draw. Animated sprites keep their repeat settings but do not use repeated rendering.

Change render order

Once you have the sprite’s EntityRef, use renderOrder() to change its scene layer or local z-index:

coin.entity().renderOrder().set(3, 10);

See Entity Facades for the complete render-order rules.

Make the asset available

If the asset is already placed in the scene, Studio includes it automatically. If gameplay spawns or switches to an asset used only from code, add it to Runtime Availability before export.

spawn(...) throws IllegalArgumentException when the asset is not available for the current scene.