Accessing Documents

Having a solid grasp of how to interact with documents in Foundry VTT, you're now ready to incorporate them into your macros effectively. While macros naturally access token and actor objects, understanding how to access other documents opens up more possibilities.

Accessing Documents

IDs and UUIDs

In Foundry VTT, documents are distinguished by their IDs and UUIDs.

IDs

IDs are unique identifiers specific to a document. However, most IDs require contextual information, typically their container.

UUIDs

UUIDs serve as universal identifiers for documents, generated automatically by Foundry VTT. They enable document identification across the game world, irrespective of context or container.

IDs vs UUIDs: A Practical Example

Consider our token from the previous article.

console.log(token.document.id); // Output: 'ieHxQxCWYVtY07oi' (this ID is unique to your token)
console.log(token.document.uuid); // Output: 'Scene.xcKEdiLWe09s5Pfl.Token.ieHxQxCWYVtY07oi'

Here, the ID uniquely identifies the token within its scene. Meanwhile, the UUID not only includes the token's ID (ieHxQxCWYVtY07oi) but also the scene it belongs to (xcKEdiLWe09s5Pfl). Generally, working with UUIDs is more reliable.

Finding the ID or UUID of a Document

To retrieve a document's ID or UUID (aside from logging it), follow these steps within the FVTT interface:

• Open the document sheet (e.g., token configuration, actor sheet, or scene configuration).
• On the top-left, locate the book icon.
• Left-click to copy the ID; Right-click to copy the UUID.

Accessing Documents in Macros by ID or UUID

Now equipped with the ID or UUID knowledge, you can utilize them in macros to access documents.

Accessing Documents in Macros by UUID

const tokenUUID = "Scene.xcKEdiLWe09s5Pfl.Token.ieHxQxCWYVtY07oi";
const tokenDocument = fromUuidSync(tokenUUID);
console.log(tokenDocument);

When a document resides within a compendium, data retrieval requires database access, necessitating an await for data retrieval, as discussed with the update method.

const tokenUUID = "Scene.xcKEdiLWe09s5Pfl.Token.ieHxQxCWYVtY07oi";
const tokenDocument = await fromUuid(tokenUUID);
console.log(tokenDocument);

Note that fromUuid requires an await regardless of whether the document is within a compendium.

Accessing Documents in Macros by ID

Accessing documents by ID is more complex, as it requires knowledge of the document's location in the game world. In such cases, the get method is employed.

const tokenID = "ieHxQxCWYVtY07oi";
// Assuming the token is in the current scene
const tokenDocument = canvas.scene.tokens.get(tokenID);
console.log(tokenDocument);

For instance, accessing a journal page by its ID necessitates knowledge of the journal's ID.

const pageID = "jKgK9K9gK9gK9K9g";
const journalID = "f3qwfqwfqwfqwfqw";
const journalDocument = game.journal.get(journalID);
const pageDocument = journalDocument.pages.get(pageID);
console.log(pageDocument);

In Practice: Toggling a Light on and Off

Let's apply our knowledge to create a macro toggling a light on and off.

• Open the Light configuration sheet.
• Copy the UUID of the light.

const lightUUID = "Scene.xcKEdiLWe09s5Pfl.AmbientLight.jKgK9K9gK9gK9K9g";
const lightDocument = fromUuidSync(lightUUID);
const isLightOff = lightDocument.hidden;
 
if (isLightOff) {
  lightDocument.update({ hidden: false });
} else {
  lightDocument.update({ hidden: true });
}

Alternatively, using the ID approach:

• Open the Light configuration sheet.
• Copy the light's ID.
• Open the scene configuration sheet.
• Copy the scene's ID.

const lightID = "jKgK9K9gK9gK9K9g";
const sceneID = "xcKEdiLWe09s5Pfl";
const scene = game.scenes.get(sceneID);
const lightDocument = scene.lights.get(lightID);
const isLightOff = lightDocument.hidden;
 
if (isLightOff) {
  lightDocument.update({ hidden: false });
} else {
  lightDocument.update({ hidden: true });
}

With this understanding, you're well-equipped to craft diverse and useful macros. In the next chapter, we'll explore how to access documents in other ways.