pixijs-core-concepts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Foundational model for how PixiJS v8 gets pixels on the screen: the renderer decides which GPU backend to use, the render loop drives per-frame work, and the environment layer adapts the library to browser, Web Worker, or SSR contexts. For the scene graph itself (Containers, transforms, destroy), see

pixijs-scene-core-concepts

PixiJS v8将像素渲染到屏幕的基础模型：渲染器决定使用哪个GPU后端，渲染循环驱动每帧的工作，环境层使库适配浏览器、Web Worker或SSR上下文。关于场景图本身（Containers、transforms、destroy），请查看

pixijs-scene-core-concepts

。

Quick Start

快速入门

console.log(app.renderer.name); // 'webgl' | 'webgpu' | 'canvas'

app.ticker.add((ticker) => {
  sprite.rotation += 0.01 * ticker.deltaTime;
});

const tex = app.renderer.extract.texture({ target: app.stage });

app.renderer.render({ container: app.stage });

app.renderer

is the

WebGLRenderer

WebGPURenderer

, or

CanvasRenderer

chosen by

autoDetectRenderer

. The TickerPlugin drives

renderer.render()

automatically; call it manually only with

autoStart: false

. Backend selection happens in

Application.init({ preference })

; see

pixijs-application

for setup.

Related skills:

pixijs-application

(Application construction and lifecycle),

pixijs-ticker

(per-frame logic, priorities, FPS capping),

pixijs-environments

(Web Worker, SSR, strict CSP),

pixijs-custom-rendering

(writing a RenderPipe),

pixijs-scene-core-concepts

(scene graph basics).

console.log(app.renderer.name); // 'webgl' | 'webgpu' | 'canvas'

app.ticker.add((ticker) => {
  sprite.rotation += 0.01 * ticker.deltaTime;
});

const tex = app.renderer.extract.texture({ target: app.stage });

app.renderer.render({ container: app.stage });

app.renderer

是由

autoDetectRenderer

选择的

WebGLRenderer

、

WebGPURenderer

或

CanvasRenderer

。TickerPlugin会自动驱动

renderer.render()

；仅当设置

autoStart: false

时才需要手动调用。后端选择在

Application.init({ preference })

中进行；设置方法请查看

pixijs-application

。

相关技能：

pixijs-application

（应用构建与生命周期）、

pixijs-ticker

（每帧逻辑、优先级、FPS限制）、

pixijs-environments

（Web Worker、SSR、严格CSP）、

pixijs-custom-rendering

（编写RenderPipe）、

pixijs-scene-core-concepts

（场景图基础）。

Topics

主题

Topic	Reference	When
Choosing a backend	references/renderers.md	Preference forms, per-renderer options, systems and pipes
Per-frame execution	references/render-loop.md	Priority order, time units, manual rendering

For deep dives into any single topic, open the corresponding reference file. Non-browser targets (

DOMAdapter

WebWorkerAdapter

, custom adapters, strict CSP) are covered in the

pixijs-environments

skill.

主题	参考文档	适用场景
选择后端	references/renderers.md	偏好设置、各渲染器选项、系统与管道
每帧执行逻辑	references/render-loop.md	优先级顺序、时间单位、手动渲染

如需深入了解任一主题，请打开对应的参考文档。非浏览器目标（

DOMAdapter

、

WebWorkerAdapter

、自定义适配器、严格CSP）在

pixijs-environments

技能中讲解。

Decision guide

决策指南

Setting up an Application? Start with
```
pixijs-application
```
. This skill explains what the renderer does under the hood.
Choosing between WebGL and WebGPU? Use
```
['webgpu', 'webgl']
```
as your preference array. WebGPU is fastest where available; WebGL is the reliable fallback. See
```
references/renderers.md
```
.
Running in a Web Worker? Set
```
DOMAdapter.set(WebWorkerAdapter)
```
before
```
app.init
```
. See the
```
pixijs-environments
```
skill for complete setup.
Need manual control over when rendering happens? Set
```
autoStart: false
```
and call
```
app.renderer.render(app.stage)
```
from your own loop. See
```
references/render-loop.md
```
.
Integrating with a physics library? Add your update at
```
UPDATE_PRIORITY.HIGH
```
so physics runs before the render at
```
LOW
```
. See
```
references/render-loop.md
```
.
Writing a custom renderable? Implement a
```
RenderPipe
```
. See
```
pixijs-custom-rendering
```
skill.
Running under strict CSP? Import
```
'pixi.js/unsafe-eval'
```
. See the
```
pixijs-environments
```
skill.

