pixijs-math

PixiJS は、ライブラリ全体で変換、ヒットテスト、座標変換に使用される軽量な数学プリミティブ（Point、Matrix、形状クラス）を公開しています。ベクトル操作（add、dot、magnitude、reflect）と Rectangle の交差/合併ヘルパーを追加するには、pixi.js/math-extras をインポートします。

クイックスタート

const parent = new Container();
parent.position.set(100, 100);
parent.scale.set(2);
app.stage.addChild(parent);

const child = new Container();
child.position.set(50, 50);
parent.addChild(child);

const globalPt = child.toGlobal(new Point(0, 0));

const m = new Matrix()
  .translate(100, 50)
  .rotate(Math.PI / 4)
  .scale(2, 2);
const world = m.apply(new Point(10, 20));

const hitArea = new Rectangle(0, 0, 200, 100);
console.log(hitArea.contains(50, 50));

関連スキル: pixijs-scene-container（変換プロパティ）、pixijs-events（hitArea の使用）、pixijs-scene-core-concepts（Rectangle でのカリング）。

コアパターン

Point と ObservablePoint

Point は単純な {x, y} 値型です。ObservablePoint は x または y が変更されると、コールバックを発火します。Container の position、scale、pivot、origin、skew 内部で使用されます。

import { Point } from "pixi.js";

const p = new Point(10, 20);
p.set(30, 40); // 両方を設定
p.set(50); // x=50, y=50

const clone = p.clone();
console.log(p.equals(clone)); // true

p.copyFrom({ x: 1, y: 2 }); // any PointData を受け入れる

// Point.shared: 一時的なポイント、各アクセス時に (0,0) にリセット
const temp = Point.shared;
temp.set(100, 200);
// Point.shared への参照を保存しないでください

Container の position、scale、pivot、origin、skew のようなプロパティは ObservablePoint です。それらの .x または .y を設定すると、変換の再計算が自動的にトリガーされます。

import { Container } from "pixi.js";

const obj = new Container();
obj.position.set(100, 200); // オブザーバーをトリガー -> 変換を dirty とマーク
obj.position.x = 150; // これもオブザーバーをトリガー

Matrix（2D アフィン変換）

Matrix は 3x3 アフィン変換を表します。| a c tx | b d ty | 0 0 1 | 変換、スケール、回転、append、prepend、invert、decompose をサポートします。

import { Matrix, Point } from "pixi.js";

// 変換を構築
const m = new Matrix()
  .translate(100, 50)
  .rotate(Math.PI / 4)
  .scale(2, 2);

// ポイントを変換（ローカル -> 親スペース）
const local = new Point(10, 20);
const world = m.apply(local);

// 逆変換（親 -> ローカルスペース）
const backToLocal = m.applyInverse(world);

// マトリックスを結合
const a = new Matrix().translate(50, 0);
const b = new Matrix().rotate(Math.PI / 2);
a.append(b); // a = a * b

// 位置/スケール/回転/スキューに分解
const transform = {
  position: new Point(),
  scale: new Point(),
  pivot: new Point(),
  skew: new Point(),
  rotation: 0,
};
m.decompose(transform);
console.log(transform.rotation); // ~0.785 (PI/4)

// 共有一時マトリックス（各アクセス時にリセット）
const temp = Matrix.shared;
// IDENTITY は読み取り専用参照
const isDefault = m.equals(Matrix.IDENTITY);

Container経由の座標変換

Container は、座標変換のために toGlobal、toLocal、getGlobalPosition を提供します。

import { Container, Point } from "pixi.js";

const parent = new Container();
parent.position.set(100, 100);
parent.scale.set(2);

const child = new Container();
child.position.set(50, 50);
parent.addChild(child);

// 子のスペース内のローカルポイント -> グローバル（ワールド）スペース
const globalPt = child.toGlobal(new Point(0, 0));
// globalPt = { x: 200, y: 200 } (100 + 50*2, 100 + 50*2)

// グローバルポイント -> 子のローカルスペース
const localPt = child.toLocal(new Point(200, 200));
// localPt = { x: 0, y: 0 }

