v4-new-features

Nouvelles fonctionnalités de Phaser 4

Nouvelles fonctionnalités et capacités de Phaser 4 : Filtres (remplaçant FX/BitmapMask), RenderNodes (remplaçant les pipelines), objets de jeu CaptureFrame, Gradient et Noise, SpriteGPULayer, TilemapGPULayer, composant Lighting, RenderSteps et nouveaux modes de teinte.

Compétences associées :../v3-to-v4-migration/SKILL.md, ../filters-and-postfx/SKILL.md, ../game-object-components/SKILL.md, ../tilemaps/SKILL.md

Vous effectuez une migration depuis la v3 ? Consultez le Guide de migration de la v3 vers la v4 pour connaître les modifications de code étape par étape, les API supprimées et obtenir une liste de contrôle pour la migration.

Présentation : ce qui a changé dans la v4

Phaser 4 est une refonte complète du moteur de rendu WebGL. Le moteur de rendu v3 permettait à chaque sous-système de gérer l’état WebGL de manière indépendante, ce qui entraînait des conflits (par exemple, certains effets visuels perturbaient les masques). La v4 centralise la gestion de l’état WebGL via un graphe RenderNode, dans lequel chaque nœud gère exactement une tâche de rendu.

Principales suppressions

Principaux ajouts

• Nouveaux GameObjects: CaptureFrame, Gradient, Noise, NoiseCell2D/3D/4D, NoiseSimplex2D/3D, SpriteGPULayer, Stamp, TilemapGPULayer
• Nouveaux composants: Lighting, RenderSteps, RenderNodes
• Nouveaux modes de teinte: MULTIPLY, FILL, ADD, SCREEN, OVERLAY, HARD_LIGHT
• Nouveaux filtres: Blend, Blocky, CombineColorMatrix, GradientMap, ImageLight, Key, Mask, NormalTools, PanoramaBlur, ParallelFilters, Quantize, Sampler, Threshold
• Orientation GL: la v4 utilise l'orientation GL standard (Y=0 en bas pour les textures)

Système de filtres (remplaçant FX et BitmapMask)

Référence complète : filters-and-postfx.md

Les filtres unifient les systèmes FX et Mask de la v3. Chaque filtre prend une image en entrée et produit une image en sortie via un passage de shader. Les filtres peuvent être appliqués à n’importe quel objet de jeu ou caméra — la v3 imposait des restrictions quant aux objets prenant en charge les effets FX.

// Approche v3 (FX) :
sprite.preFX.addGlow(0xff00ff, 4);
sprite.postFX.addBlur(0, 2, 2, 1);// Approche v4 (filtres) :
sprite.enableFilters();
sprite.filters.internal.addGlow(0xff00ff, 4, 0, 1);
sprite.filters.external.addBlur(0, 2, 2, 1);// Approche v3 (BitmapMask) :
const mask = new Phaser.Display.Masks.BitmapMask(scene, maskImage);
sprite.setMask(mask);// Approche v4 (FilterMask) :
sprite.enableFilters();
sprite.filters.internal.addMask(maskImage);

Filtres internes vs externes: les filtres internes s’exécutent avant la transformation de la caméra (espace local à l’objet, moins coûteux). Les filtres externes s’exécutent après (espace écran, pleine résolution).

RenderNodes (remplacement des pipelines)

Dans la v3, un pipeline était un système de rendu qui assumait souvent plusieurs responsabilités. Dans la v4, chaque RenderNode gère une seule tâche de rendu via sa méthode run(). Certains nœuds disposent également d’une méthode batch() permettant d’accumuler l’état avant le dessin.

Architecture

Le RenderNodeManager (sur le moteur de rendu WebGL) gère tous les nœuds de rendu. Les objets de jeu font référence aux nœuds via des mappages basés sur les rôles.

// Rôles des RenderNodes sur un objet de jeu :
// - « Submitter » : exécute les autres rôles de nœuds pour chaque élément
// - « Transformer » : fournit les coordonnées des sommets
// - « Texturer » : gère les textures// Les GameObjects disposent de mappages de nœuds de rendu par défaut et personnalisés :
gameObject.defaultRenderNodes  // nœuds intégrés par rôle
gameObject.customRenderNodes   // remplacements par rôle
gameObject.renderNodeData      // données indexées par nom de nœud

