playcanvas-engine

PlayCanvas エンジンスキル

エンティティ・コンポーネントアーキテクチャ、ビジュアルエディターとの統合、パフォーマンス重視の設計を備えた、軽量な WebGL/WebGPU ゲームエンジンです。

このスキルを使う場面

次のような語句が出てきた場合に、このスキルを使用します。

• 「PlayCanvas エンジン」
• 「WebGL ゲームエンジン」
• 「エンティティ・コンポーネントシステム」
• 「PlayCanvas アプリケーション」
• 「3D ブラウザーゲーム」
• 「オンライン 3D エディター」
• 「軽量 3D エンジン」
• エディターを中心としたワークフローが必要な場合

次のものと比較してください。

• Three.js：より低レベルで柔軟性がありますが、セットアップがより必要です
• Babylon.js：機能が豊富ですが、より重く、エディターはあるものの成熟度は劣ります
• A-Frame：VR に特化し、宣言的な HTML アプローチを採用しています
• 次の場合は PlayCanvas を使用します：ゲームプロジェクト、エディターを中心としたワークフロー、パフォーマンスが重要なアプリ

---

基本概念

1. アプリケーション

ルートとなる PlayCanvas アプリケーションがレンダリングループを管理します。

import * as pc from 'playcanvas';

// Create canvas
const canvas = document.createElement('canvas');
document.body.appendChild(canvas);

// Create application
const app = new pc.Application(canvas, {
  keyboard: new pc.Keyboard(window),
  mouse: new pc.Mouse(canvas),
  touch: new pc.TouchDevice(canvas),
  gamepads: new pc.GamePads()
});

// Configure canvas
app.setCanvasFillMode(pc.FILLMODE_FILL_WINDOW);
app.setCanvasResolution(pc.RESOLUTION_AUTO);

// Handle resize
window.addEventListener('resize', () => app.resizeCanvas());

// Start the application
app.start();

---

2. エンティティ・コンポーネントシステム

PlayCanvas は ECS アーキテクチャを使用します。エンティティはコンポーネントを含みます。

// Create entity
const entity = new pc.Entity('myEntity');

// Add to scene hierarchy
app.root.addChild(entity);

// Add components
entity.addComponent('model', {
  type: 'box'
});

entity.addComponent('script');

// Transform
entity.setPosition(0, 1, 0);
entity.setEulerAngles(0, 45, 0);
entity.setLocalScale(2, 2, 2);

// Parent-child hierarchy
const parent = new pc.Entity('parent');
const child = new pc.Entity('child');
parent.addChild(child);

---

3. 更新ループ

アプリケーションは更新ループ中にイベントを発生させます。

app.on('update', (dt) => {
  // dt is delta time in seconds
  entity.rotate(0, 10 * dt, 0);
});

app.on('prerender', () => {
  // Before rendering
});

app.on('postrender', () => {
  // After rendering
});

---

4. コンポーネント

基本的なコンポーネントによって、エンティティの機能を拡張します。

モデルコンポーネント：

entity.addComponent('model', {
  type: 'box',           // 'box', 'sphere', 'cylinder', 'cone', 'capsule', 'asset'
  material: material,
  castShadows: true,
  receiveShadows: true
});

カメラコンポーネント：

entity.addComponent('camera', {
  clearColor: new pc.Color(0.1, 0.2, 0.3),
  fov: 45,
  nearClip: 0.1,
  farClip: 1000,
  projection: pc.PROJECTION_PERSPECTIVE  // or PROJECTION_ORTHOGRAPHIC
});

ライトコンポーネント：

entity.addComponent('light', {
  type: pc.LIGHTTYPE_DIRECTIONAL,  // DIRECTIONAL, POINT, SPOT
  color: new pc.Color(1, 1, 1),
  intensity: 1,
  castShadows: true,
  shadowDistance: 50
});

剛体コンポーネント（物理演算が必要です）：

entity.addComponent('rigidbody', {
  type: pc.BODYTYPE_DYNAMIC,  // STATIC, DYNAMIC, KINEMATIC
  mass: 1,
  friction: 0.5,
  restitution: 0.3
});

entity.addComponent('collision', {
  type: 'box',
  halfExtents: new pc.Vec3(0.5, 0.5, 0.5)
});

