Scene Regions | Foundry Virtual Tabletop

Most interesting battlemaps aren't just featureless grids. Perhaps part of your Scene is a set of stairs, a dark cave, a magical portal to another realm, or even a dastardly trap.

Scene Regions allow you to define these interesting parts of your map so that they do remarkable things or behave in certain ways. With Scene Regions, you could:

Set up “stairways”

Scene Regions allow you to define automatic teleportation zones which your players can easily use themselves without GM intervention.

These zones can be used to replicate stairs, elevators, magical portals, or similar concepts within Foundry. This teleportation can be set up between different Scene Regions as needed, even if one is on a different Scene.

Give “indoor” areas the properties you expect

You can make a building or a cave keep out the things it should, like weather and or daylight.

Perform actions when the Region detects certain changes

As an example, when a Token enters a Scene Region, that Region can automatically pause the game or even execute a custom Macro. Combined with Foundry's powerful API, this adds the potential for nearly limitless functionality, such as powering intricate puzzles or devious traps.

A player's Token enjoying the convenience of the Teleport Token Scene Region Behavior.

Scene Region Terminology Guide

Understanding Scene Regions begins with learning a few important concepts:

Scene Region Definitions

Region

A Region, often called a “Scene Region”, represents one or more parts of a Scene that you would like to behave in a certain way.

Each Region may contain many Shapes (which all share the same Behaviors). Without at least one Shape and Behavior, a Region doesn't actually do anything.

Shape

The geometry of a Scene Region is made out of Shapes that cover an area in the canvas, much like Drawings.

Each Shape can be rectangular, elliptical, or polygonal, and the part of the canvas that is considered to be within the Region is determined by the combination of all its Shapes. Some of these Shapes may be “holes,” which actually remove areas from the Region.

A single elevation range may be assigned to every Shape in the Scene Region. This means it is possible to go “under” or “over” a Scene Region's Shapes without traveling through them.

Hole

A hole is a Shape, but it is considered a "negative Shape" that removes geometry from the Region instead of adding it.

Behavior

Behaviors are the functionality that a Scene Region can perform. Each Region can have multiple Behaviors.

Event

An Event is a change that is related to a Region, such as a Token entering or leaving one of its Shapes.

Behaviors can “subscribe” to Events, allowing them to "trigger" when the Region detects that Event.

Three different Scene Regions, each containing a single Shape of a different geometry type.

Three heroes avoiding a Scene Region by standing in holes inside it.

Scene Region Controls

The Scene Regions Layer's Tool pallette can opened by clicking the chessboard icon () on the left-hand side of the user interface. When you click this menu button, a Scene Region Legend also displays to help manage Regions in the Scene.

The Scene Region Layer Menu

The following tools are available in the Scene Regions Layer Menu:

Select Regions ( ): This tool allows you to select Regions by clicking or drag-selecting their Shapes in the canvas so that you can configure or delete them. Use SHIFT to select more than one Scene Region at a time.
Draw Rectangle ( ): Used for drawing rectangular Shapes. Holding ALT while drawing creates a perfect square.; If an existing Scene Region is already selected, this new Shape will be added to that existing Scene Region. Otherwise, a new Scene Region is automatically created and this Shape is added to it.
Draw Ellipse ( ): Used for drawing elliptical Shapes. Holding ALT while drawing creates a perfect circle.; If an existing Scene Region is already selected, this new Shape will be added to that existing Scene Region. Otherwise, a new Scene Region is created and this Shape is automatically added to it.
Draw Polygon ( ): Left-click with this tool to create polygonal Shapes from a sequence of straight lines. Right-click to remove the last point drawn or double-click to finish.; If an existing Scene Region is already selected, this new Shape will be added to that existing Scene Region. Otherwise, a new Scene Region is created and this Shape is automatically added to it.
Create Holes ( ): This option is a toggle that stays enabled or disabled. When it is enabled, it glows visually and any new Shapes that are drawn are created as holes. For more information, see holes.
Force Snap to Grid Vertices ( ): This option is a toggle that stays enabled or disabled. When it is enabled, it glows visually and any new Shapes that are drawn automatically snap to the grid.
Clear Regions ( ): After a confirmation prompt, this button clears all existing Regions that you own in the Scene.

The Scene Region Legend

The Scene Regions Legend offers a unique way to view and manage your Scene Regions. You can use this tool to create a blank new Scene Region or to view, select, or configure any Region in the currently viewed scene.

Creating a Blank Scene Region Using the Legend

Click the "Create Region" button (the icon in the upper-right corner) to create a blank new Scene Region. For more information about configuring a Scene Regions, see Configuring Scene Regions below.

The Scene Region Legend Interface