Configuration de nœuds de rendu personnalisés

// Remplacer un rôle de rendu spécifique :
gameObject.setRenderNodeRole('Submitter', 'MyCustomSubmitter');// Transmettre des données à un nœud de rendu :
gameObject.setRenderNodeRole('Transformer', 'MyTransformer', {
    customProperty: 42
});// Supprimer un nœud personnalisé (retour à la valeur par défaut) :
gameObject.setRenderNodeRole('Submitter', null);

Types de nœuds de rendu intégrés

Gestionnaires de lots (accumulent et dessinent plusieurs objets par appel de dessin) :

• BatchHandlerQuad -- regroupement standard de quadrilatères (Image, Sprite, BitmapText, etc.)
• BatchHandlerQuadSingle -- variante à quad unique
• BatchHandlerTileSprite -- traitement par lots de TileSprite
• BatchHandlerTriFlat -- traitement par lots de triangles plats (Graphics, Shape)
• BatchHandlerPointLight -- traitement par lots des lumières ponctuelles
• BatchHandlerStrip -- traitement par lots de bandes de triangles

Soumetteurs (coordonnées de rendu par type d’objet) :

• SubmitterQuad, SubmitterTile, SubmitterTileSprite
• SubmitterSpriteGPULayer, SubmitterTilemapGPULayer

Transformateurs (calcul des positions des sommets) :

• TransformerImage, TransformerStamp, TransformerTile, TransformerTileSprite

Texturiseurs (gestion de la liaison des textures) :

• TexturerImage, TexturerTileSprite

Filtres (post-traitement — voir filters-and-postfx.md) :

• BaseFilter, BaseFilterShader
• FilterBarrel, FilterBlend, FilterBlocky, FilterBlur (variantes Faible/Moyenne/Élevée)
• FilterBokeh, FilterColorMatrix, FilterCombineColorMatrix
• FilterDisplacement, FilterGlow, FilterGradientMap, FilterImageLight
• FilterKey, FilterMask, FilterNormalTools, FilterPanoramaBlur
• FilterParallelFilters, FilterPixelate, FilterQuantize
• FilterSampler, FilterShadow, FilterThreshold, FilterVignette, FilterWipe

Autres:

• Camera, FillCamera, FillRect, FillPath, FillTri
• DrawLine, StrokePath, ShaderQuad
• ListCompositor, RebindContext, YieldContext
• Gestionnaire de textures dynamiques

Extension : nœuds de rendu personnalisés

// Enregistrer un constructeur de nœud personnalisé :
renderer.renderNodes.addNodeConstructor('MyNode', MyNodeClass);// Ou ajouter une instance de nœud pré-construite :
renderer.renderNodes.addNode('MyNode', myNodeInstance);

Nouveaux objets de jeu

CaptureFrame

Capture le contenu actuel du framebuffer dans une texture à l'emplacement où il se trouve dans la liste d'affichage. Ne rend rien en soi. WebGL uniquement.

// Tout ce qui se trouve au-dessus de cet élément dans la liste d'affichage est capturé :
const image1 = this.add.image(400, 300, 'background');// Active l'utilisation du tampon de trame sur la caméra :
this.cameras.main.setForceComposite(true);// Crée le point de capture :
const capture = this.add.captureFrame('myCapturedTexture');// Utiliser la texture capturée sur un autre objet :
const overlay = this.add.image(400, 300, 'myCapturedTexture');
// Ajouter des filtres à la superposition pour déformer la scène capturée

Détails importants :

• Nécessite camera.setForceComposite(true) ou un contexte de framebuffer (filtres, DynamicTexture, caméra avec alpha partiel)
• À l’intérieur d’un conteneur comportant des filtres, seule le contenu de ce conteneur est capturé
• Définir visible = false arrête la capture
• Composants : BlendMode, Depth, RenderNodes, Visible

Source: src/gameobjects/captureframe/CaptureFrame.js

Dégradé

Affiche des dégradés de couleurs rendus par le GPU. Étend l’interface Shader. Prend en charge les modes linéaires, radiaux et d’autres formes grâce à un ColorRamp configurable contenant des objets ColorBand.

