Back to Details

pixijs-migration-v8

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
This skill is a breaking-change checklist for bringing a v7 codebase up to v8. Work top-down through the categories; the list maps each v7 pattern to its v8 replacement.
本Skill是一份将v7代码库升级到v8的破坏性变更检查清单。按从上到下的顺序处理各个分类；清单将每个v7模式映射到对应的v8替代方案。

Quick Start

快速开始

Install the single package, then port in this order: imports → Application init → Graphics → Text → events → shaders/filters → cleanup.
ts
const app = new Application();
await app.init({ width: 800, height: 600 });
document.body.appendChild(app.canvas);

const g = new Graphics()
  .rect(0, 0, 100, 100)
  .fill({ color: 0xff0000 })
  .stroke({ width: 2, color: 0x000000 });
app.stage.addChild(g);
Related skills: 
pixijs-application
(async init), 
pixijs-scene-graphics
(new fill/stroke API), 
pixijs-custom-rendering
(shader rework), 
pixijs-scene-text
(Text constructor changes), 
pixijs-performance
(destroy patterns).
安装单一包，然后按以下顺序迁移：导入 → Application初始化 → Graphics → Text → 事件 → 着色器/滤镜 → 清理。
ts
const app = new Application();
await app.init({ width: 800, height: 600 });
document.body.appendChild(app.canvas);

const g = new Graphics()
  .rect(0, 0, 100, 100)
  .fill({ color: 0xff0000 })
  .stroke({ width: 2, color: 0x000000 });
app.stage.addChild(g);
相关Skill： 
pixijs-application
（异步初始化）、
pixijs-scene-graphics
（新的填充/描边API）、
pixijs-custom-rendering
（着色器重构）、
pixijs-scene-text
（Text构造函数变更）、
pixijs-performance
（销毁模式）。

Migration Checklist: v7 to v8

迁移检查清单：v7 到 v8

Work through each category. Each item shows the expected v8 pattern and the v7 pattern that must be replaced.
逐个处理每个分类。每个条目展示了预期的v8模式以及必须替换的v7模式。

Initialization

初始化

Async app.init() -- Expected:
ts
const app = new Application();
await app.init({ width: 800, height: 600 });
document.body.appendChild(app.canvas);
Fail: passing options to 
new Application({...})
and using synchronously.
app.canvas replaces app.view -- 
app.view
emits a deprecation warning.
Application type parameter -- Expected: 
new Application<Renderer<HTMLCanvasElement>>()
. Fail: 
new Application<HTMLCanvasElement>()
.
异步app.init() -- 预期写法：
ts
const app = new Application();
await app.init({ width: 800, height: 600 });
document.body.appendChild(app.canvas);
错误写法：将选项传入
new Application({...})
并同步使用。
app.canvas替代app.view -- 
app.view
会触发弃用警告。
Application类型参数 -- 预期写法：
new Application<Renderer<HTMLCanvasElement>>()
。错误写法：
new Application<HTMLCanvasElement>()
。

Imports

导入

