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.
The render intent below (Sprite, Texture, Tint, SpriteSheet, NineSlice, ColorOverlay,
Text, RenderLayer) is @shell/render-data-2d, plain data with no renderer, which
@shell/pixi re-exports and installs (RenderData2DPlugin). In a Pixi world a Sprite, a Text and
a RenderLayer each bring a PixiTransformGroup, Pixi’s own, which PixiPlugin requires of them.
Render intent
Section titled “Render intent”Sprite
Section titled “Sprite”Sprite is a serializable, editor-visible marker that requests a PixiJS Sprite. In a Pixi world it
brings the runtime PixiTransformGroup component, which PixiPlugin requires of it.
entity.addComponent(Sprite);Text is serializable, editor-visible text content and style. In a Pixi world it brings the
runtime PixiTransformGroup component, which PixiPlugin requires of it.
| Field | Type | Default |
|---|---|---|
text | string | '' |
fontFamily | string | '' |
fontSize | number | 16 |
fontWeight | string | 'normal' |
align | string | 'left' |
fill | number | 0xffffff |
stroke | number | 0x000000 |
strokeWidth | number | 0 |
wrapWidth | number | 0 |
A weight and an edge. fontWeight is 'normal' or 'bold', or '100' to '900' in hundreds;
anything else is drawn as normal. stroke is the colour of an edge around the letters and
strokeWidth its width, in pixels at the text’s own size. With a width of 0 there is no edge.
entity.addComponent(Text, { text: 'Score 120', fontSize: 24, fontWeight: 'bold', fill: 0xffcc00, stroke: 0x1a1a2e, strokeWidth: 4,});Each look with an edge (font family, size, weight, fill and edge) is one bitmap font, with the fill drawn into it, shared by every text of that look, in the editor and in every play of the game. PixiJS warns past 50 fonts, so give many texts a few looks, not one each.
Changing only text keeps the font, so a score or a timer can change its words every frame. Never
animate fontSize, fill, stroke or strokeWidth: each new value is another font. To make a
text pop, animate its Scale or Position instead.
A wrap. wrapWidth is how wide the lines may be, in pixels at the text’s own size: a longer line
breaks at a space. At 0 the lines break only where the words do. In a UI Canvas a text wraps at its
Element’s width instead (LayoutWrap), and wrapWidth is not used.
Texture
Section titled “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.
SpriteSheet
Section titled “SpriteSheet”SpriteSheet shows one frame of the sprite’s picture, which is then a sheet of frames of one size,
in columns and rows. It requires Texture. Without it a sprite shows its whole picture.
| Field | Type | Default | What |
|---|---|---|---|
columns | number | 1 | Frames across the picture |
rows | number | 1 | Frames down it |
count | number | 0 | Frames in use, for a last row that is not full; 0 is all |
frame | number | 0 | The frame shown |
Frames are counted from 0, left to right and then top to bottom. Which frame a number shows:
- Its whole part: 2.7 shows frame 2.
- Past the last it goes round, and so below 0: of 8 frames, 9 is frame 1 and -1 is frame 7.
- A number that ends a whole run of the sheet shows the last frame: of 8, 8 and 16 are frame 7.
- What is not a number shows frame 0, and so do columns or rows that are not at least 1.
So a sprite’s frames are played by tweening frame from 0 to the count with @shell/animate.
Every frame gets the same time, and the tween stops on the last; with loop: -1 it goes round:
const animate = resources.get('animate');
// A bird of 4 frames, in a sheet of 4 columns: it flaps until the tween is cancelled.entity.addComponent(SpriteSheet, { columns: 4, rows: 1 });const flap = animate.tween(entity, SpriteSheet, { frame: [0, 4], duration: 400, loop: -1 });flap.cancel(); // It stays on the frame it shows.
// A door of 6 frames opens once, and stays open on the last.animate.tween(door, SpriteSheet, { frame: [0, 6], duration: 600 });The tween runs on the game’s clock, so the editor’s Pause stops it. Setting frame by hand shows a
frame and plays nothing.
AnchorandSizeare of the frame: the frame is what is anchored and sized.NineSlice’s borders are in pixels of the frame.- Taking
SpriteSheetoff shows the whole picture again.
Tint.color applies a color tint to a sprite and defaults to 0xffffff.
NineSlice
Section titled “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; without one it is its picture’s size, as a plain sprite
is.
| Field | Type | Default |
|---|---|---|
left | number | 0 |
top | number | 0 |
right | number | 0 |
bottom | number | 0 |
The borders are in pixels of the picture, or of the frame of a SpriteSheet. Adding or removing
NineSlice on a sprite that exists replaces its PixiJS node.
Shape draws one shape in the entity’s own space: a rounded rectangle from (0, 0) to (width,
height) with corners of radius (0 for square ones), or a circle of radius about (0, 0). It is
filled first, then stroked along its edge, centred on it. It is what the UI’s controls and the touch
controls are drawn with, each part an entity of its own.
| Field | Type | Default |
|---|---|---|
kind | 'roundRect' | 'circle' | 'roundRect' |
width | number | 100 |
height | number | 100 |
radius | number | 0 |
fill | number (colour) | 0xffffff |
fillAlpha | number, 0 to 1 | 1 |
stroke | number (colour) | 0x000000 |
strokeWidth | number | 0 |
strokeAlpha | number, 0 to 1 | 1 |
A fill of alpha 0 is not drawn, nor is a stroke of width or alpha 0. Its size is its own width and
height: a Size on the entity scales it as it scales a sprite, and its corners with it.
Camera
Section titled “Camera”The camera shows the world around its Transform. Keep one camera alive in the world at a time (scenes loaded
together are one world): with several, which one shows and whose background clears is not decided today. The rule
agreed for when several cameras are built is that the newest shows.
| Field | What it does |
|---|---|
zoom | Multiplies the scale, 1 by default. Zoom over time is a tween of it. |
viewWidth, viewHeight | The area of the world always shown, fitted to the screen. 0 is not set. |
smoothing | The ms the camera takes to close half the distance to its target. 0 keeps to the target. |
deadZoneWidth, deadZoneHeight | How far the target moves before the camera follows, around the view’s centre. |
offsetX, offsetY | Where the camera aims, beside its target. A negative offsetY shows more above it. |
shakeDistance, shakeFade | The farthest a shake moves the view (0: no shake), and the ms a full shake takes to fade. |
background, backgroundColor | A colour of the camera’s own to clear the screen with. |
What it shows. With viewWidth and viewHeight set, the whole area always shows, scaled to
fit the screen. The smaller fit counts, so the longer side of the screen shows more of the world.
With only one set, that one fits; with neither, the scale is zoom, one world unit a pixel.
cameraView(camera, screen) gives the { scale, width, height } that CameraSync applies.
The camera’s components, cameraView, CameraFollow and the camera resource are in
@shell/camera-2d, which has no renderer: @shell/pixi re-exports them and installs its
Camera2DPlugin, and each renderer writes the screenSize resource the follow fits the view to,
and the screenTransform resource as it places the view: screenTransform.toWorld() and
toScreen() go through the camera’s view, without its shake. The HUD (UiScaling) blends the two axes of
the screen, so away from 16:9 it is drawn larger than the world: on a phone held upright, about
twice as large.
Following. Put CameraTarget on what the camera follows, normally the player prefab. It is
found by a query, so it works in every level, with no reference to the player.
- Which target: the highest
priority, and of equals the newest. A cut-scene adds a higher one and takes it away again, and the camera glides there and back. - Each frame: the aim is the target plus the offset. The camera moves only as far as keeps the
aim inside the dead zone. That point is kept inside the bounds, then approached by
smoothing, so a change of room glides too. - Snaps, with no glide: on the first frame; when the target it had is gone for one that was not
there, as at a level
switch; when the target, or what it hangs from, is moved withtransforms.teleport; and onworld.get('camera').snap(). - No jitter:
CameraFollowruns in PreRender, after the transforms are interpolated, and puts the camera where the target is drawn in the same frame. It runs in Play and the game, not in edit mode.
Bounds. CameraBounds { width, height } on an entity of a level: a rectangle centred on it.
- The view stays inside the bounds that hold the target. Where two overlap, the ones it is in are kept.
- A view larger than its bounds is centred on them.
- With no bounds holding the target, nothing holds the view.
The player moves it. CameraPanZoom on the camera lets the player drag, move and zoom the map, as
in a city or strategy game. It is in every 2D game (@shell/camera-controls, installed by
Engine2D) and does nothing until a camera has it.
| Field | Default | What it does |
|---|---|---|
drag | left | The mouse button that drags the map: left, middle, right or none. One finger always drags. |
keys | both | The keys that move it: arrows, wasd, both or none. |
keySpeed | 600 | How fast the keys move it, in screen pixels a second, at any zoom. |
wheelZoom | on | The wheel, a trackpad pinch and two fingers zoom about the pointer. |
zoomSpeed | 1 | How much a turn of the wheel zooms: 1 is the editor’s Scene view. |
minZoom, maxZoom | 0.25, 4 | The Camera.zoom it keeps between. |
free | off | The player has the camera, and its follow waits. |
- A drag keeps the world point under the pointer under it; the keys run on the wall clock, so a hit-stop does not stop them, and do nothing while a text field has the focus.
- The view stays inside the
CameraBoundsthat hold the camera’s centre, by the follow’s rule. - With a
CameraTarget, the follow has the camera until the player drags or uses the keys, which switchesfreeon. Switch it off to follow again. While the follow has it, the wheel zooms about the screen’s centre. - While a camera has it, the wheel over the view and the view’s touches are the game’s: the page does not scroll or zoom. Not in the editor’s edit mode.
Shake.
world.get('camera').shake(0.4)adds trauma (0..1, and hits add up), which fades overshakeFadeon the wall clock.- The view moves up to
shakeDistance× trauma², on smooth noise that repeats for the same frames. It is drawn only:toWorld,toScreenand the camera’sPositionstay steady. world.get('camera').shakeScale(0..1) is0by default when the player’s system asks for reduced motion; a game’s options menu can set it.
With scaleMode: 'nearest' (pixel art), the view is drawn on whole pixels.
A camera can have a background of its own: with Camera.background on, the screen is cleared with Camera.backgroundColor. Without it the screen has the backgroundColor given to the plugin. In the editor, a scene whose camera has no background is drawn on the colour of the editor’s Theme, so give the camera one when the background is part of the game.
camera.addComponent(Camera, { zoom: 1, background: true, backgroundColor: 0x1099bb });RenderLayer
Section titled “RenderLayer”RenderLayer.layer selects where an entity renders. Layer.World is camera-transformed;
Layer.Ui uses screen coordinates and renders above the world. The number names the layer, it is
not a place in a list: 0 is World and 1 is Ui, and they keep those numbers. Only these two are drawn apart
today; any other number is drawn as World. Inside a layer, a higher position.z is in front, and of equal
z usually the entity made later; give each its own z where the order matters.
import { Layer, RenderLayer } from '@shell/pixi';
const screen = resources.get('screenTransform').toScreen(entity.$position.x, entity.$position.y);resources.get('transforms').teleport(entity, screen);entity.addComponent(RenderLayer, { layer: Layer.Ui });Runtime group
Section titled “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
Section titled “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. Removing any other
component that is drawn puts the node back as one that never had it: no Tint is untinted, no
Anchor or Pivot is at 0, 0, no RenderLayer is in the world layer, and no Texture is the
white square.
Transform components
Section titled “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';