When you hover over a region in the Scene Region Legend, it is visually highlighted in the canvas and the Legend. If you click a Scene Region's row, you can select or deselect it. You can also select more than one Scene Region at a time using the SHIFT key.

The row for each Scene Region has the following features:

Elevation Range Label (not always present): If an elevation range is specified for this Scene Region, this elevation range displays in the Region's row in the format [bottom,top]. If no elevation range is specified, the Scene Region applies to all elevations.
Configure Region ( ): Opens the Scene Region's configuration dialog, just like double-clicking it in the canvas.
Lock Region ( ): Locks the region, preventing it deleting the Scene Region, adding Shapes to it, or removing any of its Shapes.
Delete Region ( ): If the Region is locked, this icon is disabled. If the Region is not locked, clicking this button prompts the user whether they want to delete the entire Scene Region.

Creating Scene Regions

There are two ways to create Scene Regions:

The Scene Region Legend

You can use the Scene Region Legend's "Create Region" button (the icon in the upper-right corner) to create a new, empty Scene Region. Because this Scene Region has no Shapes or Behaviors, it is just a placeholder until you configure it (see below).
Drawing new Shapes

If you have no Scene Region currently selected, using one of the Region Layer's tools that draw a new Shape ("Draw Rectangle", "Draw Ellipse", or "Draw Polygon") automatically creates a new Region to contain that Shape.

Note: If a Scene Region is already selected when you draw a Shape, that Shape is automatically added to the selected Scene Region instead of creating a new one.

You can deselect Scene Regions using either the Scene Region Legend or the canvas. Please note that if you do not have the "Left Click to Deselect Objects" Game Setting enabled, you may need to draw an empty selection to deselect Scene Regions.

Configuring Scene Regions

After creating a Scene Region, use the Scene Region Configuration dialog to edit its properties. You can open this dialog using the Scene Region Legend or by double-clicking it in the canvas.

The Identity Tab

The available fields in the Identity tab allow you to control how the Scene Region is identified and displayed.

Name

A name used to identify this Scene Region which is used to label it in the Scene Region legend.

Color

The color that is used to identify this Scene Region in both the canvas and the Scene Region Legend.

Elevation

These two fields define the top and the bottom of range of elevations that the Scene Region applies to, potentially allowing Tokens to avoid it by passing "under" or "over" it. By default, a Scene Region exists at all elevations.

If an elevation is specified, it also displays in the Scene Region Legend.

Visibility

This field provides options to control when this Scene Region should be displayed in the canvas:

Only on Regions Layer

The default visibility option. With this option selected, Scene Regions are only visible when you are viewing the Scene Regions Layer of the canvas, just like Lights or Walls.
Always for Gamemaster

If this option is chosen, users with Assistant GM or Gamemaster permissions can always see this scene region, regardless of the current canvas layer. For example, you might choose this option to indicate a region that is functioning as a trap.
Always for Everyone

With this option selected, all users can always see this scene region, regardless of the current canvas layer. For example, you might choose this option to indicate the region of a trap region that has been discovered by the party.

The Scene Region Configuration Dialog with the "Identity" tab shown.

The Shapes Tab

Because Shapes define the geometry of the Scene Region, the fields in this tab control how the Scene Region exists in the canvas.

There are two ways to add new Shapes to this Scene Region so that they display in this tab:

Draw a new Shape

Ensure this Scene Region is selected, then use this layer's "Draw Rectangle", "Draw Circle", or "Draw Polygon" tools to add the new Shape to it.
Add a new Shape using Walls

Adding New Shapes Using Walls

Often, you have already used Walls to trace out the exact geometry that you want to add as a Shape, such as when you want to add a Scene Region for an entire building. The "Create Shape from Controlled Walls" button ( ) in the upper-right of this tab allows you to easily create a Shape using that existing Wall geometry.

Please Note: The controlled walls must form a complete loop.

To add a Shape using Walls:

Click the "Create Shape from Controlled Walls" button

Foundry automatically switches to the Walls layer and selects the Select Walls tool.
Select the loop of outermost walls that trace out your future Shape

Select ("control") the walls that contain the area that you want to add as a Shape.

You may consider adding a wall or two temporarily to form a loop. If your walls look like they close but don't, you may have small gaps in your Walls. If necessary, make sure that you are not holding the SHIFT key, then adjust wall endpoints to allow grid snapping to connect them perfectly.
Click the "Create Shape from Controlled Walls" button again

If your wall selection is valid, a Shape is created and added to your Scene Region. If your Wall selection is not valid, please see the previous step for tips on how to correct the issue.

After adding a Shape in this way, Foundry remains on the Walls layer. You can either continue adding additional Shapes from Walls, or return to the Scene Regions layer to continue working with Regions.

