playcanvas
Version:
PlayCanvas WebGL game engine
261 lines (260 loc) • 8.83 kB
TypeScript
/**
* @param {Function} constructorFn - The constructor function of the script type.
* @returns {string|undefined} The script name.
*/
export function getScriptName(constructorFn: Function): string | undefined;
/**
* @import { AppBase } from '../app-base.js'
* @import { Entity } from '../entity.js'
*/
/**
* The `Script` class is the fundamental base class for all scripts within PlayCanvas. It provides
* the minimal interface required for a script to be compatible with both the Engine and the
* Editor.
*
* At its core, a script is simply a collection of methods that are called at various points in the
* Engine's lifecycle. These methods are:
*
* - `Script#initialize` - Called once when the script is initialized.
* - `Script#postInitialize` - Called once after all scripts have been initialized.
* - `Script#update` - Called every frame, if the script is enabled.
* - `Script#postUpdate` - Called every frame, after all scripts have been updated.
* - `Script#swap` - Called when a script is redefined.
*
* These methods are entirely optional, but provide a useful way to manage the lifecycle of a
* script and perform any necessary setup and cleanup.
*
* Below is a simple example of a script that rotates an entity every frame.
* @example
* ```javascript
* import { Script } from 'playcanvas';
*
* export class Rotator extends Script {
* static scriptName = 'rotator';
*
* update(dt) {
* this.entity.rotateLocal(0, 1, 0);
* }
* }
* ```
*
* When this script is attached to an entity, the update will be called every frame, slowly
* rotating the entity around the Y-axis.
*
* For more information on how to create scripts, see the [Scripting Overview](https://developer.playcanvas.com/user-manual/scripting/).
*
* @category Script
*/
export class Script extends EventHandler {
/**
* Fired when a script instance becomes enabled.
*
* @event
* @example
* export class PlayerController extends Script {
* static scriptName = 'playerController';
* initialize() {
* this.on('enable', () => {
* // Script Instance is now enabled
* });
* }
* };
*/
static EVENT_ENABLE: string;
/**
* Fired when a script instance becomes disabled.
*
* @event
* @example
* export class PlayerController extends Script {
* static scriptName = 'playerController';
* initialize() {
* this.on('disable', () => {
* // Script Instance is now disabled
* });
* }
* };
*/
static EVENT_DISABLE: string;
/**
* Fired when a script instance changes state to enabled or disabled. The handler is passed a
* boolean parameter that states whether the script instance is now enabled or disabled.
*
* @event
* @example
* export class PlayerController extends Script {
* static scriptName = 'playerController';
* initialize() {
* this.on('state', (enabled) => {
* console.log(`Script Instance is now ${enabled ? 'enabled' : 'disabled'}`);
* });
* }
* };
*/
static EVENT_STATE: string;
/**
* Fired when a script instance is destroyed and removed from component.
*
* @event
* @example
* export class PlayerController extends Script {
* static scriptName = 'playerController';
* initialize() {
* this.on('destroy', () => {
* // no longer part of the entity
* // this is a good place to clean up allocated resources used by the script
* });
* }
* };
*/
static EVENT_DESTROY: string;
/**
* Fired when script attributes have changed. This event is available in two forms. They are as
* follows:
*
* 1. `attr` - Fired for any attribute change. The handler is passed the name of the attribute
* that changed, the value of the attribute before the change and the value of the attribute
* after the change.
* 2. `attr:[name]` - Fired for a specific attribute change. The handler is passed the value of
* the attribute before the change and the value of the attribute after the change.
*
* @event
* @example
* export class PlayerController extends Script {
* static scriptName = 'playerController';
* initialize() {
* this.on('attr', (name, newValue, oldValue) => {
* console.log(`Attribute '${name}' changed from '${oldValue}' to '${newValue}'`);
* });
* }
* };
* @example
* export class PlayerController extends Script {
* static scriptName = 'playerController';
* initialize() {
* this.on('attr:speed', (newValue, oldValue) => {
* console.log(`Attribute 'speed' changed from '${oldValue}' to '${newValue}'`);
* });
* }
* };
*/
static EVENT_ATTR: string;
/**
* Fired when a script instance had an exception. The script instance will be automatically
* disabled. The handler is passed an Error object containing the details of the
* exception and the name of the method that threw the exception.
*
* @event
* @example
* export class PlayerController extends Script {
* static scriptName = 'playerController';
* initialize() {
* this.on('error', (err, method) => {
* // caught an exception
* console.log(err.stack);
* });
* }
* };
*/
static EVENT_ERROR: string;
/**
* Name of a Script Type.
*
* @type {string}
* @private
*/
private static __name;
/**
* @param {*} constructorFn - The constructor function of the script type.
* @returns {string} The script name.
* @private
*/
private static __getScriptName;
/**
* Name of a Script Type.
*
* @type {string|null}
*/
static get scriptName(): string | null;
/**
* Create a new Script instance.
*
* @param {object} args - The input arguments object.
* @param {AppBase} args.app - The {@link AppBase} that is running the script.
* @param {Entity} args.entity - The {@link Entity} that the script is attached to.
*/
constructor(args: {
app: AppBase;
entity: Entity;
});
/**
* The {@link AppBase} that the instance of this script belongs to.
*
* @type {AppBase}
*/
app: AppBase;
/**
* The {@link Entity} that the instance of this script belongs to.
*
* @type {Entity}
*/
entity: Entity;
/** @private */
private _enabled;
/** @private */
private _enabledOld;
/** @private */
private _initialized;
/** @private */
private _postInitialized;
/** @private */
private __destroyed;
/** @private */
private __scriptType;
/**
* The order in the script component that the methods of this script instance will run
* relative to other script instances in the component.
*
* @type {number}
* @private
*/
private __executionOrder;
/**
* True if the instance of this script is in running state. False when script is not running,
* because the Entity or any of its parents are disabled or the {@link ScriptComponent} is
* disabled or the Script Instance is disabled. When disabled, no update methods will be called
* on each tick. `initialize` and `postInitialize` methods will run once when the script
* instance is in the `enabled` state during an app tick.
*
* @type {boolean}
*/
set enabled(value: boolean);
get enabled(): boolean;
/**
* @typedef {object} ScriptInitializationArgs
* @property {boolean} [enabled] - True if the script instance is in running state.
* @property {AppBase} app - The {@link AppBase} that is running the script.
* @property {Entity} entity - The {@link Entity} that the script is attached to.
*/
/**
* @param {ScriptInitializationArgs} args - The input arguments object.
* @protected
*/
protected initScript(args: {
/**
* - True if the script instance is in running state.
*/
enabled?: boolean;
/**
* - The {@link AppBase} that is running the script.
*/
app: AppBase;
/**
* - The {@link Entity} that the script is attached to.
*/
entity: Entity;
}): void;
}
import { EventHandler } from '../../core/event-handler.js';
import type { AppBase } from '../app-base.js';
import type { Entity } from '../entity.js';