Scene entities represent the areas of a World that the players may explore. Scenes may depict a variety of settings ranging from world or regional maps all the way down to small buildings or dungeons. At each point in time, one Scene may be treated as the active scene. The same scene is active for all users. For each individual user a different Scene may be treated as the viewed scene, which is the area currently rendered on the game canvas for that user. The Foundry VTT framework provides APIs for manipulating and modifying Scene structure and configuration.

There are several important API layers which are useful when working with Scenes. The Scenes() collection contains all of the Scene() instances which are defined by the World, the collection of these scenes is available as game.scenes.

When modifying the scene configuration, the data is rendered and edited using the SceneSheet() class which can be extended or overridden by systems or modules. To override the default implementation, a module should define the Config.Scene.sheetClass global configuration value.

Additionally, each scene has rich notes associated with it which are customizable using the SceneNotes() class. Similarly, this class can be overridden or extended by modules by altering the Config.Scene.notesClass global configuration.

The Scenes Collection

class Scenes()

The collection of Scene entities


Add a new Entity to the Collection, asserting that they are of the correct type

  • entity (Entity) – The entity instance to add to the collection

Remove an Entity from the Collection by its ID.

  • id (String) – The entity ID which should be removed

Get an element from the collection by ID

  • id (String) – The entity ID to retrieve from the collection

Entity – The retrieved Entity, if the ID was found, otherwise null;


Retrieve the index of an entity within the collection by its ID

  • id (String) – The entity ID to retrieve from the collection

Number – The index of the Entity within the collection, if found, otherwise -1;


Render all applications associated with this Collection

Scenes.activate(sceneId, push=false)

Set a new Scene as active

  • sceneId (String) – The ID of the scene to activate
  • push (Boolean) – Push the scene activation to other connected clients

The Scene Class

class Scene(data, apps)

The Scene entity

Scene.deleteToken(tokenId, push=false)

Delete a Token from this scene by its ID

  • tokenId (Number) – The ID of the Token to delete
  • push (Boolean) – Push the Token deletion to other clients?

A singleton instance of the SheetNotes class


The Scene sheet is the singleton instance of SceneSheet


Open socket listeners which transact Scene data

  • socket (Socket) –
    The connection
Scene.update(data, push)

Modify scene update logic. If the updated scene is currently active, we need to re-draw the canvas


Update scene token data. This method should only ever be used with inactive (background) scenes. For updating the scene which is active in the canvas, the token layer should be updated directly.

  • data (Object) – The new tokenData to update or insert

Set this scene as the current view

The Scene Sheet

class SceneSheet(scene, options)

A Scene configuration sheet


Assign the default options which are supported by this Application