graphics-and-shapes

name	graphics-and-shapes
description	Use this skill when drawing shapes and graphics in Phaser 4. Covers the Graphics game object, lines, rectangles, circles, arcs, polygons, gradients, fill, stroke, and generated textures. Triggers on: Graphics, draw shape, fillRect, lineStyle, polygon, arc.

Phaser 4 — Graphics and Shapes

Drawing primitives with the Graphics game object, and using Shape game objects (Arc, Curve, Ellipse, Grid, IsoBox, IsoTriangle, Line, Polygon, Rectangle, Star, Triangle).

Related skills: sprites-and-images.md, game-object-components.md

---

Quick Start

// Draw a filled rectangle and stroked circle with Graphics
const gfx = this.add.graphics();

gfx.fillStyle(0x00aa00, 1);
gfx.fillRect(50, 50, 200, 100);

gfx.lineStyle(3, 0xff0000, 1);
gfx.strokeCircle(400, 150, 60);

// Same shapes as standalone Shape game objects
const rect = this.add.rectangle(150, 100, 200, 100, 0x00aa00);
const circle = this.add.circle(400, 150, 60);
circle.setStrokeStyle(3, 0xff0000);

---

Core Concepts — Graphics vs Shape Objects

Phaser offers two approaches for rendering primitives without textures.

Graphics Game Object

Created with this.add.graphics(). An imperative drawing surface — you call methods like fillRect, strokeCircle, beginPath/lineTo/strokePath to build up a command buffer that replays each frame.

• Factory: this.add.graphics(config?) where config is { x?, y?, lineStyle?, fillStyle? }.
• Supports paths, arcs, gradients, rounded rectangles, canvas transforms (translateCanvas, scaleCanvas, rotateCanvas), and save/restore.
• Can generate a Texture from the drawing via generateTexture(key, width, height).
• Expensive to render, especially with complex shapes. Uses its own WebGL shader. Group Graphics objects together to minimize batch flushes.
• Components: AlphaSingle, BlendMode, Depth, Lighting, Mask, RenderNodes, Transform, Visible, ScrollFactor.
• Does NOT include Origin or GetBounds (position is set via options or setPosition).

Shape Game Objects

Individual game objects (Arc, Rectangle, Star, etc.) extending the base Shape class. Each renders one predefined geometric shape with precomputed path data.

• Created via dedicated factory methods: this.add.rectangle(...), this.add.circle(...), etc.
• Fully featured game objects: can be tweened, scaled, added to groups/containers, enabled for input/physics.
• Style via setFillStyle(color, alpha) and setStrokeStyle(lineWidth, color, alpha).
• Share the same WebGL batch as Graphics for efficient rendering.
• Do NOT support gradients, path detail threshold, or canvas transforms.
• Components: AlphaSingle, BlendMode, Depth, GetBounds, Lighting, Mask, Origin, RenderNodes, ScrollFactor, Transform, Visible.
• Include Origin and GetBounds (unlike Graphics).

When to use which:

• Use Graphics for dynamic drawing, complex paths, multiple shapes on one object, gradients, or generating textures.
• Use Shape objects for individual UI elements, simple indicators, physics-enabled shapes, or anything that benefits from game object features (origin, bounds, input).

---

Common Patterns

Fill and Stroke Styles (Graphics)

const gfx = this.add.graphics();

// Solid fill — call before any fill* method
gfx.fillStyle(0xff0000, 1);          // (color, alpha)

// Line style — call before any stroke* method
gfx.lineStyle(4, 0x00ff00, 1);       // (width, color, alpha)

// Gradient fill (WebGL only) — 4 corner colors
gfx.fillGradientStyle(
    0xff0000, 0x00ff00, 0x0000ff, 0xffff00,  // tl, tr, bl, br colors
    1, 1, 1, 1                                 // tl, tr, bl, br alphas
);
gfx.fillRect(0, 0, 300, 200);

// Gradient line style (WebGL only)
gfx.lineGradientStyle(2, 0xff0000, 0x00ff00, 0x0000ff, 0xffff00, 1);

Drawing Primitives (Graphics)

const gfx = this.add.graphics();

// Rectangles
gfx.fillStyle(0x0000ff);
gfx.fillRect(x, y, width, height);
gfx.lineStyle(2, 0xffffff);
gfx.strokeRect(x, y, width, height);

