Graphics And Shapes

phaserjs/phaser/skills/graphics-and-shapes

作者 phaserjs02d8931b626d9764c133cbb3fbf99966c03c757c無授權條款收錄於 2026年10月9日更新於 2026年10月9日

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.

AI 產生的概覽

介紹在 Phaser 4 中使用 Graphics 遊戲物件與 Shape 遊戲物件繪製形狀與圖形的參考文件。

功能
本技能說明 Phaser 4 中兩種不需紋理即可繪製基本圖形的方式:命令式的 Graphics 遊戲物件,以及獨立的 Shape 遊戲物件。內容涵蓋填色與描邊樣式、漸層、路徑、圓弧、多邊形、圓角矩形、畫布變換、紋理產生以及所有內建形狀類型。此外也列出 API 簽章、各形狀專屬方法與常見陷阱。
適用情境
適用於撰寫繪製線條、矩形、圓形、圓弧、多邊形、格線或等距形狀的 Phaser 4 程式碼時。也適合在 Graphics 與 Shape 物件之間做選擇,或排查樣式、角度單位與效能問題時使用。
執行需求
不需指令碼或資源,僅為純說明性參考。使用前提是已有 Phaser 4 專案並了解其遊戲物件 API。

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 Graphicsconst 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 objectsconst 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* methodgfx.fillStyle(0xff0000, 1);          // (color, alpha)
// Line style — call before any stroke* methodgfx.lineStyle(4, 0x00ff00, 1);       // (width, color, alpha)
// Gradient fill (WebGL only) — 4 corner colorsgfx.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();
// Rectanglesgfx.fillStyle(0x0000ff);gfx.fillRect(x, y, width, height);gfx.lineStyle(2, 0xffffff);gfx.strokeRect(x, y, width, height);
// Circlesgfx.fillCircle(x, y, radius);gfx.strokeCircle(x, y, radius);
// Ellipsesgfx.fillEllipse(x, y, width, height, smoothness);gfx.strokeEllipse(x, y, width, height, smoothness);   // smoothness defaults to 32
// Trianglesgfx.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
// Linesgfx.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 radiusgfx.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 pathgfx.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 pathgfx.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 slicegfx.slice(200, 200, 80, 0, Math.PI / 3, false);     // auto begins/closes pathgfx.fillPath();
// Stroke/fill from point arraysgfx.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);           // radiansgfx.scaleCanvas(2, 2);gfx.fillStyle(0xff0000);gfx.fillRect(0, 0, 50, 50);     // draws at translated/rotated/scaled positiongfx.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 texturethis.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 setFillStyleconst rect = this.add.rectangle(200, 150, 100, 80, 0xff0000, 1);
// Change fill laterrect.setFillStyle(0x00ff00, 0.8);
// Add stroke (not set by default)rect.setStrokeStyle(3, 0xffffff, 1);  // (lineWidth, color, alpha)
// Remove fill or strokerect.setFillStyle();    // no args = isFilled becomes falserect.setStrokeStyle();  // no args = isStroked becomes false
// Direct property accessrect.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 MethodClassParameters (after x, y)FillStrokeNotes
this.add.arc(x, y, radius, startAngle, endAngle, anticlockwise, fillColor, fillAlpha)Arcradius=128, startAngle=0, endAngle=360 (degrees), anticlockwise=falseYesYesAngles in degrees. Full circle by default.
this.add.circle(x, y, radius, fillColor, fillAlpha)Arcradius=128YesYesAlias for Arc with 0-360 angles.
this.add.curve(x, y, curve, fillColor, fillAlpha)CurvePhaser.Curves.Curve objectYesYesHas smoothness property / setSmoothness().
this.add.ellipse(x, y, width, height, fillColor, fillAlpha)Ellipsewidth=128, height=128YesYesEqual w/h renders as circle. Has smoothness.
this.add.grid(x, y, width, height, cellWidth, cellHeight, fillColor, fillAlpha, outlineFillColor, outlineFillAlpha)Gridwidth=128, height=128, cellWidth=32, cellHeight=32YesNoHas altFillColor/altFillAlpha for checkerboard. Outline via outlineFillColor.
this.add.isobox(x, y, size, height, fillTop, fillLeft, fillRight)IsoBoxsize=48, height=32, fillTop=0xeeeeee, fillLeft=0x999999, fillRight=0xccccccYesNoIsometric box. showTop, showLeft, showRight, projection.
this.add.isotriangle(x, y, size, height, reversed, fillTop, fillLeft, fillRight)IsoTrianglesize=48, height=32, reversed=falseYesNoIsometric pyramid. showTop, showLeft, showRight, projection, reversed.
this.add.line(x, y, x1, y1, x2, y2, strokeColor, strokeAlpha)Linex1=0, y1=0, x2=128, y2=0NoYesStroke only. Constructor takes stroke color (not fill).
this.add.polygon(x, y, points, fillColor, fillAlpha)Polygonpoints (various formats)YesYesPoints: array of Vec2, [x,y,...] pairs, or [[x,y],...].
this.add.rectangle(x, y, width, height, fillColor, fillAlpha)Rectanglewidth=128, height=128YesYesChange size via width/height properties.
this.add.star(x, y, points, innerRadius, outerRadius, fillColor, fillAlpha)Starpoints=5, innerRadius=32, outerRadius=64YesYes4 points = diamond. More points = spikier.
this.add.triangle(x, y, x1, y1, x2, y2, x3, y3, fillColor, fillAlpha)Trianglex1=0,y1=128, x2=64,y2=0, x3=128,y3=128YesYesAlways closed. Use Polygon for open shapes.

