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 |
slice |
(x, y, radius, startAngle, endAngle, anticlockwise=false, overshoot=0) |
Pie slice. Auto begins/closes path. Angles in radians. |
Shape Drawing Methods
| Method |
Signature |
fillRect |
(x, y, width, height) |
strokeRect |
(x, y, width, height) |
fillRoundedRect |
(x, y, width, height, radius=20) |
strokeRoundedRect |
(x, y, width, height, radius=20) |
fillCircle |
(x, y, radius) |
strokeCircle |
(x, y, radius) |
fillEllipse |
(x, y, width, height, smoothness=32) |
strokeEllipse |
(x, y, width, height, smoothness=32) |
fillTriangle |
(x0, y0, x1, y1, x2, y2) |
strokeTriangle |
(x0, y0, x1, y1, x2, y2) |
fillPoint |
(x, y, size=1) |
lineBetween |
(x1, y1, x2, y2) |
strokePoints |
(points, closeShape=false, closePath=false, endIndex) |
fillPoints |
(points, closeShape=false, closePath=false, endIndex) |
Geom Shape Methods
| Method |
Signature |
fillRectShape |
(rect) |
strokeRectShape |
(rect) |
fillCircleShape |
(circle) |
strokeCircleShape |
(circle) |
fillTriangleShape |
(triangle) |
strokeTriangleShape |
(triangle) |
strokeLineShape |
(line) |
fillEllipseShape |
(ellipse, smoothness=32) |
strokeEllipseShape |
(ellipse, smoothness=32) |
Transform and State Methods
| Method |
Signature |
Notes |
translateCanvas |
(x, y) |
Translate subsequent draws |
scaleCanvas |
(x, y) |
Scale subsequent draws |
rotateCanvas |
(radians) |
Rotate subsequent draws |
save |
() |
Push state to stack |
restore |
() |
Pop state from stack |
clear |
() |
Clear command buffer, reset to default styles |
generateTexture |
(key, width, height) |
Bake to a Texture (Canvas API) |
Shape Base Class Methods
| Method |
Signature |
Notes |
setFillStyle |
(color?, alpha=1) |
No args = disable fill |
setStrokeStyle |
(lineWidth?, color?, alpha=1) |
No args = disable stroke |
Gotchas
Graphics arc() uses radians; Shape arc factory uses degrees. The Graphics arc method takes start/end angles in radians. The this.add.arc() factory takes them in degrees (0-360). Mixing these up is the most common bug.
Set style BEFORE drawing. fillStyle and lineStyle must be called before the corresponding fill/stroke method. They are not retroactive.
Graphics has no Origin or GetBounds. Unlike Shape objects, Graphics does not include the Origin or GetBounds components. Use setPosition(x, y) and displayOriginX/displayOriginY instead.
Shape isFilled/isStroked defaults. Shapes created with a fillColor parameter have isFilled = true. But isStroked defaults to false — you must call setStrokeStyle() explicitly.
Line shape is stroke-only. The Line shape does not support fill. Its constructor takes strokeColor/strokeAlpha (not fillColor).
IsoBox/IsoTriangle are fill-only. These shapes cannot be stroked. Grid supports outline strokes via its constructor parameters (outlineFillColor, outlineFillAlpha).
generateTexture uses Canvas API. Gradient fills (fillGradientStyle) will not appear in textures generated with generateTexture. Only Canvas-compatible features are captured.
Performance: Graphics is expensive. Each frame the command buffer is replayed and geometry is rebuilt (WebGL decomposes to polygons). For static shapes, call generateTexture and use the resulting texture as a Sprite. Group Graphics objects together to minimize batch breaks.
pathDetailThreshold (v4 new). Graphics has a pathDetailThreshold property (default -1, uses config render.pathDetailThreshold). Path segments below this pixel threshold are combined, improving WebGL performance on complex shapes. Evaluated in screen pixels, so detail emerges when zoomed in.
Rounded rect radius can be an object or number. Pass { tl, tr, bl, br } for per-corner control. Negative values create concave corners. Default is 20 when omitted.
Shape closePath property. The closePath property on Shape objects (default true) controls whether the stroke path is automatically closed. Set to false for open stroked shapes.
Shape objects do NOT support tint methods. Unlike Sprites and Images, Shape game objects do not have setTint() or tint properties. Use setFillStyle(color, alpha) and setStrokeStyle(lineWidth, color, alpha) instead.
Polygon getBounds() incorrect with negative points. If any polygon points have negative coordinates, getBounds() returns wrong values. Use Phaser.Geom.Polygon.GetAABB(polygon.geom) instead and adjust the returned Rectangle position.
Shape-Specific Methods
Star
const star = this.add.star(400, 300, 5, 32, 64, 0xffff00);
star.setPoints(8); // change number of points
star.setInnerRadius(20); // change inner radius
star.setOuterRadius(80); // change outer radius
Line (Tapering)
const line = this.add.line(400, 300, 0, 0, 200, 100, 0xffffff);
// setLineWidth(startWidth, endWidth) — endWidth is WebGL only (tapering effect)
line.setLineWidth(4, 1); // tapers from 4px to 1px (Canvas uses startWidth only)
Grid (Alternating Colors, Stroke, Padding)
const grid = this.add.grid(400, 300, 320, 240, 32, 32, 0x222222);
// Alternating cell color (checkerboard)
grid.setAltFillStyle(0x444444, 1); // no args = disable alternating cells
// Grid uses setStrokeStyle for cell outlines (inherited from Shape)
grid.setStrokeStyle(1, 0x666666, 1);
// v4: control outside edge stroke
grid.strokeOutside = true; // stroke the outer border
grid.strokeOutsideIncomplete = false; // skip partial cells on right/bottom edges
// Cell padding (default 0.5) — gutter between cells is 2x this value
grid.cellPadding = 1;
IsoBox / IsoTriangle
const box = this.add.isobox(200, 200, 48, 32, 0xeeeeee, 0x999999, 0xcccccc);
box.setFaces(true, true, false); // showTop, showLeft, showRight
box.setProjection(4); // isometric projection value
const tri = this.add.isotriangle(400, 200, 48, 32, false, 0xeeeeee, 0x999999, 0xcccccc);
tri.setReversed(true); // flip upside down
tri.setFaces(true, true, true);
tri.setProjection(4);
Source File Map
| File |
Purpose |
src/gameobjects/graphics/Graphics.js |
Graphics class — all drawing methods |
src/gameobjects/graphics/GraphicsFactory.js |
this.add.graphics() factory |
src/gameobjects/graphics/Commands.js |
Internal command constants for the command buffer |
src/gameobjects/graphics/GraphicsRender.js |
Render dispatch |
src/gameobjects/shape/Shape.js |
Base Shape class (fill/stroke/path data, setFillStyle, setStrokeStyle) |
src/gameobjects/shape/arc/Arc.js |
Arc shape (also used for circle) |
src/gameobjects/shape/arc/ArcFactory.js |
this.add.arc() and this.add.circle() factories |
src/gameobjects/shape/curve/Curve.js |
Curve shape |
src/gameobjects/shape/curve/CurveFactory.js |
this.add.curve() factory |
src/gameobjects/shape/ellipse/Ellipse.js |
Ellipse shape |
src/gameobjects/shape/ellipse/EllipseFactory.js |
this.add.ellipse() factory |
src/gameobjects/shape/grid/Grid.js |
Grid shape |
src/gameobjects/shape/grid/GridFactory.js |
this.add.grid() factory |
src/gameobjects/shape/isobox/IsoBox.js |
IsoBox shape |
src/gameobjects/shape/isobox/IsoBoxFactory.js |
this.add.isobox() factory |
src/gameobjects/shape/isotriangle/IsoTriangle.js |
IsoTriangle shape |
src/gameobjects/shape/isotriangle/IsoTriangleFactory.js |
this.add.isotriangle() factory |
src/gameobjects/shape/line/Line.js |
Line shape |
src/gameobjects/shape/line/LineFactory.js |
this.add.line() factory |
src/gameobjects/shape/polygon/Polygon.js |
Polygon shape |
src/gameobjects/shape/polygon/PolygonFactory.js |
this.add.polygon() factory |
src/gameobjects/shape/rectangle/Rectangle.js |
Rectangle shape |
src/gameobjects/shape/rectangle/RectangleFactory.js |
this.add.rectangle() factory |
src/gameobjects/shape/star/Star.js |
Star shape |
src/gameobjects/shape/star/StarFactory.js |
this.add.star() factory |
src/gameobjects/shape/triangle/Triangle.js |
Triangle shape |
src/gameobjects/shape/triangle/TriangleFactory.js |
this.add.triangle() factory |
1---2name: graphics-and-shapes3description: "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."4metadata:5 source: https://skillmd.com/skills/phaserjs/graphics-and-shapes6---78# Phaser 4 — Graphics and Shapes910> Drawing primitives with the Graphics game object, and using Shape game objects (Arc, Curve, Ellipse, Grid, IsoBox, IsoTriangle, Line, Polygon, Rectangle, Star, Triangle).1112Related skills: sprites-and-images.md, game-object-components.md1314---1516## Quick Start1718```js19// Draw a filled rectangle and stroked circle with Graphics20const gfx = this.add.graphics();2122gfx.fillStyle(0x00aa00, 1);23gfx.fillRect(50, 50, 200, 100);2425gfx.lineStyle(3, 0xff0000, 1);26gfx.strokeCircle(400, 150, 60);27```2829```js30// Same shapes as standalone Shape game objects31const rect = this.add.rectangle(150, 100, 200, 100, 0x00aa00);32const circle = this.add.circle(400, 150, 60);33circle.setStrokeStyle(3, 0xff0000);34```3536---3738## Core Concepts — Graphics vs Shape Objects3940Phaser offers two approaches for rendering primitives without textures.4142### Graphics Game Object4344Created 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.4546- Factory: `this.add.graphics(config?)` where config is `{ x?, y?, lineStyle?, fillStyle? }`.47- Supports paths, arcs, gradients, rounded rectangles, canvas transforms (`translateCanvas`, `scaleCanvas`, `rotateCanvas`), and `save`/`restore`.48- Can generate a Texture from the drawing via `generateTexture(key, width, height)`.49- Expensive to render, especially with complex shapes. Uses its own WebGL shader. Group Graphics objects together to minimize batch flushes.50- Components: AlphaSingle, BlendMode, Depth, Lighting, Mask, RenderNodes, Transform, Visible, ScrollFactor.51- Does NOT include Origin or GetBounds (position is set via options or `setPosition`).5253### Shape Game Objects5455Individual game objects (Arc, Rectangle, Star, etc.) extending the base `Shape` class. Each renders one predefined geometric shape with precomputed path data.5657- Created via dedicated factory methods: `this.add.rectangle(...)`, `this.add.circle(...)`, etc.58- Fully featured game objects: can be tweened, scaled, added to groups/containers, enabled for input/physics.59- Style via `setFillStyle(color, alpha)` and `setStrokeStyle(lineWidth, color, alpha)`.60- Share the same WebGL batch as Graphics for efficient rendering.61- Do NOT support gradients, path detail threshold, or canvas transforms.62- Components: AlphaSingle, BlendMode, Depth, GetBounds, Lighting, Mask, Origin, RenderNodes, ScrollFactor, Transform, Visible.63- Include Origin and GetBounds (unlike Graphics).6465**When to use which:**66- Use **Graphics** for dynamic drawing, complex paths, multiple shapes on one object, gradients, or generating textures.67- Use **Shape objects** for individual UI elements, simple indicators, physics-enabled shapes, or anything that benefits from game object features (origin, bounds, input).6869---7071## Common Patterns7273### Fill and Stroke Styles (Graphics)7475```js76const gfx = this.add.graphics();7778// Solid fill — call before any fill* method79gfx.fillStyle(0xff0000, 1); // (color, alpha)8081// Line style — call before any stroke* method82gfx.lineStyle(4, 0x00ff00, 1); // (width, color, alpha)8384// Gradient fill (WebGL only) — 4 corner colors85gfx.fillGradientStyle(86 0xff0000, 0x00ff00, 0x0000ff, 0xffff00, // tl, tr, bl, br colors87 1, 1, 1, 1 // tl, tr, bl, br alphas88);89gfx.fillRect(0, 0, 300, 200);9091// Gradient line style (WebGL only)92gfx.lineGradientStyle(2, 0xff0000, 0x00ff00, 0x0000ff, 0xffff00, 1);93```9495### Drawing Primitives (Graphics)9697```js98const gfx = this.add.graphics();99100// Rectangles101gfx.fillStyle(0x0000ff);102gfx.fillRect(x, y, width, height);103gfx.lineStyle(2, 0xffffff);104gfx.strokeRect(x, y, width, height);105106// Circles107gfx.fillCircle(x, y, radius);108gfx.strokeCircle(x, y, radius);109110// Ellipses111gfx.fillEllipse(x, y, width, height, smoothness);112gfx.strokeEllipse(x, y, width, height, smoothness); // smoothness defaults to 32113114// Triangles115gfx.fillTriangle(x0, y0, x1, y1, x2, y2);116gfx.strokeTriangle(x0, y0, x1, y1, x2, y2);117118// Points (draws a small square)119gfx.fillPoint(x, y, size); // size defaults to 1120121// Lines122gfx.lineBetween(x1, y1, x2, y2);123```124125### Rounded Rectangles126127```js128const gfx = this.add.graphics();129130// Uniform radius (default 20)131gfx.fillStyle(0x333333);132gfx.fillRoundedRect(50, 50, 300, 200, 16);133gfx.lineStyle(2, 0xffffff);134gfx.strokeRoundedRect(50, 50, 300, 200, 16);135136// Per-corner radius137gfx.fillRoundedRect(50, 50, 300, 200, {138 tl: 20, tr: 20, bl: 0, br: 0139});140141// Concave corners (negative values)142gfx.fillRoundedRect(50, 50, 300, 200, { tl: -10, tr: -10, bl: -10, br: -10 });143```144145### Path Drawing146147```js148const gfx = this.add.graphics();149150// Manual path151gfx.lineStyle(3, 0xffff00);152gfx.beginPath();153gfx.moveTo(100, 100);154gfx.lineTo(200, 50);155gfx.lineTo(300, 100);156gfx.lineTo(250, 200);157gfx.closePath();158gfx.strokePath(); // or gfx.stroke() — alias for strokePath159160// Fill a path161gfx.fillStyle(0x00aaff);162gfx.beginPath();163gfx.moveTo(100, 100);164gfx.lineTo(200, 50);165gfx.lineTo(300, 100);166gfx.closePath();167gfx.fillPath(); // or gfx.fill() — alias for fillPath168169// Arc within a path (angles in radians)170gfx.beginPath();171gfx.arc(200, 200, 80, 0, Math.PI / 2, false, 0); // (x, y, radius, startAngle, endAngle, anticlockwise, overshoot)172gfx.strokePath();173174// Pie slice175gfx.slice(200, 200, 80, 0, Math.PI / 3, false); // auto begins/closes path176gfx.fillPath();177178// Stroke/fill from point arrays179gfx.strokePoints(points, closeShape, closePath, endIndex);180gfx.fillPoints(points, closeShape, closePath, endIndex);181```182183### Geom Shape Helpers184185Graphics has convenience methods that accept Phaser.Geom objects directly:186187```js188const circle = new Phaser.Geom.Circle(200, 200, 50);189const rect = new Phaser.Geom.Rectangle(50, 50, 100, 80);190191gfx.fillCircleShape(circle);192gfx.strokeCircleShape(circle);193gfx.fillRectShape(rect);194gfx.strokeRectShape(rect);195gfx.fillTriangleShape(triangle);196gfx.strokeTriangleShape(triangle);197gfx.strokeLineShape(line);198gfx.fillEllipseShape(ellipse, smoothness);199gfx.strokeEllipseShape(ellipse, smoothness);200```201202### Canvas Transforms (Graphics)203204```js205const gfx = this.add.graphics();206207gfx.save();208gfx.translateCanvas(100, 100);209gfx.rotateCanvas(0.5); // radians210gfx.scaleCanvas(2, 2);211gfx.fillStyle(0xff0000);212gfx.fillRect(0, 0, 50, 50); // draws at translated/rotated/scaled position213gfx.restore();214```215216### Generating Textures from Graphics217218```js219const gfx = this.add.graphics();220gfx.fillStyle(0xff0000);221gfx.fillCircle(32, 32, 32);222gfx.generateTexture('redCircle', 64, 64);223gfx.destroy();224225// Now use as a regular texture226this.add.image(400, 300, 'redCircle');227```228229Note: `fillGradientStyle` will NOT appear in generated textures (Canvas API limitation).230231### Shape Objects — Fill and Stroke232233```js234// Shapes set fill via constructor or setFillStyle235const rect = this.add.rectangle(200, 150, 100, 80, 0xff0000, 1);236237// Change fill later238rect.setFillStyle(0x00ff00, 0.8);239240// Add stroke (not set by default)241rect.setStrokeStyle(3, 0xffffff, 1); // (lineWidth, color, alpha)242243// Remove fill or stroke244rect.setFillStyle(); // no args = isFilled becomes false245rect.setStrokeStyle(); // no args = isStroked becomes false246247// Direct property access248rect.fillColor = 0x0000ff;249rect.fillAlpha = 0.5;250rect.strokeColor = 0xffffff;251rect.strokeAlpha = 1;252rect.lineWidth = 2;253rect.isFilled = true;254rect.isStroked = true;255rect.closePath = true; // close stroke path (default true)256```257258---259260## All Shape Types261262| Factory Method | Class | Parameters (after x, y) | Fill | Stroke | Notes |263|---|---|---|---|---|---|264| `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. |265| `this.add.circle(x, y, radius, fillColor, fillAlpha)` | Arc | radius=128 | Yes | Yes | Alias for Arc with 0-360 angles. |266| `this.add.curve(x, y, curve, fillColor, fillAlpha)` | Curve | Phaser.Curves.Curve object | Yes | Yes | Has `smoothness` property / `setSmoothness()`. |267| `this.add.ellipse(x, y, width, height, fillColor, fillAlpha)` | Ellipse | width=128, height=128 | Yes | Yes | Equal w/h renders as circle. Has `smoothness`. |268| `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. |269| `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`. |270| `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`. |271| `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). |272| `this.add.polygon(x, y, points, fillColor, fillAlpha)` | Polygon | points (various formats) | Yes | Yes | Points: array of Vec2, `[x,y,...]` pairs, or `[[x,y],...]`. |273| `this.add.rectangle(x, y, width, height, fillColor, fillAlpha)` | Rectangle | width=128, height=128 | Yes | Yes | Change size via `width`/`height` properties. |274| `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. |275| `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. |276277---278279## API Quick Reference — Graphics Methods280281### Style Methods282283| Method | Signature | Notes |284|---|---|---|285| `fillStyle` | `(color, alpha=1)` | Set fill for subsequent fill calls |286| `lineStyle` | `(lineWidth, color, alpha=1)` | Set stroke for subsequent stroke calls |287| `fillGradientStyle` | `(tl, tr, bl, br, aTL=1, aTR, aBL, aBR)` | WebGL only. 4 corner colors. |288| `lineGradientStyle` | `(lineWidth, tl, tr, bl, br, alpha=1)` | WebGL only. |289| `setDefaultStyles` | `(options)` | Set via `{ lineStyle: {width,color,alpha}, fillStyle: {color,alpha} }` |290291### Path Methods292293| Method | Signature | Notes |294|---|---|---|295| `beginPath` | `()` | Start a new path |296| `moveTo` | `(x, y)` | Move draw position |297| `lineTo` | `(x, y)` | Line to position |298| `arc` | `(x, y, radius, startAngle, endAngle, anticlockwise=false, overshoot=0)` | Angles in radians |299| `closePath` | `()` | Close current path |300| `fillPath` / `fill` | `()` | Fill the current path |301| `strokePath` / `stroke` | `()` | Stroke the current path |302| `slice` | `(x, y, radius, startAngle, endAngle, anticlockwise=false, overshoot=0)` | Pie slice. Auto begins/closes path. Angles in radians. |303304### Shape Drawing Methods305306| Method | Signature |307|---|---|308| `fillRect` | `(x, y, width, height)` |309| `strokeRect` | `(x, y, width, height)` |310| `fillRoundedRect` | `(x, y, width, height, radius=20)` |311| `strokeRoundedRect` | `(x, y, width, height, radius=20)` |312| `fillCircle` | `(x, y, radius)` |313| `strokeCircle` | `(x, y, radius)` |314| `fillEllipse` | `(x, y, width, height, smoothness=32)` |315| `strokeEllipse` | `(x, y, width, height, smoothness=32)` |316| `fillTriangle` | `(x0, y0, x1, y1, x2, y2)` |317| `strokeTriangle` | `(x0, y0, x1, y1, x2, y2)` |318| `fillPoint` | `(x, y, size=1)` |319| `lineBetween` | `(x1, y1, x2, y2)` |320| `strokePoints` | `(points, closeShape=false, closePath=false, endIndex)` |321| `fillPoints` | `(points, closeShape=false, closePath=false, endIndex)` |322323### Geom Shape Methods324325| Method | Signature |326|---|---|327| `fillRectShape` | `(rect)` |328| `strokeRectShape` | `(rect)` |329| `fillCircleShape` | `(circle)` |330| `strokeCircleShape` | `(circle)` |331| `fillTriangleShape` | `(triangle)` |332| `strokeTriangleShape` | `(triangle)` |333| `strokeLineShape` | `(line)` |334| `fillEllipseShape` | `(ellipse, smoothness=32)` |335| `strokeEllipseShape` | `(ellipse, smoothness=32)` |336337### Transform and State Methods338339| Method | Signature | Notes |340|---|---|---|341| `translateCanvas` | `(x, y)` | Translate subsequent draws |342| `scaleCanvas` | `(x, y)` | Scale subsequent draws |343| `rotateCanvas` | `(radians)` | Rotate subsequent draws |344| `save` | `()` | Push state to stack |345| `restore` | `()` | Pop state from stack |346| `clear` | `()` | Clear command buffer, reset to default styles |347| `generateTexture` | `(key, width, height)` | Bake to a Texture (Canvas API) |348349### Shape Base Class Methods350351| Method | Signature | Notes |352|---|---|---|353| `setFillStyle` | `(color?, alpha=1)` | No args = disable fill |354| `setStrokeStyle` | `(lineWidth?, color?, alpha=1)` | No args = disable stroke |355356---357358## Gotchas3593601. **Graphics arc() uses radians; Shape arc factory uses degrees.** The Graphics `arc` method takes start/end angles in radians. The `this.add.arc()` factory takes them in degrees (0-360). Mixing these up is the most common bug.3613622. **Set style BEFORE drawing.** `fillStyle` and `lineStyle` must be called before the corresponding fill/stroke method. They are not retroactive.3633643. **Graphics has no Origin or GetBounds.** Unlike Shape objects, Graphics does not include the Origin or GetBounds components. Use `setPosition(x, y)` and `displayOriginX`/`displayOriginY` instead.3653664. **Shape isFilled/isStroked defaults.** Shapes created with a `fillColor` parameter have `isFilled = true`. But `isStroked` defaults to `false` — you must call `setStrokeStyle()` explicitly.3673685. **Line shape is stroke-only.** The Line shape does not support fill. Its constructor takes `strokeColor`/`strokeAlpha` (not fillColor).3693706. **IsoBox/IsoTriangle are fill-only.** These shapes cannot be stroked. Grid supports outline strokes via its constructor parameters (`outlineFillColor`, `outlineFillAlpha`).3713727. **generateTexture uses Canvas API.** Gradient fills (`fillGradientStyle`) will not appear in textures generated with `generateTexture`. Only Canvas-compatible features are captured.3733748. **Performance: Graphics is expensive.** Each frame the command buffer is replayed and geometry is rebuilt (WebGL decomposes to polygons). For static shapes, call `generateTexture` and use the resulting texture as a Sprite. Group Graphics objects together to minimize batch breaks.3753769. **pathDetailThreshold (v4 new).** Graphics has a `pathDetailThreshold` property (default -1, uses config `render.pathDetailThreshold`). Path segments below this pixel threshold are combined, improving WebGL performance on complex shapes. Evaluated in screen pixels, so detail emerges when zoomed in.37737810. **Rounded rect radius can be an object or number.** Pass `{ tl, tr, bl, br }` for per-corner control. Negative values create concave corners. Default is 20 when omitted.37938011. **Shape closePath property.** The `closePath` property on Shape objects (default `true`) controls whether the stroke path is automatically closed. Set to `false` for open stroked shapes.38138212. **Shape objects do NOT support tint methods.** Unlike Sprites and Images, Shape game objects do not have `setTint()` or `tint` properties. Use `setFillStyle(color, alpha)` and `setStrokeStyle(lineWidth, color, alpha)` instead.38338413. **Polygon getBounds() incorrect with negative points.** If any polygon points have negative coordinates, `getBounds()` returns wrong values. Use `Phaser.Geom.Polygon.GetAABB(polygon.geom)` instead and adjust the returned Rectangle position.385386---387388## Shape-Specific Methods389390### Star391392```js393const star = this.add.star(400, 300, 5, 32, 64, 0xffff00);394395star.setPoints(8); // change number of points396star.setInnerRadius(20); // change inner radius397star.setOuterRadius(80); // change outer radius398```399400### Line (Tapering)401402```js403const line = this.add.line(400, 300, 0, 0, 200, 100, 0xffffff);404405// setLineWidth(startWidth, endWidth) — endWidth is WebGL only (tapering effect)406line.setLineWidth(4, 1); // tapers from 4px to 1px (Canvas uses startWidth only)407```408409### Grid (Alternating Colors, Stroke, Padding)410411```js412const grid = this.add.grid(400, 300, 320, 240, 32, 32, 0x222222);413414// Alternating cell color (checkerboard)415grid.setAltFillStyle(0x444444, 1); // no args = disable alternating cells416417// Grid uses setStrokeStyle for cell outlines (inherited from Shape)418grid.setStrokeStyle(1, 0x666666, 1);419420// v4: control outside edge stroke421grid.strokeOutside = true; // stroke the outer border422grid.strokeOutsideIncomplete = false; // skip partial cells on right/bottom edges423424// Cell padding (default 0.5) — gutter between cells is 2x this value425grid.cellPadding = 1;426```427428### IsoBox / IsoTriangle429430```js431const box = this.add.isobox(200, 200, 48, 32, 0xeeeeee, 0x999999, 0xcccccc);432433box.setFaces(true, true, false); // showTop, showLeft, showRight434box.setProjection(4); // isometric projection value435436const tri = this.add.isotriangle(400, 200, 48, 32, false, 0xeeeeee, 0x999999, 0xcccccc);437438tri.setReversed(true); // flip upside down439tri.setFaces(true, true, true);440tri.setProjection(4);441```442443---444445## Source File Map446447| File | Purpose |448|---|---|449| `src/gameobjects/graphics/Graphics.js` | Graphics class — all drawing methods |450| `src/gameobjects/graphics/GraphicsFactory.js` | `this.add.graphics()` factory |451| `src/gameobjects/graphics/Commands.js` | Internal command constants for the command buffer |452| `src/gameobjects/graphics/GraphicsRender.js` | Render dispatch |453| `src/gameobjects/shape/Shape.js` | Base Shape class (fill/stroke/path data, setFillStyle, setStrokeStyle) |454| `src/gameobjects/shape/arc/Arc.js` | Arc shape (also used for circle) |455| `src/gameobjects/shape/arc/ArcFactory.js` | `this.add.arc()` and `this.add.circle()` factories |456| `src/gameobjects/shape/curve/Curve.js` | Curve shape |457| `src/gameobjects/shape/curve/CurveFactory.js` | `this.add.curve()` factory |458| `src/gameobjects/shape/ellipse/Ellipse.js` | Ellipse shape |459| `src/gameobjects/shape/ellipse/EllipseFactory.js` | `this.add.ellipse()` factory |460| `src/gameobjects/shape/grid/Grid.js` | Grid shape |461| `src/gameobjects/shape/grid/GridFactory.js` | `this.add.grid()` factory |462| `src/gameobjects/shape/isobox/IsoBox.js` | IsoBox shape |463| `src/gameobjects/shape/isobox/IsoBoxFactory.js` | `this.add.isobox()` factory |464| `src/gameobjects/shape/isotriangle/IsoTriangle.js` | IsoTriangle shape |465| `src/gameobjects/shape/isotriangle/IsoTriangleFactory.js` | `this.add.isotriangle()` factory |466| `src/gameobjects/shape/line/Line.js` | Line shape |467| `src/gameobjects/shape/line/LineFactory.js` | `this.add.line()` factory |468| `src/gameobjects/shape/polygon/Polygon.js` | Polygon shape |469| `src/gameobjects/shape/polygon/PolygonFactory.js` | `this.add.polygon()` factory |470| `src/gameobjects/shape/rectangle/Rectangle.js` | Rectangle shape |471| `src/gameobjects/shape/rectangle/RectangleFactory.js` | `this.add.rectangle()` factory |472| `src/gameobjects/shape/star/Star.js` | Star shape |473| `src/gameobjects/shape/star/StarFactory.js` | `this.add.star()` factory |474| `src/gameobjects/shape/triangle/Triangle.js` | Triangle shape |475| `src/gameobjects/shape/triangle/TriangleFactory.js` | `this.add.triangle()` factory |