graphics-and-shapes

Phaser 4 — グラフィックスとシェイプ

Graphics ゲームオブジェクトによる描画プリミティブと、Shape ゲームオブジェクト（Arc、Curve、Ellipse、Grid、IsoBox、IsoTriangle、Line、Polygon、Rectangle、Star、Triangle）の使用。

関連スキル: sprites-and-images.md、game-object-components.md

---

クイックスタート

// 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);

---

基本概念 — Graphics と Shape オブジェクト

Phaser では、テクスチャを使わずにプリミティブをレンダリングするための 2 つのアプローチを提供しています。

Graphics ゲームオブジェクト

this.add.graphics() で作成します。命令型の描画面であり、fillRect、strokeCircle、beginPath/lineTo/strokePath などのメソッドを呼び出して、毎フレーム再生されるコマンドバッファを構築します。

• ファクトリ: this.add.graphics(config?)。ここで config は { x?, y?, lineStyle?, fillStyle? } です。
• パス、円弧、グラデーション、角丸矩形、キャンバストランスフォーム（translateCanvas、scaleCanvas、rotateCanvas）、および save/restore をサポートします。
• generateTexture(key, width, height) を使って、描画からテクスチャを生成できます。
• レンダリングコストが高く、特に複雑なシェイプでは顕著です。独自の WebGL シェーダーを使用します。Graphics オブジェクトをまとめてグループ化すると、バッチフラッシュを最小限に抑えられます。
• コンポーネント: AlphaSingle、BlendMode、Depth、Lighting、Mask、RenderNodes、Transform、Visible、ScrollFactor。
• Origin や GetBounds は含まれません（位置はオプションまたは setPosition で設定します）。

Shape ゲームオブジェクト

基底クラス Shape を継承する個別のゲームオブジェクト（Arc、Rectangle、Star など）です。それぞれが事前計算されたパスデータを持つ、あらかじめ定義された 1 つの図形をレンダリングします。

• 専用のファクトリメソッドで作成します: this.add.rectangle(...)、this.add.circle(...) など。
• 完全な機能を備えたゲームオブジェクトです。トゥイーン、スケーリング、グループやコンテナへの追加、入力や物理の有効化が可能です。
• setFillStyle(color, alpha) と setStrokeStyle(lineWidth, color, alpha) でスタイルを設定します。
• 効率的なレンダリングのために、Graphics と同じ WebGL バッチを共有します。
• グラデーション、パスの詳細しきい値、キャンバストランスフォームはサポートしていません。
• コンポーネント: AlphaSingle、BlendMode、Depth、GetBounds、Lighting、Mask、Origin、RenderNodes、ScrollFactor、Transform、Visible。
• Origin と GetBounds を含みます（Graphics とは異なります）。

どちらを使うべきか:

• Graphics は、動的な描画、複雑なパス、1 つのオブジェクト上の複数のシェイプ、グラデーション、またはテクスチャの生成に使用します。
• Shape オブジェクト は、個別の UI 要素、シンプルなインジケーター、物理を有効にしたシェイプ、またはゲームオブジェクトの機能（原点、境界、入力）の恩恵を受けるものに使用します。

---

一般的なパターン

塗りつぶしと線のスタイル（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);

描画プリミティブ（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);

角丸矩形

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 });

パスの描画

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 シェイプヘルパー

Graphics には、Phaser.Geom オブジェクトを直接受け取る便利なメソッドがあります:

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

キャンバストランスフォーム（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();

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');

注: fillGradientStyle は生成されたテクスチャには表示されません（Canvas API の制限）。

Shape オブジェクト — 塗りつぶしと線

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

---

すべての図形タイプ

ファクトリメソッド	クラス	パラメータ（x, y の後）	塗りつぶし	ストローク	備考
this.add.arc(x, y, radius, startAngle, endAngle, anticlockwise, fillColor, fillAlpha)	Arc	radius=128, startAngle=0, endAngle=360（度）、anticlockwise=false	はい	はい	角度は度単位。デフォルトでは完全な円。
this.add.circle(x, y, radius, fillColor, fillAlpha)	Arc	radius=128	はい	はい	0～360 度の角度を持つ Arc のエイリアス。
this.add.curve(x, y, curve, fillColor, fillAlpha)	Curve	Phaser.Curves.Curve オブジェクト	はい	はい	smoothness プロパティ / setSmoothness() があります。
this.add.ellipse(x, y, width, height, fillColor, fillAlpha)	Ellipse	width=128, height=128	はい	はい	幅と高さが等しい場合は円として描画されます。smoothness があります。
this.add.grid(x, y, width, height, cellWidth, cellHeight, fillColor, fillAlpha, outlineFillColor, outlineFillAlpha)	Grid	width=128, height=128, cellWidth=32, cellHeight=32	はい	いいえ	チェッカーボード用の altFillColor/altFillAlpha があります。アウトラインは outlineFillColor で指定します。
this.add.isobox(x, y, size, height, fillTop, fillLeft, fillRight)	IsoBox	size=48, height=32, fillTop=0xeeeeee, fillLeft=0x999999, fillRight=0xcccccc	はい	いいえ	アイソメトリックボックス。showTop、showLeft、showRight、projection があります。
this.add.isotriangle(x, y, size, height, reversed, fillTop, fillLeft, fillRight)	IsoTriangle	size=48, height=32, reversed=false	はい	いいえ	アイソメトリックピラミッド。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	いいえ	はい	ストロークのみ。コンストラクタはストローク色（塗りつぶしではない）を取ります。
this.add.polygon(x, y, points, fillColor, fillAlpha)	Polygon	points（さまざまな形式）	はい	はい	ポイント: Vec2 の配列、[x,y,...] のペア、または [[x,y],...]。
this.add.rectangle(x, y, width, height, fillColor, fillAlpha)	Rectangle	width=128, height=128	はい	はい	width/height プロパティでサイズを変更します。
this.add.star(x, y, points, innerRadius, outerRadius, fillColor, fillAlpha)	Star	points=5, innerRadius=32, outerRadius=64	はい	はい	4 ポイント = ひし形。ポイントが多いほど尖ります。
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	はい	はい	常に閉じられます。開いた図形には Polygon を使用してください。

