Components

@shell/pixi separates serializable render intent from transient PixiJS object references. An entity can own multiple PixiJS nodes while sharing one ECS transform, size, and pivot.

Render intent

Sprite

Sprite is a serializable, editor-visible marker that requests a PixiJS Sprite. It requires the runtime PixiTransformGroup component automatically.

entity.addComponent(Sprite);

Text

Text is serializable, editor-visible text content and style. It requires the runtime PixiTransformGroup component automatically.

Field	Type	Default
text	string	''
fontFamily	string	''
fontSize	number	16
align	string	'left'
fill	number	0xffffff

Texture

Texture specifies the sprite asset source. It requires Sprite, so legacy scene data containing Texture without a serialized Sprite marker still recreates the complete runtime component chain.

Field	Type	Default
source	string	''

Texture loading is asynchronous. Completion is ignored if the original sprite was removed or its registry handle was reused.

Tint

Tint.color applies a color tint to a sprite and defaults to 0xffffff.

NineSlice

NineSlice keeps the borders of a sprite’s picture from stretching: the corners keep their size, the edges stretch along themselves, and the middle stretches both ways. It requires Sprite. Give the sprite a Size to say how large it is.

Field	Type	Default
left	number	0
top	number	0
right	number	0
bottom	number	0

The borders are in pixels of the picture. Adding or removing NineSlice on a sprite that exists replaces its PixiJS node.

Camera

Camera.zoom controls the world view zoom and defaults to 1.

PixiRenderLayer

PixiRenderLayer.layer selects where an entity renders. PixiLayer.World is camera-transformed; PixiLayer.Ui uses screen coordinates and renders above the world.

import { PixiLayer, PixiRenderLayer } from '@shell/pixi';

const screen = resources.get('pixiApp').toScreen(entity.$position.x, entity.$position.y);
resources.get('transforms').teleport(entity, screen);
entity.addComponent(PixiRenderLayer, { layer: PixiLayer.Ui });

Runtime group

PixiTransformGroup is runtime-only and is neither serialized nor shown in the editor:

Field	Purpose
handle	Numeric registry handle for all PixiJS nodes owned by an entity.
revision	Changes whenever a render role is attached to the group.

PixiTransformGroup is a logical registry group, not a physical PixiJS Container. Renderables remain direct children of either the flat world or screen-space UI container. The registry owns concrete sprite and text references by role; they are not stored in ECS components.

Most applications should use Sprite, Text, Image, and TextLabel directly.

Multiple render roles

An entity may contain both Sprite and Text. Both PixiJS objects receive the same transform, Size, and Pivot values:

entity.addComponent(Sprite);
entity.addComponent(Text, { text: 'Selected' });

Removing Sprite destroys only the sprite. Removing Text destroys only the text. Removing the entity or PixiTransformGroup destroys all remaining nodes synchronously.

Transform components

Pixi systems consume Position, Rotation, Transform, Pivot, Anchor, and Size from the canonical @shell/transform package. @shell/pixi does not re-export these components.

import { Sprite, Texture } from '@shell/pixi';
import { Position, Size } from '@shell/transform';