Configuring Existing Shapes

Each existing Shape of the Scene Region is listed as a row in the Shapes tab. When you hover the rows in this tab, that Shape is outlined in dashes in the canvas (even if it is a hole).

If at least one Shape is a hole, then the order of the Shapes matter. A Shape that is a hole only "punches through" the Shapes that are above it in the list of Shapes, as shown by the bottom Circle shape in the previous figure.

Several buttons are available to control the existing Shapes in this tab.

Make Hole ( or )

Clicking this button toggles whether the Shape is considered a hole or not.

A filled circle ( )indicates that the Shape is not currently considered a hole.
An empty circle ( ) indicates that this Shape is a hole.

Move Shape Up and Move Shape Down ( and )

These two buttons change the relative order of Shapes in this list, which is mostly important for determining how holes are applied to the Scene Region's geometry.

Delete Shape ( )

After a confirmation prompt, this button deletes the Shape from the Scene Region.

A Shape created using the "Create Shape from Controlled Walls" button.

The "Shapes" tab and those same Shapes in the canvas.

The Behaviors tab

Behaviors are the functionality that a Scene Region can perform, and each Scene Region can support many Behaviors. This tab allows you tc create and manage these behaviors. Each Behavior of the Scene Region appears in a row in this tab, sorted alphabetically by name.

When a new Scene Region is created, no Behaviors are present. At least one Behavior must be added for the Scene Region to have any functionality. You can create a new behavior by clicking the "Create Behavior" button ( ).

Several buttons are available in each Behavior's row:

The Enable / Disable slider ( or ): A Behavior is only functional if this slider is enabled ( ) . When a Behavior is disabled ( ), it does not affect its Scene Region in any way.
Edit Behavior ( ): Clicking this button opens its "Configure Behavior" dialog. For more information on how to configure each type of Behavior, see the "Scene Region Behaviors" section below.
Delete Behavior ( ): After a confirmation prompt, this button deletes the Behavior from the Scene Region.

The "Scene Region Configuration" dialog with the "Behaviors" tab and some example Behaviors shown.

Scene Region Behaviors

Behaviors are what a Scene Region actually does. Each Region can support multiple Behaviors, and every Shape within that region shares the same set of Behaviors.

The available built-in Behaviors can be leveraged to accomplish a variety of goals. Some Behaviors require Events, while others have a continuous effect on their Region.

UUIDs and Behaviors

Some Behavior types, notably the Teleport Token and Execute Macro Behaviors, need to identify a different thing that they work with. The Teleport Token behavior needs to specify which Scene Region it teleports into, and the Execute Macro button needs to specify which Macro it executes. In both cases, this is performed by providing the behavior with the UUID ("Universally Unique IDentifier") of the thing that it links to.

Two Behavior fields which require adding document UUIDs and where to find them.

Looking up the UUID of any object in Foundry is the same. Simply open its Configuration Dialog and left-click the "Copy ID" button in its header to copy the UUID to the clipboard. Once you have the UUID that you want to use with your Behavior, paste it into the Behavior's configuration dialog as needed. Make sure to press the "Add Document" button ( )!

Note: Remember to double-check that you clicked the "Add Document" button before closing the dialog!

Available Behaviors

Continuous Behaviors

These behaviors do not require a subscribed Event. If these Behaviors are enabled, they always have their effect on their Region.

Adjust Darkness Level: Have you ever wanted to exclude part of a scene from Global Illumination, so that the light level outside was different from the light level inside? This Behavior delivers that ability and more.; If the result of this Behavior makes the region dark enough, the area is no longer considered lit, even if Global Illumination is enabled on the Scene. This means that Tokens will need a source of light or a special vision mode to be able to see in this darkened area. This works exactly the same way that Global Illumination can be automatically disabled "at night": the level of darkness is checked agains the Scene's Global Illumination Threshold. For more information, see the Scenes article.
Suppress Weather: Foundry allows the prevention of weather effects through the use of Tiles, but you may not have a convenient tile to place for a roof. Additionally, it might not make much sense to place a "roof" tile for an area, such as a natural cave. Adding this behavior to a Region will stop rendering weather effects inside the Region, whether there's a roof there or not.

A cozy cave that is protected from the elements by a Scene Region's Suppress Weather behavior.

Event-based Behaviors

The Region only performs this type of Behavior if it is enabled and a subscribed Event is detected for that Region.

Execute Macro

