pixijs-migration-v8

Cette compétence est une liste de contrôle des changements majeurs pour porter une base de code v7 vers v8. Travaillez de haut en bas à travers les catégories ; la liste associe chaque motif v7 à son remplacement v8.

Quick Start

Installez le package unique, puis portez dans cet ordre : imports → Application init → Graphics → Text → events → shaders/filters → cleanup.

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);

Compétences associées : pixijs-application (async init), pixijs-scene-graphics (nouvelle API fill/stroke), pixijs-custom-rendering (refonte des shaders), pixijs-scene-text (changements du constructeur Text), pixijs-performance (motifs destroy).

Migration Checklist : v7 vers v8

Travaillez à travers chaque catégorie. Chaque élément montre le motif v8 attendu et le motif v7 qui doit être remplacé.

Initialization

Async app.init() -- Attendu :

const app = new Application();
await app.init({ width: 800, height: 600 });
document.body.appendChild(app.canvas);

Échoue : passer des options à new Application({...}) et l'utiliser de manière synchrone.

app.canvas remplace app.view -- app.view émet un avertissement de dépréciation.

Paramètre de type Application -- Attendu : new Application<Renderer<HTMLCanvasElement>>(). Échoue : new Application<HTMLCanvasElement>().

Imports

Package unique -- Attendu :

import { Sprite, Application, Assets, Graphics } from "pixi.js";

Échoue : importer depuis l'un des sous-packages v7 core dépréciés @pixi/* (voir la liste ci-dessous). Les packages supplémentaires comme @pixi/sound sont toujours valides et doivent continuer à être utilisés.

Packages dépréciés @pixi/* (à ne jamais utiliser, dans n'importe quelle 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.

Builds personnalisés -- Définissez skipExtensionImports: true et importez uniquement les extensions nécessaires :

import "pixi.js/graphics";
import "pixi.js/text";
import "pixi.js/events";
import { Application } from "pixi.js";
await app.init({ skipExtensionImports: true });

Remarque : manageImports: false est toujours accepté mais @deprecated since 8.1.6 ; préférez skipExtensionImports: true.

Extensions non auto-importées (nécessitent un import explicite même avec les auto-imports par défaut activés) : 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.

Filtres communautaires -- Attendu : import { AdjustmentFilter } from 'pixi-filters/adjustment'. Échoue : @pixi/filter-adjustment.

Graphics API

Shape-then-fill -- Attendu :

const g = new Graphics().rect(50, 50, 100, 100).fill(0xff0000);

Échoue : beginFill(0xff0000).drawRect(50, 50, 100, 100).endFill().

Méthodes de forme renommées :

Fill remplace beginFill/beginTextureFill -- Attendu :

graphics
  .rect(0, 0, 100, 100)
  .fill({ texture: Texture.WHITE, alpha: 0.5, color: 0xff0000 });

Échoue : beginFill(color, alpha) ou beginTextureFill({ texture, alpha, color }).

Stroke remplace lineStyle -- Attendu :

graphics.rect(0, 0, 100, 100).fill("blue").stroke({ width: 2, color: "white" });

Échoue : lineStyle(2, 'white') ou lineTextureStyle({ texture, width, color }).

Les trous utilisent cut() -- Attendu :

graphics.rect(0, 0, 100, 100).fill(0x00ff00).circle(50, 50, 20).cut();

Échoue : beginHole() / endHole().

GraphicsContext remplace GraphicsGeometry -- Attendu :

const context = new GraphicsContext().rect(0, 0, 100, 100).fill(0xff0000);
const g1 = new Graphics(context);
const g2 = new Graphics(context);

Échoue : new Graphics(graphics.geometry).

Text

Constructeur avec objet options -- Attendu :

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 } });

Échoue : new Text('Hello', { fontSize: 24 }) (arguments positionnels).

Chargement de polices bitmap -- Doit import 'pixi.js/text-bitmap' avant Assets.load('font.fnt').

Sprites / Mesh

Texture.from ne charge plus les URLs -- Doit d'abord appeler await Assets.load('image.png'), puis Texture.from('image.png').

NineSliceSprite remplace NineSlicePlane -- Attendu :

const ns = new NineSliceSprite({
  texture,
  leftWidth: 10,
  topHeight: 10,
  rightWidth: 10,
  bottomHeight: 10,
});

Renommages Mesh : SimpleMesh -> MeshSimple, SimplePlane -> MeshPlane, SimpleRope -> MeshRope. Tous utilisent des objets options.

Options MeshGeometry -- Attendu :

const geom = new MeshGeometry({
  positions: vertices,
  uvs,
  indices,
  topology: "triangle-list",
});

Échoue : new MeshGeometry(vertices, uvs, indices).

ParticleContainer utilise Particle -- Attendu :

const container = new ParticleContainer({
  boundsArea: new Rectangle(0, 0, 800, 600),
});
const particle = new Particle(texture);
container.addParticle(particle);

Échoue : container.addChild(new Sprite(texture)).

Events

eventMode remplace interactive -- Attendu :

sprite.eventMode = "static";
sprite.cursor = "pointer";
sprite.on("pointertap", () => {
  /* handle */
});

