pixijs-scene-core-concepts
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseThis skill is the shared mental model referenced by all leaves. It explains what the scene graph is in PixiJS v8, how a differs from a leaf, and where each concept lives. It does not go deep on any single API; it frames the pieces and points to the skill or reference file that does.
pixijs-scene-*Container本技能是所有叶子节点技能的通用参考模型。它解释了PixiJS v8中的场景图是什么、与叶子节点的区别，以及各个概念的定位。本技能不会深入讲解单个API，而是梳理各个组件的关系，并指向对应的技能或参考文档。
pixijs-scene-*ContainerQuick Start
快速入门
ts
const world = new Container({ isRenderGroup: true });
app.stage.addChild(world);
const hero = new Container({ label: "hero" });
hero.addChild(new Sprite(bodyTexture));
hero.addChild(new Sprite(faceTexture));
world.addChild(hero);
const mask = new Graphics().rect(0, 0, 800, 600).fill(0xffffff);
world.mask = mask;
world.addChild(mask);
hero.position.set(world.width / 2, world.height / 2);Related skills: (Container API in detail), the leaf skills (, , , , , , ), (hit testing traverses the scene graph), (cache, culling, render groups), (Matrix, toGlobal/toLocal detail).
pixijs-scene-containerpixijs-scene-spritepixijs-scene-graphicspixijs-scene-textpixijs-scene-meshpixijs-scene-particle-containerpixijs-scene-dom-containerpixijs-scene-gifpixijs-eventspixijs-performancepixijs-mathts
const world = new Container({ isRenderGroup: true });
app.stage.addChild(world);
const hero = new Container({ label: "hero" });
hero.addChild(new Sprite(bodyTexture));
hero.addChild(new Sprite(faceTexture));
world.addChild(hero);
const mask = new Graphics().rect(0, 0, 800, 600).fill(0xffffff);
world.mask = mask;
world.addChild(mask);
hero.position.set(world.width / 2, world.height / 2);相关技能： （详细讲解Container API）、叶子节点技能（、、、、、、）、（点击测试会遍历场景图）、（缓存、剔除、渲染组）、（Matrix、toGlobal/toLocal细节）。
pixijs-scene-containerpixijs-scene-spritepixijs-scene-graphicspixijs-scene-textpixijs-scene-meshpixijs-scene-particle-containerpixijs-scene-dom-containerpixijs-scene-gifpixijs-eventspixijs-performancepixijs-mathCore Concepts
核心概念
What the scene graph is
什么是场景图
The PixiJS scene graph is a tree of display objects rooted at . Each node has a parent, a transform (position, scale, rotation, pivot, skew) relative to its parent, and optional visual state (alpha, tint, blendMode, visibility). Each frame the renderer walks the tree, composes transforms and visual state down to world-space, culls what's offscreen, and emits draw calls. The scene graph is both the layout model and the render order: earlier siblings draw behind later siblings.
app.stageEvery display object in v8 is a subclass. from earlier versions was removed.
ContainerDisplayObjectPixiJS场景图是以为根节点的显示对象树。每个节点都有父节点、相对于父节点的变换（位置、缩放、旋转、轴心、倾斜），以及可选的视觉状态（透明度、色调、混合模式、可见性）。渲染器每帧都会遍历该树，将变换和视觉状态组合为世界空间状态，剔除屏幕外的对象，然后发出绘制调用。场景图既是布局模型，也是渲染顺序：先添加的兄弟节点会绘制在后续兄弟节点的后方。
app.stagev8中的所有显示对象都是的子类。旧版本中的已被移除。
ContainerDisplayObjectContainer vs leaf (CRITICAL)
容器 vs 叶子节点（关键）
There are two roles in the tree:
- Containers: nodes that hold children. Use a (or
Container) for any node that groups, positions, or transforms other nodes.RenderLayer - Leaves: nodes that draw something and have no children. Use ,
Sprite,Graphics,Text,Mesh'sParticleContainer,Particle, orDOMContaineras leaves.GifSprite
In PixiJS v8, leaves must not have children. Adding children to a / / / logs a deprecation warning and is scheduled to become a hard error. The rule is: use for any node that needs children; do not nest children inside leaf scene objects. If you need to group a leaf with other leaves, wrap them in a .
SpriteGraphicsTextMeshContainerContainerThis distinction is why the skills are split the way they are: covers the grouping node, and each leaf gets its own skill focused on its draw behavior.
pixijs-scene-*pixijs-scene-container树中有两种角色：
- 容器：用于容纳子节点的节点。当你需要对其他节点进行分组、定位或变换时，使用（或
Container）。RenderLayer - 叶子节点：用于绘制内容且没有子节点的节点。叶子节点可使用、
Sprite、Graphics、Text、Mesh的ParticleContainer、Particle或DOMContainer。GifSprite
在PixiJS v8中，叶子节点不能拥有子节点。如果给///添加子节点，会输出弃用警告，未来会变为硬性错误。规则是：任何需要子节点的节点都使用；不要在叶子节点内嵌套子节点。如果需要将一个叶子节点与其他叶子节点分组，用包裹它们。
SpriteGraphicsTextMeshContainerContainer这种区分也是技能拆分的原因：讲解分组节点，每个叶子节点都有专注于其绘制行为的独立技能。
pixijs-scene-*pixijs-scene-containerTransforms and coordinate spaces
变换与坐标空间
Every container composes a (a ) from its , , , , and . The renderer multiplies parents' local transforms together to produce the (and if a render group is in the chain), which maps local points to scene-root space. Use and to convert between spaces, and for this object's world position. Full Matrix detail lives in ; transform setters and / live in .
localTransformMatrixpositionscalerotationpivotskewworldTransformgroupTransformtoGlobal(point)toLocal(point, from?)getGlobalPosition()pixijs-mathtoLocaltoGlobalpixijs-scene-container每个容器都会根据自身的、、、和生成（一个）。渲染器会将父节点的局部变换相乘，生成（如果链中有渲染组，则还会生成），用于将局部点映射到场景根空间。使用和进行空间转换，使用获取对象的世界位置。完整的Matrix细节在中；变换设置器和/在中。
positionscalerotationpivotskewlocalTransformMatrixworldTransformgroupTransformtoGlobal(point)toLocal(point, from?)getGlobalPosition()pixijs-mathtoLocaltoGlobalpixijs-scene-containerRender order and explicit z-ordering
渲染顺序与显式Z轴排序
Children render in array order: index 0 first, last index last. For explicit z-ordering on a single container, set and assign values to children. For render order that is decoupled from the logical hierarchy (e.g., a character's parent is a game world but its drawing happens on a UI layer), use . Deep detail, including when to prefer sortable children vs RenderLayer, is in .
sortableChildren = truezIndexRenderLayerreferences/scene-management.md子节点按数组顺序渲染：索引0最先渲染，最后一个索引最后渲染。如果要对单个容器进行显式Z轴排序，设置并为子节点分配值。如果需要与逻辑层级解耦的渲染顺序（例如，角色的父节点是游戏世界，但绘制在UI层），使用。包括何时优先使用可排序子节点或RenderLayer的详细内容，可查看。
sortableChildren = truezIndexRenderLayerreferences/scene-management.mdRender groups
渲染组
Flagging a container with (or calling ) tells PixiJS to apply its transform on the GPU as a single matrix instead of recomputing every descendant's world transform on the CPU each frame. Use render groups on large, stable sub-trees such as worlds, UI layers, or parallax strips. Deep detail in .
isRenderGroup: truecontainer.enableRenderGroup()references/scene-management.md给容器标记（或调用）会告诉PixiJS在GPU上以单个矩阵的形式应用其变换，而不是每帧在CPU上重新计算每个后代的世界变换。在大型、稳定的子树（如游戏世界、UI层或视差条）上使用渲染组。详细内容在中。
isRenderGroup: truecontainer.enableRenderGroup()references/scene-management.mdCulling
剔除
cullable = truecullArea: RectangleCullerPlugincullableChildren = falsepixijs-performancereferences/scene-management.md设置 + 会告诉（或任何剔除流程）跳过渲染可见区域外的对象。会终止子树的递归剔除，适用于子节点始终在屏幕上的情况。剔除是性能优化相关话题；和会讲解其权衡。
cullable = truecullArea: RectangleCullerPlugincullableChildren = falsepixijs-performancereferences/scene-management.mdMasking
遮罩
Set to another display object to clip its rendering. PixiJS picks the mask type automatically: a or mask uses a stencil buffer, a mask uses an alpha filter, and a number selects a . All four mask types (AlphaMask, StencilMask, ScissorMask, ColorMask) are covered in .
container.maskGraphicsContainerSpriteColorMaskreferences/masking.md将设置为另一个显示对象即可裁剪其渲染内容。PixiJS会自动选择遮罩类型：或遮罩使用模板缓冲区，遮罩使用透明度滤镜，数字则选择。所有四种遮罩类型（AlphaMask、StencilMask、ScissorMask、ColorMask）的详细内容在中。
container.maskGraphicsContainerSpriteColorMaskreferences/masking.mdVisibility, alpha, tint, and blend mode
可见性、透明度、色调与混合模式
visible = falserenderable = falsealphatintblendModepixijs-blend-modespixijs-scene-containervisible = falserenderable = falsealphatintblendModepixijs-blend-modespixijs-scene-containerDestroy semantics
销毁语义
container.destroy()container.destroy({ children: true })texture: truetextureSource: truecacheAsTexturepixijs-scene-containercontainer.destroy()container.destroy({ children: true })texture: truetextureSource: truecacheAsTexturepixijs-scene-containerLifecycle events
生命周期事件
Containers emit events for hierarchy and visibility changes: / on the parent, / on the child, plus and on the container itself. Useful for wiring reactive UI updates or resource bookkeeping. Full details in .
childAddedchildRemovedaddedremovedvisibleChangeddestroyedreferences/container-hierarchy.md容器会针对层级和可见性变化触发事件：父节点触发/，子节点触发/，容器自身还会触发和。这些事件可用于响应式UI更新或资源记账。详细内容在中。
childAddedchildRemovedaddedremovedvisibleChangeddestroyedreferences/container-hierarchy.mdLeaf comparison: which skill covers which object
叶子节点对比：不同对象对应的技能
| Leaf | Primary use | Skill |
|---|---|---|
| Draw a single texture at a position (with variants | |
| Render text. Canvas-based | |
| Vector drawing: shapes, lines, paths, fills, strokes. Backed by a | |
| Custom geometry with a shader or texture. Use | |
| Thousands of lightweight sprites with a restricted transform set, for high-throughput particle effects. | |
| Render an HTML element positioned inside the scene graph (useful for inputs, iframes, accessibility overlays). | |
| Animated GIF playback as a display object. Requires | |
Containerpixijs-scene-container| 叶子节点 | 主要用途 | 技能 |
|---|---|---|
| 在指定位置绘制单个纹理（包含变体 | |
| 渲染文本。基于Canvas的 | |
| 矢量绘制：形状、线条、路径、填充、描边。由 | |
| 带有着色器或纹理的自定义几何体。使用 | |
| 数千个轻量级精灵，具有受限的变换集，用于高吞吐量的粒子效果。 | |
| 在场景图中定位渲染HTML元素（适用于输入框、iframe、无障碍覆盖层）。 | |
| 将GIF动画作为显示对象播放。需要依赖 | |
Containerpixijs-scene-containerWhen to use what (quick decisions)
场景决策速查
- "I want to group and transform some display objects" → , see
Container.pixijs-scene-container - "I want to draw a texture" → , see
Sprite.pixijs-scene-sprite - "I want to draw vector shapes or paths" → , see
Graphics.pixijs-scene-graphics - "I want to draw text" → /
Text/BitmapText, seeHTMLText.pixijs-scene-text - "I want thousands of cheap sprites" → , see
ParticleContainer.pixijs-scene-particle-container - "I want a custom-geometry mesh or a deformed sprite" → or one of its variants, see
Mesh.pixijs-scene-mesh - "I want to clip a sub-tree" → set , see
.mask.references/masking.md - "I want a decoupled render order" → , see
RenderLayer.references/scene-management.md - "I want GPU-level transforms for a big stable sub-tree" → , see
isRenderGroup: true.references/scene-management.md - "I want to skip offscreen rendering" → +
cullable = true, seeCullerPlugin.pixijs-performance
- "我想对一些显示对象进行分组和变换" → 使用，查看
Container。pixijs-scene-container - "我想绘制纹理" → 使用，查看
Sprite。pixijs-scene-sprite - "我想绘制矢量形状或路径" → 使用，查看
Graphics。pixijs-scene-graphics - "我想绘制文本" → 使用/
Text/BitmapText，查看HTMLText。pixijs-scene-text - "我需要数千个低成本精灵" → 使用，查看
ParticleContainer。pixijs-scene-particle-container - "我需要自定义几何体网格或变形精灵" → 使用或其变体，查看
Mesh。pixijs-scene-mesh - "我想裁剪子树" → 设置，查看
.mask。references/masking.md - "我需要解耦的渲染顺序" → 使用，查看
RenderLayer。references/scene-management.md - "我想为大型稳定子树启用GPU级变换" → 设置，查看
isRenderGroup: true。references/scene-management.md - "我想跳过屏幕外渲染" → 设置+
cullable = true，查看CullerPlugin。pixijs-performance
References
参考文档
- references/constructor-options.md: the ~30 fields inherited by every -derived node (transform, display, hierarchy, sorting, layout, effects, callbacks), with defaults, types, and when line-by-line assignment is appropriate. Shared reference for all leaf skills.
Container - references/container-hierarchy.md: add/remove/swap children, reparenting with transform preservation, label navigation, destroy sub-trees.
- references/transforms.md: position, scale, rotation, pivot, origin, skew, toGlobal/toLocal, the three matrices (local/group/world), bounds.
- references/masking.md: AlphaMask, StencilMask, ScissorMask, ColorMask, inverse masking, cost comparison.
- references/layers.md: , attach/detach, sorted layers, layer + logical parent split.
RenderLayer - references/render-groups.md: , GPU-level transforms, when to use, render-groups vs
isRenderGroup.cacheAsTexture - references/scene-management.md: combined view; render groups, , culling, zIndex sorting,
RenderLayer.boundsArea
- references/constructor-options.md：所有派生节点继承的约30个字段（变换、显示、层级、排序、布局、效果、回调），包含默认值、类型以及逐行赋值的适用场景。是所有叶子节点技能的通用参考。
Container - references/container-hierarchy.md：添加/移除/交换子节点、保留变换的重父化、标签导航、销毁子树。
- references/transforms.md：位置、缩放、旋转、轴心、原点、倾斜、toGlobal/toLocal、三种矩阵（局部/组/世界）、边界。
- references/masking.md：AlphaMask、StencilMask、ScissorMask、ColorMask、反向遮罩、成本对比。
- references/layers.md：、附加/分离、排序层、层与逻辑父节点拆分。
RenderLayer - references/render-groups.md：、GPU级变换、使用场景、渲染组与
isRenderGroup对比。cacheAsTexture - references/scene-management.md：综合视图；渲染组、、剔除、zIndex排序、
RenderLayer。boundsArea
Common Mistakes
常见错误
[CRITICAL] Adding children to a leaf display object
[关键] 给叶子显示对象添加子节点
Wrong:
ts
const sprite = new Sprite(texture);
sprite.addChild(new Graphics().rect(0, 0, 10, 10).fill(0xff0000));Correct:
ts
const group = new Container();
group.addChild(new Sprite(texture));
group.addChild(new Graphics().rect(0, 0, 10, 10).fill(0xff0000));In v8 leaves (, , , , , , ) technically extend but should not hold children. Adding children to a leaf produces undefined rendering behavior. Wrap the leaf in a when you need grouping.
SpriteGraphicsTextMeshParticleContainerDOMContainerGifSpriteContainerContainer错误示例：
ts
const sprite = new Sprite(texture);
sprite.addChild(new Graphics().rect(0, 0, 10, 10).fill(0xff0000));正确示例：
ts
const group = new Container();
group.addChild(new Sprite(texture));
group.addChild(new Graphics().rect(0, 0, 10, 10).fill(0xff0000));在v8中，叶子节点（、、、、、、）虽然技术上继承自，但不应包含子节点。给叶子节点添加子节点会导致未定义的渲染行为。需要分组时，用包裹叶子节点。
SpriteGraphicsTextMeshParticleContainerDOMContainerGifSpriteContainerContainer[CRITICAL] Referencing DisplayObject
[关键] 引用DisplayObject
Wrong:
ts
import { DisplayObject } from "pixi.js"; // no such export in v8
function moveNode(node: DisplayObject) {
node.x += 1;
}Correct:
ts
import { Container } from "pixi.js";
function moveNode(node: Container) {
node.x += 1;
}DisplayObjectSpriteGraphicsTextMeshContainerContainer错误示例：
ts
import { DisplayObject } from "pixi.js"; // v8中无此导出
function moveNode(node: DisplayObject) {
node.x += 1;
}正确示例：
ts
import { Container } from "pixi.js";
function moveNode(node: Container) {
node.x += 1;
}DisplayObjectSpriteGraphicsTextMeshContainerContainer[HIGH] Forgetting isRenderGroup on large static subtrees
[高风险] 大型静态子树未设置isRenderGroup
Wrong:
ts
const world = new Container();
for (let i = 0; i < 5000; i++) {
world.addChild(new Sprite(texture));
}
app.stage.addChild(world);Correct:
ts
const world = new Container({ isRenderGroup: true });
for (let i = 0; i < 5000; i++) {
world.addChild(new Sprite(texture));
}
app.stage.addChild(world);Without , the renderer recomposes every child's transform against its parents every frame. Marking the subtree as a render group caches transforms and draw state until a child changes, which is essential for large or mostly-static trees.
isRenderGroup: true错误示例：
ts
const world = new Container();
for (let i = 0; i < 5000; i++) {
world.addChild(new Sprite(texture));
}
app.stage.addChild(world);正确示例：
ts
const world = new Container({ isRenderGroup: true });
for (let i = 0; i < 5000; i++) {
world.addChild(new Sprite(texture));
}
app.stage.addChild(world);如果不设置，渲染器每帧都会重新计算每个子节点相对于父节点的变换。将子树标记为渲染组会缓存变换和绘制状态，直到子节点发生变化，这对大型或基本静态的树至关重要。
isRenderGroup: true[HIGH] Treating child.x as world space
[高风险] 将child.x视为世界空间坐标
Wrong:
ts
const enemy = new Container();
enemy.x = 500;
world.addChild(enemy);
world.x = 200;
console.log(enemy.x); // 500 (local), not 700 (world)Correct:
ts
const worldPos = enemy.toGlobal({ x: 0, y: 0 });
console.log(worldPos.x); // 700Container.x/y/scale/rotationtoGlobal(point)getGlobalPosition()x/y错误示例：
ts
const enemy = new Container();
enemy.x = 500;
world.addChild(enemy);
world.x = 200;
console.log(enemy.x); // 500（局部坐标），不是700（世界坐标）正确示例：
ts
const worldPos = enemy.toGlobal({ x: 0, y: 0 });
console.log(worldPos.x); // 700Container.x/y/scale/rotationtoGlobal(point)getGlobalPosition()x/y[MEDIUM] sortableChildren without zIndex
[中风险] 设置sortableChildren但未配置zIndex
Wrong:
ts
const layer = new Container();
layer.sortableChildren = true;
layer.addChild(bg); // no zIndex
layer.addChild(mid); // no zIndex
layer.addChild(fg); // no zIndex
// order is unchanged — all zIndex default to 0Correct:
ts
const layer = new Container();
layer.sortableChildren = true;
bg.zIndex = 0;
mid.zIndex = 10;
fg.zIndex = 20;
layer.addChild(bg, mid, fg);sortableChildrenzIndexzIndex错误示例：
ts
const layer = new Container();
layer.sortableChildren = true;
layer.addChild(bg); // 无zIndex
layer.addChild(mid); // 无zIndex
layer.addChild(fg); // 无zIndex
// 顺序不变——所有zIndex默认值为0正确示例：
ts
const layer = new Container();
layer.sortableChildren = true;
bg.zIndex = 0;
mid.zIndex = 10;
fg.zIndex = 20;
layer.addChild(bg, mid, fg);sortableChildrenzIndexzIndexTooling
工具
The PixiJS Devtools Chrome extension lets you inspect and manipulate a running scene graph in real time. Install it for any non-trivial layout or render-order debugging.
PixiJS Devtools Chrome扩展允许你实时检查和操作运行中的场景图。进行任何非 trivial 的布局或渲染顺序调试时，请安装此扩展。