{
  "name": "Extended Syntax Roll20 Objects",
  "script": "ESRO.js",
  "version": "0.1",
  "previousversions": [],
  "description": "Extends the syntax for Roll20 objects for use in scripts. This script is not intended to stand alone.\n\n### Overridden Functions\nEach function you set to be overridden below will have the normal Roll20 library function overridden with a custom version in this script's `ready` event. Any code executed by other scripts *prior* to this script's `ready` function completing will not benefit from the change. This is most relevant if you want to make use of the overridden `on` function, or use other functions inside another script's `ready` event. Using other overridden functions inside an event other than `ready` which are themselves bound within a `ready` event is guaranteed to function as expected regardless of script load order. For example:\n\n    // Will not be the overridden `on` function if loaded before ESRO\n    on('ready', function() {\n        // Will not be the overridden `on` function if loaded before ESRO\n        on('change:graphic', function(obj, prev) {\n            // Guaranteed to be the overridden `getObj` function regardless of load order\n            var character = getObj('character', obj.get('represents'));\n            ...\n        });\n    });\n\n### Direct Function Access\nYou can access the overridden version of a function directly (whether you have it set to be overridden below or not) from the `bshields.esro` object. For example, `bshields.esro.getObj` is the new version of `getObj`. You can also access the original Roll20 library versions of these functions directly in a similar way, through the `bshields.esro.r20` object. For example, `bshields.esro.r20.getObj` is the original version of `getObj`. Note that `bshields.esro` is not defined until this script's `ready` event completes.\n\n### What Do These New Functions Do?\nThe main purpose of these functions is to wrap objects and enhance their functionality. At this time, that specifically means creating properties that are directly accessible. So, instead of writing `token.set('left', token.get('left') + 70)`, you can write `token.left = token.left + 70` or even `token.left += 70`! Please note that if you wish to set multiple properties at once, it is still recommended that you call the `set` function, eg `token.set({ left: xCoord, top: yCoord })`. Read-only properties such as `_type` cannot have their values set, but you can access them with or without the leading underscore.\n\nThe modified versions of the object finding and creation functions (`getObj`, `Campaign`, `findObjs`, `filterObjs`, `getAllObjs`, and `createObj`) will all return appropriately wrapped objects; the functions that return arrays will return arrays of wrapped objects. The modified version of the event registering function (`on`) will pass wrapped objects to the callbacks of appropriate events. The modified versions of the object layering functions (`toFront` and `toBack`) will *unwrap* the object prior to sending it to Roll20's native `toFront` and `toBack` functions. **Please Note:** if you choose not to override `toFront` and `toBack`, but you *are* manipulating wrapped objects (for example, because you're overriding the object finding and/or creation functions), you must call `unwrap()` when sending the object to either of these ordering functions. If you are overriding the layering functions, the system will correctly handle passing both wrapped and unwrapped objects to them.\n\n#### `notes`, `gmnotes`, and `bio` Properties for Characters and Handouts\nFor these properties on a Character or Handout object, the `get` function is asynchronous. As such, you must call these properties like a function, instead of just treating them like a value. For example:\n\n    var system = findObjs({ type: 'character', name: 'System' })[0];\n    system.bio(function(text) {\n        log(text); // Print the System character's bio to the log\n    });\n\n#### Functions of Wrapped Objects\nIn addition to direct property access, there are some functions available to wrapped objects. The list of available functions includes *all* functions that are normally available to the Roll20 objects (`get`, `set`, `remove`, etc.) even if some (`get` and `set`, specifically) are redundant.\n\n**toString(minimal)**: the `toString` function has been redefined for wrapped objects. Instead of simply outputting \"[object Object]\", it will attempt to produce the JSON data for the object. In corner cases where that is not possible, or if you provide `true` as a parameter to the function, it will return \"[object Roll20Object -Abc_123]\" (using the object's actual `id` instead of `-Abc_123`). In corner cases where it is not possible to include the object's id, the return value will simply be \"[object Roll20Object]\", which at least is still more descriptive than the standard `toString`.\n\n**unwrap()**: the `unwrap` function is available for all wrapped objects to gain access to the original, unwrapped version of the object. This should not be needed under most circumstances, but it is required for `toFront` and `toBack` if you are not overwriting them despite using wrapped objects in your script.\n\n### Wrapping Objects Yourself\nIn addition to overwriting existing Roll20 functions to produce wrapped objects, you can wrap a normal Roll20 object manually by calling `bshields.esro.wrap(obj)`. Assuming no other script has already defined it, this script will also create the function `wrap` as a shorthand to the fully-qualified version, so you can just use `wrap(obj)`. The wrap function will be available regardless of whether you have any or all of the Roll20 functions being overwritten.",
  "authors": "Brian Shields",
  "roll20userid": "235259",
  "patreon": "https://www.patreon.com/bshields",
  "useroptions": [
    {
      "name": "Overwrite `getObj()`",
      "type": "checkbox",
      "value": "true",
      "checked": "checked",
      "description": "Overwrite the standard Roll20 `getObj` function with a version that will return a wrapped object."
    },
    {
      "name": "Overwrite `Campaign()`",
      "type": "checkbox",
      "value": "true",
      "checked": "checked",
      "description": "Overwrite the standard Roll20 `Campaign` function with a version that will return a wrapped object."
    },
    {
      "name": "Overwrite `findObjs()`",
      "type": "checkbox",
      "value": "true",
      "checked": "checked",
      "description": "Overwrite the standard Roll20 `findObjs` function with a version that will return an array of wrapped objects."
    },
    {
      "name": "Overwrite `filterObjs()`",
      "type": "checkbox",
      "value": "true",
      "checked": "checked",
      "description": "Overwrite the standard Roll20 `filterObjs` function with a version that will return an array of wrapped objects."
    },
    {
      "name": "Overwrite `getAllObjs()`",
      "type": "checkbox",
      "value": "true",
      "checked": "checked",
      "description": "Overwrite the standard Roll20 `getAllObjs` function with a version that will return an array of wrapped objects."
    },
    {
      "name": "Overwrite `createObj()`",
      "type": "checkbox",
      "value": "true",
      "checked": "checked",
      "description": "Overwrite the standard Roll20 `createObj` function with a version that will return a wrapped object."
    },
    {
      "name": "Overwrite `on()`",
      "type": "checkbox",
      "value": "true",
      "checked": "checked",
      "description": "Overwrite the standard Roll20 `on` function with a version that will pass a wrapped object to the callback function."
    },
    {
      "name": "Overwrite `toFront()`",
      "type": "checkbox",
      "value": "true",
      "checked": "checked",
      "description": "Overwrite the standard Roll20 `toFront` function with a version that will accept a wrapped object."
    },
    {
      "name": "Overwrite `toBack()`",
      "type": "checkbox",
      "value": "true",
      "checked": "checked",
      "description": "Overwrite the standard Roll20 `toBack` function with a version that will accept a wrapped object."
    }
  ],
  "dependencies": [],
  "modifies": {},
  "conflicts": []
}