pixijs-scene-sprite

PixiJS has three sprite classes for different drawing tasks. `Sprite` is the default image-drawing leaf; `NineSliceSprite` is a resizable UI-panel variant that preserves corner art; `TilingSprite` repeats a texture across an area. The `AnimatedSprite` subclass of `Sprite` cycles through texture frames for frame-based animation. Assumes familiarity with `pixijs-scene-core-concepts`. All sprite classes are leaf nodes; they cannot have children. Wrap multiple sprites in a `Container` to group them. ## Quick Start ```ts const texture = await Assets.load("bunny.png"); const sprite = new Sprite({ texture, anchor: 0.5, tint: 0xff8888, }); sprite.x = app.screen.width / 2; sprite.y = app.screen.height / 2; app.stage.addChild(sprite); ``` Position is set after construction because `app.screen.width / 2` depends on the live renderer size. Literal positions can go directly in the options object via `x`/`y` (inherited from `Container`). **Related skills:** `pixijs-scene-core-concepts` (leaves, transforms), `pixijs-assets` (texture loading), `pixijs-scene-particle-container` (thousands of sprites), `pixijs-performance` (spritesheets, batching). ## Variants | Variant | Use when | Trade-offs | Reference | | ----------------- | --------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------- | | `Sprite` | Draw a single texture at a position | Fixed size = texture size | [references/sprite.md](references/sprite.md) | | `AnimatedSprite` | Frame-based animation from a texture array or spritesheet | Pre-rendered frames only; no tweening | [references/animated-sprite.md](references/animated-sprite.md) | | `NineSliceSprite` | Resizable UI panels, buttons, dialog frames | Border width is fixed; center stretches | [references/nineslice-sprite.md](references/nineslice-sprite.md) | | `TilingSprite` | Scrolling backgrounds, parallax, repeating patterns | Single texture repeated; `tilePosition` scrolls | [references/tiling-sprite.md](references/tiling-sprite.md) | `AnimatedSprite` is a subclass of `Sprite`; all `Sprite` properties (anchor, tint, position) apply. Each variant's constructor options are documented in its sub-reference file (`references/{variant}.md`). All variants also accept the `Container` options (`position`, `scale`, `tint`, `label`, `filters`, `zIndex`, etc.) — see `skills/pixijs-scene-core-concepts/references/constructor-options.md`. ## When to use what - **"I want to draw a single image at a position"** → `Sprite`. The default choice for 90% of 2D game and app content. - **"I want to animate a character through a series of frames"** → `AnimatedSprite`. Load a spritesheet via Assets and pass `sheet.animations['walk']`. See `references/animated-sprite.md`. - **"I want a UI button/panel that resizes without stretching the borders"** → `NineSliceSprite`. Set border widths, then set `width`/`height`. See `references/nineslice-sprite.md`. - **"I want a scrolling repeating background"** → `TilingSprite`. Animate `tilePosition` to scroll. See `references/tiling-sprite.md`. - **"I want thousands of identical sprites"** → Use `ParticleContainer` with `Particle` instances (see `pixijs-scene-particle-container`), not plain sprites. - **"I want to draw shapes or paths"** → Use `Graphics` (see `pixijs-scene-graphics`), not a sprite. ## Quick concepts ### Anchor vs pivot `Sprite.anchor` is normalized `[0, 1]` and shifts only the texture draw origin; no position offset. `Container.pivot` is pixel-space and shifts both the transform origin and the visual position. For centering a sprite, always use `anchor.set(0.5)`. ### Loading before creating `Sprite.from(id)` only reads the Assets cache; it does not fetch. Always `await Assets.load(...)` first, or pass the returned `Texture` directly to `new Sprite(texture)`. ### Dynamic textures Once a texture is loaded, modifying its `frame` or swapping its source does not automatically notify sprites. Set `texture.dynamic = true` once, or call `sprite['onViewUpdate']()` manually after changes. ## Common Mistakes ### [HIGH] Using `Texture.from(url)` to load Wrong: ```ts const texture = Texture.from("https://example.com/image.png"); ``` Correct: ```ts const texture = await Assets.load("https://example.com/image.png"); ``` `Texture.from()` only reads the cache in v8. Use `Assets.load()` first; its return value is the texture. ### [HIGH] Confusing anchor and pivot Wrong: ```ts sprite.pivot.set(sprite.width / 2, sprite.height / 2); ``` Correct: ```ts sprite.anchor.set(0.5); ``` `anchor` shifts only the draw origin. `pivot` shifts the transform origin AND the visual position, causing the sprite to move unexpectedly. ### [HIGH] Old `NineSlicePlane` name `NineSlicePlane` was renamed to `NineSliceSprite` in v8 and switched to an options-object constructor: `new NineSliceSprite({ texture, leftWidth, topHeight, rightWidth, bottomHeight })`. ### [MEDIUM] Adding children to a sprite `Sprite`, `NineSliceSprite`, and `TilingSprite` all set `allowChildren = false`. Wrap in a `Container` to group sprites with other content. ## API Reference - [Sprite](https://pixijs.download/release/docs/scene.Sprite.html.md) - [SpriteOptions](https://pixijs.download/release/docs/scene.SpriteOptions.html.md) - [AnimatedSprite](https://pixijs.download/release/docs/scene.AnimatedSprite.html.md) - [NineSliceSprite](https://pixijs.download/release/docs/scene.NineSliceSprite.html.md) - [TilingSprite](https://pixijs.download/release/docs/scene.TilingSprite.html.md) - [Texture](https://pixijs.download/release/docs/rendering.Texture.html.md)