// Circles
gfx.fillCircle(x, y, radius);
gfx.strokeCircle(x, y, radius);

// Ellipses
gfx.fillEllipse(x, y, width, height, smoothness);
gfx.strokeEllipse(x, y, width, height, smoothness);   // smoothness defaults to 32

// Triangles
gfx.fillTriangle(x0, y0, x1, y1, x2, y2);
gfx.strokeTriangle(x0, y0, x1, y1, x2, y2);

// Points (draws a small square)
gfx.fillPoint(x, y, size);                             // size defaults to 1

// Lines
gfx.lineBetween(x1, y1, x2, y2);

Rounded Rectangles

const gfx = this.add.graphics();

// Uniform radius (default 20)
gfx.fillStyle(0x333333);
gfx.fillRoundedRect(50, 50, 300, 200, 16);
gfx.lineStyle(2, 0xffffff);
gfx.strokeRoundedRect(50, 50, 300, 200, 16);

// Per-corner radius
gfx.fillRoundedRect(50, 50, 300, 200, {
    tl: 20, tr: 20, bl: 0, br: 0
});

// Concave corners (negative values)
gfx.fillRoundedRect(50, 50, 300, 200, { tl: -10, tr: -10, bl: -10, br: -10 });

Path Drawing

const gfx = this.add.graphics();

// Manual path
gfx.lineStyle(3, 0xffff00);
gfx.beginPath();
gfx.moveTo(100, 100);
gfx.lineTo(200, 50);
gfx.lineTo(300, 100);
gfx.lineTo(250, 200);
gfx.closePath();
gfx.strokePath();       // or gfx.stroke() — alias for strokePath

// Fill a path
gfx.fillStyle(0x00aaff);
gfx.beginPath();
gfx.moveTo(100, 100);
gfx.lineTo(200, 50);
gfx.lineTo(300, 100);
gfx.closePath();
gfx.fillPath();         // or gfx.fill() — alias for fillPath

// Arc within a path (angles in radians)
gfx.beginPath();
gfx.arc(200, 200, 80, 0, Math.PI / 2, false, 0);   // (x, y, radius, startAngle, endAngle, anticlockwise, overshoot)
gfx.strokePath();

// Pie slice
gfx.slice(200, 200, 80, 0, Math.PI / 3, false);     // auto begins/closes path
gfx.fillPath();

// Stroke/fill from point arrays
gfx.strokePoints(points, closeShape, closePath, endIndex);
gfx.fillPoints(points, closeShape, closePath, endIndex);

Geom Shape Helpers

Graphics has convenience methods that accept Phaser.Geom objects directly:

const circle = new Phaser.Geom.Circle(200, 200, 50);
const rect = new Phaser.Geom.Rectangle(50, 50, 100, 80);

gfx.fillCircleShape(circle);
gfx.strokeCircleShape(circle);
gfx.fillRectShape(rect);
gfx.strokeRectShape(rect);
gfx.fillTriangleShape(triangle);
gfx.strokeTriangleShape(triangle);
gfx.strokeLineShape(line);
gfx.fillEllipseShape(ellipse, smoothness);
gfx.strokeEllipseShape(ellipse, smoothness);

Canvas Transforms (Graphics)

const gfx = this.add.graphics();

gfx.save();
gfx.translateCanvas(100, 100);
gfx.rotateCanvas(0.5);           // radians
gfx.scaleCanvas(2, 2);
gfx.fillStyle(0xff0000);
gfx.fillRect(0, 0, 50, 50);     // draws at translated/rotated/scaled position
gfx.restore();

Generating Textures from Graphics

const gfx = this.add.graphics();
gfx.fillStyle(0xff0000);
gfx.fillCircle(32, 32, 32);
gfx.generateTexture('redCircle', 64, 64);
gfx.destroy();

// Now use as a regular texture
this.add.image(400, 300, 'redCircle');

Note: fillGradientStyle will NOT appear in generated textures (Canvas API limitation).

Shape Objects — Fill and Stroke

// Shapes set fill via constructor or setFillStyle
const rect = this.add.rectangle(200, 150, 100, 80, 0xff0000, 1);

// Change fill later
rect.setFillStyle(0x00ff00, 0.8);

// Add stroke (not set by default)
rect.setStrokeStyle(3, 0xffffff, 1);  // (lineWidth, color, alpha)