Héritage : sprite.interactive = true; (fonctionne toujours comme alias pour eventMode = 'static', mais préférez la forme explicite).

eventMode par défaut est 'passive' (pas d'événements). Doit être défini explicitement à 'static' ou 'dynamic'.

Callback Ticker -- Attendu :

app.ticker.add((ticker) => {
  bunny.rotation += ticker.deltaTime;
});

Rompu : app.ticker.add((dt) => { bunny.rotation += dt; }) -- compile mais dt est un objet Ticker, pas un nombre. Fait une coercition en NaN, corrompant silencieusement la rotation.

updateTransform supprimé -- Utilisez this.onRender = this._onRender.bind(this) dans le constructeur à la place.

Shaders

Shader.from utilise les options -- Attendu :

const shader = Shader.from({
  gl: { vertex: vertexSrc, fragment: fragmentSrc },
  resources: {
    myUniforms: new UniformGroup({ uTime: { value: 0, type: "f32" } }),
  },
});

Échoue : Shader.from(vertex, fragment, uniforms).

Constructeur Filter -- Attendu :

const filter = new Filter({
  glProgram: GlProgram.from({ fragment, vertex }),
  resources: { filterUniforms: { uTime: { value: 0, type: "f32" } } },
});

Échoue : new Filter(vertex, fragment, { uTime: 0 }).

Les uniforms nécessitent un type -- new UniformGroup({ uTime: { value: 1, type: 'f32' } }). Échoue : new UniformGroup({ uTime: 1 }).

Les textures sont des ressources, pas des uniforms -- Passez comme entrées de ressources au niveau supérieur (texture.source, texture.style), pas à l'intérieur d'UniformGroup.

Textures

Sprite ne détecte plus automatiquement les changements de texture UV -- Si vous modifiez le frame d'une texture après sa création, appelez texture.update() pour recalculer les UVs, puis appelez sprite.onViewUpdate() pour rafraîchir le sprite. Les deux appels sont nécessaires dans cet ordre. La mise à jour des données source (par exemple les textures vidéo) reste automatique.

texture.frame.width = texture.frame.width / 2;
texture.update(); // recalculer les UVs de la texture en premier
sprite.onViewUpdate(); // puis rafraîchir l'affichage du sprite

Mipmaps -- BaseTexture.mipmap renommé en autoGenerateMipmaps. Pour les RenderTextures, vous devez mettre à jour manuellement les mipmaps :

const rt = RenderTexture.create({
  width: 100,
  height: 100,
  autoGenerateMipmaps: true,
});
renderer.render({ target: rt, container: scene });
rt.source.updateMipmaps();

Adapters

DOMAdapter remplace settings.ADAPTER -- Attendu :

import { DOMAdapter, WebWorkerAdapter } from "pixi.js";
DOMAdapter.set(WebWorkerAdapter);
DOMAdapter.get().createCanvas();

Échoue : settings.ADAPTER = WebWorkerAdapter; settings.ADAPTER.createCanvas();.

Adaptateurs intégrés : BrowserAdapter (par défaut), WebWorkerAdapter (pour les web workers).

Other

DisplayObject supprimé -- Container est la classe de base. class MyObj extends DisplayObject échoue.

Les nœuds feuilles ne peuvent pas avoir d'enfants -- Sprite, Graphics, Mesh, Text sont des nœuds feuilles. Enveloppez dans Container.

Propriétés renommées (les anciens noms existent toujours comme alias dépréciés avec avertissements) :

• container.name -> container.label
• container.cacheAsBitmap = true -> container.cacheAsTexture(true)

Type de retour getBounds() modifié : getBounds() retourne maintenant un objet Bounds, pas un Rectangle. Bounds a des getters .x, .y, .width, .height, donc l'utilisation basique fonctionne. Utilisez .rectangle quand vous avez besoin d'une instance Rectangle (par exemple, pour .contains()).

Objet settings supprimé -- Utilisez AbstractRenderer.defaultOptions.resolution = 1 et DOMAdapter.set(BrowserAdapter).

Namespace utils supprimé -- import { isMobile } from 'pixi.js' au lieu de utils.isMobile.

Renommages du analyseur Text :

• TextFormat -> bitmapFontTextParser
• XMLStringFormat -> bitmapFontXMLStringParser
• XMLFormat -> bitmapFontXMLParser

Assets.add -- Assets.add({ alias: 'bunny', src: 'bunny.png' }). Échoue : Assets.add('bunny', 'bunny.png').

Constantes enum remplacées par des chaînes :

Culling est manuel -- Définissez cullable = true, puis appelez Culler.shared.cull(container, viewRect) avant le rendu. Ou ajoutez CullerPlugin via extensions.add(CullerPlugin).

Résumé avant migration

• [ ] Pas de packages v7 core @pixi/* dépréciés dans les dépendances (les packages supplémentaires comme @pixi/sound vont bien)
• [ ] Tous les imports core @pixi/* convertis en pixi.js
• [ ] Tous les new Application({...}) convertis en await app.init({...})
• [ ] Tout le code Graphics utilise le motif shape-then-fill
• [ ] Tous les constructeurs utilisent des objets options (Text, Mesh, NineSliceSprite, etc.)
• [ ] Le code Shader/Filter utilise le motif {gl, resources} avec uniforms typés
• [ ] Le code ParticleContainer utilise Particle, pas Sprite
• [ ] Les callbacks Ticker accèdent à ticker.deltaTime, pas au premier paramètre comme delta
• [ ] La gestion des événements utilise eventMode au lieu de interactive
• [ ] Les références settings et utils supprimées
• [ ] Les références DisplayObject remplacées par Container
• [ ] Les modifications d'UV de texture appellent sprite.onViewUpdate() si nécessaire
• [ ] Le code RenderTexture mipmap appelle source.updateMipmaps() manuellement
• [ ] settings.ADAPTER remplacé par DOMAdapter.set()

Erreurs courantes

[CRITICAL] Importer depuis les sous-packages v7 core @pixi/* dépréciés

Faux :

import { Sprite } from "@pixi/sprite";
import { Application } from "@pixi/app";

Correct :

import { Sprite, Application } from "pixi.js";

v8 utilise un package unique pixi.js. Les sous-packages v7 core @pixi/* sont dépréciés et ne doivent pas être utilisés (voir la liste complète sous Imports ci-dessus). Les packages supplémentaires comme @pixi/sound sont toujours valides.

[CRITICAL] Utiliser DisplayObject comme classe de base

Faux : class MyObject extends DisplayObject { ... } Correct : class MyObject extends Container { ... }

DisplayObject a été supprimé dans v8. Container est la classe de base pour tous les objets d'affichage.

[HIGH] Utiliser les anciens enums SCALE_MODES/WRAP_MODES/DRAW_MODES

Faux : texture.source.scaleMode = SCALE_MODES.NEAREST; Correct : texture.source.scaleMode = 'nearest';

v8 utilise les valeurs de chaîne. Les anciens enums peuvent fonctionner comme alias dépréciés mais doivent être remplacés.

[HIGH] Utiliser interactive = true au lieu de eventMode

Héritage : sprite.interactive = true; (fonctionne toujours comme alias pour eventMode = 'static') Préféré : sprite.eventMode = 'static';

eventMode par défaut est 'passive' (pas d'événements). Doit être défini explicitement à 'static' (testable au hit, pas de vérifications de tick) ou 'dynamic' (testable au hit avec vérifications de tick). interactive = true fonctionne toujours sans avertissement de dépréciation, mais eventMode est l'API canonique v8.

[HIGH] Utiliser le namespace utils

Faux : import { utils } from 'pixi.js'; utils.isMobile.any(); Correct : import { isMobile } from 'pixi.js'; isMobile.any();

Le namespace utils a été supprimé. Toutes les fonctions utilitaires sont des imports directs.

[HIGH] S'attendre à ce que les changements de texture UV mettent automatiquement à jour les sprites

Faux : modifier texture.frame et supposer que le sprite se met à jour automatiquement. Correct : appeler sprite.onViewUpdate() après modification des UVs de texture.

Les sprites ne s'abonnent plus aux événements de changement d'UV de texture pour des raisons de performance. Les mises à jour de données source (par exemple vidéo) se reflètent toujours automatiquement.

API Reference

• v8 Migration Guide
• v7 Migration Guide
• Application
• Graphics
• Container