# Script

Class · extends [`EventHandler`](https://api.playcanvas.com/engine/classes/EventHandler.md) · category: Script

Source: https://github.com/playcanvas/engine/blob/970d89f6d3bc6667f4e1f88153abd6e7e82ed52c/src/framework/script/script.js#L54

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/).

The `playcanvas` package also ships a library of ready-to-use `Script` subclasses under the
`playcanvas/scripts/esm/` subpath — camera and character controllers, post-processing, water,
sky, grid, shadow catcher, planar reflections, XR and Gaussian-splat effects. Import them
directly, for example
`import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs'`.

## Constructors

### constructor

```ts
new Script(args: object)
```

Create a new Script instance.

**Parameters**

- `args` (`object`): The input arguments object.
    - `args.app` ([`AppBase`](https://api.playcanvas.com/engine/classes/AppBase.md)): The AppBase that is running the script.
    - `args.entity` ([`Entity`](https://api.playcanvas.com/engine/classes/Entity.md)): The Entity that the script is attached to.

## Properties

### app

```ts
app: AppBase
```

The [AppBase](https://api.playcanvas.com/engine/classes/AppBase.md) that the instance of this script belongs to.

### entity

```ts
entity: Entity
```

The [Entity](https://api.playcanvas.com/engine/classes/Entity.md) that the instance of this script belongs to.

## Accessors

### enabled

```ts
get enabled(): boolean
set enabled(value: boolean)
```

Gets the running state of the script instance. Returns true when the script instance is
enabled and its owning [Entity](https://api.playcanvas.com/engine/classes/Entity.md) (and all ancestors) and [ScriptComponent](https://api.playcanvas.com/engine/classes/ScriptComponent.md) are
also enabled; otherwise false.

### scriptName

```ts
static get scriptName(): string | null
static set scriptName(value: string | null)
```

Gets the unique name of the script.

## Methods

### initScript

```ts
protected initScript(args: ScriptInitializationArgs): void
```

**Parameters**

- `args` ([`ScriptInitializationArgs`](https://api.playcanvas.com/engine/interfaces/ScriptInitializationArgs.md)): The input arguments object.

## Events

### EVENT_ATTR

```ts
static EVENT_ATTR: string = 'attr'
```

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.

**Example**

```ts
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**

```ts
export class PlayerController extends Script {
    static scriptName = 'playerController';
    initialize() {
        this.on('attr:speed', (newValue, oldValue) => {
            console.log(`Attribute 'speed' changed from '${oldValue}' to '${newValue}'`);
        });
    }
};
```

### EVENT_DESTROY

```ts
static EVENT_DESTROY: string = 'destroy'
```

Fired when a script instance is destroyed and removed from component.

**Example**

```ts
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
        });
    }
};
```

### EVENT_DISABLE

```ts
static EVENT_DISABLE: string = 'disable'
```

Fired when a script instance becomes disabled.

**Example**

```ts
export class PlayerController extends Script {
    static scriptName = 'playerController';
    initialize() {
        this.on('disable', () => {
            // Script Instance is now disabled
        });
    }
};
```

### EVENT_ENABLE

```ts
static EVENT_ENABLE: string = 'enable'
```

Fired when a script instance becomes enabled.

**Example**

```ts
export class PlayerController extends Script {
    static scriptName = 'playerController';
    initialize() {
        this.on('enable', () => {
            // Script Instance is now enabled
        });
    }
};
```

### EVENT_ERROR

```ts
static EVENT_ERROR: string = 'error'
```

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.

**Example**

```ts
export class PlayerController extends Script {
    static scriptName = 'playerController';
    initialize() {
        this.on('error', (err, method) => {
            // caught an exception
            console.log(err.stack);
        });
    }
};
```

### EVENT_STATE

```ts
static EVENT_STATE: string = 'state'
```

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.

**Example**

```ts
export class PlayerController extends Script {
    static scriptName = 'playerController';
    initialize() {
        this.on('state', (enabled) => {
            console.log(`Script Instance is now ${enabled ? 'enabled' : 'disabled'}`);
        });
    }
};
```

## Inherited from [EventHandler](https://api.playcanvas.com/engine/classes/EventHandler.md)

- `fire(name: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any, arg5?: any, arg6?: any, arg7?: any, arg8?: any): EventHandler`
- `hasEvent(name: string): boolean`
- `off(name?: string, callback?: HandleEventCallback, scope?: any): EventHandler`
- `on(name: string, callback: HandleEventCallback, scope?: any): EventHandle`
- `once(name: string, callback: HandleEventCallback, scope?: any): EventHandle`