Single package -- Expected:
ts
import { Sprite, Application, Assets, Graphics } from "pixi.js";
Fail: importing from any of the deprecated v7 core 
@pixi/*
sub-packages (see list below). Supplemental packages like 
@pixi/sound
are still valid and should continue to be used.
Deprecated 
@pixi/*
packages (never use, any version): 
@pixi/accessibility
, 
@pixi/app
, 
@pixi/assets
, 
@pixi/compressed-textures
, 
@pixi/core
, 
@pixi/display
, 
@pixi/events
, 
@pixi/extensions
, 
@pixi/extract
, 
@pixi/filter-alpha
, 
@pixi/filter-blur
, 
@pixi/filter-color-matrix
, 
@pixi/filter-displacement
, 
@pixi/filter-fxaa
, 
@pixi/filter-noise
, 
@pixi/graphics
, 
@pixi/mesh
, 
@pixi/mesh-extras
, 
@pixi/mixin-cache-as-bitmap
, 
@pixi/mixin-get-child-by-name
, 
@pixi/mixin-get-global-position
, 
@pixi/particle-container
, 
@pixi/prepare
, 
@pixi/sprite
, 
@pixi/sprite-animated
, 
@pixi/sprite-tiling
, 
@pixi/spritesheet
, 
@pixi/text
, 
@pixi/text-bitmap
, 
@pixi/text-html
.
Custom builds -- Set 
skipExtensionImports: true
and import only needed extensions:
ts
import "pixi.js/graphics";
import "pixi.js/text";
import "pixi.js/events";
import { Application } from "pixi.js";
await app.init({ skipExtensionImports: true });
Note: 
manageImports: false
is still accepted but 
@deprecated since 8.1.6
; prefer 
skipExtensionImports: true
.
Extensions not auto-imported (require explicit import even with default auto-imports enabled): 
pixi.js/advanced-blend-modes
, 
pixi.js/unsafe-eval
, 
pixi.js/prepare
, 
pixi.js/math-extras
, 
pixi.js/dds
, 
pixi.js/ktx
, 
pixi.js/ktx2
, 
pixi.js/basis
.
Community filters -- Expected: 
import { AdjustmentFilter } from 'pixi-filters/adjustment'
. Fail: 
@pixi/filter-adjustment
.
单一包 -- 预期写法：
ts
import { Sprite, Application, Assets, Graphics } from "pixi.js";
错误写法：从任何已弃用的v7核心
@pixi/*
子包导入（见下方列表）。
@pixi/sound
等补充包仍然有效，可继续使用。
已弃用的
@pixi/*
包（任何版本均禁止使用）： 
@pixi/accessibility
, 
@pixi/app
, 
@pixi/assets
, 
@pixi/compressed-textures
, 
@pixi/core
, 
@pixi/display
, 
@pixi/events
, 
@pixi/extensions
, 
@pixi/extract
, 
@pixi/filter-alpha
, 
@pixi/filter-blur
, 
@pixi/filter-color-matrix
, 
@pixi/filter-displacement
, 
@pixi/filter-fxaa
, 
@pixi/filter-noise
, 
@pixi/graphics
, 
@pixi/mesh
, 
@pixi/mesh-extras
, 
@pixi/mixin-cache-as-bitmap
, 
@pixi/mixin-get-child-by-name
, 
@pixi/mixin-get-global-position
, 
@pixi/particle-container
, 
@pixi/prepare
, 
@pixi/sprite
, 
@pixi/sprite-animated
, 
@pixi/sprite-tiling
, 
@pixi/spritesheet
, 
@pixi/text
, 
@pixi/text-bitmap
, 
@pixi/text-html
。
自定义构建 -- 设置
skipExtensionImports: true
并仅导入所需扩展：
ts
import "pixi.js/graphics";
import "pixi.js/text";
import "pixi.js/events";
import { Application } from "pixi.js";
await app.init({ skipExtensionImports: true });
注意：
manageImports: false
仍可接受，但
@deprecated since 8.1.6
；优先使用
skipExtensionImports: true
。
不会自动导入的扩展（即使启用默认自动导入，也需要显式导入）： 
pixi.js/advanced-blend-modes
, 
pixi.js/unsafe-eval
, 
pixi.js/prepare
, 
pixi.js/math-extras
, 
pixi.js/dds
, 
pixi.js/ktx
, 
pixi.js/ktx2
, 
pixi.js/basis
。
社区滤镜 -- 预期写法：
import { AdjustmentFilter } from 'pixi-filters/adjustment'
。错误写法：
@pixi/filter-adjustment
。

Graphics API

Graphics API

Shape-then-fill -- Expected:
ts
const g = new Graphics().rect(50, 50, 100, 100).fill(0xff0000);
Fail: 
beginFill(0xff0000).drawRect(50, 50, 100, 100).endFill()
.
Renamed shape methods:
v7v8
drawRect
rect
drawCircle
circle
drawEllipse
ellipse
drawPolygon
poly
drawRoundedRect
roundRect
drawStar
star
drawRegularPolygon
regularPoly
drawRoundedPolygon
roundPoly
drawRoundedShape
roundShape
drawChamferRect
chamferRect
drawFilletRect
filletRect
Fill replaces beginFill/beginTextureFill -- Expected:
ts
graphics
  .rect(0, 0, 100, 100)
  .fill({ texture: Texture.WHITE, alpha: 0.5, color: 0xff0000 });
Fail: 
beginFill(color, alpha)
or 
beginTextureFill({ texture, alpha, color })
.
Stroke replaces lineStyle -- Expected:
ts
graphics.rect(0, 0, 100, 100).fill("blue").stroke({ width: 2, color: "white" });
Fail: 
lineStyle(2, 'white')
or 
lineTextureStyle({ texture, width, color })
.
Holes use cut() -- Expected:
ts
graphics.rect(0, 0, 100, 100).fill(0x00ff00).circle(50, 50, 20).cut();
Fail: 
beginHole()
/ 
endHole()
.
GraphicsContext replaces GraphicsGeometry -- Expected:
ts
const context = new GraphicsContext().rect(0, 0, 100, 100).fill(0xff0000);
const g1 = new Graphics(context);
const g2 = new Graphics(context);
Fail: 
new Graphics(graphics.geometry)
.
先绘形状再填充 -- 预期写法：
ts
const g = new Graphics().rect(50, 50, 100, 100).fill(0xff0000);
错误写法：
beginFill(0xff0000).drawRect(50, 50, 100, 100).endFill()
。
重命名的形状方法：
v7v8
drawRect
rect
drawCircle
circle
drawEllipse
ellipse
drawPolygon
poly
drawRoundedRect
roundRect
drawStar
star
drawRegularPolygon
regularPoly
drawRoundedPolygon
roundPoly
drawRoundedShape
roundShape
drawChamferRect
chamferRect
drawFilletRect
filletRect
Fill替代beginFill/beginTextureFill -- 预期写法：
ts
graphics
  .rect(0, 0, 100, 100)
  .fill({ texture: Texture.WHITE, alpha: 0.5, color: 0xff0000 });
错误写法：
beginFill(color, alpha)
或
beginTextureFill({ texture, alpha, color })
。
Stroke替代lineStyle -- 预期写法：
ts
graphics.rect(0, 0, 100, 100).fill("blue").stroke({ width: 2, color: "white" });
错误写法：
lineStyle(2, 'white')
或
lineTextureStyle({ texture, width, color })
。
使用cut()绘制孔洞 -- 预期写法：
ts
graphics.rect(0, 0, 100, 100).fill(0x00ff00).circle(50, 50, 20).cut();
错误写法：
beginHole()
/ 
endHole()
。
GraphicsContext替代GraphicsGeometry -- 预期写法：
ts
const context = new GraphicsContext().rect(0, 0, 100, 100).fill(0xff0000);
const g1 = new Graphics(context);
const g2 = new Graphics(context);
错误写法：
new Graphics(graphics.geometry)
。

Text

Text

Options object constructor -- Expected:
ts
const text = new Text({ text: "Hello", style: { fontSize: 24 } });
const bmp = new BitmapText({ text: "Hello", style: { fontFamily: "MyFont" } });
const html = new HTMLText({ text: "<b>Hello</b>", style: { fontSize: 24 } });
Fail: 
new Text('Hello', { fontSize: 24 })
(positional args).
Bitmap font loading -- Must 
import 'pixi.js/text-bitmap'
before 
Assets.load('font.fnt')
.
选项对象构造函数 -- 预期写法：
ts
const text = new Text({ text: "Hello", style: { fontSize: 24 } });
const bmp = new BitmapText({ text: "Hello", style: { fontFamily: "MyFont" } });
const html = new HTMLText({ text: "<b>Hello</b>", style: { fontSize: 24 } });
错误写法：
new Text('Hello', { fontSize: 24 })
（位置参数）。
位图字体加载 -- 必须在
Assets.load('font.fnt')
之前导入
'pixi.js/text-bitmap'
。

Sprites / Mesh

精灵 / 网格

Texture.from no longer loads URLs -- Must call 
await Assets.load('image.png')
first, then 
Texture.from('image.png')
.
NineSliceSprite replaces NineSlicePlane -- Expected:
ts
const ns = new NineSliceSprite({
  texture,
  leftWidth: 10,
  topHeight: 10,
  rightWidth: 10,
  bottomHeight: 10,
});
Mesh renames: 
SimpleMesh
-> 
MeshSimple
, 
SimplePlane
-> 
MeshPlane
, 
SimpleRope
-> 
MeshRope
. All use options objects.
MeshGeometry options -- Expected:
ts
const geom = new MeshGeometry({
  positions: vertices,
  uvs,
  indices,
  topology: "triangle-list",
});
Fail: 
new MeshGeometry(vertices, uvs, indices)
.
ParticleContainer uses Particle -- Expected:
ts
const container = new ParticleContainer({
  boundsArea: new Rectangle(0, 0, 800, 600),
});
const particle = new Particle(texture);
container.addParticle(particle);
Fail: 
container.addChild(new Sprite(texture))
.
Texture.from不再加载URL -- 必须先调用
await Assets.load('image.png')
，再调用
Texture.from('image.png')
。
NineSliceSprite替代NineSlicePlane -- 预期写法：
ts
const ns = new NineSliceSprite({
  texture,
  leftWidth: 10,
  topHeight: 10,
  rightWidth: 10,
  bottomHeight: 10,
});
Mesh重命名： 
SimpleMesh
-> 
MeshSimple
, 
SimplePlane
-> 
MeshPlane
, 
SimpleRope
-> 
MeshRope
。所有类均使用选项对象。
MeshGeometry选项 -- 预期写法：
ts
const geom = new MeshGeometry({
  positions: vertices,
  uvs,
  indices,
  topology: "triangle-list",
});
错误写法：
new MeshGeometry(vertices, uvs, indices)
。
ParticleContainer使用Particle -- 预期写法：
ts
const container = new ParticleContainer({
  boundsArea: new Rectangle(0, 0, 800, 600),
});
const particle = new Particle(texture);
container.addParticle(particle);
错误写法：
container.addChild(new Sprite(texture))
。

Events

事件

eventMode replaces interactive -- Expected:
ts
sprite.eventMode = "static";
sprite.cursor = "pointer";
sprite.on("pointertap", () => {
  /* handle */
});
Legacy: 
sprite.interactive = true;
(still works as an alias for 
eventMode = 'static'
, but prefer the explicit form).
Default 
eventMode
is 
'passive'
(no events). Must set 
'static'
or 
'dynamic'
explicitly.
Ticker callback -- Expected:
ts
app.ticker.add((ticker) => {
  bunny.rotation += ticker.deltaTime;
});
Broken: 
app.ticker.add((dt) => { bunny.rotation += dt; })
-- compiles but 
dt
is a 
Ticker
object, not a number. Coerces to 
NaN
, silently corrupting rotation.
updateTransform removed -- Use 
this.onRender = this._onRender.bind(this)
in constructor instead.
eventMode替代interactive -- 预期写法：
ts
sprite.eventMode = "static";
sprite.cursor = "pointer";
sprite.on("pointertap", () => {
  /* 处理逻辑 */
});
遗留写法：
sprite.interactive = true;
（仍可作为
eventMode = 'static'
的别名，但推荐使用显式写法）。
默认
eventMode
为
'passive'
（不响应事件）。必须显式设置为
'static'
或
'dynamic'
。
Ticker回调 -- 预期写法：
ts
app.ticker.add((ticker) => {
  bunny.rotation += ticker.deltaTime;
});
错误写法：
app.ticker.add((dt) => { bunny.rotation += dt; })
-- 可以编译，但
dt
是
Ticker
对象而非数字，会被转换为
NaN
，导致旋转值静默损坏。
updateTransform已移除 -- 改为在构造函数中使用
this.onRender = this._onRender.bind(this)
。

