0
# Display Objects and Scene Graph
1

2
Hierarchical display object system including containers, sprites, graphics, text, and other visual elements. The scene graph provides transform inheritance, rendering order, and event propagation throughout the display hierarchy.
3

4
## Capabilities
5

6
### Container
7

8
Base display object that can contain other display objects, forming the scene graph hierarchy.
9

10
```typescript { .api }
11
/**
12
 * Base display object container that can hold other display objects
13
 */
14
class Container<C extends ContainerChild = ContainerChild> extends EventEmitter {
15
  constructor();
16
  
17
  /**
18
   * Add child display objects
19
   * @param children - Display objects to add
20
   * @returns First child added
21
   */
22
  addChild<U extends ContainerChild[]>(...children: U): U[0];
23
  
24
  /**
25
   * Add child at specific index
26
   * @param child - Child to add
27
   * @param index - Index position
28
   * @returns Added child
29
   */
30
  addChildAt<U extends ContainerChild>(child: U, index: number): U;
31
  
32
  /**
33
   * Remove child display objects
34
   * @param children - Display objects to remove
35
   * @returns First child removed
36
   */
37
  removeChild<U extends ContainerChild>(...children: U[]): U[0];
38
  
39
  /**
40
   * Remove child at specific index
41
   * @param index - Index of child to remove
42
   * @returns Removed child
43
   */
44
  removeChildAt(index: number): ContainerChild;
45
  
46
  /**
47
   * Get child at index
48
   * @param index - Child index
49
   * @returns Child at index
50
   */
51
  getChildAt(index: number): ContainerChild;
52
  
53
  /**
54
   * Get child index
55
   * @param child - Child to find
56
   * @returns Index of child
57
   */
58
  getChildIndex(child: ContainerChild): number;
59
  
60
  /**
61
   * Set child index
62
   * @param child - Child to move
63
   * @param index - New index
64
   */
65
  setChildIndex(child: ContainerChild, index: number): void;
66
  
67
  /** Array of child display objects */
68
  readonly children: ContainerChild[];
69
  
70
  /** Parent container */
71
  readonly parent: Container;
72
  
73
  /** X position */
74
  x: number;
75
  
76
  /** Y position */
77
  y: number;
78
  
79
  /** Scale factor */
80
  scale: PointData;
81
  
82
  /** Rotation in radians */
83
  rotation: number;
84
  
85
  /** Skew values */
86
  skew: ObservablePoint;
87
  
88
  /** Pivot point */
89
  pivot: ObservablePoint;
90
  
91
  /** Alpha transparency (0-1) */
92
  alpha: number;
93
  
94
  /** Visibility */
95
  visible: boolean;
96
  
97
  /** Renderable flag */
98
  renderable: boolean;
99
  
100
  /** Interactive flag */
101
  interactive: boolean;
102
  
103
  /** Interactivity for children */
104
  interactiveChildren: boolean;
105
  
106
  /** Hit area for interactions */
107
  hitArea: Rectangle | Circle | Ellipse | Polygon;
108
  
109
  /** Cursor style */
110
  cursor: string;
111
  
112
  /** Blend mode */
113
  blendMode: BLEND_MODES;
114
  
115
  /** Tint color */
116
  tint: ColorSource;
117
  
118
  /** Mask for clipping */
119
  mask: Container | MaskData;
120
  
121
  /** Filters array */
122
  filters: Filter[];
123
  
124
  /** Z-index for sorting */
125
  zIndex: number;
126
  
127
  /** Enable sorting children by zIndex */
128
  sortableChildren: boolean;
129
  
130
  /**
131
   * Remove all children
132
   * @param beginIndex - Start index
133
   * @param endIndex - End index
134
   * @returns Removed children
135
   */
136
  removeChildren(beginIndex?: number, endIndex?: number): ContainerChild[];
137
  
138
  /**
139
   * Destroy container and children
140
   * @param options - Destruction options
141
   */
142
  destroy(options?: boolean | DestroyOptions): void;
143
  
144
  /**
145
   * Get local bounds
146
   * @param rect - Rectangle to store bounds
147
   * @returns Local bounds rectangle
148
   */
149
  getLocalBounds(rect?: Rectangle): Rectangle;
150
  
151
  /**
152
   * Get global bounds
153
   * @param skipUpdate - Skip transform update
154
   * @param rect - Rectangle to store bounds
155
   * @returns Global bounds rectangle
156
   */
157
  getBounds(skipUpdate?: boolean, rect?: Rectangle): Rectangle;
158
  
159
  /**
160
   * Convert local point to global
161
   * @param position - Local position
162
   * @param point - Point to store result
163
   * @param skipUpdate - Skip transform update
164
   * @returns Global position
165
   */
166
  toGlobal(position: PointData, point?: Point, skipUpdate?: boolean): Point;
167
  
168
  /**
169
   * Convert global point to local
170
   * @param position - Global position
171
   * @param point - Point to store result
172
   * @param skipUpdate - Skip transform update
173
   * @returns Local position
174
   */
175
  toLocal(position: PointData, from?: Container, point?: Point, skipUpdate?: boolean): Point;
176
}
177
```
178