---

よく使われるパターン

パターン 1：基本的なシーンのセットアップ

カメラ、ライト、モデルを含む完全なシーンを作成します。

import * as pc from 'playcanvas';

// Initialize application
const canvas = document.createElement('canvas');
document.body.appendChild(canvas);

const app = new pc.Application(canvas);
app.setCanvasFillMode(pc.FILLMODE_FILL_WINDOW);
app.setCanvasResolution(pc.RESOLUTION_AUTO);
window.addEventListener('resize', () => app.resizeCanvas());

// Create camera
const camera = new pc.Entity('camera');
camera.addComponent('camera', {
  clearColor: new pc.Color(0.2, 0.3, 0.4)
});
camera.setPosition(0, 2, 5);
camera.lookAt(0, 0, 0);
app.root.addChild(camera);

// Create directional light
const light = new pc.Entity('light');
light.addComponent('light', {
  type: pc.LIGHTTYPE_DIRECTIONAL,
  castShadows: true
});
light.setEulerAngles(45, 30, 0);
app.root.addChild(light);

// Create ground
const ground = new pc.Entity('ground');
ground.addComponent('model', {
  type: 'plane'
});
ground.setLocalScale(10, 1, 10);
app.root.addChild(ground);

// Create cube
const cube = new pc.Entity('cube');
cube.addComponent('model', {
  type: 'box',
  castShadows: true
});
cube.setPosition(0, 1, 0);
app.root.addChild(cube);

// Animate cube
app.on('update', (dt) => {
  cube.rotate(10 * dt, 20 * dt, 30 * dt);
});

app.start();

---

パターン 2：GLTF モデルの読み込み

アセット管理を使用して外部の 3D モデルを読み込みます。

// Create asset for model
const modelAsset = new pc.Asset('model', 'container', {
  url: '/models/character.glb'
});

// Add to asset registry
app.assets.add(modelAsset);

// Load asset
modelAsset.ready((asset) => {
  // Create entity from loaded model
  const entity = asset.resource.instantiateRenderEntity();

  app.root.addChild(entity);

  // Scale and position
  entity.setLocalScale(2, 2, 2);
  entity.setPosition(0, 0, 0);
});

app.assets.load(modelAsset);

エラー処理を含む場合：

modelAsset.ready((asset) => {
  console.log('Model loaded:', asset.name);
  const entity = asset.resource.instantiateRenderEntity();
  app.root.addChild(entity);
});

modelAsset.on('error', (err) => {
  console.error('Failed to load model:', err);
});

app.assets.load(modelAsset);

---

パターン 3：マテリアルとテクスチャ

PBR ワークフローでカスタムマテリアルを作成します。

// Create material
const material = new pc.StandardMaterial();
material.diffuse = new pc.Color(1, 0, 0);  // Red
material.metalness = 0.5;
material.gloss = 0.8;
material.update();

// Apply to entity
entity.model.material = material;

// With textures
const textureAsset = new pc.Asset('diffuse', 'texture', {
  url: '/textures/brick_diffuse.jpg'
});

app.assets.add(textureAsset);
app.assets.load(textureAsset);

textureAsset.ready((asset) => {
  material.diffuseMap = asset.resource;
  material.update();
});

// PBR material with all maps
const pbrMaterial = new pc.StandardMaterial();

// Load all textures
const textures = {
  diffuse: '/textures/albedo.jpg',
  normal: '/textures/normal.jpg',
  metalness: '/textures/metalness.jpg',
  gloss: '/textures/roughness.jpg',
  ao: '/textures/ao.jpg'
};

Object.keys(textures).forEach(key => {
  const asset = new pc.Asset(key, 'texture', { url: textures[key] });
  app.assets.add(asset);

  asset.ready((loadedAsset) => {
    switch(key) {
      case 'diffuse':
        pbrMaterial.diffuseMap = loadedAsset.resource;
        break;
      case 'normal':
        pbrMaterial.normalMap = loadedAsset.resource;
        break;
      case 'metalness':
        pbrMaterial.metalnessMap = loadedAsset.resource;
        break;
      case 'gloss':
        pbrMaterial.glossMap = loadedAsset.resource;
        break;
      case 'ao':
        pbrMaterial.aoMap = loadedAsset.resource;
        break;
    }
    pbrMaterial.update();
  });

  app.assets.load(asset);
});

