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
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), andsave/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)andsetStrokeStyle(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)
Drawing Primitives (Graphics)
Rounded Rectangles
Path Drawing
Geom Shape Helpers
Graphics has convenience methods that accept Phaser.Geom objects directly:
Canvas Transforms (Graphics)
Generating Textures from Graphics
Note: fillGradientStyle will NOT appear in generated textures (Canvas API limitation).
Shape Objects — Fill and Stroke
All Shape Types
API Quick Reference — Graphics Methods
Style Methods
Path Methods
Shape Drawing Methods
Geom Shape Methods
Transform and State Methods
Shape Base Class Methods
Gotchas
-
Graphics arc() uses radians; Shape arc factory uses degrees. The Graphics
arcmethod takes start/end angles in radians. Thethis.add.arc()factory takes them in degrees (0-360). Mixing these up is the most common bug. -
Set style BEFORE drawing.
fillStyleandlineStylemust 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)anddisplayOriginX/displayOriginYinstead. -
Shape isFilled/isStroked defaults. Shapes created with a
fillColorparameter haveisFilled = true. ButisStrokeddefaults tofalse— you must callsetStrokeStyle()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 withgenerateTexture. 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
generateTextureand use the resulting texture as a Sprite. Group Graphics objects together to minimize batch breaks. -
pathDetailThreshold (v4 new). Graphics has a
pathDetailThresholdproperty (default -1, uses configrender.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
closePathproperty on Shape objects (defaulttrue) controls whether the stroke path is automatically closed. Set tofalsefor open stroked shapes. -
Shape objects do NOT support tint methods. Unlike Sprites and Images, Shape game objects do not have
setTint()ortintproperties. UsesetFillStyle(color, alpha)andsetStrokeStyle(lineWidth, color, alpha)instead. -
Polygon getBounds() incorrect with negative points. If any polygon points have negative coordinates,
getBounds()returns wrong values. UsePhaser.Geom.Polygon.GetAABB(polygon.geom)instead and adjust the returned Rectangle position.