Shaders

着色器

Shader.from uses options -- Expected:
ts
const shader = Shader.from({
  gl: { vertex: vertexSrc, fragment: fragmentSrc },
  resources: {
    myUniforms: new UniformGroup({ uTime: { value: 0, type: "f32" } }),
  },
});
Fail: 
Shader.from(vertex, fragment, uniforms)
.
Filter constructor -- Expected:
ts
const filter = new Filter({
  glProgram: GlProgram.from({ fragment, vertex }),
  resources: { filterUniforms: { uTime: { value: 0, type: "f32" } } },
});
Fail: 
new Filter(vertex, fragment, { uTime: 0 })
.
Uniforms require type -- 
new UniformGroup({ uTime: { value: 1, type: 'f32' } })
. Fail: 
new UniformGroup({ uTime: 1 })
.
Textures are resources, not uniforms -- Pass as top-level resource entries (
texture.source
, 
texture.style
), not inside UniformGroup.
Shader.from使用选项 -- 预期写法：
ts
const shader = Shader.from({
  gl: { vertex: vertexSrc, fragment: fragmentSrc },
  resources: {
    myUniforms: new UniformGroup({ uTime: { value: 0, type: "f32" } }),
  },
});
错误写法：
Shader.from(vertex, fragment, uniforms)
。
Filter构造函数 -- 预期写法：
ts
const filter = new Filter({
  glProgram: GlProgram.from({ fragment, vertex }),
  resources: { filterUniforms: { uTime: { value: 0, type: "f32" } } },
});
错误写法：
new Filter(vertex, fragment, { uTime: 0 })
。
Uniforms需要指定类型 -- 
new UniformGroup({ uTime: { value: 1, type: 'f32' } })
。错误写法：
new UniformGroup({ uTime: 1 })
。
纹理是资源而非uniforms -- 作为顶级资源条目传递（
texture.source
, 
texture.style
），而非放在UniformGroup内。