---

パターン 4：物理演算の統合

物理シミュレーションに Ammo.js を使用します。

import * as pc from 'playcanvas';

// Initialize with Ammo.js
const app = new pc.Application(canvas, {
  keyboard: new pc.Keyboard(window),
  mouse: new pc.Mouse(canvas)
});

// Load Ammo.js
const ammoScript = document.createElement('script');
ammoScript.src = 'https://cdn.jsdelivr.net/npm/[email protected]/ammo.js';
document.body.appendChild(ammoScript);

ammoScript.onload = () => {
  Ammo().then((AmmoLib) => {
    window.Ammo = AmmoLib;

    // Create static ground
    const ground = new pc.Entity('ground');
    ground.addComponent('model', { type: 'plane' });
    ground.setLocalScale(10, 1, 10);

    ground.addComponent('rigidbody', {
      type: pc.BODYTYPE_STATIC
    });

    ground.addComponent('collision', {
      type: 'box',
      halfExtents: new pc.Vec3(5, 0.1, 5)
    });

    app.root.addChild(ground);

    // Create dynamic cube
    const cube = new pc.Entity('cube');
    cube.addComponent('model', { type: 'box' });
    cube.setPosition(0, 5, 0);

    cube.addComponent('rigidbody', {
      type: pc.BODYTYPE_DYNAMIC,
      mass: 1,
      friction: 0.5,
      restitution: 0.5
    });

    cube.addComponent('collision', {
      type: 'box',
      halfExtents: new pc.Vec3(0.5, 0.5, 0.5)
    });

    app.root.addChild(cube);

    // Apply force
    cube.rigidbody.applyForce(10, 0, 0);
    cube.rigidbody.applyTorque(0, 10, 0);

    app.start();
  });
};

---

パターン 5：カスタムスクリプト

再利用可能なスクリプトコンポーネントを作成します。

// Define script class
const RotateScript = pc.createScript('rotate');

// Script attributes (editor-exposed)
RotateScript.attributes.add('speed', {
  type: 'number',
  default: 10,
  title: 'Rotation Speed'
});

RotateScript.attributes.add('axis', {
  type: 'vec3',
  default: [0, 1, 0],
  title: 'Rotation Axis'
});

// Initialize method
RotateScript.prototype.initialize = function() {
  console.log('RotateScript initialized');
};

// Update method (called every frame)
RotateScript.prototype.update = function(dt) {
  this.entity.rotate(
    this.axis.x * this.speed * dt,
    this.axis.y * this.speed * dt,
    this.axis.z * this.speed * dt
  );
};

// Cleanup
RotateScript.prototype.destroy = function() {
  console.log('RotateScript destroyed');
};

// Usage
const entity = new pc.Entity('rotatingCube');
entity.addComponent('model', { type: 'box' });
entity.addComponent('script');
entity.script.create('rotate', {
  attributes: {
    speed: 20,
    axis: new pc.Vec3(0, 1, 0)
  }
});
app.root.addChild(entity);

スクリプトのライフサイクルメソッド：

const MyScript = pc.createScript('myScript');

MyScript.prototype.initialize = function() {
  // Called once after all resources are loaded
};

MyScript.prototype.postInitialize = function() {
  // Called after all entities have initialized
};

MyScript.prototype.update = function(dt) {
  // Called every frame before rendering
};

MyScript.prototype.postUpdate = function(dt) {
  // Called every frame after update
};

MyScript.prototype.swap = function(old) {
  // Hot reload support
};

MyScript.prototype.destroy = function() {
  // Cleanup when entity is destroyed
};

---

パターン 6：入力処理

キーボード、マウス、タッチ入力を処理します。

// Keyboard
if (app.keyboard.isPressed(pc.KEY_W)) {
  entity.translate(0, 0, -speed * dt);
}

if (app.keyboard.wasPressed(pc.KEY_SPACE)) {
  entity.rigidbody.applyImpulse(0, 10, 0);
}

// Mouse
app.mouse.on(pc.EVENT_MOUSEDOWN, (event) => {
  if (event.button === pc.MOUSEBUTTON_LEFT) {
    console.log('Left click at', event.x, event.y);
  }
});

