The singleton collection of Macro documents which exist within the active World. This Collection is accessible within the Game object as game.macros.


Hierarchy (view full)



apps: Application[]

An Array of application references which will be automatically updated when the collection content changes

invalidDocumentIds: Set<string> = ...

Record the set of document ids where the Document was not initialized because of invalid source data

documentName: string = "Macro"


  • get directory(): any
  • Returns any

  • get folders(): Collection<string, Folder>
  • Reference the set of Folders which contain documents in this collection

    Returns Collection<string, Folder>

  • get documentClass(): typeof Document
  • A reference to the Document class definition which is contained within this DocumentCollection.

    Returns typeof Document

  • get documentName(): any
  • Returns any

    Inherit Doc

  • get name(): string
  • The Collection class name

    Returns string

  • get instance(): WorldCollection
  • Return a reference to the singleton instance of this WorldCollection, or null if it has not yet been created.

    Returns WorldCollection

  • get registeredSheets(): DocumentSheet[]
  • Return an array of currently registered sheet classes for this Document type.

    Returns DocumentSheet[]



  • Apply data transformations when importing a Document from a Compendium pack


    • document: any

      The source Document, or a plain data object

    • options: {} = {}

      Additional options which modify how the document is imported

      Returns any

      The processed data ready for world Document creation

    • Import a Document from a Compendium collection, adding it to the current World.


      • pack: CompendiumCollection

        The CompendiumCollection instance from which to import

      • id: string

        The ID of the compendium entry to import

      • Optional updateData: any = {}

        Optional additional data used to modify the imported Document before it is created

      • Optional options: any = {}

        Optional arguments passed to the WorldCollection#fromCompendium and Document.create methods

      Returns Promise<Document>

      The imported Document instance

    • Instantiate a Document for inclusion in the Collection.


      • data: any

        The Document data.

      • Optional context: any = {}

        Document creation context.

      Returns Document

    • Obtain a temporary Document instance for a document id which currently has invalid source data.


      • id: string

        A document ID with invalid source data.

      • Optional options: {
            strict: boolean;
        } = {}

        Additional options to configure retrieval.

        • strict: boolean

          Throw an Error if the requested ID is not in the set of invalid IDs for this collection.

      Returns Document

      An in-memory instance for the invalid Document


      If strict is true and the requested ID is not in the set of invalid IDs for this collection.

    • Get an element from the DocumentCollection by its ID.


      • id: string

        The ID of the Document to retrieve.

      • Optional options: {
            strict: boolean;
            invalid: boolean;
        } = {}

        Additional options to configure retrieval.

        • strict: boolean

          Throw an Error if the requested Document does not exist.

        • invalid: boolean

          Allow retrieving an invalid Document.

      Returns Document


      If strict is true and the Document cannot be found.

    • Parameters

      • id: any
      • document: any

      Returns void

      Inherit Doc

    • Render any Applications associated with this DocumentCollection.


      • force: any
      • options: any

      Returns void

    • Find all Documents which match a given search term using a full-text search against their indexed HTML fields and their name. If filters are provided, results are filtered to only those that match the provided values.


      • search: {
            query: string;
            filters: FieldFilter[];
            exclude: string[];

        An object configuring the search

        • query: string

          A case-insensitive search string

        • filters: FieldFilter[]

          An array of filters to apply

        • exclude: string[]

          An array of document IDs to exclude from search results

      Returns string[]

    • Update all objects in this DocumentCollection with a provided transformation. Conditionally filter to only apply to Entities which match a certain condition.


      • transformation: any

        An object of data or function to apply to all matched objects

      • condition: Function = null

        A function which tests whether to target each object

      • Optional options: any = {}

        Additional options passed to Document.updateDocuments

      Returns Promise<Document[]>

      An array of updated data once the operation is complete

    • Internal

      Follow-up actions to take when a database operation modifies Documents in this DocumentCollection.


      • action: DatabaseAction

        The database action performed

      • documents: ClientDocument[]

        The array of modified Documents

      • result: any[]

        The result of the database operation

      • operation: DatabaseOperation

        Database operation details

      • user: User

        The User who performed the operation

      Returns void

    • Register a Document sheet class as a candidate which can be used to display Documents of a given type. See DocumentSheetConfig.registerSheet for details.


      • Rest ...args: any[]

        Arguments forwarded to the DocumentSheetConfig.registerSheet method

      Returns void


      Example: Register a new ActorSheet subclass for use with certain Actor types.

      Actors.registerSheet("dnd5e", ActorSheet5eCharacter, { types: ["character], makeDefault: true });
    • Unregister a Document sheet class, removing it from the list of available sheet Applications to use. See DocumentSheetConfig.unregisterSheet for detauls.


      • Rest ...args: any[]

        Arguments forwarded to the DocumentSheetConfig.unregisterSheet method

      Returns void


      Example: Deregister the default ActorSheet subclass to replace it with others.

      Actors.unregisterSheet("core", ActorSheet);
    • Get the searchable fields for a given document or index, based on its data model


      • documentName: string

        The document type name

      • Optional documentSubtype: string = ""

        The document subtype name

      • Optional isEmbedded: boolean = false

        Whether the document is an embedded object

      Returns Set<string>

      The dot-delimited property paths of searchable fields