// 2つのコンテナ間で変換
const other = new Container();
other.position.set(300, 300);
const ptInOther = child.toLocal(new Point(10, 10), other);

形状とヒットテスト

Rectangle、Circle、Ellipse、Polygon、RoundedRectangle、Triangle はすべて点が形状内にあるテストのために contains(x, y) を実装しており、さらに getBounds(out?)と strokeContains(x, y, width, alignment?) があります。コンテナの hitArea として使用して、カスタム相互作用領域を作成できます。

import { Rectangle, Circle, Polygon, Container } from "pixi.js";

const rect = new Rectangle(0, 0, 200, 100);
rect.contains(50, 50); // true
rect.contains(300, 50); // false
rect.left; // 0
rect.right; // 200
rect.top; // 0
rect.bottom; // 100
rect.isEmpty(); // false (Rectangle.EMPTY は新しい空の rect を返す)

// ネイティブ Rectangle-to-Rectangle メソッド（math-extras は不要）
const other = new Rectangle(50, 50, 100, 100);
rect.containsRect(other); // true if `other` は完全に `rect` 内
rect.intersects(other); // boolean: オーバーラップするか?
rect.intersects(other, matrix); // `other` を変換した後のオーバーラップ

// ストローク ヒットテスト（alignment: 1 = inner、0.5 = centered、0 = outer）
rect.strokeContains(0, 50, 4); // true if (0,50) は 4px の中央配置ストロク上
const circle = new Circle(100, 100, 50);
circle.strokeContains(150, 100, 4, 1); // 内側配置ストロク チェック

// getBounds はすべての形状で機能（Rectangle を返す、out パラメータを受け入れる）
const bounds = circle.getBounds();
const reused = new Rectangle();
new Polygon([0, 0, 100, 0, 50, 100]).getBounds(reused);

// インタラクション用の hit area として使用
const button = new Container();
button.hitArea = new Rectangle(0, 0, 200, 50);
button.eventMode = "static";
button.on("pointerdown", () => {
  /* clicked */
});

ネイティブ Rectangle.intersects(other)（boolean を返す）と math-extras intersection(other)（オーバーラップ領域を記述する Rectangle を返す）を混同しないでください。

Rectangle レイアウトヘルパー

Rectangle には、UI/レイアウト、境界集約、ピクセルスナップで頻繁に使用される変更ヘルパーが付属しています。すべてチェーン用に this を返します。

import { Rectangle } from "pixi.js";

const r = new Rectangle(10, 10, 100, 50);

r.pad(5); // すべての辺で増加: x=5, y=5, w=110, h=60
r.pad(10, 4); // 水平/垂直パディングを分離
r.scale(2); // x、y、width、height に 2 を乗算

// fit は `this` を別の rect 内に収まるように縮小（クリップ）
const viewport = new Rectangle(0, 0, 200, 200);
new Rectangle(150, 150, 200, 200).fit(viewport); // -> 150, 150, 50, 50

// enlarge は `this` を別の rect を含むように拡張（境界集約）
const total = new Rectangle();
items.forEach((item) =>
  total.enlarge(new Rectangle().copyFromBounds(item.getBounds())),
);

// ceil はピクセルグリッドにスナップ（resolution: 1 = 整数ピクセル、2 = 半ピクセル）
new Rectangle(10.2, 10.6, 100.8, 100.4).ceil();

// Container/Mesh の境界オブジェクトを Rectangle に直接コピー
new Rectangle().copyFromBounds(container.getBounds());

Polygon

Polygon は 4つのコンストラクタ形式を受け入れます。フラット数値配列、ポイントのような オブジェクトの配列、またはスプレッド引数として渡されたどちらか。

import { Polygon, Point } from "pixi.js";

new Polygon([0, 0, 100, 0, 50, 100]); // フラット数値
new Polygon([new Point(0, 0), new Point(100, 0), new Point(50, 100)]); // PointData[]
new Polygon(0, 0, 100, 0, 50, 100); // スプレッド数値
new Polygon(new Point(0, 0), new Point(100, 0), new Point(50, 100)); // スプレッドポイント