app.mouse.on(pc.EVENT_MOUSEMOVE, (event) => {
  const dx = event.dx;
  const dy = event.dy;
  camera.rotate(-dy * 0.2, -dx * 0.2, 0);
});

// Touch
app.touch.on(pc.EVENT_TOUCHSTART, (event) => {
  event.touches.forEach((touch) => {
    console.log('Touch at', touch.x, touch.y);
  });
});

// Raycasting (mouse picking)
app.mouse.on(pc.EVENT_MOUSEDOWN, (event) => {
  const camera = app.root.findByName('camera');
  const cameraComponent = camera.camera;

  const from = cameraComponent.screenToWorld(
    event.x,
    event.y,
    cameraComponent.nearClip
  );

  const to = cameraComponent.screenToWorld(
    event.x,
    event.y,
    cameraComponent.farClip
  );

  const result = app.systems.rigidbody.raycastFirst(from, to);

  if (result) {
    console.log('Hit:', result.entity.name);
    result.entity.model.material.emissive = new pc.Color(1, 0, 0);
  }
});

---

パターン 7：アニメーション

スケルタルアニメーションとトゥイーンを再生します。

スケルタルアニメーション：

// Load animated model
const modelAsset = new pc.Asset('character', 'container', {
  url: '/models/character.glb'
});

app.assets.add(modelAsset);

modelAsset.ready((asset) => {
  const entity = asset.resource.instantiateRenderEntity();
  app.root.addChild(entity);

  // Get animation component
  entity.addComponent('animation', {
    assets: [asset],
    speed: 1.0,
    loop: true,
    activate: true
  });

  // Play specific animation
  entity.animation.play('Walk', 0.2);  // 0.2s blend time

  // Later, transition to run
  entity.animation.play('Run', 0.5);
});

app.assets.load(modelAsset);

プロパティのトゥイーン：

// Animate position
entity.tween(entity.getLocalPosition())
  .to({ x: 5, y: 2, z: 0 }, 2.0, pc.SineInOut)
  .start();

// Animate rotation
entity.tween(entity.getLocalEulerAngles())
  .to({ x: 0, y: 180, z: 0 }, 1.0, pc.Linear)
  .loop(true)
  .yoyo(true)
  .start();

// Animate material color
const color = material.emissive;
app.tween(color)
  .to(new pc.Color(1, 0, 0), 1.0, pc.SineInOut)
  .yoyo(true)
  .loop(true)
  .start();

// Chain tweens
entity.tween(entity.getLocalPosition())
  .to({ y: 2 }, 1.0)
  .to({ y: 0 }, 1.0)
  .delay(0.5)
  .repeat(3)
  .start();

---

統合パターン

統合 1：React との統合

PlayCanvas を React コンポーネントでラップします。

import React, { useEffect, useRef } from 'react';
import * as pc from 'playcanvas';

function PlayCanvasScene() {
  const canvasRef = useRef(null);
  const appRef = useRef(null);

  useEffect(() => {
    // Initialize
    const app = new pc.Application(canvasRef.current);
    appRef.current = app;

    app.setCanvasFillMode(pc.FILLMODE_FILL_WINDOW);
    app.setCanvasResolution(pc.RESOLUTION_AUTO);

    // Create scene
    const camera = new pc.Entity('camera');
    camera.addComponent('camera', {
      clearColor: new pc.Color(0.1, 0.2, 0.3)
    });
    camera.setPosition(0, 0, 5);
    app.root.addChild(camera);

    const cube = new pc.Entity('cube');
    cube.addComponent('model', { type: 'box' });
    app.root.addChild(cube);

    const light = new pc.Entity('light');
    light.addComponent('light');
    light.setEulerAngles(45, 0, 0);
    app.root.addChild(light);

    app.on('update', (dt) => {
      cube.rotate(10 * dt, 20 * dt, 30 * dt);
    });

    app.start();

    // Cleanup
    return () => {
      app.destroy();
    };
  }, []);

  return (
    <canvas
      ref={canvasRef}
      style={{ width: '100%', height: '100vh' }}
    />
  );
}

export default PlayCanvasScene;

