0
# PixiJS
1
2
PixiJS is a fast, lightweight 2D graphics rendering library that enables developers to create rich, interactive graphics and cross-platform applications. It provides WebGL-first rendering with HTML5 canvas fallback, offering hardware acceleration for superior performance across all devices.
3
4
## Package Information
5
6
- **Package Name**: pixi.js
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Installation**: `npm install pixi.js`
10
11
## Core Imports
12
13
```typescript
14
import * as PIXI from "pixi.js";
15
// or
16
import { Application, Sprite, Graphics, Container } from "pixi.js";
17
```
18
19
For CommonJS:
20
21
```javascript
22
const PIXI = require("pixi.js");
23
// or
24
const { Application, Sprite, Graphics, Container } = require("pixi.js");
25
```
26
27
## Basic Usage
28
29
```typescript
30
import { Application, Sprite, Assets } from "pixi.js";
31
32
// Create application
33
const app = new Application({ width: 800, height: 600 });
34
document.body.appendChild(app.view);
35
36
// Load texture and create sprite
37
const texture = await Assets.load("https://pixijs.com/assets/bunny.png");
38
const bunny = new Sprite(texture);
39
40
// Position and add to stage
41
bunny.x = app.screen.width / 2;
42
bunny.y = app.screen.height / 2;
43
bunny.anchor.set(0.5);
44
app.stage.addChild(bunny);
45
46
// Animate (requires ticker plugin)
47
// app.ticker.add(() => {
48
// bunny.rotation += 0.01;
49
// });
50
```
51
52
## Architecture
53
54
PixiJS is built around several key systems:
55
56
- **Display System**: Scene graph with `DisplayObject` base class and `Container` for grouping
57
- **Rendering System**: WebGL-first renderer with optimized batching and state management
58
- **Asset System**: Modern async loading with `Assets` API replacing legacy `Loader`
59
- **Interaction System**: Touch, mouse, and pointer event handling with event propagation
60
- **Filter System**: WebGL shader-based post-processing effects
61
- **Math System**: 2D geometry classes (`Point`, `Rectangle`, `Matrix`) for spatial calculations
62
63
## Capabilities
64
65
### Application & Setup
66
67
Application management, renderer creation, and lifecycle control. The Application class provides the easiest way to get started with PixiJS.
68
69
```typescript { .api }
70
class Application {
71
stage: Container;
72
renderer: Renderer;
73
screen: Rectangle;
74
view: HTMLCanvasElement;
75
76
constructor(options?: ApplicationOptions);
77
render(): void;
78
destroy(removeView?: boolean, stageOptions?: boolean | IDestroyOptions): void;
79
}
80
81
interface ApplicationOptions {
82
width?: number;
83
height?: number;
84
view?: HTMLCanvasElement;
85
backgroundColor?: number;
86
backgroundAlpha?: number;
87
antialias?: boolean;
88
resolution?: number;
89
resizeTo?: Window | HTMLElement;
90
}
91
```
92
93
[Application & Setup](./application.md)
94
95
### Display Objects & Scene Graph
96
97
Core display object system providing the foundation for all renderable objects, including the scene graph hierarchy.
98
99
```typescript { .api }
100
class DisplayObject extends EventEmitter {
101
position: ObservablePoint;
102
scale: ObservablePoint;
103
pivot: ObservablePoint;
104
rotation: number;
105
alpha: number;
106
visible: boolean;
107
renderable: boolean;
108
parent: Container;
109
worldTransform: Matrix;
110
111
getBounds(skipUpdate?: boolean, rect?: Rectangle): Rectangle;
112
toGlobal(position: IPointData, point?: Point, skipUpdate?: boolean): Point;
113
toLocal(position: IPointData, from?: DisplayObject, point?: Point, skipUpdate?: boolean): Point;
114
destroy(): void;
115
}
116
117
class Container extends DisplayObject {
118
children: DisplayObject[];
119
sortableChildren: boolean;
120
interactiveChildren: boolean;
121
122
addChild<T extends DisplayObject[]>(...children: T): T[0];
123
removeChild<T extends DisplayObject[]>(...children: T): T[0];
124
getChildAt(index: number): DisplayObject;
125
getChildIndex(child: DisplayObject): number;
126
setChildIndex(child: DisplayObject, index: number): void;
127
removeChildren(beginIndex?: number, endIndex?: number): DisplayObject[];
128
}
129
```
130
131
[Display Objects](./display-objects.md)
132
133
### Asset Loading
134
135
Modern asset loading system with support for various formats, bundles, and caching strategies.
136
137
```typescript { .api }
138
class Assets {
139
static load<T = any>(urls: string | string[]): Promise<T>;
140
static loadBundle<T = any>(bundleIds: string | string[]): Promise<T>;
141
static get<T = any>(keys: string | string[]): T;
142
static unload(urls: string | string[]): Promise<void>;
143
static add(assets: AssetsManifest): void;
144
static init(options?: AssetsInitOptions): Promise<void>;
145
}
146
147
interface AssetsManifest {
148
bundles?: AssetsBundle[];
149
}
150
151
interface AssetsBundle {
152
name: string;
153
assets: AssetsManifestEntry[];
154
}
155
156
interface AssetsManifestEntry {
157
alias: string | string[];
158
src: string | string[];
159
data?: any;
160
}
161
```
162
163
[Asset Loading](./assets.md)
164
165
### Sprites & Textures
166
167
Textured display objects and texture management system for efficient rendering of images and sprite sheets.
168
169
```typescript { .api }
170
class Sprite extends Container {
171
texture: Texture;
172
anchor: ObservablePoint;
173
tint: number;
174
blendMode: BLEND_MODES;
175
176
static from(source: TextureSource, skipCache?: boolean): Sprite;
177
178
constructor(texture?: Texture);
179
}
180
181
class Texture extends EventEmitter {
182
baseTexture: BaseTexture;
183
frame: Rectangle;
184
rotate: number;
185
width: number;
186
height: number;
187
188
static from(source: TextureSource, options?: IBaseTextureOptions): Texture;
189
static fromURL(url: string, options?: IBaseTextureOptions): Promise<Texture>;
190
static fromBuffer(buffer: Float32Array | Uint8Array, width: number, height: number, options?: IBaseTextureOptions): Texture;
191
192
constructor(baseTexture: BaseTexture, frame?: Rectangle);
193
clone(): Texture;
194
update(): void;
195
destroy(destroyBase?: boolean): void;
196
}
197
```
198
199
[Sprites & Textures](./sprites-textures.md)
200
201
### Vector Graphics
202
203
Canvas-like vector graphics API for drawing shapes, paths, and complex graphics programmatically.
204
205
```typescript { .api }
206
class Graphics extends Container {
207
constructor();
208
209
beginFill(color?: number, alpha?: number): this;
210
endFill(): this;
211
lineStyle(width?: number, color?: number, alpha?: number, alignment?: number, native?: boolean): this;
212
moveTo(x: number, y: number): this;
213
lineTo(x: number, y: number): this;
214
bezierCurveTo(cpX: number, cpY: number, cpX2: number, cpY2: number, toX: number, toY: number): this;
215
quadraticCurveTo(cpX: number, cpY: number, toX: number, toY: number): this;
216
drawRect(x: number, y: number, width: number, height: number): this;
217
drawRoundedRect(x: number, y: number, width: number, height: number, radius: number): this;
218
drawCircle(x: number, y: number, radius: number): this;
219
drawEllipse(x: number, y: number, halfWidth: number, halfHeight: number): this;
220
drawPolygon(path: number[] | Point[] | Polygon): this;
221
clear(): this;
222
}
223
```
224
225
[Vector Graphics](./graphics.md)
226
227
### Text Rendering
228
229
Multiple text rendering approaches including canvas-based text, bitmap fonts, and HTML text for various performance and styling needs.
230
231
```typescript { .api }
232
class Text extends Sprite {
233
text: string;
234
style: TextStyle;
235
236
constructor(text?: string, style?: Partial<ITextStyle>);
237
updateText(respectDirty?: boolean): void;
238
}
239
240
class TextStyle {
241
constructor(style?: Partial<ITextStyle>);
242
clone(): TextStyle;
243
reset(): void;
244
}
245
246
interface ITextStyle {
247
fontFamily?: string | string[];
248
fontSize?: number | string;
249
fill?: string | string[] | number | number[] | CanvasGradient | CanvasPattern;
250
stroke?: string | number;
251
strokeThickness?: number;
252
align?: 'left' | 'center' | 'right' | 'justify';
253
fontWeight?: 'normal' | 'bold' | 'bolder' | 'lighter' | number | string;
254
fontStyle?: 'normal' | 'italic' | 'oblique';
255
wordWrap?: boolean;
256
wordWrapWidth?: number;
257
}
258
```
259
260
[Text Rendering](./text.md)
261
262
### Animation & Sprites
263
264
Frame-based animation system and animated sprite functionality for creating sprite animations and sequences.
265
266
```typescript { .api }
267
class AnimatedSprite extends Sprite {
268
textures: Texture[];
269
currentFrame: number;
270
playing: boolean;
271
loop: boolean;
272
animationSpeed: number;
273
274
constructor(textures: Texture[], autoUpdate?: boolean);
275
play(): void;
276
stop(): void;
277
gotoAndPlay(frameNumber: number): void;
278
gotoAndStop(frameNumber: number): void;
279
update(deltaTime: number): void;
280
}
281
282
class Spritesheet {
283
textures: Record<string, Texture>;
284
animations: Record<string, Texture[]>;
285
286
constructor(texture: BaseTexture | Texture, data: ISpritesheetData);
287
parse(): Promise<Record<string, Texture>>;
288
}
289
```
290
291
[Animation](./animation.md)
292
293
### Interaction & Events
294
295
Modern event system with support for mouse, touch, and pointer events with proper event propagation through the scene graph.
296
297
```typescript { .api }
298
interface IPointData {
299
x: number;
300
y: number;
301
}
302
303
class FederatedPointerEvent extends FederatedEvent {
304
pointerId: number;
305
width: number;
306
height: number;
307
isPrimary: boolean;
308
pointerType: string;
309
pressure: number;
310
tangentialPressure: number;
311
tiltX: number;
312
tiltY: number;
313
twist: number;
314
button: number;
315
buttons: number;
316
317
getLocalPosition(displayObject: DisplayObject, point?: Point): Point;
318
getModifierState(key: string): boolean;
319
}
320
321
interface EventTarget {
322
interactive: boolean;
323
interactiveChildren: boolean;
324
hitArea: Rectangle | Circle | Ellipse | Polygon | RoundedRectangle;
325
326
on(event: string, fn: Function, context?: any): this;
327
once(event: string, fn: Function, context?: any): this;
328
off(event: string, fn?: Function, context?: any): this;
329
emit(event: string, ...args: any[]): boolean;
330
}
331
```
332
333
[Interaction & Events](./interaction.md)
334
335
### Filters & Effects
336
337
WebGL shader-based post-processing effects system with built-in filters and support for custom shaders.
338
339
```typescript { .api }
340
class Filter {
341
constructor(vertexSrc?: string, fragmentSrc?: string, uniforms?: any);
342
apply(filterManager: FilterSystem, input: RenderTexture, output: RenderTexture, clearMode?: CLEAR_MODES): void;
343
}
344
345
class BlurFilter extends Filter {
346
blur: number;
347
blurX: number;
348
blurY: number;
349
quality: number;
350
351
constructor(strength?: number, quality?: number, resolution?: number, kernelSize?: number);
352
}
353
354
class ColorMatrixFilter extends Filter {
355
matrix: number[];
356
alpha: number;
357
358
constructor();
359
brightness(b: number, multiply?: boolean): void;
360
contrast(amount: number, multiply?: boolean): void;
361
saturate(amount?: number, multiply?: boolean): void;
362
desaturate(): void;
363
hue(rotation: number, multiply?: boolean): void;
364
}
365
```
366
367
[Filters & Effects](./filters.md)
368
369
### Math & Geometry
370
371
2D mathematics utilities including points, rectangles, matrices, and geometric shapes for spatial calculations.
372
373
```typescript { .api }
374
class Point implements IPointData {
375
x: number;
376
y: number;
377
378
constructor(x?: number, y?: number);
379
clone(): Point;
380
copyFrom(p: IPointData): this;
381
copyTo<T extends IPoint>(p: T): T;
382
equals(p: IPointData): boolean;
383
set(x?: number, y?: number): this;
384
}
385
386
class Rectangle {
387
x: number;
388
y: number;
389
width: number;
390
height: number;
391
392
constructor(x?: number, y?: number, width?: number, height?: number);
393
clone(): Rectangle;
394
contains(x: number, y: number): boolean;
395
intersects(other: Rectangle): boolean;
396
pad(paddingX: number, paddingY?: number): this;
397
}
398
399
class Matrix {
400
a: number; b: number; c: number; d: number; tx: number; ty: number;
401
402
constructor(a?: number, b?: number, c?: number, d?: number, tx?: number, ty?: number);
403
apply(pos: IPointData, newPos?: Point): Point;
404
translate(x: number, y: number): this;
405
scale(x: number, y: number): this;
406
rotate(angle: number): this;
407
invert(): this;
408
}
409
```
410
411
[Math & Geometry](./math.md)
412
413
### Utilities & Constants
414
415
Core utilities, device detection, performance helpers, and WebGL constants used throughout the library.
416
417
```typescript { .api }
418
const utils: {
419
EventEmitter: typeof EventEmitter;
420
uid(): number;
421
hex2rgb(hex: number, out?: number[]): number[];
422
hex2string(hex: number): string;
423
rgb2hex(rgb: number[]): number;
424
getResolutionOfUrl(url: string): number;
425
isPow2(v: number): boolean;
426
nextPow2(v: number): number;
427
earcut(data: number[], holeIndices?: number[], dim?: number): number[];
428
isMobile: {
429
apple: { phone: boolean; ipod: boolean; tablet: boolean; universal: boolean; device: boolean; };
430
amazon: { phone: boolean; tablet: boolean; device: boolean; };
431
android: { phone: boolean; tablet: boolean; device: boolean; };
432
windows: { phone: boolean; tablet: boolean; device: boolean; };
433
other: { blackberry: boolean; blackberry10: boolean; opera: boolean; firefox: boolean; chrome: boolean; device: boolean; };
434
any: boolean;
435
phone: boolean;
436
tablet: boolean;
437
};
438
};
439
440
enum BLEND_MODES {
441
NORMAL = 0,
442
ADD = 1,
443
MULTIPLY = 2,
444
SCREEN = 3,
445
OVERLAY = 4,
446
DARKEN = 5,
447
LIGHTEN = 6,
448
COLOR_DODGE = 7,
449
COLOR_BURN = 8,
450
HARD_LIGHT = 9,
451
SOFT_LIGHT = 10,
452
DIFFERENCE = 11,
453
EXCLUSION = 12,
454
HUE = 13,
455
SATURATION = 14,
456
COLOR = 15,
457
LUMINOSITY = 16
458
}
459
460
enum SCALE_MODES {
461
NEAREST = 0,
462
LINEAR = 1
463
}
464
```
465
466
[Utilities & Constants](./utilities.md)
467
468
## Types
469
470
```typescript { .api }
471
interface IPointData {
472
x: number;
473
y: number;
474
}
475
476
interface IPoint extends IPointData {
477
copyFrom(p: IPointData): this;
478
copyTo<T extends IPoint>(p: T): T;
479
equals(p: IPointData): boolean;
480
set(x?: number, y?: number): this;
481
}
482
483
type TextureSource = string | BaseTexture | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement | ImageBitmap;
484
485
interface IBaseTextureOptions {
486
scaleMode?: SCALE_MODES;
487
resolution?: number;
488
mipmap?: MIPMAP_MODES;
489
anisotropicLevel?: number;
490
wrapMode?: WRAP_MODES;
491
format?: FORMATS;
492
type?: TYPES;
493
target?: TARGETS;
494
alphaMode?: ALPHA_MODES;
495
width?: number;
496
height?: number;
497
resourceOptions?: any;
498
}
499
```