🎉 The new Community Maps feature just launched! Learn More →

Prerequisites, Interacting with the Console, and Macro Arguments

Interacting with the Console

The JavaScript console is a web browser tool that allows you to interact with the code running in the browser. It is a powerful tool that can be used to debug and test your macros.

  • To open the console, right-click on the page and select "Inspect" or press Ctrl + Shift + I (Windows), F12, or Cmd + Option + I (Mac).
  • Switch to the Console tab at the top of the panel.
  • You will now be able to read the Console logs.
  • Identify the bottom text input box (it will be a text box with a > symbol at the beginning). This will be used to enter code into the console when needed.

We will be using the console to log data from our macros and inspect the Foundry VTT (FVTT) data structures.

Macro Arguments

Every macro will have two default arguments that we can use. These will be used in the examples, so let's discuss what they represent:

  • token: This references the currently selected token. If no token is selected and the user is a GM, this value will be missing. If the user is a player, this will reference the token matching the actor assigned to the player.
  • actor: This references the actor of the currently selected token. If no token is selected and the user is a GM, this value will be missing. If the user is a player, this will reference the user's assigned character.

Your First Macro

Let's create a simple macro that will log the actor and the token to the console for inspection.

console.log(actor);
console.log(token);

or

console.log(actor, token);

While the console is open, save and run the macro, making sure to have a token selected on the scene. You should see the following output in the console:

Token {...}
Actor {...}

where {...} represents the actual data of the token and actor.

Using the Console to Inspect Data

We can use the console to inspect the data of the token and actor.

  • Click on either the token or the actor to expand its data in the console.
  • You will see a long list of keys. This is a JavaScript object. You can keep expanding the object to go deeper into the data structure.

JavaScript Objects

JavaScript objects are a way to store data in a structured way. An object is a collection of key-value pairs, where each key is a string and each value can be any type of data, including other objects.

Objects can be recognized by their curly braces {}. For example:

{
  name: "John",
  age: 30,
  city: "New York",
}

Object properties can be accessed using dot notation. For example, if this is part of the data of a token:

{
    document: {
        name: "John",
        texture: {
            src: "icons/svg/dice-target.svg",
        },
        width: 1,
        height: 1,
    }
}

You can access the image path of the token by using token.document.texture.src.

Example:

console.log(token.document.texture.src);

Console output:

icons/svg/dice-target.svg

A note on Quotation Marks

When accessing objects and in these examples you can sometime see parts of the object that are enclosed in quotation marks. This is because the object is a string. For example, the src property of the token's document object is a string that contains the path to the image.

At times, quotation marks are required for object keys as well, this is because the key contains special characters.

Example:

{
    document: { // The document key, has not special characters, so we don't need to use quotation marks
        name: "John", // "John" is a string, so we need to use quotation marks
        texture: {
            src: "icons/svg/dice-target.svg",
        },
        width: 1, // 1 is a number, so we don't use quotation marks
        height: 1,
    }
}

Nested properties can also be accessed using the dot notation within the Object, the above example is equivalent to:

{
    document: {
        name: "John",
        "texture.src": "icons/svg/dice-target.svg", // The texture key has a special character, so we need to use quotation marks
        width: 1,
        height: 1,
    }
}

Note that if you wish to avoid confusion, you can always use quotation marks, such as:

{
    "document": {
        "name": "John",
        "texture.src": "icons/svg/dice-target.svg",
        "width": 1,
        "height": 1,
    }
}
Auto Cover