Skip to content

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.

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.

FieldTypeDefault
textstring''
fontFamilystring''
fontSizenumber16
fontWeightstring'normal'
alignstring'left'
fillnumber0xffffff
strokenumber0x000000
strokeWidthnumber0
wrapWidthnumber0

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 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.

FieldTypeDefault
sourcestring''

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

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.

FieldTypeDefaultWhat
columnsnumber1Frames across the picture
rowsnumber1Frames down it
countnumber0Frames in use, for a last row that is not full; 0 is all
framenumber0The 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.

  • Anchor and Size are of the frame: the frame is what is anchored and sized.
  • NineSlice’s borders are in pixels of the frame.
  • Taking SpriteSheet off shows the whole picture again.

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

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.

FieldTypeDefault
leftnumber0
topnumber0
rightnumber0
bottomnumber0

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.

FieldTypeDefault
kind'roundRect' | 'circle''roundRect'
widthnumber100
heightnumber100
radiusnumber0
fillnumber (colour)0xffffff
fillAlphanumber, 0 to 11
strokenumber (colour)0x000000
strokeWidthnumber0
strokeAlphanumber, 0 to 11

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.

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.

FieldWhat it does
zoomMultiplies the scale, 1 by default. Zoom over time is a tween of it.
viewWidth, viewHeightThe area of the world always shown, fitted to the screen. 0 is not set.
smoothingThe ms the camera takes to close half the distance to its target. 0 keeps to the target.
deadZoneWidth, deadZoneHeightHow far the target moves before the camera follows, around the view’s centre.
offsetX, offsetYWhere the camera aims, beside its target. A negative offsetY shows more above it.
shakeDistance, shakeFadeThe farthest a shake moves the view (0: no shake), and the ms a full shake takes to fade.
background, backgroundColorA 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 with transforms.teleport; and on world.get('camera').snap().
  • No jitter: CameraFollow runs 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.

FieldDefaultWhat it does
dragleftThe mouse button that drags the map: left, middle, right or none. One finger always drags.
keysbothThe keys that move it: arrows, wasd, both or none.
keySpeed600How fast the keys move it, in screen pixels a second, at any zoom.
wheelZoomonThe wheel, a trackpad pinch and two fingers zoom about the pointer.
zoomSpeed1How much a turn of the wheel zooms: 1 is the editor’s Scene view.
minZoom, maxZoom0.25, 4The Camera.zoom it keeps between.
freeoffThe 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 CameraBounds that 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 switches free on. 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 over shakeFade on the wall clock.
  • The view moves up to shakeDistance × trauma², on smooth noise that repeats for the same frames. It is drawn only: toWorld, toScreen and the camera’s Position stay steady.
  • world.get('camera').shakeScale (0..1) is 0 by 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.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 });

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

FieldPurpose
handleNumeric registry handle for all PixiJS nodes owned by an entity.
revisionChanges 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.

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.

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';