// Remove fill or stroke
rect.setFillStyle();    // no args = isFilled becomes false
rect.setStrokeStyle();  // no args = isStroked becomes false

// Direct property access
rect.fillColor = 0x0000ff;
rect.fillAlpha = 0.5;
rect.strokeColor = 0xffffff;
rect.strokeAlpha = 1;
rect.lineWidth = 2;
rect.isFilled = true;
rect.isStroked = true;
rect.closePath = true;   // close stroke path (default true)

---

All Shape Types

Factory Method	Class	Parameters (after x, y)	Fill	Stroke	Notes
this.add.arc(x, y, radius, startAngle, endAngle, anticlockwise, fillColor, fillAlpha)	Arc	radius=128, startAngle=0, endAngle=360 (degrees), anticlockwise=false	Yes	Yes	Angles in degrees. Full circle by default.
this.add.circle(x, y, radius, fillColor, fillAlpha)	Arc	radius=128	Yes	Yes	Alias for Arc with 0-360 angles.
this.add.curve(x, y, curve, fillColor, fillAlpha)	Curve	Phaser.Curves.Curve object	Yes	Yes	Has smoothness property / setSmoothness().
this.add.ellipse(x, y, width, height, fillColor, fillAlpha)	Ellipse	width=128, height=128	Yes	Yes	Equal w/h renders as circle. Has smoothness.
this.add.grid(x, y, width, height, cellWidth, cellHeight, fillColor, fillAlpha, outlineFillColor, outlineFillAlpha)	Grid	width=128, height=128, cellWidth=32, cellHeight=32	Yes	No	Has altFillColor/altFillAlpha for checkerboard. Outline via outlineFillColor.
this.add.isobox(x, y, size, height, fillTop, fillLeft, fillRight)	IsoBox	size=48, height=32, fillTop=0xeeeeee, fillLeft=0x999999, fillRight=0xcccccc	Yes	No	Isometric box. showTop, showLeft, showRight, projection.
this.add.isotriangle(x, y, size, height, reversed, fillTop, fillLeft, fillRight)	IsoTriangle	size=48, height=32, reversed=false	Yes	No	Isometric pyramid. showTop, showLeft, showRight, projection, reversed.
this.add.line(x, y, x1, y1, x2, y2, strokeColor, strokeAlpha)	Line	x1=0, y1=0, x2=128, y2=0	No	Yes	Stroke only. Constructor takes stroke color (not fill).
this.add.polygon(x, y, points, fillColor, fillAlpha)	Polygon	points (various formats)	Yes	Yes	Points: array of Vec2, [x,y,...] pairs, or [[x,y],...].
this.add.rectangle(x, y, width, height, fillColor, fillAlpha)	Rectangle	width=128, height=128	Yes	Yes	Change size via width/height properties.
this.add.star(x, y, points, innerRadius, outerRadius, fillColor, fillAlpha)	Star	points=5, innerRadius=32, outerRadius=64	Yes	Yes	4 points = diamond. More points = spikier.
this.add.triangle(x, y, x1, y1, x2, y2, x3, y3, fillColor, fillAlpha)	Triangle	x1=0,y1=128, x2=64,y2=0, x3=128,y3=128	Yes	Yes	Always closed. Use Polygon for open shapes.

---

API Quick Reference — Graphics Methods

Style Methods

Method	Signature	Notes
fillStyle	(color, alpha=1)	Set fill for subsequent fill calls
lineStyle	(lineWidth, color, alpha=1)	Set stroke for subsequent stroke calls
fillGradientStyle	(tl, tr, bl, br, aTL=1, aTR, aBL, aBR)	WebGL only. 4 corner colors.
lineGradientStyle	(lineWidth, tl, tr, bl, br, alpha=1)	WebGL only.
setDefaultStyles	(options)	Set via { lineStyle: {width,color,alpha}, fillStyle: {color,alpha} }

Path Methods

Method	Signature	Notes
beginPath	()	Start a new path
moveTo	(x, y)	Move draw position
lineTo	(x, y)	Line to position
arc	(x, y, radius, startAngle, endAngle, anticlockwise=false, overshoot=0)	Angles in radians
closePath	()	Close current path
fillPath / fill	()	Fill the current path
strokePath / stroke	()	Stroke the current path