API Quick Reference — Graphics Methods

Style Methods

MethodSignatureNotes
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

MethodSignatureNotes
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

MethodSignature
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

MethodSignature
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

MethodSignatureNotes
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

MethodSignatureNotes
setFillStyle(color?, alpha=1)No args = disable fill
setStrokeStyle(lineWidth?, color?, alpha=1)No args = disable stroke

Gotchas

  1. 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.

  2. Set style BEFORE drawing. fillStyle and lineStyle must be called before the corresponding fill/stroke method. They are not retroactive.

  3. 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.

  4. Shape isFilled/isStroked defaults. Shapes created with a fillColor parameter have isFilled = true. But isStroked defaults to false — you must call setStrokeStyle() explicitly.

  5. Line shape is stroke-only. The Line shape does not support fill. Its constructor takes strokeColor/strokeAlpha (not fillColor).

  6. IsoBox/IsoTriangle are fill-only. These shapes cannot be stroked. Grid supports outline strokes via its constructor parameters (outlineFillColor, outlineFillAlpha).

  7. generateTexture uses Canvas API. Gradient fills (fillGradientStyle) will not appear in textures generated with generateTexture. Only Canvas-compatible features are captured.

  8. 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.

  9. 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.

  10. 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.

  11. 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.

  12. 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.

  13. 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

js
const star = this.add.star(400, 300, 5, 32, 64, 0xffff00);
star.setPoints(8);          // change number of pointsstar.setInnerRadius(20);    // change inner radiusstar.setOuterRadius(80);    // change outer radius

Line (Tapering)

js
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)

js
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 strokegrid.strokeOutside = true;             // stroke the outer bordergrid.strokeOutsideIncomplete = false;  // skip partial cells on right/bottom edges
// Cell padding (default 0.5) — gutter between cells is 2x this valuegrid.cellPadding = 1;

IsoBox / IsoTriangle

js
const box = this.add.isobox(200, 200, 48, 32, 0xeeeeee, 0x999999, 0xcccccc);
box.setFaces(true, true, false);  // showTop, showLeft, showRightbox.setProjection(4);             // isometric projection value
const tri = this.add.isotriangle(400, 200, 48, 32, false, 0xeeeeee, 0x999999, 0xcccccc);
tri.setReversed(true);            // flip upside downtri.setFaces(true, true, true);tri.setProjection(4);

Source File Map

FilePurpose
src/gameobjects/graphics/Graphics.jsGraphics class — all drawing methods
src/gameobjects/graphics/GraphicsFactory.jsthis.add.graphics() factory
src/gameobjects/graphics/Commands.jsInternal command constants for the command buffer
src/gameobjects/graphics/GraphicsRender.jsRender dispatch
src/gameobjects/shape/Shape.jsBase Shape class (fill/stroke/path data, setFillStyle, setStrokeStyle)
src/gameobjects/shape/arc/Arc.jsArc shape (also used for circle)
src/gameobjects/shape/arc/ArcFactory.jsthis.add.arc() and this.add.circle() factories
src/gameobjects/shape/curve/Curve.jsCurve shape
src/gameobjects/shape/curve/CurveFactory.jsthis.add.curve() factory
src/gameobjects/shape/ellipse/Ellipse.jsEllipse shape
src/gameobjects/shape/ellipse/EllipseFactory.jsthis.add.ellipse() factory
src/gameobjects/shape/grid/Grid.jsGrid shape
src/gameobjects/shape/grid/GridFactory.jsthis.add.grid() factory
src/gameobjects/shape/isobox/IsoBox.jsIsoBox shape
src/gameobjects/shape/isobox/IsoBoxFactory.jsthis.add.isobox() factory
src/gameobjects/shape/isotriangle/IsoTriangle.jsIsoTriangle shape
src/gameobjects/shape/isotriangle/IsoTriangleFactory.jsthis.add.isotriangle() factory
src/gameobjects/shape/line/Line.jsLine shape
src/gameobjects/shape/line/LineFactory.jsthis.add.line() factory
src/gameobjects/shape/polygon/Polygon.jsPolygon shape
src/gameobjects/shape/polygon/PolygonFactory.jsthis.add.polygon() factory
src/gameobjects/shape/rectangle/Rectangle.jsRectangle shape
src/gameobjects/shape/rectangle/RectangleFactory.jsthis.add.rectangle() factory
src/gameobjects/shape/star/Star.jsStar shape
src/gameobjects/shape/star/StarFactory.jsthis.add.star() factory
src/gameobjects/shape/triangle/Triangle.jsTriangle shape
src/gameobjects/shape/triangle/TriangleFactory.jsthis.add.triangle() factory

來源與署名

來源:phaserjs/phaser位於skills/graphics-and-shapes提交02d8931

授權條款: 無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架