v4-new-features

Neue Funktionen in Phaser 4

Neue Funktionen und Möglichkeiten in Phaser 4: Filter (ersetzen FX/BitmapMask), RenderNodes (ersetzen Pipelines), die Game-Objekte „CaptureFrame“, „Gradient“ und „Noise“, SpriteGPULayer, TilemapGPULayer, die Lighting-Komponente, RenderSteps sowie neue Farbtonmodi.

Zugehörige Kenntnisse:../v3-to-v4-migration/SKILL.md, ../filters-and-postfx/SKILL.md, ../game-object-components/SKILL.md, ../tilemaps/SKILL.md

Migration von v3? Im Migrationsleitfaden von v3 nach v4 finden Sie schrittweise Anleitungen zu Codeänderungen, entfernten APIs und eine Migrations-Checkliste.

Übersicht: Was hat sich in v4 geändert?

Phaser 4 ist eine komplette Überarbeitung der WebGL-Rendering-Engine. Der v3-Renderer ließ jedes Subsystem den WebGL-Status unabhängig verwalten, was zu Konflikten führte (z. B. bestimmte Effekte, die Masken beeinträchtigten). v4 zentralisiert die Verwaltung des WebGL-Status über einen RenderNode-Graphen, in dem jeder Knoten genau eine Rendering-Aufgabe übernimmt.

Wichtige Entfernungen

Wichtige Neuerungen

• Neue GameObjects: CaptureFrame, Gradient, Noise, NoiseCell2D/3D/4D, NoiseSimplex2D/3D, SpriteGPULayer, Stamp, TilemapGPULayer
• Neue Komponenten: Lighting, RenderSteps, RenderNodes
• Neue Tönungsmodi: MULTIPLY, FILL, ADD, SCREEN, OVERLAY, HARD_LIGHT
• Neue Filter: „Blend“, „Blocky“, „CombineColorMatrix“, „GradientMap“, „ImageLight“, „Key“, „Mask“, „NormalTools“, „PanoramaBlur“, „ParallelFilters“, „Quantize“, „Sampler“, „Threshold“
• GL-Ausrichtung: v4 verwendet die Standard-GL-Ausrichtung (Y=0 unten für Texturen)

Filtersystem (ersetzt FX und BitmapMask)

Vollständige Referenz: filters-and-postfx.md

Filter vereinen die FX- und Mask-Systeme von v3. Jeder Filter nimmt ein Eingabebild entgegen und erzeugt über einen Shader-Durchlauf ein Ausgabebild. Filter können auf jedes Spielobjekt oder jede Kamera angewendet werden – in v3 gab es Einschränkungen hinsichtlich der Objekte, die FX unterstützten.

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

Intern vs. extern: Interne Filter werden vor der Kameratransformation ausgeführt (objektlokaler Raum, weniger rechenintensiv). Externe Filter werden danach ausgeführt (Bildschirmraum, volle Auflösung).

RenderNodes (Ersatz für Pipelines)

In v3 war eine Pipeline ein Rendering-System, das oft mehrere Aufgaben übernahm. In v4 übernimmt jeder RenderNode über seine run() -Methode eine einzelne Rendering-Aufgabe. Einige Knoten verfügen zudem über eine batch() -Methode, um den Status vor dem Zeichnen zu akkumulieren.

Architektur

Der RenderNodeManager (im WebGL-Renderer) verwaltet alle Render-Knoten. Spielobjekte verweisen über rollenbasierte Zuordnungen auf Knoten.

// RenderNode-Rollen für ein Spielobjekt:
// - „Submitter“: führt andere Knotenrollen für jedes Element aus
// - „Transformer“: liefert Scheitelpunktkoordinaten
// - „Texturer“: verarbeitet Texturen// Spielobjekte verfügen über Standard- und benutzerdefinierte Render-Knoten-Zuordnungen:
gameObject.defaultRenderNodes  // integrierte Knoten pro Rolle
gameObject.customRenderNodes   // Überschreibungen pro Rolle
gameObject.renderNodeData      // Daten, indiziert nach Knotennamen

Benutzerdefinierte Render-Knoten festlegen