const poly = new Polygon([0, 0, 100, 0, 100, 100, 0, 100]);
poly.points; // [0, 0, 100, 0, 100, 100, 0, 100]（変更可能なフラット配列）
poly.closePath; // デフォルトは true；false は開いたパスを生成
poly.startX; // 0  - 最初の頂点
poly.lastX; // 0  - 最後の頂点（y の場合は lastY）
poly.isClockwise(); // 靴ひも巻きテスト（SVG ホール検出に有用）

// ホール検出用 Polygon-in-polygon 包含
const outer = new Polygon([0, 0, 100, 0, 100, 100, 0, 100]);
const hole = new Polygon([25, 25, 75, 25, 75, 75, 25, 75]);
outer.containsPolygon(hole); // true

定数

import { DEG_TO_RAD, RAD_TO_DEG, PI_2 } from "pixi.js";

const angle = 45 * DEG_TO_RAD; // 0.785...
const degrees = angle * RAD_TO_DEG; // 45
const fullCircle = PI_2; // Math.PI * 2

型

• PointData - ほとんどの API で受け入れられる最小限の {x, y} インターフェース。座標の読み取りのみが必要なパラメータに型を指定する場合に使用します。
• PointLike - set()、copyFrom()、copyTo()、equals() で PointData を拡張します。Point と ObservablePoint の両方で実装されます。
• Size - レンダラー/キャンバス API で使用される { width, height } インターフェース。
• SHAPE_PRIMITIVE - 文字列リテラル合併: 'rectangle' | 'circle' | 'ellipse' | 'polygon' | 'roundedRectangle' | 'triangle'。すべての形状は type を公開しているため、instanceof なしで分岐できます。

import type { PointData } from "pixi.js";

function distance(a: PointData, b: PointData): number {
  const dx = a.x - b.x;
  const dy = a.y - b.y;
  return Math.sqrt(dx * dx + dy * dy);
}

math-extras（サイドエフェクトインポート）

import 'pixi.js/math-extras' は、プロトタイプ拡張を通じて Point、ObservablePoint、Rectangle にメソッドを追加します。デフォルトバンドルには含まれません。

import "pixi.js/math-extras";
import { Point } from "pixi.js";

Point / ObservablePoint ベクトルメソッド

すべてのメソッドは、割り当てを避けるために、オプションの out パラメータを受け入れます。out がない場合、新しい Point が返されます。

const a = new Point(3, 4);
const b = new Point(1, 2);

// 算術
const sum = a.add(b); // Point(4, 6)
const diff = a.subtract(b); // Point(2, 2)
const prod = a.multiply(b); // Point(3, 8) - コンポーネント単位
const scaled = a.multiplyScalar(2); // Point(6, 8)

// ドット積とクロス積
const dot = a.dot(b); // 11
const cross = a.cross(b); // 2 (3D クロスの z コンポーネント)

// 長さ
const len = a.magnitude(); // 5
const lenSq = a.magnitudeSquared(); // 25（比較に高速）

// 単位ベクトルに正規化
const unit = a.normalize(); // Point(0.6, 0.8)

// 射影と反射
const proj = a.project(b); // a を b に射影
const refl = a.reflect(new Point(0, 1)); // 法線で反射

// 回転
const rotated = a.rotate(Math.PI / 2); // 90 度回転

// 既存ポイントを再利用して割り当てを避ける
const out = new Point();
a.add(b, out); // 結果は out に書き込まれる

Rectangle 拡張メソッド

containsRect と intersects はネイティブ Rectangle メソッドです（上記参照）。math-extras は equals、intersection（オーバーラップ rect を返す）、union を追加します：

import "pixi.js/math-extras";
import { Rectangle } from "pixi.js";

const r1 = new Rectangle(0, 0, 100, 100);
const r2 = new Rectangle(50, 50, 100, 100);

r1.equals(r2); // false