// Dégradé linéaire simple :
const grad = this.add.gradient(undefined, 100, 100, 200, 200);// Dégradé radial complexe avec plusieurs bandes de couleur :
const halo = this.add.gradient({
   bands: [
        { start: 0.5, end: 0.6, colorStart: [0.5, 0.5, 1, 0], colorEnd: 0xffffff, colorSpace: 1, interpolation: 4 },
        { start: 0,6, end: 1, colorStart: 0xffffff, colorEnd: [1, 0, 5, 0 ,5, 0], colorSpace: 1, interpolation: 3 }
    ],
    dither: true,
    repeatMode: 1,
    shapeMode: 2,       // radial
    start: { x: 0,5, y: 0,5 },
    shape: { x: 0,5, y: 0,0 }
}, 400, 300, 800, 800);// Animation :
halo.offset = 0,1 * (1 + Math.sin(time / 1000));

Détails clés :

• Configuration : GradientQuadConfig avec bands, shapeMode, repeatMode, start, shape, dither
• Couleurs définies via ColorRamp avec des objets ColorBand (prend en charge le mode HSV et divers modes d'interpolation)
• Appeler gradient.ramp.encode() après avoir modifié les données de la rampe à l'exécution

Source: src/gameobjects/gradient/Gradient.js

Objets de jeu « Noise »

Tous les types de bruit héritent de Shader et sont réservés à WebGL. Six variantes disponibles :

// Bruit blanc de base :
const noise = this.add.noise({
    noiseOffset: [0, 0],
    noisePower: 1
}, 100, 100, 256, 256);// Bruit cellulaire personnalisable :
const cells = this.add.noiseCell2D({
    noiseOffset: [0, 0],
   noiseIterations: 3,
    noiseNormalMap: true    // sortie sous forme de carte normale pour l'éclairage
}, 200, 200, 256, 256);// Bruit simplex pour des effets naturels :
const simplex = this.add.noiseSimplex2D({
    noiseFlow: 0,           // animer ce paramètre pour faire évoluer le bruit
   noiseIterations: 4,
    noiseWarpAmount: 0.5,   // turbulence
    noiseSeed: 42,
    noiseNormalMap: false
}, 300, 300, 256, 256);

Propriétés communes à tous les types de bruit :

• noiseOffset -- tableau [x, y] permettant de faire défiler le motif
• noisePower -- permet de modeler les niveaux de sortie (une valeur plus élevée atténue les valeurs élevées)
• noiseNormalMap -- carte normale de sortie (pour l’intégration à l’éclairage)
• noiseIterations -- niveau de détail (types cellulaires/simplex)

Équivalents mathématiques: Phaser.Math.Hash(), Phaser.Math.HashCell(), Phaser.Math.HashSimplex()

Source: src/gameobjects/noise/

SpriteGPULayer

Permet de rendre un très grand nombre de quadrilatères (jusqu’à plusieurs millions) en un seul appel de dessin en stockant les données dans un tampon GPU statique. Jusqu’à 100 fois plus rapide que les sprites individuels. WebGL uniquement.

const layer = this.add.spriteGPULayer(texture, size); // size = nombre maximal d'éléments // Ajoute des éléments (effectuez cette opération en une seule fois, et non de manière incrémentielle) :
const member = { x: 100, y: 200, frame: 'tree', scaleX: 1, scaleY: 1, alpha: 1 };
layer.addMember(member);// Réutilisez l’objet membre pour plus d’efficacité avec des millions d’entrées :
member.x = 300;
member.y = 400;
member.frame = 'bush';
layer.addMember(member);// Activez l'éclairage sur le calque :
layer.setLighting(true);

Détails clés :

• Une seule texture (pas d’atlas multiple), une seule image par couche
• Les membres prennent en charge des animations de type « tween » (fondu, rebond, ondulation, changement de couleur) définies lors de la création
• La mise à jour du contenu du tampon est coûteuse — remplissez-le une seule fois, puis ne le modifiez plus
• Il est recommandé d’utiliser des textures de taille puissance de deux pour le pixel art afin d’éviter les raccords
• « Supprimez » visuellement des membres en définissant scaleX/scaleY/alpha sur 0 (ce qui évite la reconstruction du tampon)
• Composants : Alpha, BlendMode, Depth, ElapseTimer, Lighting, Mask, RenderNodes, TextureCrop, Visible

Source: src/gameobjects/spritegpulayer/SpriteGPULayer.js

Nouveaux composants

Référence complète des composants : game-object-components.md

Composant Lighting

Remplace l'approche de la v3 consistant à attribuer un pipeline d'éclairage. WebGL uniquement.

// Approche v3 :
sprite.setPipeline('Light2D');// Approche v4 :
sprite.setLighting(true);// Auto-ombrage (simule les ombres de surface à partir de la luminosité de la texture) :
sprite.setSelfShadow(true, 0.5,1/3);
// Arguments : enabled, penumbra (valeur plus faible = contour plus net), diffuseFlatThreshold (0-1)// Utilisation de la valeur par défaut à l'échelle du jeu pour les ombres propres :
sprite.setSelfShadow(null);  // lit la valeur dans config.render.selfShadow

Pris en charge sur: BitmapText, Blitter, Graphics, Shape, Image, Sprite, Particles, SpriteGPULayer, Stamp, Text, TileSprite, Video, TilemapLayer, TilemapGPULayer.

Remarque concernant le regroupement: l’éclairage modifie le shader, ce qui rompt les lots. Regroupez les objets éclairés entre eux et les objets non éclairés entre eux pour optimiser les performances.

Source: src/gameobjects/components/Lighting.js

Composant RenderSteps

Permet d’injecter une logique personnalisée dans le processus de rendu d’un objet de jeu. WebGL uniquement. Le système de filtres utilise RenderSteps en interne.

// Ajouter une étape de rendu personnalisée :
gameObject.addRenderStep(function (renderer, gameObject, drawingContext, parentMatrix, renderStep, displayList, displayListIndex) {
    // Logique de rendu personnalisée ici
    // Appeler l'étape suivante lorsque prêt :
   var nextFn = gameObject._renderSteps[renderStep + 1];
    if (nextFn) {
        nextFn(renderer, gameObject, drawingContext, parentMatrix, renderStep + 1, displayList, displayListIndex);
    }
});

Points clés :

• Les étapes sont stockées dans le tableau _renderSteps et exécutées via renderWebGLStep()
• La première étape s’exécute en premier et est chargée d’appeler les étapes suivantes
• C'est ainsi que les filtres différèrent et contrôlent le flux renderWebGL

Source: src/gameobjects/components/RenderSteps.js

Composant RenderNodes

Fournit les cartes `defaultRenderNodes`, `customRenderNodes` et `renderNodeData ` sur les objets de jeu. Reportez-vous à la section « RenderNodes » ci-dessus pour connaître leur utilisation.

Source: src/gameobjects/components/RenderNodes.js

TilemapGPULayer

Référence complète sur les tilemaps : tilemaps.md

Rendu de tilemap haute performance basé sur le GPU. Rendu de la couche entière sous la forme d’un seul quad via un shader spécialisé. WebGL uniquement.

// Création via Tilemap avec l'indicateur gpu :
const map = this.make.tilemap({ key: 'level1' });
const tileset = map.addTilesetImage('tiles', 'tilesImage');
const gpuLayer = map.createLayer('Ground', tileset, 0, 0, true);  // dernier argument : gpu = true

Fonctionnalités :

• Un seul ensemble de tuiles avec une seule image de texture
• 4 096 x 4 096 tuiles maximum, jusqu’à 2^23 identifiants de tuiles uniques
• Prise en charge du retournement de tuiles et des animations
• Cartes de tuiles orthographiques uniquement (pas d’isométriques ni d’hexagonales)
• Filtrage parfait des textures en mode LINÉAIRE (pas de joints entre les tuiles)
• Le coût est calculé par pixel, et non par tuile — aucune perte de performances même avec un grand nombre de tuiles visibles

Restrictions :

• Impossible d’utiliser plusieurs jeux de tuiles
• L'édition nécessite un appel manuel à la fonction generateLayerDataTexture() pour la mise à jour
• Mode orthographique uniquement

Données internes: les données de tuiles sont stockées dans une texture (4 octets par tuile : 2 bits de retournement, 1 bit d’animation, 1 bit inutilisé, index de tuile sur 28 bits). Les données d’animation sont stockées dans une texture distincte.

Source: src/tilemaps/TilemapGPULayer.js

Pour les options de configuration détaillées, les tableaux de référence de l'API et les correspondances des fichiers source, consultez le guide de référence.