// Eine bestimmte Render-Rolle überschreiben:
gameObject.setRenderNodeRole('Submitter', 'MyCustomSubmitter');// Daten an einen Render-Knoten übergeben:
gameObject.setRenderNodeRole('Transformer', 'MyTransformer', {
    customProperty: 42
});// Einen benutzerdefinierten Knoten entfernen (es wird auf die Standardeinstellung zurückgegriffen):
gameObject.setRenderNodeRole('Submitter', null);

Integrierte Render-Knotentypen

Batch-Handler (sammeln und zeichnen mehrere Objekte pro Zeichenaufruf):

• BatchHandlerQuad – Standard-Quad-Batching (Image, Sprite, BitmapText usw.)
• BatchHandlerQuadSingle – Variante für einzelne Quads
• BatchHandlerTileSprite – TileSprite-Batching
• BatchHandlerTriFlat – Batching von flachen Dreiecken (Graphics, Shape)
• BatchHandlerPointLight – Batching von Punktlichtern
• BatchHandlerStrip – Dreiecksstreifen-Batching

Submitter (koordinieren das Rendering pro Objekttyp):

• SubmitterQuad, SubmitterTile, SubmitterTileSprite
• SubmitterSpriteGPULayer, SubmitterTilemapGPULayer

Transformatoren (Berechnung der Scheitelpunktpositionen):

• TransformerImage, TransformerStamp, TransformerTile, TransformerTileSprite

Texturierer (Verwalten der Texturbindung):

• TexturerImage, TexturerTileSprite

Filter (Nachbearbeitung – siehe filters-and-postfx.md):

• BaseFilter, BaseFilterShader
• FilterBarrel, FilterBlend, FilterBlocky, FilterBlur (Varianten „Low“, „Med“ und „High“)
• FilterBokeh, FilterColorMatrix, FilterCombineColorMatrix
• FilterDisplacement, FilterGlow, FilterGradientMap, FilterImageLight
• FilterKey, FilterMask, FilterNormalTools, FilterPanoramaBlur
• FilterParallelFilters, FilterPixelate, FilterQuantize
• FilterSampler, FilterShadow, FilterThreshold, FilterVignette, FilterWipe

Sonstiges:

• Kamera, Kamera füllen, Rechteck füllen, Pfad füllen, Dreieck füllen
• DrawLine, StrokePath, ShaderQuad
• ListCompositor, RebindContext, YieldContext
• Dynamischer Textur-Handler

Erweiterung: Benutzerdefinierte RenderNodes

// Einen benutzerdefinierten Knoten-Konstruktor registrieren:
renderer.renderNodes.addNodeConstructor('MyNode', MyNodeClass);// Oder eine vorgefertigte Knoteninstanz hinzufügen:
renderer.renderNodes.addNode('MyNode', myNodeInstance);

Neue Spielobjekte

CaptureFrame

Erfasst den aktuellen Inhalt des Framebuffers als Textur an der Stelle in der Anzeigeliste, an der er sich befindet. Rendert selbst nichts. Nur WebGL.

// Alles, was in der Anzeigeliste darüber steht, wird erfasst:
const image1 = this.add.image(400, 300, 'background');// Framebuffer-Nutzung für die Kamera aktivieren:
this.cameras.main.setForceComposite(true);// Erstelle den Erfassungspunkt:
const capture = this.add.captureFrame('myCapturedTexture');// Die erfasste Textur auf einem anderen Objekt verwenden:
const overlay = this.add.image(400, 300, 'myCapturedTexture');
// Dem Overlay Filter hinzufügen, um die erfasste Szene zu verzerren

Wichtige Details:

• Erfordert camera.setForceComposite(true) oder einen Framebuffer-Kontext (Filter, DynamicTexture, Kamera mit partiellem Alpha)
• Innerhalb eines Containers mit Filtern wird nur der Inhalt dieses Containers erfasst
• Die Einstellung ` visible = false ` stoppt die Erfassung
• Komponenten: BlendMode, Depth, RenderNodes, Visible

Quelle: src/gameobjects/captureframe/CaptureFrame.js

Gradient

Zeigt GPU-gerenderte Farbverläufe an. Erweitert Shader. Unterstützt lineare, radiale und andere Formmodi mit konfigurierbaren „ColorRamp“-Objekten, die „ColorBand“-Objekte enthalten.

// Einfacher linearer Farbverlauf:
const grad = this.add.gradient(undefined, 100, 100, 200, 200);// Komplexer radialer Farbverlauf mit mehreren Farbbändern:
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);// Animieren:
halo.offset = 0,1 * (1 + Math.sin(time / 1000));

