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. ## 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). ## Migration Checklist: v7 to v8 Work through each category. Each item shows the expected v8 pattern and the v7 pattern that must be replaced. ### 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>()`. ### 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`. ### 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:** | 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: ```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)`. ### 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')`. ### 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))`. ### 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. ### 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. ### 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(); ``` ### 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). ### 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)`