This Canvas Layer provides a container for AmbientSound objects.

Hierarchy (view full)

Properties

livePreview: boolean = false

Track whether to actively preview ambient sounds with mouse cursor movements

sources: Collection<string, PointSoundSource> = ...

A mapping of ambient audio sources which are active within the rendered Scene

objects: any = null

Placeable Layer Objects

preview: any = null

Preview Object Placement

history: CanvasHistory[] = []

Keep track of history so that CTRL+Z can undo changes

_copy: PlaceableObject[] = []

Keep track of an object copied with CTRL+C which can be pasted later

quadtree: Quadtree = ...

A Quadtree which partitions and organizes Walls into quadrants for efficient target identification.

highlightObjects: boolean = false

Track whether "highlight all objects" is currently active

eventMode: string = "passive"
options: {
    name: string;
} = ...

Options for this layer instance.

Type declaration

  • name: string
#onDarknessChange: _onDarknessChange

Darkness change event handler function.

#drawing: Promise<CanvasLayer> = ...

An internal reference to a Promise in-progress to draw the CanvasLayer.

#drawn: boolean = false

Is the layer drawn?

documentName: string = "AmbientSound"

A reference to the named Document type which is contained within this Canvas Layer.

SORT_ORDER: number = 0

Sort order for placeables belonging to this layer.

CREATION_STATES: {
    NONE: number;
    POTENTIAL: number;
    CONFIRMED: number;
    COMPLETED: number;
} = ...

Creation states affected to placeables during their construction.

Type declaration

  • NONE: number
  • POTENTIAL: number
  • CONFIRMED: number
  • COMPLETED: number

Accessors

  • get hookName(): string
  • The name used by hooks to construct their hook string. Note: You should override this getter if hookName should not return the class constructor name.

    Returns string

  • get documentCollection(): any
  • Obtain a reference to the Collection of embedded Document instances within the currently viewed Scene

    Returns any

  • get hud(): BasePlaceableHUD<any, any, any>
  • If objects on this PlaceablesLayer have a HUD UI, provide a reference to its instance

    Returns BasePlaceableHUD<any, any, any>

  • get placeables(): PlaceableObject[]
  • A convenience method for accessing the placeable object instances contained in this layer

    Returns PlaceableObject[]

  • get controlled(): PlaceableObject[]
  • An Array of placeable objects in this layer which have the _controlled attribute

    Returns PlaceableObject[]

  • get controlledObjects(): Map<string, PlaceableObject>
  • Track the set of PlaceableObjects on this layer which are currently controlled.

    Returns Map<string, PlaceableObject>

  • get hover(): PlaceableObject
  • Track the PlaceableObject on this layer which is currently hovered upon.

    Returns PlaceableObject

  • get active(): boolean
  • Is this layer currently active

    Returns boolean

  • get name(): string
  • The canonical name of the CanvasLayer is the name of the constructor that is the immediate child of the defined baseClass for the layer type.

    Returns string

    Example

    canvas.lighting.name -> "LightingLayer"
    
  • get layerOptions(): any
  • Configuration options for the PlaceablesLayer.

    Returns any

  • get placeableClass(): Function
  • Obtain a reference to the PlaceableObject class definition which represents the Document type in this layer.

    Returns Function

  • get instance(): CanvasLayer
  • Return a reference to the active instance of this canvas layer

    Returns CanvasLayer

