Custom Sheet Macro Attributes

When utilizing Macroswithin the Roll20 Tabletop or Roll20 Characters (both refered to as host throughout this page), there are instances where a older Custom Sheet macro might need to be employed for a Beacon sheet.

This scenario commonly arises when transitioning from an existing older Custom Sheet to a Beacon sheet. During such transitions, it’s possible that the attributes or roll templates called from the older Custom Sheet macros may not align with the structure of attributes or the lack of roll templates in the Beacon Sheet.

convertLegacyMacroAttributes#

The convertLegacyMacroAttributes method allows us to determine the mapping strategy for older Custom Sheet attributes to the new Beacon Sheet.

initRelay({
  convertLegacyMacroAttributes: (messages:  {
    attribute: string,
    characterId: string,
    character: Character
  }) => {}: string | number | null,
}): Promise<Dispatch>

This method is defined during the initial SDK initialization process and is invoked by the host when it attempts to parse a macro and encounters a failure in locating an attribute’s value during an macro’s execution.

The method’s purpose is to return a value that will be substituted in the macro. However, it grants us the autonomy to devise the preferred approach for handling older Custom Sheet attribute values.

handleLegacyRollTemplates#

Since Beacon sheets no longer require or use roll templates as previously needed in older custom sheets, there will be times where a older Custom Sheet macro might make include a reference to a older Custom Sheet roll template. We can use the handleLegacyRollTemplates to determine how to handle these cases.

initRelay({
  handleLegacyRollTemplates: (message: { 
    templateName: string, // name of the template that triggered this method
    properties: Record<string, any>, // a list of the values and formulas for rolls and macro in the template
    // along with values for other properties in the template
    dispatch: Dispatch, 
    playerid: string ,
    originalInput: string // the original text input for the entire roll template string
  }) => {}: any,
}): Promise<Dispatch>

{
  //... other arguments
  properties: {
    attack: { value: 12, formula: '1d20' },
    damage: { value: 5, formula: '2d6' },
    foo: { value: 'bar' },
    name: {
      formula: "@{Helga|name}"
      value: "Helga"
    },
    plainText: ['apicallback', 'apple=red'],
    something: { 
      value: "I went to get tacos"
    },
    ............
  }
}