For those Macro-hoarding GMs who already have all manner of pre-coded scripts ready to go for certain actions and just want them to trigger automatically, the Execute Macro behavior does what it says on the label: when you assign it the UUID of a given Macro (which can be gotten by right-clicking the ID button in the Macro's header), it will trigger that Macro when its Scene Region detects that one of its subscribed events occurs.

If you want to write your own Macros to use, the Scene Region passes in several important values to help you:

behavior

The Execute Macro behavior itself.
event

The Event that triggered the execution of the macro. Using event.data.token is particularly useful, since it recontains the Token that triggered the Event (or null if there isn't one).
region

The Region that triggered the Macro.
scene

The Scene that contains the Region that called the Macro.

For more information about writing and using Macros, see the Macros article.

Execute Script

This Behavior functions exactly like the Execute Macro behavior but it executes a script file instead of a Macro. It provides the same values to any Script that is called as the Execute Macro behavior does also.

Pause Game

This Behavior only happens when the user controlling the token is not a GM. This means testing this Region requires you to log in as a player.

Sick of your players running off like a shot and skipping past your carefully planned traps, having to move them back and clear the fog of war? Just draw a scene region that will pause the game whenever a token enters the region. For convenience, you can also toggle the "Once" option so it doesn't do it every single time a token passes by.

Teleport Token

Perhaps one of the most desired features, the Teleport Token behavior allows you to instantaneously transport a token that enters the region from one region to another. Similar to Execute Macro, this behavior requires the UUID of another Scene Region to serve as a destination. The destination region can even be in a different scene!

Toggle Behavior

Have a particular behavior you only want to activate after a certain condition has been met, such as a trap that is only active after a token has stepped on its pressure plate? Toggle behavior allows you to link to the UUID of a different Behavior, enabling or disabling the linked behavior when a certain triggering event occurs.

In the hands of even a novice coder, Scene Regions can be leveraged to create truly powerful automations.

Note: Modules or Game Systems may provide additional Behaviors. Please consult their documentation for more information about them.

Scene Region Events

Behaviors can check for Events to determine if they need to perform certain Behaviors, like Pause Game or Execute Script. You can add an Event to a Behavior to have it "subscribe" to that Event, causing it to regularly check whether that Event occurred within its geometry.

Available Events

By default, the following Events are available:

Region Boundary Changed: This Event occurs if the Scene Region's geometry changed in any way, such as by adding a Shape, removing it, or changing whether that Shape is a hole. It also fires if the order of the Shapes are changed, but it does not fire if the entire Region is deleted.
Behavior Status Changed: Occurs if the Behavior that is subscribed to this Event is enabled or disabled. It does not occur if other Behaviors in the same Region (or different Regions) are enabled or disabled.
Token Enters: This Event fires if a Token enters the Region by any method, including the token being created there as a result of a Copy or drag-and-drop operation. It does not fire if the Token is already in the region when the Scene is loaded.

Token Exits: Event occurs if a Token leaves the Region by any method, including the token being deleted.
After Token Moved: A Token "moves" in relation to a Region when it is about to move into, out of, through, or within a Region. This Event occurs immediately after a Token completes such a move.
Before Token Moves: A Token "moves" in relation to a Region when it is about to move into, out of, through, or within a Region. This Event occurs immediately when a Token is about to perform such a move.
Token Moved In: This Event occurs when a Token begins a movement that has a destination inside a Region and the Token was not inside that Region's boundaries before the movement began.
Token Moved Out: This Event occurs when a Token begins a movement that has a destination outside a Region and the Token was inside that Region's boundaries before the movement began.
Token Starts Turn: Occurs when a Token inside this region is part of a Combat Encounter and a Combat Turn begins.
Token Ends Turn: Occurs when a Token inside this region is part of a Combat Encounter and a Combat Turn ends.
Token Starts Round: Occurs when a Token inside this region is part of a Combat Encounter and a Combat Turn begins.
Token Ends Round: Occurs when a Token inside this region is part of a Combat Encounter and a Combat Round ends.

Watch where you step! There may be slide traps powered by the Token Enters Event...

Note: Modules or Game Systems may provide additional Events. Please consult their documentation for more information about them.

Scene Region Examples

The following common examples are provided to illustrate how Scene Regions operate and how you might want to use them.

Pause Game "Trap"

Coming soon!
The Cosy Cave

Coming soon!
Stairs

Coming soon!
Execute Macro

Coming soon!
Slide Trap

Coming soon!

Developer Notes and API References

Scene Regions are built so that game systems and modules can easily add their own functionality. We can't wait to see what mad creations our developer community implements using this framework!

Developer Note: The name of the new Document type that stores Scene Region information is Region, and it contains BehaviorEmbedded Documents. Shapes are not embedded documents, but rather are stored in an array in the Region document.

To interact with Scene Regions programmatically, you will primarily use the following API concepts:

The classes/client.BaseRegion document