An AmbientLight is an implementation of PlaceableObject which represents a dynamic light source within the Scene.

Hierarchy (View Summary)

Constructors

Properties

Accessors

Methods

Constructors

Properties

controlIcon: null | ControlIcon

A control icon for interacting with the object

document: CanvasDocument

A reference to the Scene embedded Document instance which this object represents

field: Graphics

The area that is affected by this light.

lightSource: any

A reference to the PointSource object which defines this light or darkness area of effect. This is undefined if the AmbientLight does not provide an active source of light.

mouseInteractionManager: MouseInteractionManager

A mouse interaction manager instance which handles mouse workflows related to this object.

renderFlags: RenderFlags

Status flags which are applied at render-time to update the PlaceableObject. If an object defines RenderFlags, it should at least include flags for "redraw" and "refresh".

Retain a reference to the Scene within which this Placeable Object resides

embeddedName: string = "AmbientLight"

Identify the official Document name for this PlaceableObject class

RENDER_FLAG_PRIORITY: string = "OBJECTS"

The ticker priority when RenderFlags of this class are handled. Valid values are OBJECTS or PERCEPTION.

RENDER_FLAGS: {
    redraw: { propagate: string[] };
    refresh: { alias: boolean; propagate: string[] };
    refreshElevation: {};
    refreshField: { propagate: string[] };
    refreshPosition: {};
    refreshState: {};
} = ...

Accessors

  • get _original(): undefined | PlaceableObject

    The object that this object is a preview of if this object is a preview.

    Returns undefined | PlaceableObject

  • get bounds(): Rectangle

    The bounding box for this PlaceableObject. This is required if the layer uses a Quadtree, otherwise it is optional

    Returns Rectangle

  • get brightRadius(): number

    Get the pixel radius of bright light emitted by this light source

    Returns number

  • get center(): Point

    The central coordinate pair of the placeable object based on it's own width and height

    Returns Point

  • get config(): LightData

    A convenience accessor to the LightData configuration object

    Returns LightData

  • get controlled(): boolean

    An indicator for whether the object is currently controlled

    Returns boolean

  • get dimRadius(): number

    Get the pixel radius of dim light emitted by this light source

    Returns number

  • get emitsDarkness(): boolean

    Does this Ambient Light actively emit darkness light given its properties and the current darkness level of the Scene?

    Returns boolean

  • get emitsLight(): boolean

    Does this Ambient Light actively emit positive light given its properties and the current darkness level of the Scene?

    Returns boolean

  • get global(): boolean

    Test whether a specific AmbientLight source provides global illumination

    Returns boolean

  • get hasActiveHUD(): boolean

    Is the HUD display active for this Placeable?

    Returns boolean

  • get hasPreview(): boolean

    Does there exist a temporary preview of this placeable object?

    Returns boolean

  • get hover(): boolean

    An indicator for whether the object is currently a hover target

    Returns boolean

  • get id(): string

    The id of the corresponding Document which this PlaceableObject represents.

    Returns string

  • get interactionState(): | undefined
    | {
        CLICKED: number;
        DRAG: number;
        DROP: number;
        GRABBED: number;
        HOVER: number;
        NONE: number;
    }

    The mouse interaction state of this placeable.

    Returns
        | undefined
        | {
            CLICKED: number;
            DRAG: number;
            DROP: number;
            GRABBED: number;
            HOVER: number;
            NONE: number;
        }

  • get isDarknessSource(): boolean

    Check if the point source is a DarknessSource instance

    Returns boolean

  • get isLightSource(): boolean

    Check if the point source is a LightSource instance

    Returns boolean

  • get isOwner(): boolean

    A convenient reference for whether the current User has full control over the document.

    Returns boolean

  • get isPreview(): boolean

    Is this placeable object a temporary preview?

    Returns boolean

  • get isVisible(): boolean

    Is this Ambient Light currently visible? By default, true only if the source actively emits light or darkness.

    Returns boolean

  • get layer(): PlaceablesLayer

    Provide a reference to the CanvasLayer which contains this PlaceableObject.

    Returns PlaceablesLayer

  • get objectId(): string

    A unique identifier which is used to uniquely identify elements on the canvas related to this object.

    Returns string

  • get radius(): number

    The maximum radius in pixels of the light field

    Returns number

  • get sheet(): DocumentSheetV2

    A document sheet used to configure the properties of this Placeable Object or the Document it represents.

    Returns DocumentSheetV2

  • get sourceId(): string

    Returns string

  • get implementation(): typeof PlaceableObject

    Return a reference to the configured subclass of this base PlaceableObject type.

    Returns typeof PlaceableObject

