Class: ScriptComponent

pc.ScriptComponent

The ScriptComponent allows you to extend the functionality of an Entity by attaching your own Script Types defined in JavaScript files to be executed with access to the Entity. For more details on scripting see Scripting.

Constructor

new ScriptComponent(system, entity)

Parameters:
Name Type Description
system pc.ScriptComponentSystem The ComponentSystem that created this Component
entity pc.Entity The Entity that this Component is attached to.
Properties:
Name Type Description
scripts Array.<ScriptType> An array of all script instances attached to an entity. This Array shall not be modified by developer.
Source:

Extends

Methods

create(name, argsopt) → {ScriptType}

Create a script instance using name of a ScriptType and attach to an entity script component.
Parameters:
Name Type Attributes Description
name String The name of the Script Type
args Object <optional>
Object with arguments for a script
Properties
Name Type Attributes Description
enabled Boolean <optional>
if script instance is enabled after creation
attributes Object <optional>
Object with values for attributes, where key is name of an attribute
Source:
Returns:
Returns an instance of a ScriptType if successfully attached to an entity, or null if it failed because a script with a same name has already been added or if the ScriptType cannot be found by name in the pc.ScriptRegistry.
Type
ScriptType
Example
entity.script.create('playerController', {
    attributes: {
        speed: 4
    }
});

destroy(name) → {Boolean}

Destroy the script instance that is attached to an entity.
Parameters:
Name Type Description
name String The name of the Script Type
Source:
Returns:
If it was successfully destroyed
Type
Boolean
Example
entity.script.destroy('playerController');

has(name) → {Boolean}

Detect if script is attached to an entity using name of ScriptType.
Parameters:
Name Type Description
name String The name of the Script Type
Source:
Returns:
If script is attached to an entity
Type
Boolean
Example
if (entity.script.has('playerController')) {
    // entity has script
}

move(name, ind) → {Boolean}

Move script instance to different position to alter update order of scripts within entity.
Parameters:
Name Type Description
name String The name of the Script Type
ind Number New position index
Source:
Returns:
If it was successfully moved
Type
Boolean
Example
entity.script.move('playerController', 0);

(private) resolveDuplicatedEntityReferenceProperties(oldScriptComponent, duplicatedIdsMap)

When an entity is cloned and it has entity script attributes that point to other entities in the same subtree that is cloned, then we want the new script attributes to point at the cloned entities. This method remaps the script attributes for this entity and it assumes that this entity is the result of the clone operation.
Parameters:
Name Type Description
oldScriptComponent pc.ScriptComponent The source script component that belongs to the entity that was being cloned.
duplicatedIdsMap Object A dictionary with guid-entity values that contains the entities that were cloned
Source:

Events

create:[name]

Fired when a script instance is created and attached to component
Parameters:
Name Type Description
scriptInstance ScriptType The instance of the ScriptType that has been created
Source:
Example
entity.script.on('create:playerController', function (scriptInstance) {
    // new script instance 'playerController' is added to component
});

destroy:[name]

Fired when a script instance is destroyed and removed from component
Parameters:
Name Type Description
scriptInstance ScriptType The instance of the ScriptType that has been destroyed
Source:
Example
entity.script.on('destroy:playerController', function (scriptInstance) {
    // script instance 'playerController' has been destroyed and removed from component
});

create

Fired when a script instance is created and attached to component
Parameters:
Name Type Description
name String The name of the Script Type
scriptInstance ScriptType The instance of the ScriptType that has been created
Source:
Example
entity.script.on('create', function (name, scriptInstance) {
    // new script instance added to component
});

destroy

Fired when a script instance is destroyed and removed from component
Parameters:
Name Type Description
name String The name of the Script Type
scriptInstance ScriptType The instance of the ScriptType that has been destroyed
Source:
Example
entity.script.on('destroy', function (name, scriptInstance) {
    // script instance has been destroyed and removed from component
});

disable

Fired when Component becomes disabled Note: this event does not take in account entity or any of its parent enabled state
Source:
Example
entity.script.on('disable', function () {
    // component is disabled
});

enable

Fired when Component becomes enabled Note: this event does not take in account entity or any of its parent enabled state
Source:
Example
entity.script.on('enable', function () {
    // component is enabled
});

error

Fired when a script instance had an exception
Parameters:
Name Type Description
scriptInstance ScriptType The instance of the ScriptType that raised the exception
err Error Native JS Error object with details of an error
method String The method of the script instance that the exception originated from.
Source:
Example
entity.script.on('error', function (scriptInstance, err, method) {
    // script instance caught an exception
});

move

Fired when a script instance is moved in component
Parameters:
Name Type Description
name String The name of the Script Type
scriptInstance ScriptType The instance of the ScriptType that has been moved
ind Number New position index
indOld Number Old position index
Source:
Example
entity.script.on('move', function (name, scriptInstance, ind, indOld) {
    // script instance has been moved in component
});

remove

Fired when Component is removed from entity
Source:
Example
entity.script.on('remove', function () {
    // entity has no more script component
});

state

Fired when Component changes state to enabled or disabled Note: this event does not take in account entity or any of its parent enabled state
Parameters:
Name Type Description
enabled Boolean True if now enabled, False if disabled
Source:
Example
entity.script.on('state', function (enabled) {
    // component changed state
});

move:[name]

Fired when a script instance is moved in component
Parameters:
Name Type Description
scriptInstance ScriptType The instance of the ScriptType that has been moved
ind Number New position index
indOld Number Old position index
Source:
Example
entity.script.on('move:playerController', function (scriptInstance, ind, indOld) {
    // script instance 'playerController' has been moved in component
});