Wichtige Details:

• Konfiguration: „GradientQuadConfig“ mit „bands“, „shapeMode“, „repeatMode“, „start“, „shape“ und „dither“
• Farben definiert über `ColorRamp` mit `ColorBand` -Objekten (unterstützt HSV, verschiedene Interpolationsmodi)
• Rufe gradient.ramp.encode() auf, nachdem du die Rampendaten zur Laufzeit geändert hast

Quelle: src/gameobjects/gradient/Gradient.js

Noise-Game-Objekte

Alle Rauschtypen erben von Shader und sind nur für WebGL verfügbar. Sechs Varianten stehen zur Verfügung:

// Einfaches weißes Rauschen:
const noise = this.add.noise({
    noiseOffset: [0, 0],
    noisePower: 1
}, 100, 100, 256, 256);// Zelluläres Rauschen mit Anpassungsmöglichkeiten:
const cells = this.add.noiseCell2D({
    noiseOffset: [0, 0],
   noiseIterations: 3,
    noiseNormalMap: true    // Ausgabe als Normal Map für die Beleuchtung
}, 200, 200, 256, 256);// Simplex-Rauschen für natürliche Effekte:
const simplex = this.add.noiseSimplex2D({
    noiseFlow: 0,           // animiere diesen Wert für die Entwicklung
   noiseIterations: 4,
    noiseWarpAmount: 0.5,   // Turbulenz
    noiseSeed: 42,
    noiseNormalMap: false
}, 300, 300, 256, 256);

Gemeinsame Eigenschaften aller Rauschtypen:

• noiseOffset -- [x, y] -Array zum Verschieben des Musters
• noisePower -- Ausgabepegel anpassen (höhere Werte unterdrücken hohe Werte)
• noiseNormalMap – Ausgabe einer Normal Map (für die Beleuchtungsintegration)
• noiseIterations -- Detailstufe (Zell- und Simplex-Typen)

Mathematische Entsprechungen: Phaser.Math.Hash(), Phaser.Math.HashCell(), Phaser.Math.HashSimplex()

Quelle: src/gameobjects/noise/

SpriteGPULayer

Rendert sehr große Anzahlen von Quads (bis zu Millionen) in einem einzigen Draw-Call, indem Daten in einem statischen GPU-Puffer gespeichert werden. Bis zu 100-mal schneller als einzelne Sprites. Nur WebGL.

const layer = this.add.spriteGPULayer(texture, size); // size = maximale Anzahl an Elementen// Elemente hinzufügen (alles auf einmal, nicht schrittweise):
const member = { x: 100, y: 200, frame: 'tree', scaleX: 1, scaleY: 1, alpha: 1 };
layer.addMember(member);// Das Member-Objekt aus Effizienzgründen bei Millionen von Einträgen wiederverwenden:
member.x = 300;
member.y = 400;
member.frame = 'bush';
layer.addMember(member);// Beleuchtung auf der Ebene aktivieren:
layer.setLighting(true);

Wichtige Details:

• Nur eine Textur (kein Multi-Atlas), ein Bild pro Ebene
• Mitglieder unterstützen bei der Erstellung definierte, Tween-ähnliche Animationen (Einblenden, Abprallen, Welle, Farbverschiebung)
• Das Aktualisieren des Pufferinhaltes ist rechenintensiv – einmal füllen, dann unverändert lassen
• Für Pixelkunst werden Texturen mit einer Größe, die eine Zweierpotenz ist, empfohlen, um Nahtstellen zu vermeiden
• „Entfernen“ Sie Elemente visuell, indem Sie scaleX/scaleY/alpha auf 0 setzen (vermeidet einen Neuaufbau des Puffers)
• Komponenten: Alpha, BlendMode, Depth, ElapseTimer, Lighting, Mask, RenderNodes, TextureCrop, Visible

Quelle: src/gameobjects/spritegpulayer/SpriteGPULayer.js

Neue Komponenten

Vollständige Komponentenreferenz: game-object-components.md

Lighting-Komponente

Ersetzt den v3-Ansatz zur Zuweisung einer Beleuchtungspipeline. Nur WebGL.