179
### Sprite
180

181
Display object for rendering textures and images.
182

183
```typescript { .api }
184
/**
185
 * Sprite display object for rendering textures
186
 */
187
class Sprite extends Container {
188
  constructor(texture?: Texture);
189
  
190
  /** Texture to render */
191
  texture: Texture;
192
  
193
  /** Anchor point (0-1) */
194
  anchor: ObservablePoint;
195
  
196
  /** Tint color */
197
  tint: ColorSource;
198
  
199
  /** Blend mode */
200
  blendMode: BLEND_MODES;
201
  
202
  /** Width of sprite */
203
  width: number;
204
  
205
  /** Height of sprite */
206
  height: number;
207
  
208
  /**
209
   * Create sprite from texture or source
210
   * @param source - Texture source
211
   * @param options - Creation options
212
   * @returns New sprite
213
   */
214
  static from(source: Texture | string, options?: SpriteOptions): Sprite;
215
}
216

217
interface SpriteOptions {
218
  /** Texture to use */
219
  texture?: Texture;
220
  
221
  /** Anchor point */
222
  anchor?: PointData;
223
  
224
  /** Tint color */
225
  tint?: ColorSource;
226
  
227
  /** Blend mode */
228
  blendMode?: BLEND_MODES;
229
}
230
```
231

232
### Animated Sprite
233

234
Sprite with texture-based frame animation.
235

236
```typescript { .api }
237
/**
238
 * Animated sprite for texture-based animations
239
 */
240
class AnimatedSprite extends Sprite {
241
  constructor(textures: Texture[] | FrameObject[], autoUpdate?: boolean);
242
  
243
  /** Animation textures */
244
  textures: Texture[] | FrameObject[];
245
  
246
  /** Current frame index */
247
  currentFrame: number;
248
  
249
  /** Animation speed multiplier */
250
  animationSpeed: number;
251
  
252
  /** Loop animation */
253
  loop: boolean;
254
  
255
  /** Animation update anchor */
256
  updateAnchor: boolean;
257
  
258
  /** Animation callback on complete */
259
  onComplete: () => void;
260
  
261
  /** Animation callback on frame change */
262
  onFrameChange: (currentFrame: number) => void;
263
  
264
  /** Animation callback on loop */
265
  onLoop: () => void;
266
  
267
  /** Total number of frames */
268
  readonly totalFrames: number;
269
  
270
  /** Is animation playing */
271
  readonly playing: boolean;
272
  
273
  /**
274
   * Play animation
275
   */
276
  play(): void;
277
  
278
  /**
279
   * Stop animation
280
   */
281
  stop(): void;
282
  
283
  /**
284
   * Go to frame and play
285
   * @param frameNumber - Frame to go to
286
   */
287
  gotoAndPlay(frameNumber: number): void;
288
  
289
  /**
290
   * Go to frame and stop
291
   * @param frameNumber - Frame to go to
292
   */
293
  gotoAndStop(frameNumber: number): void;
294
}
295

296
interface FrameObject {
297
  /** Texture for frame */
298
  texture: Texture;
299
  
300
  /** Time to display frame */
301
  time: number;
302
}
303
```
304

305
### Tiling Sprite
306

307
Sprite that repeats a texture in a tiled pattern.
308