---

統合 2：エディターからのエクスポート

PlayCanvas Editor プロジェクトを扱います。

// Export from PlayCanvas Editor
// Download build files, then load in code:

import * as pc from 'playcanvas';

const app = new pc.Application(canvas);

// Load exported project config
fetch('/config.json')
  .then(response => response.json())
  .then(config => {
    // Load scene
    app.scenes.loadSceneHierarchy(config.scene_url, (err, parent) => {
      if (err) {
        console.error('Failed to load scene:', err);
        return;
      }

      // Start application
      app.start();

      // Find entities by name
      const player = app.root.findByName('Player');
      const enemy = app.root.findByName('Enemy');

      // Access scripts
      player.script.myScript.doSomething();
    });
  });

---

パフォーマンスの最適化

1. オブジェクトプーリング

エンティティを作成・破棄する代わりに再利用します。

class EntityPool {
  constructor(app, count) {
    this.app = app;
    this.pool = [];
    this.active = [];

    for (let i = 0; i < count; i++) {
      const entity = new pc.Entity('pooled');
      entity.addComponent('model', { type: 'box' });
      entity.enabled = false;
      app.root.addChild(entity);
      this.pool.push(entity);
    }
  }

  spawn(position) {
    let entity = this.pool.pop();

    if (!entity) {
      // Pool exhausted, create new
      entity = new pc.Entity('pooled');
      entity.addComponent('model', { type: 'box' });
      this.app.root.addChild(entity);
    }

    entity.enabled = true;
    entity.setPosition(position);
    this.active.push(entity);

    return entity;
  }

  despawn(entity) {
    entity.enabled = false;
    const index = this.active.indexOf(entity);
    if (index > -1) {
      this.active.splice(index, 1);
      this.pool.push(entity);
    }
  }
}

// Usage
const pool = new EntityPool(app, 100);
const bullet = pool.spawn(new pc.Vec3(0, 0, 0));

// Later
pool.despawn(bullet);

---

2. LOD（詳細度）

遠くにあるオブジェクトのジオメトリを簡略化します。

// Manual LOD switching
app.on('update', () => {
  const distance = camera.getPosition().distance(entity.getPosition());

  if (distance < 10) {
    entity.model.asset = highResModel;
  } else if (distance < 50) {
    entity.model.asset = mediumResModel;
  } else {
    entity.model.asset = lowResModel;
  }
});

// Or disable distant entities
app.on('update', () => {
  entities.forEach(entity => {
    const distance = camera.getPosition().distance(entity.getPosition());
    entity.enabled = distance < 100;
  });
});

---

3. バッチ処理

静的メッシュを結合してドローコールを減らします。

// Enable static batching for entity
entity.model.batchGroupId = 1;

// Batch all entities with same group ID
app.batcher.generate([entity1, entity2, entity3]);

---

4. テクスチャ圧縮

圧縮テクスチャ形式を使用します。

// When creating textures, use compressed formats
const texture = new pc.Texture(app.graphicsDevice, {
  width: 512,
  height: 512,
  format: pc.PIXELFORMAT_DXT5,  // GPU-compressed
  minFilter: pc.FILTER_LINEAR_MIPMAP_LINEAR,
  magFilter: pc.FILTER_LINEAR,
  mipmaps: true
});

---

よくある落とし穴

落とし穴 1：アプリケーションを開始していない

問題：シーンはレンダリングされますが、何も起こりません。

// ❌ Wrong - forgot to start
const app = new pc.Application(canvas);
// ... create entities ...
// Nothing happens!

// ✅ Correct
const app = new pc.Application(canvas);
// ... create entities ...
app.start();  // Critical!

---

落とし穴 2：更新中にエンティティを変更する

問題：反復処理中にシーングラフを変更しています。

// ❌ Wrong - modifying array during iteration
app.on('update', () => {
  entities.forEach(entity => {
    if (entity.shouldDestroy) {
      entity.destroy();  // Modifies array!
    }
  });
});

// ✅ Correct - mark for deletion, clean up after
const toDestroy = [];

app.on('update', () => {
  entities.forEach(entity => {
    if (entity.shouldDestroy) {
      toDestroy.push(entity);
    }
  });
});

