OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add pixijs/pixijs-skills --skill pixijs-migration-v8
Use this skill when upgrading to PixiJS v8 from v7 or diagnosing broken v7 code after an upgrade. Covers async app.init, single pixi.js package (deprecated @pixi/* sub-packages), Graphics shape-then-fill, BaseTexture → TextureSource, shader/uniform rework, ParticleContainer+Particle, constructor options objects, DisplayObject removal, settings/utils removal, Ticker signature, events rewrite. Triggers on: migrate v7, v8 breaking changes, @pixi/ import, DisplayObject, beginFill, endFill, cacheAsBitmap, BaseTexture, deprecated.
npx skills add pixijs/pixijs-skills --skill pixijs-migration-v8
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.
Install the single package, then port in this order: imports → Application init → Graphics → Text → events → shaders/filters → cleanup.
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).
Work through each category. Each item shows the expected v8 pattern and the v7 pattern that must be replaced.
Async app.init() -- Expected:
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>().
Single package -- Expected:
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:
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.
Shape-then-fill -- Expected:
Fail: beginFill(0xff0000).drawRect(50, 50, 100, 100).endFill().
Renamed shape methods:
| v7 | v8 |
|---|---|
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:
Fail: beginFill(color, alpha) or beginTextureFill({ texture, alpha, color }).
Stroke replaces lineStyle -- Expected:
Fail: lineStyle(2, 'white') or lineTextureStyle({ texture, width, color }).
Holes use cut() -- Expected:
Fail: beginHole() / endHole().
GraphicsContext replaces GraphicsGeometry -- Expected:
Fail: new Graphics(graphics.geometry).
Options object constructor -- Expected:
Fail: new Text('Hello', { fontSize: 24 }) (positional args).
Bitmap font loading -- Must import 'pixi.js/text-bitmap' before Assets.load('font.fnt').
Texture.from no longer loads URLs -- Must call await Assets.load('image.png') first, then Texture.from('image.png').
NineSliceSprite replaces NineSlicePlane -- Expected:
Mesh renames: SimpleMesh -> MeshSimple, SimplePlane -> MeshPlane, SimpleRope -> MeshRope. All use options objects.
MeshGeometry options -- Expected:
Fail: new MeshGeometry(vertices, uvs, indices).
ParticleContainer uses Particle -- Expected:
Fail: container.addChild(new Sprite(texture)).
eventMode replaces interactive -- Expected:
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:
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.
Shader.from uses options -- Expected:
Fail: Shader.from(vertex, fragment, uniforms).
Filter constructor -- Expected:
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.
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.
Mipmaps -- BaseTexture.mipmap renamed to autoGenerateMipmaps. For RenderTextures, you must manually update mipmaps:
DOMAdapter replaces settings.ADAPTER -- Expected:
Fail: settings.ADAPTER = WebWorkerAdapter; settings.ADAPTER.createCanvas();.
Built-in adapters: BrowserAdapter (default), WebWorkerAdapter (for web workers).
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.labelcontainer.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 -> bitmapFontTextParserXMLStringFormat -> bitmapFontXMLStringParserXMLFormat -> bitmapFontXMLParserAssets.add -- Assets.add({ alias: 'bunny', src: 'bunny.png' }). Fail: Assets.add('bunny', 'bunny.png').
Enum constants replaced with strings:
| v7 | v8 |
|---|---|
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).
@pixi/* packages in dependencies (supplemental packages like @pixi/sound are fine)@pixi/* imports converted to pixi.jsnew Application({...}) converted to await app.init({...}){gl, resources} pattern with typed uniformsParticle, not Spriteticker.deltaTime, not first param as deltaeventMode instead of interactivesettings and utils references removedDisplayObject references replaced with Containersprite.onViewUpdate() where neededsource.updateMipmaps() manuallysettings.ADAPTER replaced with DOMAdapter.set()Wrong:
Correct:
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.
Wrong: class MyObject extends DisplayObject { ... }
Correct: class MyObject extends Container { ... }
DisplayObject was removed in v8. Container is the base class for all display objects.
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.
interactive = true instead of eventModeLegacy: 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.
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.
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.
const app = new Application();
await app.init({ width: 800, height: 600 });
document.body.appendChild(app.canvas);import { Sprite, Application, Assets, Graphics } from "pixi.js";import "pixi.js/graphics";
import "pixi.js/text";
import "pixi.js/events";
import { Application } from "pixi.js";
await app.init({ skipExtensionImports: true });const g = new Graphics().rect(50, 50, 100, 100).fill(0xff0000);graphics
.rect(0, 0, 100, 100)
.fill({ texture: Texture.WHITE, alpha: 0.5, color: 0xff0000 });graphics.rect(0, 0, 100, 100).fill("blue").stroke({ width: 2, color: "white" });graphics.rect(0, 0, 100, 100).fill(0x00ff00).circle(50, 50, 20).cut();const context = new GraphicsContext().rect(0, 0, 100, 100).fill(0xff0000);
const g1 = new Graphics(context);
const g2 = new Graphics(context);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 } });const ns = new NineSliceSprite({
texture,
leftWidth: 10,
topHeight: 10,
rightWidth: 10,
bottomHeight: 10,
});const geom = new MeshGeometry({
positions: vertices,
uvs,
indices,
topology: "triangle-list",
});const container = new ParticleContainer({
boundsArea: new Rectangle(0, 0, 800, 600),
});
const particle = new Particle(texture);
container.addParticle(particle);sprite.eventMode = "static";
sprite.cursor = "pointer";
sprite.on("pointertap", () => {
/* handle */
});app.ticker.add((ticker) => {
bunny.rotation += ticker.deltaTime;
});const shader = Shader.from({
gl: { vertex: vertexSrc, fragment: fragmentSrc },
resources: {
myUniforms: new UniformGroup({ uTime: { value: 0, type: "f32" } }),
},
});const filter = new Filter({
glProgram: GlProgram.from({ fragment, vertex }),
resources: { filterUniforms: { uTime: { value: 0, type: "f32" } } },
});texture.frame.width = texture.frame.width / 2;
texture.update(); // recalculate texture UVs first
sprite.onViewUpdate(); // then refresh the sprite's displayconst rt = RenderTexture.create({
width: 100,
height: 100,
autoGenerateMipmaps: true,
});
renderer.render({ target: rt, container: scene });
rt.source.updateMipmaps();import { DOMAdapter, WebWorkerAdapter } from "pixi.js";
DOMAdapter.set(WebWorkerAdapter);
DOMAdapter.get().createCanvas();import { Sprite } from "@pixi/sprite";
import { Application } from "@pixi/app";import { Sprite, Application } from "pixi.js";