309
```typescript { .api }
310
/**
311
 * Sprite that tiles a texture
312
 */
313
class TilingSprite extends Container {
314
  constructor(texture: Texture, width?: number, height?: number);
315
  
316
  /** Texture to tile */
317
  texture: Texture;
318
  
319
  /** Width of tiling area */
320
  width: number;
321
  
322
  /** Height of tiling area */
323
  height: number;
324
  
325
  /** Tiling offset */
326
  tilePosition: ObservablePoint;
327
  
328
  /** Tiling scale */
329
  tileScale: ObservablePoint;
330
  
331
  /** Tiling transform */
332
  tileTransform: Transform;
333
  
334
  /** Tint color */
335
  tint: ColorSource;
336
  
337
  /** Blend mode */
338
  blendMode: BLEND_MODES;
339
  
340
  /** UV transform */
341
  uvMatrix: TextureMatrix;
342
  
343
  /**
344
   * Create from texture
345
   * @param texture - Texture to tile
346
   * @param width - Width of tiling area
347
   * @param height - Height of tiling area
348
   * @returns New tiling sprite
349
   */
350
  static from(texture: Texture, width: number, height: number): TilingSprite;
351
}
352
```
353

354
### Nine Slice Sprite
355

356
Sprite with 9-slice scaling for UI elements.
357

358
```typescript { .api }
359
/**
360
 * Sprite with 9-slice scaling
361
 */
362
class NineSliceSprite extends Container {
363
  constructor(texture: Texture, leftWidth?: number, topHeight?: number, rightWidth?: number, bottomHeight?: number);
364
  
365
  /** Texture to slice */
366
  texture: Texture;
367
  
368
  /** Left slice width */
369
  leftWidth: number;
370
  
371
  /** Top slice height */
372
  topHeight: number;
373
  
374
  /** Right slice width */
375
  rightWidth: number;
376
  
377
  /** Bottom slice height */
378
  bottomHeight: number;
379
  
380
  /** Width of sprite */
381
  width: number;
382
  
383
  /** Height of sprite */
384
  height: number;
385
  
386
  /** Tint color */
387
  tint: ColorSource;
388
  
389
  /** Blend mode */
390
  blendMode: BLEND_MODES;
391
}
392
```
393

394
### Particle Container
395

396
High-performance container for many similar display objects.
397

398
```typescript { .api }
399
/**
400
 * High-performance container for particles
401
 */
402
class ParticleContainer extends Container {
403
  constructor(maxSize?: number, properties?: ParticleContainerProperties, batchSize?: number, autoResize?: boolean);
404
  
405
  /** Maximum number of particles */
406
  maxSize: number;
407
  
408
  /** Particle properties */
409
  properties: ParticleContainerProperties;
410
  
411
  /** Batch size for rendering */
412
  batchSize: number;
413
  
414
  /** Auto resize when full */
415
  autoResize: boolean;
416
  
417
  /** Enable sorting by z-index */
418
  sortableChildren: boolean;
419
  
420
  /** Blend mode */
421
  blendMode: BLEND_MODES;
422
  
423
  /** Tint color */
424
  tint: ColorSource;
425
}
426

427
interface ParticleContainerProperties {
428
  /** Enable scale */
429
  scale?: boolean;
430
  
431
  /** Enable position */
432
  position?: boolean;
433
  
434
  /** Enable rotation */
435
  rotation?: boolean;
436
  
437
  /** Enable UV coordinates */
438
  uvs?: boolean;
439
  
440
  /** Enable alpha */
441
  alpha?: boolean;
442
}
443
```
444

445
### Mesh
446

447
Custom geometry rendering with vertex-based graphics.
448

