Skip to main content

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​

tip

IDE Support: Use the VS Code Extension for autocomplete and inline documentation while writing scripts.