API Support

Are you a programming wizard, or enjoy working with the Roll20 API? If so, we've got great news for you - Updated Dynamic Lighting now integrates with the Roll20 API! Check out all of the awesome Lighting and Vision functions and features you can use in your custom code. Keep in mind, API access is only available to Pro subscribers, so upgrade your account if you haven't already.


Token Settings

Syntax Context Type
has_bright_light_vision  Toggles vision for the token. Boolean
     
has_night_vision Toggles night vision for the token.  Boolean
night_vision_distance Sets the range of night vision for the token.  Integer
     
emits_bright_light Toggles bright light for the token.  Boolean
bright_light_distance Sets the range of the amount of bright light emitting from a token.  Integer
     
emits_low_light Toggles low light for the token. This would be useful for a torch or a source with a low amount of light. Use the booleans true to turn on or false to turn off. Boolean
low_light_distance Sets the range of the amount of low light emitting from a token. When setting this value, you must include any Bright Light Distance you have set. The reason for this is because Low Light Distance is calculated from the center of the token. So if you have set Bright Light Distance to 10, and you would like an additional 10 feet of Low Light Distance, the value of low_light_distance must be 20. Integer 

 

Directional Vision and Lighting

Syntax Context Type
has_limit_field_of_vision Toggles limit field of vision for the token. Boolean
limit_field_of_vision_center Sets the value for where the center of the field of vision starts. Integer
limit_field_of_vision_total Set the value for the total size of the field of vision. Integer
     

has_limit_field_of_night_vision

Toggles limit field of night vision for the token. Boolean
limit_field_of_night_vision_center Sets the value for where the center of the field of night vision starts. Integer 
limit_field_of_night_vision_total Set the value for the total size of the field of night vision. Integer
     
has_directional_bright_light Toggles directional bright light for the token. Boolean

directional_bright_light_center

Sets the value for where the center of the field of bright light starts. Integer
directional_bright_light_total Set the value for the total size of the field of bright light. Integer 
     

has_directional_low_light

Toggles directional low light for the token. Boolean
directional_low_light_center Sets the value for where the center of the field of low light starts. Integer
directional_low_light_total Set the value for the total size of the field of low light. Integer

 


Page Settings

Syntax Context Type
dynamic_lighting_enabled Toggles updated dynamic lighting for the page.  Boolean
daylight_mode_enabled Toggles daylight mode for the page. This should not be turned on if dynamic_lighting_enabled is not turned on.  Boolean
explorer_mode

Toggles explorer mode for the page. This should not be turned on if dynamic_lighting_enabled is not turned on.

Use the strings ”basic” to turn on or ”off” to turn off. 

String

 


Examples 

on("change:graphic", function(obj) {
  obj.set({
    has_bright_light_vision: true,
    emits_bright_light: true,
    bright_light_distance: 10
  });
});

This will add the above values to a token in two instances:

  • upon adding a new token to the VTT
  • moving a token that already exists on the VTT, with or without token settings already set.

However, using on(“change is dangerous because if you update the token settings for a specific token, that triggers a change event, which will trigger this API. So, if you have something like this in your API script, your token settings will always stay this way for every token, unless you add some conditional statements so it works the way you want.

on("change:graphic", function(obj) {
  obj.set({
    has_bright_light_vision: true,
    emits_bright_light: true,
    bright_light_distance: 10,
    emits_low_light: true,
    low_light_distance: 25
  });
});

This example will set Vision to any token that has changed (moved, updated, added to the VTT, etc). The token will also emit 10 feet of Bright Light Distance, as well as 15 feet of Low Light Distance.

Notice how low_light_distance is set to 25. That is because the value of low_light_distance must be the sum of bright_light_distance and however much you would like the token to emit Low Light Distance - in this case, it is 15.

 

Was this article helpful?
4 out of 11 found this helpful