playcanvas-engine

What this skill does

# PlayCanvas Engine Skill

Lightweight WebGL/WebGPU game engine with entity-component architecture, visual editor integration, and performance-focused design.

## When to Use This Skill

Trigger this skill when you see:
- "PlayCanvas engine"
- "WebGL game engine"
- "entity component system"
- "PlayCanvas application"
- "3D browser games"
- "online 3D editor"
- "lightweight 3D engine"
- Need for editor-first workflow

Compare with:
- **Three.js**: Lower-level, more flexible but requires more setup
- **Babylon.js**: Feature-rich but heavier, has editor but less mature
- **A-Frame**: VR-focused, declarative HTML approach
- Use PlayCanvas for: Game projects, editor-first workflow, performance-critical apps

---

## Core Concepts

### 1. Application

The root PlayCanvas application manages the rendering loop.

```javascript
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. Entity-Component System

PlayCanvas uses ECS architecture: Entities contain Components.

```javascript
// 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. Update Loop

The application fires events during the update loop.

```javascript
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. Components

Core components extend entity functionality:

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

**Camera Component**:
```javascript
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
});
```

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

**Rigidbody Component** (requires physics):
```javascript
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)
});
```

---

## Common Patterns

### Pattern 1: Basic Scene Setup

Create a complete scene with camera, light, and models.

```javascript
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();
```

---

### Pattern 2: Loading GLTF Models

Load external 3D models with asset management.

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

**With error handling**:
```javascript
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);
```

---

### Pattern 3: Materials and Textures

Create custom materials with PBR workflow.

```javascript
// 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);
});
```

---

### Pattern 4: Physics Integration

Use Ammo.js for physics simulation.

```javascript
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.addCo