# build-app

Guides setup and structure of a PlayCanvas app built with the Engine API, React, or Web Components, including input, resize, physics and UI.

Skill by PlayCanvas. Category: Web and browsers.

## Install

Project (for this project only):

```sh
npx skills add playcanvas/skills --skill build-app
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add playcanvas/skills --skill build-app -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 228. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/playcanvas/skills/build-app)

## Source

[Open the source](https://github.com/playcanvas/skills/tree/HEAD/skills/build-app). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: build-app
description: Use when creating or restructuring a PlayCanvas app with the Engine API, @playcanvas/react, or @playcanvas/web-components, covering bootstrap, input, resize, physics, update loop, UI, and lifecycle.
---

# Build an Engine application

Read `package.json` and the entry point, keep the surface that owns the lifecycle, and read only its
reference: [direct Engine](references/direct-engine.md), [React](references/react.md), or
[Web Components](references/web-components.md). Choose from imports and markup, not dependencies.

## Bootstrap

- Input is opt-in. `app.keyboard`, `mouse`, `touch`, `gamepads`, and `elementInput` stay `null`
  unless passed to `new Application(canvas, { ... })`; UI buttons need `new ElementInput(canvas)`.
- The Engine adds no window resize listener; call `app.resizeCanvas()` from your own handler.
- `graphicsDevice.maxPixelRatio` defaults to 1. Raise it, at most to `window.devicePixelRatio`, only
  where the target holds its frame budget, call `app.resizeCanvas()`, and confirm with
  `canvas.width / canvas.clientWidth`.
- Rigid bodies stay inert until Ammo loads through `WasmModule`. Copy the loader from the
  `physics/falling-shapes` example with `find-examples`.
- `devtools` defaults to `true`, so debugging tools can find the app (`inspect-runtime`). Set it to
  `false` only to hide a production build.

## Update loop

- `dt` is already clamped by `app.maxDeltaTime` (0.1 s); tune it instead of clamping by hand.
  `app.timeScale` scales it, and `0` pauses scaled time.
- Keep app state explicit and owned in one place; advance time-dependent logic from `dt`, and reset
  through the same setup used at start.

## UI

- Render UI from app state; never keep the source of truth in the DOM or UI elements.
- Use a DOM or React overlay, or Engine `screen` and `element` components adapted from a
  `user-interface` example.
- Hide unused elements with `enabled = false`; an element at opacity 0 still draws.

## Ownership

- Keep one owner for app creation, assets, entities, update callbacks, and teardown.
- Prefer the surface's declarative primitives. Put per-entity and per-frame behaviour in an Engine
  `Script`.
- Remove external events and resources in the lifecycle that created them.
````

- Previous: [light-scene](https://syn4pse.dev/terminal/playcanvas-light-scene.md)
- Next: [configure-animation](https://syn4pse.dev/terminal/playcanvas-configure-animation.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