app.on('postUpdate', () => {
  toDestroy.forEach(entity => entity.destroy());
  toDestroy.length = 0;
});

---

落とし穴 3：アセットによるメモリーリーク

問題：読み込んだアセットをクリーンアップしていません。

// ❌ Wrong - assets never cleaned up
function loadModel() {
  const asset = new pc.Asset('model', 'container', { url: '/model.glb' });
  app.assets.add(asset);
  app.assets.load(asset);
  // Asset stays in memory forever
}

// ✅ Correct - clean up when done
function loadModel() {
  const asset = new pc.Asset('model', 'container', { url: '/model.glb' });
  app.assets.add(asset);

  asset.ready(() => {
    // Use model
  });

  app.assets.load(asset);

  // Clean up later
  return () => {
    app.assets.remove(asset);
    asset.unload();
  };
}

const cleanup = loadModel();
// Later: cleanup();

---

落とし穴 4：トランスフォーム階層の誤り

問題：トランスフォームが正しく伝播しません。

// ❌ Wrong - setting world transform on child
const parent = new pc.Entity();
const child = new pc.Entity();
parent.addChild(child);

child.setPosition(5, 0, 0);  // Local position
parent.setPosition(10, 0, 0);
// Child is at (15, 0, 0) in world space

// ✅ Correct - understand local vs world
child.setLocalPosition(5, 0, 0);  // Explicit local
// or
const worldPos = new pc.Vec3(15, 0, 0);
child.setPosition(worldPos);  // Explicit world

---

落とし穴 5：物理演算が初期化されていない

問題：物理演算コンポーネントが機能しません。

// ❌ Wrong - Ammo.js not loaded
const entity = new pc.Entity();
entity.addComponent('rigidbody', { type: pc.BODYTYPE_DYNAMIC });
// Error: Ammo is not defined

// ✅ Correct - ensure Ammo.js is loaded
const script = document.createElement('script');
script.src = 'https://cdn.jsdelivr.net/npm/[email protected]/ammo.js';
document.body.appendChild(script);

script.onload = () => {
  Ammo().then((AmmoLib) => {
    window.Ammo = AmmoLib;

    // Now physics works
    const entity = new pc.Entity();
    entity.addComponent('rigidbody', { type: pc.BODYTYPE_DYNAMIC });
    entity.addComponent('collision', { type: 'box' });
  });
};

---

落とし穴 6：キャンバスのサイズ設定の問題

問題：キャンバスがコンテナー全体に広がらない、またはリサイズに応答しません。

// ❌ Wrong - fixed size canvas
const canvas = document.createElement('canvas');
canvas.width = 800;
canvas.height = 600;

// ✅ Correct - responsive canvas
const canvas = document.createElement('canvas');
const app = new pc.Application(canvas);

app.setCanvasFillMode(pc.FILLMODE_FILL_WINDOW);
app.setCanvasResolution(pc.RESOLUTION_AUTO);

window.addEventListener('resize', () => app.resizeCanvas());

---

リソース

• 公式 API：https://api.playcanvas.com/
• 開発者向けドキュメント：https://developer.playcanvas.com/
• サンプル：https://playcanvas.github.io/
• エディター：https://playcanvas.com/
• GitHub：https://github.com/playcanvas/engine
• フォーラム：https://forum.playcanvas.com/

---

クイックリファレンス

アプリケーションのセットアップ

const app = new pc.Application(canvas);
app.setCanvasFillMode(pc.FILLMODE_FILL_WINDOW);
app.setCanvasResolution(pc.RESOLUTION_AUTO);
app.start();

エンティティの作成

const entity = new pc.Entity('name');
entity.addComponent('model', { type: 'box' });
entity.setPosition(x, y, z);
app.root.addChild(entity);

更新ループ

app.on('update', (dt) => {
  // Logic here
});

アセットの読み込み

const asset = new pc.Asset('name', 'type', { url: '/path' });
app.assets.add(asset);
asset.ready(() => { /* use asset */ });
app.assets.load(asset);

---

関連スキル：より低レベルの WebGL 制御については、threejs-webgl を参照してください。React との統合パターンについては、react-three-fiber を参照してください。物理演算を多用するシミュレーションについては、babylonjs-engine を参照してください。