设置应用程序？ 从
```
pixijs-application
```
开始。本技能解释渲染器的底层工作原理。
在WebGL和WebGPU之间选择？ 使用
```
['webgpu', 'webgl']
```
作为你的偏好数组。WebGPU在支持的环境中速度最快；WebGL是可靠的备选方案。请查看
```
references/renderers.md
```
。
在Web Worker中运行？ 在
```
app.init
```
之前设置
```
DOMAdapter.set(WebWorkerAdapter)
```
。完整设置请查看
```
pixijs-environments
```
技能。
需要手动控制渲染时机？ 设置
```
autoStart: false
```
，并在你自己的循环中调用
```
app.renderer.render(app.stage)
```
。请查看
```
references/render-loop.md
```
。
与物理库集成？ 在
```
UPDATE_PRIORITY.HIGH
```
添加你的更新逻辑，这样物理计算会在
```
LOW
```
优先级的渲染之前运行。请查看
```
references/render-loop.md
```
。
编写自定义可渲染对象？ 实现一个
```
RenderPipe
```
。请查看
```
pixijs-custom-rendering
```
技能。
在严格CSP下运行？ 导入
```
'pixi.js/unsafe-eval'
```
。请查看
```
pixijs-environments
```
技能。

Quick concepts

核心概念

Renderer = systems + pipes

渲染器 = 系统 + 管道

Each renderer is composed of

Systems

(lifecycle services: textures, buffers, state, filters, masks) and

RenderPipes

(per-renderable instruction builders: sprite, graphics, mesh, particle, text, tiling). Writing a custom renderable means implementing a

RenderPipe

and registering it via extensions.

每个渲染器由

Systems

（生命周期服务：纹理、缓冲区、状态、滤镜、遮罩）和

RenderPipes

（每个可渲染对象的指令构建器：精灵、图形、网格、粒子、文本、平铺）组成。编写自定义可渲染对象意味着实现一个

RenderPipe

并通过扩展进行注册。

The render loop

渲染循环

app.ticker.add(fn)

registers a callback that runs every frame. The

TickerPlugin

registers

app.render()

UPDATE_PRIORITY.LOW

, so ticker callbacks at

NORMAL

HIGH

run before the draw. Disable the plugin with

autoStart: false

for manual control.

app.ticker.add(fn)

注册一个每帧运行的回调函数。TickerPlugin会在

UPDATE_PRIORITY.LOW

优先级注册

app.render()

，因此

NORMAL

或

HIGH

优先级的ticker回调会在绘制前运行。设置

autoStart: false

可禁用该插件，实现手动控制。

Environments

环境适配

DOMAdapter

abstracts every DOM call PixiJS makes (canvas creation, image loading, fetch, XML parsing). Swap with

DOMAdapter.set(WebWorkerAdapter)

for Workers or implement a custom

Adapter

for Node/SSR. Must be done before

Application.init

DOMAdapter

抽象了PixiJS进行的所有DOM调用（画布创建、图片加载、fetch、XML解析）。在Worker环境中可替换为

DOMAdapter.set(WebWorkerAdapter)

，或为Node/SSR实现自定义

Adapter

。必须在

Application.init

之前完成替换。

Common Mistakes

常见错误

[HIGH] Accessing app.renderer before init() resolves

[高风险] 在init()完成前访问app.renderer

Wrong:

const app = new Application();
app.init({ width: 800, height: 600 });
console.log(app.renderer.name); // undefined — init() is async

Correct:

const app = new Application();
await app.init({ width: 800, height: 600 });
console.log(app.renderer.name); // 'webgl' | 'webgpu' | 'canvas'