// v3-Ansatz:
sprite.setPipeline('Light2D');// v4-Ansatz:
sprite.setLighting(true);// Selbstbeschattung (simuliert Oberflächenschatten anhand der Texturhelligkeit):
sprite.setSelfShadow(true, 0.5,1/3);
// Argumente: enabled, penumbra (niedrigerer Wert = schärfer), diffuseFlatThreshold (0–1)// Spielweite Standardeinstellung für Selbstschatten verwenden:
sprite.setSelfShadow(null);  // wird aus config.render.selfShadow gelesen

Unterstützt bei: BitmapText, Blitter, Graphics, Shape, Image, Sprite, Particles, SpriteGPULayer, Stamp, Text, TileSprite, Video, TilemapLayer, TilemapGPULayer.

Hinweis zum Batching: Die Beleuchtung verändert den Shader, wodurch Batches unterbrochen werden. Gruppieren Sie beleuchtete Objekte und unbeleuchtete Objekte jeweils separat, um die beste Leistung zu erzielen.

Quelle: src/gameobjects/components/Lighting.js

RenderSteps-Komponente

Ermöglicht das Einbinden benutzerdefinierter Logik in den Renderprozess eines Spielobjekts. Nur WebGL. Das Filters-System nutzt RenderSteps intern.

// Einen benutzerdefinierten Render-Schritt hinzufügen:
gameObject.addRenderStep(function (renderer, gameObject, drawingContext, parentMatrix, renderStep, displayList, displayListIndex) {
    // Benutzerdefinierte Render-Logik hier
    // Nächsten Schritt aufrufen, sobald bereit:
   var nextFn = gameObject._renderSteps[renderStep + 1];
    if (nextFn) {
        nextFn(renderer, gameObject, drawingContext, parentMatrix, renderStep + 1, displayList, displayListIndex);
    }
});

Wichtige Details:

• Die Schritte werden im Array _renderSteps gespeichert und über renderWebGLStep() ausgeführt
• Der erste Schritt wird zuerst ausgeführt und ist für den Aufruf der nachfolgenden Schritte zuständig
• Auf diese Weise verzögern und steuern Filter den Ablauf von ` renderWebGL `

Quelle: src/gameobjects/components/RenderSteps.js

RenderNodes-Komponente

Stellt die Maps `defaultRenderNodes`, `customRenderNodes` und `renderNodeData ` für Spielobjekte bereit. Informationen zur Verwendung finden Sie im Abschnitt „RenderNodes“ weiter oben.

Quelle: src/gameobjects/components/RenderNodes.js

TilemapGPULayer

Vollständige Tilemap-Referenz: tilemaps.md

Hochleistungsfähiges, GPU-basiertes Tilemap-Rendering. Rendert die gesamte Ebene über einen speziellen Shader als einzelnes Quad. Nur WebGL.

// Mit dem GPU-Flag über Tilemap erstellen:
const map = this.make.tilemap({ key: 'level1' });
const tileset = map.addTilesetImage('tiles', 'tilesImage');
const gpuLayer = map.createLayer('Ground', tileset, 0, 0, true);  // letztes Argument: gpu = true

Funktionen:

• Ein einziges Tileset mit einem einzigen Texturbild
• Maximal 4096 × 4096 Kacheln, bis zu 2²³ eindeutige Kachel-IDs
• Kachelspiegelung und Animation werden unterstützt
• Nur orthogonale Kachelkarten (keine isometrischen/hexagonalen)
• Perfekte Texturfilterung im LINEAR-Modus (keine Kachelnähte)
• Die Kosten werden pro Pixel und nicht pro Kachel berechnet – kein Leistungsverlust bei vielen sichtbaren Kacheln

Einschränkungen:

• Es können nicht mehrere Kachelsätze verwendet werden
• Zur Bearbeitung ist ein manueller Aufruf von ` generateLayerDataTexture() ` erforderlich, um die Daten zu aktualisieren
• Nur orthografisch

Interne Daten: Kacheldaten werden in einer Textur gespeichert (4 Byte/Kachel: 2 Flip-Bits, 1 Animationsbit, 1 ungenutztes Bit, 28-Bit-Kachelindex). Animationsdaten befinden sich in einer separaten Textur.

Quelle: src/tilemaps/TilemapGPULayer.js

Ausführliche Konfigurationsoptionen, API-Referenztabellen und Zuordnungen der Quelldateien finden Sie im Referenzhandbuch.