Textures

纹理

Sprite no longer auto-detects texture UV changes -- If you modify a texture's frame after creation, call 
texture.update()
to recalculate UVs, then call 
sprite.onViewUpdate()
to refresh the sprite. Both calls are required in this order. Updating source data (e.g. video textures) is still automatic.
ts
texture.frame.width = texture.frame.width / 2;
texture.update(); // recalculate texture UVs first
sprite.onViewUpdate(); // then refresh the sprite's display
Mipmaps -- 
BaseTexture.mipmap
renamed to 
autoGenerateMipmaps
. For RenderTextures, you must manually update mipmaps:
ts
const rt = RenderTexture.create({
  width: 100,
  height: 100,
  autoGenerateMipmaps: true,
});
renderer.render({ target: rt, container: scene });
rt.source.updateMipmaps();
Sprite不再自动检测纹理UV变化 -- 如果在创建后修改纹理的frame，需先调用
texture.update()
重新计算UV，再调用
sprite.onViewUpdate()
刷新精灵。必须按此顺序调用这两个方法。源数据更新（如视频纹理）仍为自动触发。
ts
texture.frame.width = texture.frame.width / 2;
texture.update(); // 先重新计算纹理UV
sprite.onViewUpdate(); // 再刷新精灵显示
Mipmaps -- 
BaseTexture.mipmap
重命名为
autoGenerateMipmaps
。对于RenderTextures，必须手动更新mipmaps：
ts
const rt = RenderTexture.create({
  width: 100,
  height: 100,
  autoGenerateMipmaps: true,
});
renderer.render({ target: rt, container: scene });
rt.source.updateMipmaps();