Methods

  • Does the User have permission to left-click drag this Placeable Object?

    Parameters

    • user: any

      The User performing the action. Always equal to game.user.

    • event: any

      The pointer event

    Returns boolean

  • Parameters

    • options: any

    Returns Promise<void>

  • Internal

    Obtain a shifted position for the Placeable Object.

    Parameters

    • dx: -1 | 0 | 1

      The number of grid units to shift along the X-axis

    • dy: -1 | 0 | 1

      The number of grid units to shift along the Y-axis

    • dz: -1 | 0 | 1

      The number of grid units to shift along the Z-axis

    Returns object

    The shifted target coordinates

  • Callback actions which occur on a single right-click event to configure properties of the object

    Parameters

    • event: any

      The triggering canvas interaction event

    Returns void

  • Register pending canvas operations which should occur after a new PlaceableObject of this type is created

    Parameters

    • data: any
    • options: any
    • userId: any

    Returns void

  • Define additional steps taken when an existing placeable object of this type is deleted

    Parameters

    • options: any
    • userId: any

    Returns void

  • Conclude a drag operation from the perspective of the preview clone. Modify the appearance of both the clone (this) and the original (_original) object.

    Returns void

  • Callback actions which occur on a mouse-move operation.

    Parameters

    • event: any

      The triggering canvas interaction event

    Returns void

  • Parameters

    • changed: any
    • options: any
    • userId: any

    Returns void

  • Internal

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

    Parameters

    • offset: Point

      The offset relative from the current position to the destination

    • Optionaloptions: { hidden?: boolean; snap?: boolean } = {}
      • Optionalhidden?: boolean

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

      • Optionalsnap?: boolean

        Snap to the grid. Default is true.

    Returns object

    The update data

  • Internal

    Determine a new angle of rotation for a PlaceableObject either from an explicit angle or from a delta offset.

    Parameters

    • options: { angle?: number; delta?: number; snap?: number } = {}

      An object which defines the rotation update parameters

      • Optionalangle?: number

        An explicit angle, either this or delta must be provided

      • Optionaldelta?: number

        A relative angle delta, either this or the angle must be provided

      • Optionalsnap?: number

        A precision (in degrees) to which the resulting angle should snap. Default is 0.

    Returns number

    The new rotation angle for the object

  • Test whether a user can perform a certain interaction regarding a Placeable Object

    Parameters

    • user: documents.User

      The User performing the action. Must be equal to game.user.

    • action:
          | "update"
          | "delete"
          | "view"
          | "create"
          | "control"
          | "configure"
          | "hover"
          | "drag"
          | "HUD"

      The named action being attempted

    Returns boolean

    Does the User have rights to perform the action?

  • Clone the placeable object, returning a new object with identical attributes. The returned object is non-interactive, and has no assigned ID. If you plan to use it permanently you should call the create method.

    Returns PlaceableObject

    A new object with identical data

  • Assume control over a PlaceableObject, flagging it as controlled and enabling downstream behaviors

    Parameters

    • Optionaloptions: { releaseOthers?: boolean } = {}

      Additional options which modify the control request

      • OptionalreleaseOthers?: boolean

        Release any other controlled objects first

    Returns boolean

    A flag denoting whether control was successful

  • Draw the placeable object into its parent container

    Parameters

    • Optionaloptions: object = {}

      Options which may modify the draw and refresh workflow

    Returns Promise<PlaceableObject>

    The drawn object

  • Get the snapped position for a given position or the current position.

    Parameters

    • Optionalposition: any

      The position to be used instead of the current position

    Returns Point

    The snapped position

  • Update the LightSource associated with this AmbientLight object. Darkness sources always generate edges. Light sources only do so if their priority is strictly greater than 0. If any aspect changes (deletion, switching between darkness/light, or priority change), the source may be destroyed and recreated as needed, and relevant perception flags are set.

    Parameters

    • Optionaloptions: { deleted?: boolean } = {}

      Options which modify how the source is updated.

      • Optionaldeleted?: boolean

        Indicate that this light source has been deleted.

    Returns void

  • Refresh all incremental render flags for the PlaceableObject. This method is no longer used by the core software but provided for backwards compatibility.

    Parameters

    • Optionaloptions: object = {}

      Options which may modify the refresh workflow

    Returns PlaceableObject

    The refreshed object

  • Refresh the display of the ControlIcon for this AmbientLight source.

    Returns void

  • Release control over a PlaceableObject, removing it from the controlled set

    Parameters

    • options: object = {}

      Options which modify the releasing workflow

    Returns boolean

    A Boolean flag confirming the object was released.

  • Rotate the PlaceableObject to a certain angle of facing

    Parameters

    • angle: number

      The desired angle of rotation

    • snap: number

      Snap the angle of rotation to a certain target degree increment

    Returns Promise<PlaceableObject>

    The rotated object

  • Protected

    Finalize the left-drag operation.

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

      The triggering mouse click event

    Returns void

  • Protected

    Finalize the right-drag operation.

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

      The triggering mouse click event

    Returns void

  • Protected

    Get the light source data.

    Returns LightSourceData

  • Protected

    Get the target opacity that should be used for a Placeable Object depending on its preview state.

    Returns number

  • Protected

    Initialize the left-drag operation.

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

      The triggering canvas interaction event

    Returns void

  • Protected

    Initialize the right-drag operation.

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

      The triggering canvas interaction event

    Returns void

  • Protected

    Is the source of this Ambient Light disabled?

    Returns boolean

  • Protected

    Callback actions which occur on a single left-click event to assume control of the object

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

      The triggering canvas interaction event

    Returns boolean | void

  • Protected

    Callback actions which occur on a double left-click event to activate

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

      The triggering canvas interaction event

    Returns void

  • Protected

    Callback actions which occur on a double right-click event to configure properties of the object

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

      The triggering canvas interaction event

    Returns void

  • Protected

    Additional events that trigger once control of the object is established

    Parameters

    • options: object

      Optional parameters which apply for specific implementations

    Returns void

  • Protected

    Callback actions which occur on a mouse-move operation.

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

      The triggering mouse click event

    Returns boolean | void

    If false, the cancellation is prevented

  • Protected

    Callback actions which occur on a mouse-move operation.

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

      The triggering canvas interaction event

    Returns undefined | false

  • Protected

    Callback actions which occur when a mouse-drag action is first begun.

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

      The triggering canvas interaction event

    Returns boolean | void

    If false, the start if prevented

  • Protected

    Callback actions which occur on a right mouse-drag operation.

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

      The triggering mouse click event

    Returns boolean | void

    If false, the cancellation is prevented

  • Protected

    Callback actions which occur on a right mouse-drag operation.

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

      The triggering canvas interaction event

    Returns void

  • Protected

    Callback actions which occur on a right mouse-drag operation.

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

      The triggering canvas interaction event

    Returns void

  • Protected

    Callback actions which occur on a right mouse-drag operation.

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

      The triggering mouse click event

    Returns false | void

    If false, the start if prevented

  • Protected

    Begin a drag operation from the perspective of the preview clone. Modify the appearance of both the clone (this) and the original (_original) object.

    Returns void

  • Protected

    Actions that should be taken for this Placeable Object when a mouseover event occurs. Hover events on PlaceableObject instances allow event propagation by default.

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

      The triggering canvas interaction event

    • options: { hoverOutOthers?: boolean } = {}

      Options which customize event handling

      • OptionalhoverOutOthers?: boolean

        Trigger hover-out behavior on sibling objects

    Returns boolean | void

  • Protected

    Actions that should be taken for this Placeable Object when a mouseout event occurs

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

      The triggering canvas interaction event

    Returns void

  • Protected

    Callback action which occurs on a long press.

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

      The triggering canvas interaction event

    • origin: Point

      The local canvas coordinates of the mousepress.

    Returns any

  • Protected

    Additional events which trigger once control of the object is released

    Parameters

    • options: object

      Options which modify the releasing workflow

    Returns void

  • Protected

    Callback actions which occur on a single left-unclick event to assume control of the object

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

      The triggering canvas interaction event

    Returns void

  • Protected

    Callback actions which occur on a single right-unclick event

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

      The triggering canvas interaction event

    Returns void

  • Protected

    Is this PlaceableObject within the selection rectangle?

    Parameters

    • rectangle: Rectangle

      The selection rectangle

    Returns boolean

  • Protected

    Perform the database updates that should occur as the result of a drag-left-drop operation.

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

      The triggering canvas interaction event

    Returns null | object[] | [updates: object[], options?: object]

    An array of database updates to perform for documents in this collection

  • Protected

    Should the placeable propagate left click downstream?

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

    Returns boolean

  • Protected

    Should the placeable propagate right click downstream?

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

    Returns boolean

  • Protected

    Refresh the elevation of the control icon.

    Returns void

  • Protected

    Refresh the shape of the light field-of-effect. This is refreshed when the AmbientLight fov polygon changes.

    Returns void

  • Protected

    Refresh the position of the AmbientLight. Called with the coordinates change.

    Returns void

  • Protected

    Refresh the state of the light. Called when the disabled state or darkness conditions change.

    Returns void

  • Protected

    Callback actions which occur on a right mouse-drag operation.

    Parameters

    • event: FederatedEvent<UIEvent | PixiTouch>

      The triggering mouse click event

    Returns false | void

    If false, the start if prevented

  • Internal

    Obtain the shifted position.

    Parameters

    • dx: -1 | 0 | 1

      The number of grid units to shift along the X-axis

    • dy: -1 | 0 | 1

      The number of grid units to shift along the Y-axis

    • dz: -1 | 0 | 1

      The number of grid units to shift along the Z-axis

    • position: ElevatedPoint

      The unsnapped position

    • snapped: ElevatedPoint

      The snapped position

    • grid: BaseGrid<GridCoordinates2D, GridCoordinates3D>

      The grid

    Returns ElevatedPoint

    The shifted target coordinates