Calling the Engine API
When writing PlayCanvas scripts, you're working with the PlayCanvas Engine API. This page covers the essential classes and patterns you'll use most often in your scripts.
Key Classes for Script Writers
Your Script Context
Every script has access to these core objects:
this.app // The main application (AppBase)
this.entity // The entity this script is attached to
important
this.app
and this.entity
are only valid within methods defined on your Script instance (initialize
, update
, etc.). Learn more about JavaScript's this
keyword.
Essential Classes
AppBase
- Your application
// Common app operations
this.app.fire('game:start');
const player = this.app.root.findByName('Player');
const texture = this.app.assets.find('logo', 'texture');
Entity
- Objects in your scene
// Common entity operations
this.entity.setPosition(0, 5, 0);
this.entity.rotate(0, 90, 0);
const child = this.entity.findByName('Weapon');
Component
- Add functionality to entities
// Accessing components
const camera = this.entity.camera;
const light = this.entity.light;
const rigidbody = this.entity.rigidbody;
const sound = this.entity.sound;
Math Classes
Import these for calculations and transformations:
import { Vec3, Quat, Color } from 'playcanvas';
const position = new Vec3(0, 5, 0);
const rotation = new Quat();
const red = new Color(1, 0, 0);
Common Script Patterns
Finding Entities
// By name (searches entire hierarchy)
const player = this.app.root.findByName('Player');
// By tag (returns array)
const enemies = this.app.root.findByTag('enemy');
// Relative to current entity
const weapon = this.entity.findByPath('Arms/RightHand/Weapon');
Working with Assets
// Find and load assets
const sound = this.app.assets.find('explosion', 'audio');
sound.ready(() => {
this.entity.sound.play('explosion');
});
this.app.assets.load(sound);
Events and Communication
// Fire application events
this.app.fire('player:died', this.entity);
// Listen for events
this.app.on('game:start', this.onGameStart, this);
Learning More
- Full Engine API Reference - Complete documentation
- Engine Guide - In-depth guide to the PlayCanvas Engine runtime
- Script Lifecycle - When your script methods are called
- Events - Script communication patterns
tip
IDE Support: Use the VS Code Extension for autocomplete and inline documentation while writing scripts.