---

API クイックリファレンス — Graphics メソッド

スタイルメソッド

メソッド	シグネチャ	備考
fillStyle	(color, alpha=1)	以降の fill 呼び出しの塗りつぶしを設定します
lineStyle	(lineWidth, color, alpha=1)	以降の stroke 呼び出しのストロークを設定します
fillGradientStyle	(tl, tr, bl, br, aTL=1, aTR, aBL, aBR)	WebGL のみ。4 隅の色。
lineGradientStyle	(lineWidth, tl, tr, bl, br, alpha=1)	WebGL のみ。
setDefaultStyles	(options)	{ lineStyle: {width,color,alpha}, fillStyle: {color,alpha} } で設定します

パスメソッド

メソッド	シグネチャ	備考
beginPath	()	新しいパスを開始します
moveTo	(x, y)	描画位置を移動します
lineTo	(x, y)	指定位置まで線を引きます
arc	(x, y, radius, startAngle, endAngle, anticlockwise=false, overshoot=0)	角度はラジアン単位
closePath	()	現在のパスを閉じます
fillPath / fill	()	現在のパスを塗りつぶします
strokePath / stroke	()	現在のパスをストロークします
slice	(x, y, radius, startAngle, endAngle, anticlockwise=false, overshoot=0)	パイスライス。パスを自動的に開始/閉じます。角度はラジアン単位。

図形描画メソッド

メソッド	シグネチャ
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 図形メソッド

メソッド	シグネチャ
fillRectShape	(rect)
strokeRectShape	(rect)
fillCircleShape	(circle)
strokeCircleShape	(circle)
fillTriangleShape	(triangle)
strokeTriangleShape	(triangle)
strokeLineShape	(line)
fillEllipseShape	(ellipse, smoothness=32)
strokeEllipseShape	(ellipse, smoothness=32)

変換および状態メソッド

メソッド	シグネチャ	備考
translateCanvas	(x, y)	以降の描画を平行移動します
scaleCanvas	(x, y)	以降の描画を拡大縮小します
rotateCanvas	(radians)	以降の描画を回転します
save	()	状態をスタックにプッシュします
restore	()	状態をスタックからポップします
clear	()	コマンドバッファをクリアし、デフォルトのスタイルにリセットします
generateTexture	(key, width, height)	Texture にベイクします（Canvas API）

図形基底クラスのメソッド

メソッド	シグネチャ	備考
setFillStyle	(color?, alpha=1)	引数なし = 塗りつぶしを無効化
setStrokeStyle	(lineWidth?, color?, alpha=1)	引数なし = ストロークを無効化

---

注意点

1. Graphics の arc() はラジアン、Shape の arc ファクトリは度を使用します。 Graphics の arc メソッドは開始/終了角度をラジアンで受け取ります。this.add.arc() ファクトリは度 (0～360) で受け取ります。これらを混同することが最もよくあるバグです。

2. スタイルは描画する前に設定してください。 fillStyle と lineStyle は、対応する fill/stroke メソッドの前に呼び出す必要があります。これらは遡って適用されるものではありません。

3. Graphics には Origin や GetBounds がありません。 Shape オブジェクトとは異なり、Graphics には Origin や GetBounds コンポーネントが含まれていません。代わりに setPosition(x, y) と displayOriginX/displayOriginY を使用してください。

4. Shape の isFilled/isStroked のデフォルト値。 fillColor パラメータを指定して作成した Shape は isFilled = true になります。しかし isStroked のデフォルトは false です。明示的に setStrokeStyle() を呼び出す必要があります。

5. Line シェイプはストローク専用です。 Line シェイプは塗りつぶしをサポートしていません。そのコンストラクタは strokeColor/strokeAlpha を受け取ります (fillColor ではありません)。