449
```typescript { .api }
450
/**
451
 * Mesh for rendering custom geometry with shaders
452
 */
453
class Mesh<GEOMETRY extends Geometry = MeshGeometry, SHADER extends Shader = TextureShader> extends ViewContainer {
454
  constructor(options: MeshOptions<GEOMETRY, SHADER>);
455
  
456
  /** The mesh geometry containing vertices, indices, UVs */
457
  geometry: GEOMETRY;
458
  
459
  /** The shader program used to render the mesh */
460
  shader: SHADER | null;
461
  
462
  /** The texture applied to the mesh */
463
  texture: Texture;
464
  
465
  /** WebGL/WebGPU rendering state */
466
  state: State;
467
  
468
  /** Whether the mesh can be batched (readonly) */
469
  readonly batched: boolean;
470
  
471
  /** Whether to round positions to pixels */
472
  roundPixels: boolean;
473
  
474
  /**
475
   * Check if point is within mesh triangles
476
   * @param point - Point to test
477
   * @returns True if point is inside mesh
478
   */
479
  containsPoint(point: PointData): boolean;
480
}
481

482
interface MeshOptions<GEOMETRY extends Geometry = MeshGeometry, SHADER extends Shader = TextureShader> {
483
  /** Includes vertex positions, face indices, colors, UVs, and custom attributes */
484
  geometry: GEOMETRY;
485
  
486
  /** Represents the vertex and fragment shaders that processes the geometry */
487
  shader?: SHADER | null;
488
  
489
  /** The state of WebGL required to render the mesh */
490
  state?: State;
491
  
492
  /** The texture that the Mesh uses. Null for non-MeshMaterial shaders */
493
  texture?: Texture;
494
  
495
  /** Whether or not to round the x/y position */
496
  roundPixels?: boolean;
497
}
498

499
class MeshGeometry extends Geometry {
500
  constructor(options: MeshGeometryOptions);
501
  
502
  /** Vertex positions (x,y pairs) */
503
  positions: Float32Array;
504
  
505
  /** Texture coordinates (u,v pairs) */
506
  uvs: Float32Array;
507
  
508
  /** Triangle indices */
509
  indices: Uint32Array;
510
  
511
  /** Batching mode */
512
  batchMode: BatchMode;
513
}
514

515
interface MeshGeometryOptions {
516
  /** The positions of the mesh */
517
  positions?: Float32Array;
518
  
519
  /** The UVs of the mesh. If not provided, they will be filled with 0 and match the size of the positions */
520
  uvs?: Float32Array;
521
  
522
  /** The indices of the mesh */
523
  indices?: Uint32Array;
524
  
525
  /** The topology of the mesh */
526
  topology?: Topology;
527
  
528
  /** Whether to shrink the buffers to fit the data */
529
  shrinkBuffersToFit?: boolean;
530
}
531
```
532

533
**Usage Examples:**
534

535
```typescript
536
import { Container, Sprite, AnimatedSprite, TilingSprite, NineSliceSprite, ParticleContainer, Mesh, MeshGeometry, Assets } from 'pixi.js';
537

538
// Basic container hierarchy
539
const scene = new Container();
540
const character = new Container();
541
const background = new Container();
542

543
scene.addChild(background, character);
544

545
// Sprite creation
546
const texture = await Assets.load('character.png');
547
const sprite = new Sprite(texture);
548
sprite.anchor.set(0.5);
549
sprite.x = 100;
550
sprite.y = 100;
551
character.addChild(sprite);
552

553
// Animated sprite
554
const textures = [
555
  await Assets.load('walk1.png'),
556
  await Assets.load('walk2.png'),
557
  await Assets.load('walk3.png')
558
];
559
const animatedSprite = new AnimatedSprite(textures);
560
animatedSprite.animationSpeed = 0.167; // 10 FPS at 60 FPS
561
animatedSprite.play();
562

563
// Tiling background
564
const bgTexture = await Assets.load('tile.png');
565
const tilingSprite = new TilingSprite(bgTexture, 800, 600);
566
tilingSprite.tilePosition.x = -50;
567
background.addChild(tilingSprite);
568

569
// Particle system
570
const particleContainer = new ParticleContainer(1000, {
571
  scale: true,
572
  position: true,
573
  rotation: true,
574
  alpha: true
575
});
576

577
for (let i = 0; i < 100; i++) {
578
  const particle = new Sprite(texture);
579
  particle.x = Math.random() * 800;
580
  particle.y = Math.random() * 600;
581
  particle.scale.set(0.1 + Math.random() * 0.2);
582
  particleContainer.addChild(particle);
583
}
584

585
// Custom mesh geometry
586
const vertices = new Float32Array([
587
  // x, y
588
  -100, -100,  // top-left
589
   100, -100,  // top-right
590
   100,  100,  // bottom-right
591
  -100,  100   // bottom-left
592
]);
593

594
const uvs = new Float32Array([
595
  // u, v
596
  0, 0,  // top-left
597
  1, 0,  // top-right
598
  1, 1,  // bottom-right
599
  0, 1   // bottom-left
600
]);
601

602
const indices = new Uint32Array([
603
  0, 1, 2,  // first triangle
604
  0, 2, 3   // second triangle
605
]);
606

607
const geometry = new MeshGeometry({
608
  positions: vertices,
609
  uvs: uvs,
610
  indices: indices
611
});
612

613
const meshTexture = await Assets.load('mesh-texture.png');
614
const mesh = new Mesh({
615
  geometry: geometry,
616
  texture: meshTexture
617
});
618
scene.addChild(mesh);
619
```