const overlap = r1.intersection(r2); // Rectangle(50, 50, 50, 50)
const envelope = r1.union(r2); // Rectangle(0, 0, 150, 150)

// オプションの out パラメータ
const out = new Rectangle();
r1.intersection(r2, out);

ジオメトリユーティリティ関数

これらの関数は pixi.js/math-extras からエクスポートされており、メイン pixi.js エントリからではありません。

import {
  floatEqual,
  lineIntersection,
  segmentIntersection,
} from "pixi.js/math-extras";
import { Point } from "pixi.js";

// イプシロンベースの浮動小数点比較（デフォルトイプシロン: Number.EPSILON）
floatEqual(0.1 + 0.2, 0.3, 1e-10); // 合理的なイプシロンで true
floatEqual(1.0, 1.001, 0.01); // true（カスタムイプシロン）

// 無制限ラインインターセクション（平行の場合 {x: NaN, y: NaN} を返す）
const hit = lineIntersection(
  new Point(0, 0),
  new Point(10, 10), // ラインA
  new Point(10, 0),
  new Point(0, 10), // ラインB
); // Point(5, 5)
if (isNaN(hit.x)) {
  /* ラインは平行 */
}

// 境界付きセグメントインターセクション（セグメントが交差しない場合 {x: NaN, y: NaN} を返す）
const segHit = segmentIntersection(
  new Point(0, 0),
  new Point(10, 10),
  new Point(10, 0),
  new Point(0, 10),
); // Point(5, 5)
if (isNaN(segHit.x)) {
  /* セグメントは交差しない */
}

よくある間違い

高: @pixi/math からのインポート

誤り:

import { Point } from "@pixi/math";

正解:

import { Point } from "pixi.js";

v8 は単一の pixi.js パッケージを使用します。@pixi/math、@pixi/core などすべてのサブパッケージが削除されました。

中: ObservablePoint をオブザーバーをトリガーしないまま変更

誤り:

// 参照を置き換えると観察が失われる
let pos = container.position;
pos = new Point(100, 200); // container.position は変更されない

正解:

// その場で変更してオブザーバーをトリガー
container.position.set(100, 200);
// または
container.position.x = 100;
container.position.y = 200;
// または別のポイントからコピー
container.position.copyFrom(new Point(100, 200));

Container の position、scale、pivot、origin、skew は ObservablePoint です。それらの .x または .y を設定すると、コンテナの変換アップデートがトリガーされます。変数参照の再割り当てはコンテナを変更しません。常に、.set()、.copyFrom() を通じて、または元のオブジェクト上の直接プロパティ割り当てで、既存の ObservablePoint を変更します。

中: math-extras の拡張メソッドをインポートしない

誤り:

import { Point } from "pixi.js";
const p = new Point(1, 2);
p.add(new Point(3, 4)); // TypeError: p.add is not a function

正解:

import "pixi.js/math-extras";
import { Point } from "pixi.js";
const p = new Point(1, 2);
const sum = p.add(new Point(3, 4)); // 機能する

拡張数学ユーティリティ（Point の add、subtract、multiply、magnitude、normalize、dot、cross など；形状上の交差メソッド）には、明示的な import 'pixi.js/math-extras' が必要です。これらはデフォルトバンドルに含まれません。

中: 共有/一時オブジェクトへの参照を保存

誤り:

const myPoint = Point.shared;
myPoint.set(100, 200);
// ... 後で ...
console.log(myPoint.x); // 0（次のアクセス時にリセット）

正解:

const myPoint = new Point();
myPoint.copyFrom(Point.shared.set(100, 200));
// または単に
const myPoint = new Point(100, 200);

Point.shared と Matrix.shared は、アクセスされるたびにゼロ/アイデンティティにリセットされます。それらは単一式内の 1回限りの計算に存在します。それらへの参照を保存しないでください。

API リファレンス

• Point
• ObservablePoint
• Matrix
• Rectangle
• Circle
• Ellipse
• Polygon
• RoundedRectangle
• Triangle
• DEG_TO_RAD