Revision as of 12:22, 17 February 2022

Page Updated:   2022-02-17

This is related to Mods, which require Pro info to be able to use. Main Page: Mod:Development

Roll20 objects are a special kind of JavaScript object. They represent something in your campaign, such as a token on the tabletop or a character in the journal, and there is some special consideration for using them. Extended Syntax Roll20 Objects is an API script which modifies how you can interact with Roll20 objects.

Roll20 object fields

id

This field is shorthand for obj.get('id'). All Roll20 objects have a _id property which uniquely identifies them within a campaign, but their properties are not directly accessible. Normally you have to call get in order to get the value of a property, but because _id is needed on such a frequent basis, this shim field is provided for convenience.

Roll20 object functions

get

Parameters

parameter

(String) The name of the parameter to get. If you are getting the value of a read-only property (one which starts with an underscore, like _id or _type), the leading underscore is not required.

Returns

The value of the specified property

Examples

var character = getMyCharacter(),
    strength = findObjs({ type: 'attribute', characterid: character.id, name: 'strength' })[0];

log(strength.get('current'));

get [Asynchronous]

This version of get will be automatically called if parameter is "notes", "gmnotes", or "bio" and the Roll20 object is a character or handout.

Parameters

parameter

(String) The name of the parameter to get. If you are getting the value of a read-only property (one which starts with an underscore, like _id or _type), the leading underscore is not required.

callback

(Function) A callback function which will receive the value of the property as a parameter.

Returns

(Void)

Examples

var character = getMyCharacter();
character.get('bio', function(text) {
    log(text);
});

remove

Parameters

No parameters

Returns

(Void)

Examples

var graphics = findObjs({ type: 'graphic', pageid: Campaign().get('playerpageid') });
_.each(graphics, (g) => {
    g.remove();
});

set

Parameters (single property)

property

(String) The name of the property to set.

value

(varies) The value to set for the specified property.

Parameters (multiple properties)

attributes

(Object) The properties of the attributes object will be mapped to the properties of the Roll20 object.

Returns

(Void)

Examples

You can set each property one at a time:

var token = getMyToken();
token.set('left', 70);
token.set('top', 70);
token.set('rotation', 90);
token.set('flipv', true);
token.set('fliph', false);

Or you can set multiple properties at once:

var token = getMyToken();
token.set({
    left: 70,
    top: 70,
    rotation: 90,
    flipv: true,
    fliph: false
});

setWithWorker

Parameters (multiple properties)

attributes

(Object) The properties of the attributes object will be mapped to the properties of the Roll20 object.

Returns

(Void)

Examples

This function is called in the same fashion as set with a single object parameter, except it can only be used with Attribute objects.

getObj("attribute", "-KUI1fO2L7Jv0Y4AOSFK").setWithWorker({ current: "Cleric" });