Methods

  • Parameters

    • options: any

    Returns Promise<void>

  • The inner _tearDown method which may be customized by each CanvasLayer subclass.

    Parameters

    • options: any

      Options which configure how the layer is deconstructed

    Returns Promise<void>

  • Initialize all AmbientSound sources which are present on this layer

    Returns void

  • Update all AmbientSound effects in the layer by toggling their playback status. Sync audio for the positions of tokens which are capable of hearing.

    Parameters

    • Optional options: any = {}

      Additional options forwarded to AmbientSound synchronization

    Returns any

  • Preview ambient audio for a given mouse cursor position

    Parameters

    • position: Point

      The cursor position to preview

    Returns void

  • Terminate playback of all ambient audio sources

    Returns void

  • Get an array of listener positions for Tokens which are able to hear environmental sound.

    Returns Point[]

  • Internal

    Actions to take when the darkness level of the Scene is changed

    Parameters

    • event: FederatedEvent

    Returns void

  • Play a one-shot Sound originating from a predefined point on the canvas. The sound plays locally for the current client only. To play a sound for all connected clients use SoundsLayer#emitAtPosition.

    Parameters

    • src: string

      The sound source path to play

    • origin: Point

      The canvas coordinates from which the sound originates

    • radius: number

      The radius of effect in distance units

    • options: {
          volume: number;
          easing: boolean;
          walls: boolean;
          gmAlways: boolean;
          baseEffect: AmbientSoundEffect;
          muffledEffect: AmbientSoundEffect;
          sourceData: PointSourceData;
          playbackOptions: SoundPlaybackOptions;
      } = {}

      Additional options which configure playback

      • volume: number

        The maximum volume at which the effect should be played

      • easing: boolean

        Should volume be attenuated by distance?

      • walls: boolean

        Should the sound be constrained by walls?

      • gmAlways: boolean

        Should the sound always be played for GM users regardless of actively controlled tokens?

      • baseEffect: AmbientSoundEffect

        A base sound effect to apply to playback

      • muffledEffect: AmbientSoundEffect

        A muffled sound effect to apply to playback, a sound may only be muffled if it is not constrained by walls

      • sourceData: PointSourceData

        Additional data passed to the SoundSource constructor

      • playbackOptions: SoundPlaybackOptions

        Additional options passed to Sound#play

    Returns Promise<any>

    A Promise which resolves to the played Sound, or null

    Example: Play the sound of a trap springing

    const src = "modules/my-module/sounds/spring-trap.ogg";
    const origin = {x: 5200, y: 3700}; // The origin point for the sound
    const radius = 30; // Audible in a 30-foot radius
    await canvas.sounds.playAtPosition(src, origin, radius);

    Example: A Token casts a spell

    const src = "modules/my-module/sounds/spells-sprite.ogg";
    const origin = token.center; // The origin point for the sound
    const radius = 60; // Audible in a 60-foot radius
    await canvas.sounds.playAtPosition(src, origin, radius, {
    walls: false, // Not constrained by walls with a lowpass muffled effect
    muffledEffect: {type: "lowpass", intensity: 6},
    sourceData: {
    angle: 120, // Sound emitted at a limited angle
    rotation: 270 // Configure the direction of sound emission
    }
    playbackOptions: {
    loopStart: 12, // Audio sprite timing
    loopEnd: 16,
    fade: 300, // Fade-in 300ms
    onended: () => console.log("Do something after the spell sound has played")
    }
    });
  • Emit playback to other connected clients to occur at a specified position.

    Parameters

    • Rest ...args: any[]

      Arguments passed to SoundsLayer#playAtPosition

    Returns Promise<void>

    A Promise which resolves once playback for the initiating client has completed

  • Handle mouse cursor movements which may cause ambient audio previews to occur

    Returns void

  • Handle PlaylistSound document drop data.

    Parameters

    • event: DragEvent

      The drag drop event

    • data: any

      The dropped transfer data.

    Returns Promise<false | PlaceableObject>

  • Get the maximum sort value of all placeables.

    Returns number

    The maximum sort value (-Infinity if there are no objects)

  • Internal

    Send the controlled objects of this layer to the back or bring them to the front.

    Parameters

    • front: boolean

      Bring to front instead of send to back?

    Returns boolean

    Returns true if the layer has sortable object, and false otherwise

  • Snaps the given point to grid. The layer defines the snapping behavior.

    Parameters

    • point: Point

      The point that is to be snapped

    Returns Point

    The snapped point

  • Obtain an iterable of objects which should be added to this PlaceablesLayer

    Returns Document[]

  • Clear the contents of the preview container, restoring visibility of original (non-preview) objects.

    Returns void

  • Get a PlaceableObject contained in this layer by its ID. Returns undefined if the object doesn't exist or if the canvas is not rendering a Scene.

    Parameters

    • objectId: string

      The ID of the contained object to retrieve

    Returns PlaceableObject

    The object instance, or undefined

  • Acquire control over all PlaceableObject instances which are visible and controllable within the layer.

    Parameters

    • options: any = {}

      Options passed to the control method of each object

    Returns PlaceableObject[]

    An array of objects that were controlled

  • Release all controlled PlaceableObject instance from this layer.

    Parameters

    • options: any = {}

      Options passed to the release method of each object

    Returns number

    The number of PlaceableObject instances which were released

  • Simultaneously rotate multiple PlaceableObjects using a provided angle or incremental. This executes a single database operation using Scene#updateEmbeddedDocuments.

    Parameters

    • options: {
          angle: number;
          delta: number;
          snap: number;
          ids: any[];
          includeLocked: boolean;
      } = {}

      Options which configure how multiple objects are rotated

      • angle: number

        A target angle of rotation (in degrees) where zero faces "south"

      • delta: number

        An incremental angle of rotation (in degrees)

      • snap: number

        Snap the resulting angle to a multiple of some increment (in degrees)

      • ids: any[]

        An Array of object IDs to target for rotation

      • includeLocked: boolean

        Rotate objects whose documents are locked?

    Returns Promise<PlaceableObject[]>

    An array of objects which were rotated

    Throws

    An error if an explicitly provided id is not valid

  • Simultaneously move multiple PlaceableObjects via keyboard movement offsets. This executes a single database operation using Scene#updateEmbeddedDocuments.

    Parameters

    • options: {
          dx: -1 | 0 | 1;
          dy: -1 | 0 | 1;
          rotate: boolean;
          ids: string[];
          includeLocked: boolean;
      } = {}

      Options which configure how multiple objects are moved

      • dx: -1 | 0 | 1

        Horizontal movement direction

      • dy: -1 | 0 | 1

        Vertical movement direction

      • rotate: boolean

        Rotate the placeable to direction instead of moving

      • ids: string[]

        An Array of object IDs to target for movement. The default is the IDs of controlled objects.

      • includeLocked: boolean

        Move objects whose documents are locked?

    Returns Promise<PlaceableObject[]>

    An array of objects which were moved during the operation

    Throws

    An error if an explicitly provided id is not valid

  • Internal

    An internal helper method to identify the array of PlaceableObjects which can be moved or rotated.

    Parameters

    • ids: string[]

      An explicit array of IDs requested.

    • includeLocked: boolean

      Include locked objects which would otherwise be ignored?

    Returns PlaceableObject[]

    An array of objects which can be moved or rotated

    Throws

    An error if any explicitly requested ID is not valid

  • Undo a change to the objects in this layer This method is typically activated using CTRL+Z while the layer is active

    Returns Promise<Document[]>

    An array of documents which were modified by the undo operation

  • A helper method to prompt for deletion of all PlaceableObject instances within the Scene Renders a confirmation dialogue to confirm with the requester that all objects will be deleted

    Returns Promise<Document[]>

    An array of Document objects which were deleted by the operation

  • Record a new CRUD event in the history log so that it can be undone later

    Parameters

    • type: string

      The event type (create, update, delete)

    • data: any[]

      The object data

    Returns void

  • Paste currently copied PlaceableObjects back to the layer by creating new copies

    Parameters

    • position: Point

      The destination position for the copied data.

    • Optional options: {
          hidden: boolean;
          snap: boolean;
      } = {}

      Options which modify the paste operation

      • hidden: boolean

        Paste data in a hidden state, if applicable. Default is false.

      • snap: boolean

        Snap the resulting objects to the grid. Default is true.

    Returns Promise<Document[]>

    An Array of created Document instances

  • Select all PlaceableObject instances which fall within a coordinate rectangle.

    Parameters

    • Optional options: {
          x: number;
          y: number;
          width: number;
          height: number;
          releaseOptions: any;
          controlOptions: any;
      } = {}
      • x: number

        The top-left x-coordinate of the selection rectangle.

      • y: number

        The top-left y-coordinate of the selection rectangle.

      • width: number

        The width of the selection rectangle.

      • height: number

        The height of the selection rectangle.

      • releaseOptions: any

        Optional arguments provided to any called release() method.

      • controlOptions: any

        Optional arguments provided to any called control() method.

    • Optional aoptions: {
          releaseOthers: boolean;
      } = {}

      Additional options to configure selection behaviour.

      • releaseOthers: boolean

        Whether to release other selected objects.

    Returns boolean

    A boolean for whether the controlled set was changed in the operation.

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

    Parameters

    • 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.update

    Returns Promise<Document[]>

    An array of updated data once the operation is complete

  • Internal

    Create a preview of this layer's object type from a world document and show its sheet to be finalized.

    Parameters

    • createData: any

      The data to create the object with.

    • Optional options: {
          renderSheet: boolean;
          top: number;
          left: number;
      } = {}

      Options which configure preview creation

      • renderSheet: boolean

        Render the preview object config sheet?

      • top: number

        The offset-top position where the sheet should be rendered

      • left: number

        The offset-left position where the sheet should be rendered

    Returns PlaceableObject

    The created preview object

  • Activate the InteractionLayer, deactivating other layers and marking this layer's children as interactive.

    Parameters

    • Optional options: {
          tool: string;
      } = {}

      Options which configure layer activation

      • tool: string

        A specific tool in the control palette to set as active

    Returns InteractionLayer

    The layer instance, now activated

  • Get the zIndex that should be used for ordering this layer vertically relative to others in the same Container.

    Returns number

  • Draw the canvas layer, rendering its internal components and returning a Promise. The Promise resolves to the drawn layer once its contents are successfully rendered.

    Parameters

    • Optional options: any = {}

      Options which configure how the layer is drawn

    Returns Promise<CanvasLayer>

  • Deconstruct data used in the current layer in preparation to re-draw the canvas

    Parameters

    • Optional options: any = {}

      Options which configure how the layer is deconstructed

    Returns Promise<CanvasLayer>

  • Protected

    Sync the playing state and volume of all AmbientSound objects based on the position of listener points

    Parameters

    • listeners: Point[]

      Locations of listeners which have the capability to hear

    • Optional options: any

      Additional options forwarded to AmbientSound synchronization

    Returns void

  • Protected

    Configure playback by assigning the muffled state and final playback volume for the sound. This method should mutate the config object by assigning the volume and muffled properties.

    Parameters

    Returns boolean

  • Protected

    Get the data of the copied object pasted at the position given by the offset. Called by PlaceablesLayer#pasteObjects for each copied object.

    Parameters

    • copy: PlaceableObject

      The copied object that is pasted

    • offset: Point

      The offset relative from the current position to the destination

    • Optional options: {
          hidden: boolean;
          snap: boolean;
      } = {}
      • hidden: boolean

        Paste in a hidden state, if applicable. Default is false.

      • snap: boolean

        Snap to the grid. Default is true.

    Returns any

    The update data

  • Protected

    Get the world-transformed drop position.

    Parameters

    • event: DragEvent
    • Optional options: {
          center: boolean;
      } = {}
      • center: boolean

        Return the coordinates of the center of the nearest grid element.

    Returns boolean | number[]

    Returns the transformed x, y coordinates, or false if the drag event was outside the canvas.

  • Protected

    Handle double left-click events which originate from the Canvas stage.

    Parameters

    • event: FederatedEvent

      The PIXI InteractionEvent which wraps a PointerEvent

    Returns void

    See

    Canvas.#onClickLeft2