6. IsoBox/IsoTriangle は塗りつぶし専用です。 これらのシェイプはストロークできません。Grid はコンストラクタパラメータ (outlineFillColor、outlineFillAlpha) を介してアウトラインのストロークをサポートしています。

7. generateTexture は Canvas API を使用します。 グラデーション塗りつぶし (fillGradientStyle) は generateTexture で生成されたテクスチャには表示されません。Canvas 互換の機能のみがキャプチャされます。

8. パフォーマンス: Graphics は高コストです。 毎フレーム、コマンドバッファが再生され、ジオメトリが再構築されます (WebGL はポリゴンに分解します)。静的なシェイプには、generateTexture を呼び出して、その結果のテクスチャを Sprite として使用してください。Graphics オブジェクトをまとめてグループ化して、バッチの途切れを最小限に抑えてください。

9. pathDetailThreshold (v4 の新機能)。 Graphics には pathDetailThreshold プロパティがあります (デフォルトは -1 で、設定 render.pathDetailThreshold を使用します)。このピクセルしきい値を下回るパスセグメントは結合され、複雑なシェイプでの WebGL パフォーマンスが向上します。画面ピクセルで評価されるため、ズームインすると詳細が現れます。

10. 角丸矩形の半径はオブジェクトまたは数値にできます。 角ごとに制御するには { tl, tr, bl, br } を渡してください。負の値は凹んだ角を作成します。省略した場合のデフォルトは 20 です。

11. Shape の closePath プロパティ。 Shape オブジェクトの closePath プロパティ (デフォルトは true) は、ストロークパスを自動的に閉じるかどうかを制御します。開いたストロークのシェイプにするには false に設定してください。

12. Shape オブジェクトは tint メソッドをサポートしていません。 Sprite や Image とは異なり、Shape ゲームオブジェクトには setTint() や tint プロパティがありません。代わりに setFillStyle(color, alpha) と setStrokeStyle(lineWidth, color, alpha) を使用してください。

13. Polygon の getBounds() は負の座標の点で不正確になります。 ポリゴンの点に負の座標が含まれている場合、getBounds() は誤った値を返します。代わりに Phaser.Geom.Polygon.GetAABB(polygon.geom) を使用し、返された Rectangle の位置を調整してください。

---

シェイプ固有のメソッド

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 (テーパー)

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 (交互の色、ストローク、パディング)

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

---

ソースファイルマップ

ファイル	目的
src/gameobjects/graphics/Graphics.js	Graphics クラス（すべての描画メソッド）
src/gameobjects/graphics/GraphicsFactory.js	this.add.graphics() ファクトリー
src/gameobjects/graphics/Commands.js	コマンドバッファー用の内部コマンド定数
src/gameobjects/graphics/GraphicsRender.js	レンダリングのディスパッチ
src/gameobjects/shape/Shape.js	基底 Shape クラス（fill/stroke/path データ、setFillStyle、setStrokeStyle）
src/gameobjects/shape/arc/Arc.js	Arc シェイプ（円にも使用されます）
src/gameobjects/shape/arc/ArcFactory.js	this.add.arc() および this.add.circle() ファクトリー
src/gameobjects/shape/curve/Curve.js	Curve シェイプ
src/gameobjects/shape/curve/CurveFactory.js	this.add.curve() ファクトリー
src/gameobjects/shape/ellipse/Ellipse.js	Ellipse シェイプ
src/gameobjects/shape/ellipse/EllipseFactory.js	this.add.ellipse() ファクトリー
src/gameobjects/shape/grid/Grid.js	Grid シェイプ
src/gameobjects/shape/grid/GridFactory.js	this.add.grid() ファクトリー
src/gameobjects/shape/isobox/IsoBox.js	IsoBox シェイプ
src/gameobjects/shape/isobox/IsoBoxFactory.js	this.add.isobox() ファクトリー
src/gameobjects/shape/isotriangle/IsoTriangle.js	IsoTriangle シェイプ
src/gameobjects/shape/isotriangle/IsoTriangleFactory.js	this.add.isotriangle() ファクトリー
src/gameobjects/shape/line/Line.js	Line シェイプ
src/gameobjects/shape/line/LineFactory.js	this.add.line() ファクトリー
src/gameobjects/shape/polygon/Polygon.js	Polygon シェイプ
src/gameobjects/shape/polygon/PolygonFactory.js	this.add.polygon() ファクトリー
src/gameobjects/shape/rectangle/Rectangle.js	Rectangle シェイプ
src/gameobjects/shape/rectangle/RectangleFactory.js	this.add.rectangle() ファクトリー
src/gameobjects/shape/star/Star.js	Star シェイプ
src/gameobjects/shape/star/StarFactory.js	this.add.star() ファクトリー
src/gameobjects/shape/triangle/Triangle.js	Triangle シェイプ
src/gameobjects/shape/triangle/TriangleFactory.js	this.add.triangle() ファクトリー