はじめに

This guide covers the basic structure and concepts you need to understand when writing PlayCanvas scripts, whether you're using the modern ESM approach or the classic system.

What is a Script?

A script is a piece of JavaScript code that defines behavior for an Entity in your scene. Scripts are:

• Reusable - The same script can be attached to multiple entities
• Configurable - Use attributes to customize behavior per entity
• Event-driven - Respond to lifecycle events and user interactions

Basic Script Structure

Every PlayCanvas script follows a similar pattern, regardless of which system you use:

ESM (Recommended)

import { Script } from 'playcanvas';

export class MyScript extends Script {
    /** @attribute */
    speed = 10;

    initialize() {
        // Called once when the script starts
        console.log('Script initialized!');
    }

    update(dt) {
        // Called every frame
        this.entity.rotate(0, this.speed * dt, 0);
    }
}

Key points for ESM scripts:

• Import the Script class from PlayCanvas
• Export a class that extends Script
• Use /** @attribute */ to expose properties to the editor
• File must have .mjs extension

Classic

var MyScript = pc.createScript('myScript');

MyScript.attributes.add('speed', { type: 'number', default: 10 });

MyScript.prototype.initialize = function() {
    // Called once when the script starts
    console.log('Script initialized!');
};

MyScript.prototype.update = function(dt) {
    // Called every frame
    this.entity.rotate(0, this.speed * dt, 0);
};

Key points for classic scripts:

• Use pc.createScript() to declare the script
• Add attributes using the .attributes.add() method
• Define methods on the prototype
• File has .js extension

Core Concepts

Script Lifecycle

Scripts have several methods that are called automatically at different times:

• initialize() - Called once when the script starts
• update(dt) - Called every frame with delta time
• postUpdate(dt) - Called after all updates complete
• Event handlers for enable, disable, destroy

Learn more about the Script Lifecycle.

Attributes

Attributes let you expose script properties to the editor, making scripts configurable without code changes:

ESM

import { Color, Script } from 'playcanvas';

export class Configurable extends Script {
    /** @attribute */
    speed = 5;

    /** @attribute */
    color = new Color(1, 0, 0);

    /** 
     * @attribute 
     * @type {Entity}
     */
    target;
}

Classic

var Configurable = pc.createScript('configurable');

Configurable.attributes.add('speed', { type: 'number', default: 5 });
Configurable.attributes.add('color', { type: 'rgba', default: [1, 0, 0, 1] });
Configurable.attributes.add('target', { type: 'entity' });

Learn more about Script Attributes.

Accessing the Entity

Every script has access to the entity it's attached to via this.entity:

// Get the entity's position
const position = this.entity.getPosition();

// Find child entities
const child = this.entity.findByName('ChildName');

// Access components
const camera = this.entity.camera;
const rigidbody = this.entity.rigidbody;

Next Steps

• Learn ESM Scripts: If you're starting fresh, check out ESM Scripts for the modern approach
• Understand Lifecycle: Read about Script Lifecycle to understand when your code runs
• Add Interactivity: Explore Events to make scripts communicate with each other

ヒント

Which system should I use?

For new projects, we recommend ESM Scripts as they offer better tooling, cleaner syntax, and modern JavaScript features. Classic scripts are still fully supported for existing projects.