User Manual

Script Attributes

Script Attributes are a powerful feature that lets you expose values from your script files so that they appear in the PlayCanvas Editor. This means you can write code once, and then tweak values on different instances of an Entity to give them different properties.

Declaring Script Attributes

Script Attributes are declared at the top of your script file using this format:

pc.script.attribute(attributeName, attributeType, defaultValue, options);

In this example, we're declaring a property called speed which is a number and has a default value of 80:

pc.script.attribute('speed', 'number', 80);

Getting Attributes into Editor

Once you've declared your attributes they must be available for the server to analyze. If you are using PlayCanvas to write your code then you don't need to do anything. If you are using an external code repository like Github or Bitbucket then you will need to make sure that the latest version of your code is synced.

Once your code is on the PlayCanvas server then open the Editor and click the button.

Refreshing attributes loads all your scripts and parses out any attributes that were declared. Then they are inserted into the script components that reference that script (and as such are accessible in your scripts as this.attribute_name) and are also exposed into the Editor.

In the Editor each script with attributes gets its own attribute block in the Attribute Editor, just like a Component.

Types

A number of different types are supported, they are detailed below. Options are passed in a javascript object.

Number

The value is an number.

Example

pc.script.attribute('speed', 'number', 80, {
    min: 0,
    max: 100
});

Options

OptionDescription
displayNameThe name to show in the Editor.
descriptionThe description to show in the Editor when the user hovers over the script attribute.
minThe minimum value that is valid.
maxThe maximum value that is valid.
stepThe amount to increment the number by when clicking up/down in the Editor.
decimalPrecisionThe number of decimal places that are supported.

String

The value is a string

Example

pc.script.attribute('title', 'string', 'Untitled', {
    displayName: "Title"
});

Options

OptionDescription
displayNameThe name to show in the Editor.

Boolean

The value is true or false.

Example

pc.script.attribute('on', 'boolean', false, {
    displayName: "On"
});

Options

OptionDescription
displayNameThe name to show in the Editor.

Asset

The value is a reference to a list of Assets in the Project.

Example

pc.script.attribute('sound', 'asset', [], {
    displayName: "Sound Asset"
});

Options

OptionDescription
displayNameThe name to show in the Editor.
typeLimit the asset selection to a single Asset type.

Entity

The value is an Entity in the Hierarchy.

Example

pc.script.attribute('myEntity', 'entity', null, {
    displayName: "Entity"
});

Options

OptionDescription
displayNameThe name to show in the Editor.

RGB Color

The value is a color with no alpha (transparency).

Example

pc.script.attribute('color', 'rgb', [1,1,1], {
    displayName: "Color"
});

Options

OptionDescription
displayNameThe name to show in the Editor.

RGBA Color

The value is a color with alpha (transparency).

Example

pc.script.attribute('color', 'rgba', [1,1,1,0.5], {
    displayName: "Color"
});

Options

OptionDescription
displayNameThe name to show in the Editor.

Vec2, Vec3, Vec4

The value is a Vector, an array of 2, 3 or 4 numbers.

Example

pc.script.attribute('direction', 'vec2', [0,1], {
    displayName: "Vector 2"
});

pc.script.attribute('direction', 'vec3', [0,1,0], {
    displayName: "Vector 3"
});

pc.script.attribute('transform', 'vec4', [0,1,0,1], {
    displayName: "Vector 4"
});

Options

OptionDescription
displayNameThe name to show in the Editor.

Enumeration

The value is one of a possible set of values. This will expose a dropdown list of items in the Editor. You can only choose one of the predefined choices.

Example

pc.script.attribute('pet', 'enumeration', 0, {
    displayName: "Pet",
    enumerations: [{
       name: "Cat",
       value: 0
    }, {
       name: "Dog",
       value: 1
    }]
});

Options

OptionDescription
displayNameThe name to show in the Editor.
enumerationsThis list of possible enumerations. Supplied as a list of objects with a name and a value property.

Curve

The value is a pc.Curve or a pc.CurveSet if there are multiple curves.

Example

pc.script.attribute('speed', 'curve', null, {
    min: 0,
    max: 5
});
pc.script.attribute('position', 'curve', null, {
    curves: ['x', 'y', 'z']
});

Options

OptionDescription
displayNameThe name to show in the Editor.
minThe minimum value for a curve.
maxThe maximum value for a curve.
curvesAn array of strings that define the number and name of each channel in a curve. This can take up to 4 strings.

Color Curve

The value is a pc.Curve or a pc.CurveSet if there are multiple color channels.

Example

pc.script.attribute('color', 'colorcurve', null, {
    type: 'rgba'
});

Options

OptionDescription
displayNameThe name to show in the Editor.
typeThe type of the color curve. Can be one of 'r', 'g', 'b', 'rgb' or 'rgba'.