graphics-and-shapes

# 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 ```js // 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); ``` ```js // 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) ```js 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) ```js 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 ```js 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 ```js 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: ```js 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) ```js 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 ```js 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 ```js // 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 |