Adapters

适配器

DOMAdapter replaces settings.ADAPTER -- Expected:
ts
import { DOMAdapter, WebWorkerAdapter } from "pixi.js";
DOMAdapter.set(WebWorkerAdapter);
DOMAdapter.get().createCanvas();
Fail: 
settings.ADAPTER = WebWorkerAdapter; settings.ADAPTER.createCanvas();
.
Built-in adapters: 
BrowserAdapter
(default), 
WebWorkerAdapter
(for web workers).
DOMAdapter替代settings.ADAPTER -- 预期写法：
ts
import { DOMAdapter, WebWorkerAdapter } from "pixi.js";
DOMAdapter.set(WebWorkerAdapter);
DOMAdapter.get().createCanvas();
错误写法：
settings.ADAPTER = WebWorkerAdapter; settings.ADAPTER.createCanvas();
。
内置适配器：
BrowserAdapter
（默认）、
WebWorkerAdapter
（用于Web Worker）。

Other

其他

DisplayObject removed -- 
Container
is the base class. 
class MyObj extends DisplayObject
fails.
Leaf nodes cannot have children -- 
Sprite
, 
Graphics
, 
Mesh
, 
Text
are leaf nodes. Wrap in 
Container
.
Renamed properties (old names still exist as deprecated aliases with warnings):
  • container.name
    -> 
    container.label
  • container.cacheAsBitmap = true
    -> 
    container.cacheAsTexture(true)
