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.