Application.init()

is async.

app.renderer

app.canvas

, and

app.screen

do not exist until after the promise resolves.

错误示例：

const app = new Application();
app.init({ width: 800, height: 600 });
console.log(app.renderer.name); // undefined — init()是异步的

正确示例：

const app = new Application();
await app.init({ width: 800, height: 600 });
console.log(app.renderer.name); // 'webgl' | 'webgpu' | 'canvas'

Application.init()

是异步的。

app.renderer

、

app.canvas

和

app.screen

要等到Promise解析后才会存在。

[HIGH] Setting DOMAdapter after Application.init

[高风险] 在Application.init之后设置DOMAdapter

Wrong:

const app = new Application();
await app.init({ width: 800, height: 600 });
DOMAdapter.set(WebWorkerAdapter); // too late — init already allocated resources

Correct:

DOMAdapter.set(WebWorkerAdapter);
const app = new Application();
await app.init({ width: 800, height: 600 });

The adapter abstracts DOM calls the renderer makes during construction (canvas creation, image loading, fetch). Swap it before

init()

or the wrong adapter is baked into the renderer.

错误示例：

const app = new Application();
await app.init({ width: 800, height: 600 });
DOMAdapter.set(WebWorkerAdapter); // 太晚了 — init已经分配了资源

正确示例：

DOMAdapter.set(WebWorkerAdapter);
const app = new Application();
await app.init({ width: 800, height: 600 });

适配器会抽象渲染器在构建过程中进行的DOM调用（画布创建、图片加载、fetch）。必须在

init()

之前替换，否则错误的适配器会被固化到渲染器中。

[MEDIUM] Treating

preference

as a guarantee

[中风险] 将

preference

视为绝对保证

Wrong:

await app.init({ preference: "webgpu" });
// assume WebGPU is active
useWebGPUOnlyFeature(app.renderer);

Correct:

await app.init({ preference: "webgpu" });
if (app.renderer.name === "webgpu") {
  useWebGPUOnlyFeature(app.renderer);
}

preference

is a hint, not a demand. If the browser lacks WebGPU support, PixiJS falls back to WebGL (or Canvas). Always branch on

renderer.name

for backend-specific code.

错误示例：

await app.init({ preference: "webgpu" });
// 假设WebGPU已激活
useWebGPUOnlyFeature(app.renderer);

正确示例：

await app.init({ preference: "webgpu" });
if (app.renderer.name === "webgpu") {
  useWebGPUOnlyFeature(app.renderer);
}

preference

是一个提示，而非强制要求。如果浏览器不支持WebGPU，PixiJS会回退到WebGL（或Canvas）。对于后端特定代码，务必根据

renderer.name

进行分支处理。

pixijs-core-concepts

Original

Translation

Quick Start

快速入门

Topics

主题

Decision guide

决策指南

Quick concepts

核心概念

Renderer = systems + pipes

渲染器 = 系统 + 管道

The render loop

渲染循环

Environments

环境适配

Common Mistakes

常见错误

[HIGH] Accessing app.renderer before init() resolves

[高风险] 在init()完成前访问app.renderer

[HIGH] Setting DOMAdapter after Application.init

[高风险] 在Application.init之后设置DOMAdapter

[MEDIUM] Treating
`preference`
as a guarantee

[中风险] 将
`preference`
视为绝对保证

API Reference

API参考

pixijs-core-concepts

Original

Translation

Quick Start

快速入门

Topics

主题

Decision guide

决策指南

Quick concepts

核心概念

Renderer = systems + pipes

渲染器 = 系统 + 管道

The render loop

渲染循环

Environments

环境适配

Common Mistakes

常见错误

[HIGH] Accessing app.renderer before init() resolves

[高风险] 在init()完成前访问app.renderer

[HIGH] Setting DOMAdapter after Application.init

[高风险] 在Application.init之后设置DOMAdapter

[MEDIUM] Treating preference as a guarantee

[中风险] 将preference视为绝对保证

API Reference

API参考

[MEDIUM] Treating
`preference`
as a guarantee

[中风险] 将
`preference`
视为绝对保证