getBounds() return type changed: 
getBounds()
now returns a 
Bounds
object, not a 
Rectangle
. 
Bounds
has 
.x
, 
.y
, 
.width
, 
.height
getters, so basic usage works. Use 
.rectangle
when you need a 
Rectangle
instance (e.g., for 
.contains()
).
settings object removed -- Use 
AbstractRenderer.defaultOptions.resolution = 1
and 
DOMAdapter.set(BrowserAdapter)
.
utils namespace removed -- 
import { isMobile } from 'pixi.js'
instead of 
utils.isMobile
.
Text parser renames:
  • TextFormat
    -> 
    bitmapFontTextParser
  • XMLStringFormat
    -> 
    bitmapFontXMLStringParser
  • XMLFormat
    -> 
    bitmapFontXMLParser
Assets.add -- 
Assets.add({ alias: 'bunny', src: 'bunny.png' })
. Fail: 
Assets.add('bunny', 'bunny.png')
.
Enum constants replaced with strings:
v7v8
SCALE_MODES.NEAREST
'nearest'
SCALE_MODES.LINEAR
'linear'
WRAP_MODES.CLAMP
'clamp-to-edge'
WRAP_MODES.REPEAT
'repeat'
WRAP_MODES.MIRRORED_REPEAT
'mirror-repeat'
DRAW_MODES.TRIANGLES
'triangle-list'
DRAW_MODES.TRIANGLE_STRIP
'triangle-strip'
DRAW_MODES.LINES
'line-list'
DRAW_MODES.LINE_STRIP
'line-strip'
DRAW_MODES.POINTS
'point-list'
Culling is manual -- Set 
cullable = true
, then call 
Culler.shared.cull(container, viewRect)
before render. Or add 
CullerPlugin
via 
extensions.add(CullerPlugin)
.
DisplayObject已移除 -- 
Container
是基类。
class MyObj extends DisplayObject
会报错。
叶子节点不能包含子节点 -- 
Sprite
、
Graphics
、
Mesh
、
Text
均为叶子节点，需用
Container
包裹。
重命名的属性（旧名称仍作为已弃用别名存在，会触发警告）：
  • container.name
    -> 
    container.label
  • container.cacheAsBitmap = true
    -> 
    container.cacheAsTexture(true)
getBounds()返回类型变更： 
getBounds()
现在返回
Bounds
对象而非
Rectangle
。
Bounds
拥有
.x
, 
.y
, 
.width
, 
.height
getter，因此基础用法不受影响。当需要
Rectangle
实例时（如调用
.contains()
），使用
.rectangle
属性。
settings对象已移除 -- 使用
AbstractRenderer.defaultOptions.resolution = 1
和
DOMAdapter.set(BrowserAdapter)
。
utils命名空间已移除 -- 使用
import { isMobile } from 'pixi.js'
替代
utils.isMobile
。
文本解析器重命名：
  • TextFormat
    -> 
    bitmapFontTextParser
  • XMLStringFormat
    -> 
    bitmapFontXMLStringParser
  • XMLFormat
    -> 
    bitmapFontXMLParser
Assets.add -- 
Assets.add({ alias: 'bunny', src: 'bunny.png' })
。错误写法：
Assets.add('bunny', 'bunny.png')
。
枚举常量替换为字符串：
v7v8
SCALE_MODES.NEAREST
'nearest'
SCALE_MODES.LINEAR
'linear'
WRAP_MODES.CLAMP
'clamp-to-edge'
WRAP_MODES.REPEAT
'repeat'
WRAP_MODES.MIRRORED_REPEAT
'mirror-repeat'
DRAW_MODES.TRIANGLES
'triangle-list'
DRAW_MODES.TRIANGLE_STRIP
'triangle-strip'
DRAW_MODES.LINES
'line-list'
DRAW_MODES.LINE_STRIP
'line-strip'
DRAW_MODES.POINTS
'point-list'
剔除（Culling）需手动触发 -- 设置
cullable = true
，然后在渲染前调用
Culler.shared.cull(container, viewRect)
。或通过
extensions.add(CullerPlugin)
添加
CullerPlugin
。

Pre-Migration Summary

迁移前检查清单

  • No deprecated v7 core 
    @pixi/*
    packages in dependencies (supplemental packages like 
    @pixi/sound
    are fine)
  • All core 
    @pixi/*
    imports converted to 
    pixi.js
  • All 
    new Application({...})
    converted to 
    await app.init({...})
  • All Graphics code uses shape-then-fill pattern
  • All constructors use options objects (Text, Mesh, NineSliceSprite, etc.)
  • Shader/Filter code uses 
    {gl, resources}
    pattern with typed uniforms
  • ParticleContainer code uses 
    Particle
    , not 
    Sprite
  • Ticker callbacks access 
    ticker.deltaTime
    , not first param as delta
  • Event handling uses 
    eventMode
    instead of 
    interactive
  • settings
    and 
    utils
    references removed
  • DisplayObject
    references replaced with 
    Container
  • Texture UV modifications call 
    sprite.onViewUpdate()
    where needed
  • RenderTexture mipmap code calls 
    source.updateMipmaps()
    manually
  • settings.ADAPTER
    replaced with 
    DOMAdapter.set()
  • 依赖中没有已弃用的v7核心
    @pixi/*
    包（
    @pixi/sound
    等补充包没问题）
  • 所有核心
    @pixi/*
    导入已转换为
    pixi.js
  • 所有
    new Application({...})
    已转换为
    await app.init({...})
  • 所有Graphics代码使用先绘形状再填充的模式
  • 所有构造函数使用选项对象（Text、Mesh、NineSliceSprite等）
  • 着色器/滤镜代码使用带类型uniforms的
    {gl, resources}
    模式
  • ParticleContainer代码使用
    Particle
    而非
    Sprite
  • Ticker回调访问
    ticker.deltaTime
    ，而非将第一个参数视为delta值
  • 事件处理使用
    eventMode
    而非
    interactive
  • 已移除
    settings
    和
    utils
    引用
  • DisplayObject
    引用已替换为
    Container
  • 修改纹理UV时，在需要的地方调用
    sprite.onViewUpdate()
  • RenderTexture mipmap代码手动调用
    source.updateMipmaps()
  • settings.ADAPTER
    已替换为
    DOMAdapter.set()

Common Mistakes

常见错误

[CRITICAL] Importing from deprecated v7 core @pixi/* sub-packages

[CRITICAL] 从已弃用的v7核心@pixi/*子包导入

Wrong:
ts
import { Sprite } from "@pixi/sprite";
import { Application } from "@pixi/app";
Correct:
ts
import { Sprite, Application } from "pixi.js";
v8 uses a single 
pixi.js
package. The v7 core 
@pixi/*
sub-packages are deprecated and must not be used (see the full list under Imports above). Supplemental packages like 
@pixi/sound
are still valid.
错误写法：
ts
import { Sprite } from "@pixi/sprite";
import { Application } from "@pixi/app";
正确写法：
ts
import { Sprite, Application } from "pixi.js";
v8使用单一
pixi.js
包。v7核心
@pixi/*
子包已弃用，禁止使用（见上方导入部分的完整列表）。
@pixi/sound
等补充包仍然有效。

[CRITICAL] Using DisplayObject as base class

[CRITICAL] 使用DisplayObject作为基类

Wrong: 
class MyObject extends DisplayObject { ... }
Correct: 
class MyObject extends Container { ... }
DisplayObject
was removed in v8. 
Container
is the base class for all display objects.
错误写法：
class MyObject extends DisplayObject { ... }
正确写法：
class MyObject extends Container { ... }
DisplayObject
在v8中已被移除。
Container
是所有显示对象的基类。

[HIGH] Using old SCALE_MODES/WRAP_MODES/DRAW_MODES enums

[HIGH] 使用旧的SCALE_MODES/WRAP_MODES/DRAW_MODES枚举

Wrong: 
texture.source.scaleMode = SCALE_MODES.NEAREST;
Correct: 
texture.source.scaleMode = 'nearest';
v8 uses string values. Old enums may work as deprecated aliases but should be replaced.
错误写法：
texture.source.scaleMode = SCALE_MODES.NEAREST;
正确写法：
texture.source.scaleMode = 'nearest';
v8使用字符串值。旧枚举可能仍可作为已弃用别名工作，但应替换为新写法。

[HIGH] Using 
interactive = true
instead of 
eventMode

[HIGH] 使用
interactive = true
而非
eventMode

Legacy: 
sprite.interactive = true;
(still works as an alias for 
eventMode = 'static'
) Preferred: 
sprite.eventMode = 'static';
Default 
eventMode
is 
'passive'
(no events). Must set 
'static'
(hit-testable, no tick checks) or 
'dynamic'
(hit-testable with tick checks) explicitly. 
interactive = true
still works without a deprecation warning, but 
eventMode
is the canonical v8 API.
遗留写法：
sprite.interactive = true;
（仍可作为
eventMode = 'static'
的别名） 推荐写法：
sprite.eventMode = 'static';
默认
eventMode
为
'passive'
（不响应事件）。必须显式设置为
'static'
（可命中测试，无tick检查）或
'dynamic'
（可命中测试，带tick检查）。
interactive = true
仍可正常使用且无弃用警告，但
eventMode
是v8的标准API。

[HIGH] Using utils namespace

[HIGH] 使用utils命名空间

Wrong: 
import { utils } from 'pixi.js'; utils.isMobile.any();
Correct: 
import { isMobile } from 'pixi.js'; isMobile.any();
The 
utils
namespace was removed. All utility functions are direct imports.
错误写法：
import { utils } from 'pixi.js'; utils.isMobile.any();
正确写法：
import { isMobile } from 'pixi.js'; isMobile.any();
utils
命名空间已被移除。所有工具函数均为直接导入。

[HIGH] Expecting texture UV changes to auto-update sprites

[HIGH] 认为纹理UV变化会自动更新精灵

Wrong: modifying 
texture.frame
and assuming the sprite updates automatically. Correct: call 
sprite.onViewUpdate()
after modifying texture UVs.
Sprites no longer subscribe to texture UV change events for performance. Source data updates (e.g. video) still auto-reflect.
错误写法：修改
texture.frame
并假设精灵会自动更新。 正确写法：修改纹理UV后调用
sprite.onViewUpdate()
。
为提升性能，精灵不再订阅纹理UV变化事件。源数据更新（如视频）仍会自动反映到精灵上。

API Reference

API参考