Options
All
  • Public
  • Public/Protected
  • All
Menu

The virtual tabletop environment is implemented using a WebGL powered HTML 5 canvas using the powerful PIXI.js library. The canvas is comprised by an ordered sequence of layers which define rendering groups and collections of objects that are drawn on the canvas itself.

example

Canvas State

canvas.ready; // Is the canvas ready for use?
canvas.scene; // The currently viewed Scene document.
canvas.dimensions; // The dimensions of the current Scene.
example

Canvas Methods

canvas.draw(); // Completely re-draw the game canvas (this is usually unnecessary).
canvas.pan(x, y, zoom); // Pan the canvas to new coordinates and scale.
canvas.recenter(); // Re-center the canvas on the currently controlled Token.

Hierarchy

  • Canvas

Index

Constructors

Properties

pendingOperations: any[]

An Array of pending canvas operations which should trigger on the next re-paint

perception: PerceptionManager

A perception manager interface for batching lighting, sight, and sound updates

loading: boolean

A flag to indicate whether a new Scene is currently being drawn.

initializing: Promise<void>

A promise that resolves when the canvas is first initialized and ready.

_pendingOperationNames: Set<string>

A Set of unique pending operation names to ensure operations are only performed once

blurFilters: Set<filters> = ...

An set of blur filter instances which are modified by the zoom level and the "soft shadows" setting

currentMouseManager: MouseInteractionManager = null

A reference to the MouseInteractionManager that is currently controlling pointer-based interaction, or null.

dimensions: SceneDimensions

The current pixel dimensions of the displayed Scene, or null if the Canvas is blank.

fps: { average: number; values: number[]; element: HTMLElement; render: number } = ...

Record framerate performance data.

Type declaration

  • average: number
  • values: number[]
  • element: HTMLElement
  • render: number
mouseInteractionManager: MouseInteractionManager

The singleton interaction manager instance which handles mouse interaction on the Canvas.

Configured performance settings which affect the behavior of the Canvas and its renderer.

screenDimensions: number[] = ...

The renderer screen dimensions.

app: Application

The singleton PIXI.Application instance rendered on the Canvas.

stage: Container

The primary stage container of the PIXI.Application.

The primary Canvas group which generally contains tangible physical objects which exist within the Scene. This group is a CachedContainer which is rendered to the Scene as a SpriteMesh. This allows the rendered result of the Primary Canvas Group to be affected by a BaseSamplerShader.

The effects Canvas group which modifies the result of the PrimaryCanvasGroup by adding special effects. This includes lighting, weather, vision, and other visual effects which modify the appearance of the Scene.

The interface Canvas group which is rendered above other groups and contains all interactive elements. The various InteractionLayer instances of the interface group provide different control sets for interacting with different types of Documents which can be represented on the Canvas.

The singleton HeadsUpDisplay container which overlays HTML rendering on top of this Canvas.

blur: { enabled: boolean; strength: number; passes: any; kernels: any }

Type declaration

  • enabled: boolean
  • strength: number
  • passes: any
  • kernels: any
_fog: FogManager = ...

The singleton Fog of War manager instance.

#colorManager: CanvasColorManager = ...

The singleton color manager instance.

#dragDrop: DragDrop

The DragDrop instance which handles interactivity resulting from DragTransfer events.

#reload: { scene: string; layer: string; controlledTokens: string[]; targetedTokens: string[] } = {}

An object of data which caches data which should be persisted across re-draws of the game canvas.

Type declaration

  • scene: string
  • layer: string
  • controlledTokens: string[]
  • targetedTokens: string[]
#mouseMoveTime: number = 0

Track the timestamp when the last mouse move event was captured

#mouseMoveDebounceMS: number = 100

The debounce timer in milliseconds for tracking mouse movements on the Canvas.

#debounceMouseMove: ((arg0: InteractionEvent) => any) = ...

Type declaration

    • (arg0: InteractionEvent): any
    • A debounced function which tracks movements of the mouse on the game canvas.

      Parameters

      • arg0: InteractionEvent

      Returns any

Accessors

  • get initialized(): boolean
  • A flag for whether the game Canvas is fully initialized and ready for additional content to be drawn.

    Returns boolean

  • A reference to the currently displayed Scene document, or null if the Canvas is currently blank.

    Returns Scene

  • get ready(): boolean
  • A flag for whether the game Canvas is ready to be used. False if the canvas is not yet drawn, true otherwise.

    Returns boolean

  • The fog of war bound to this canvas

    Returns FogManager

  • The colors bound to this scene and handled by the color manager.

    Returns typeof utils.Color

  • get masks(): Container
  • Shortcut to get the masks container from HiddenCanvasGroup.

    Returns Container

  • get id(): string
  • The id of the currently displayed Scene.

    Returns string

  • An Array of all CanvasLayer instances which are active on the Canvas board

    Returns CanvasLayer[]

  • Return a reference to the active Canvas Layer

    Returns CanvasLayer

  • get darknessLevel(): number
  • The currently displayed darkness level, which may override the saved Scene value.

    Returns number

  • get layers(): any
  • A mapping of named CanvasLayer classes which defines the layers which comprise the Scene.

    Returns any

Methods

  • initialize(): void
  • Initialize the Canvas by creating the HTML element and PIXI application. This step should only ever be performed once per client session. Subsequent requests to reset the canvas should go through Canvas#draw

    Returns void

  • Configure performance settings for hte canvas application based on the selected performance mode.

    internal

    Returns CanvasPerformanceSettings

  • Draw the game canvas.

    Parameters

    Returns Promise<Canvas>

    A Promise which resolves once the Canvas is fully drawn

  • tearDown(): Promise<void>
  • When re-drawing the canvas, first tear down or discontinue some existing processes

    Returns Promise<void>

  • getGLParameter(parameter: string): any
  • Get the value of a GL parameter

    Parameters

    • parameter: string

      The GL parameter to retrieve

    Returns any

    The GL parameter value

  • initializeCanvasPosition(): void
  • Initialize the starting view of the canvas stage If we are re-drawing a scene which was previously rendered, restore the prior view position Otherwise set the view to the top-left corner of the scene at standard scale

    Returns void

  • Given an embedded object name, get the canvas layer for that object

    Parameters

    • embeddedName: string

    Returns PlaceablesLayer

  • activateFPSMeter(): void
  • Activate framerate tracking by adding an HTML element to the display and refreshing it every frame.

    Returns void

  • deactivateFPSMeter(): void
  • Deactivate framerate tracking by canceling ticker updates and removing the HTML element.

    Returns void

  • Pan the canvas to a certain {x,y} coordinate and a certain zoom level

    Parameters

    Returns void

  • Animate panning the canvas to a certain destination coordinate and zoom scale Customize the animation speed with additional options Returns a Promise which is resolved once the animation has completed

    Parameters

    Returns Promise<any>

    A Promise which resolves once the animation has been completed

  • Recenter the canvas with a pan animation that ends in the center of the canvas rectangle.

    Parameters

    Returns Promise<void>

    A Promise which resolves once the animation has been completed

  • highlightObjects(active: boolean): void
  • Highlight objects on any layers which are visible

    Parameters

    • active: boolean

    Returns void

  • ping(origin: Point, options: PingOptions): Promise<boolean>
  • Displays a Ping both locally and on other connected client, following these rules:

    1. Displays on the current canvas Scene
    2. If ALT is held, becomes an ALERT ping
    3. Else if the user is GM and SHIFT is held, becomes a PULL ping
    4. Else is a PULSE ping

    Parameters

    • origin: Point

      Point to display Ping at

    • options: PingOptions

    Returns Promise<boolean>

  • createBlurFilter(blurStrength?: number): BlurFilter
  • Create a BlurFilter instance and register it to the array for updates when the zoom level changes.

    Parameters

    • blurStrength: number = CONFIG.Canvas.blurStrength

      The desired blur strength to use for this filter

    Returns BlurFilter

  • addBlurFilter(filter: BlurFilter): BlurFilter
  • Add a filter to the blur filter list. The filter must have the blur property

    Parameters

    • filter: BlurFilter

      The Filter instance to add

    Returns BlurFilter

    The added filter for method chaining

  • clientCoordinatesFromCanvas(origin: Point): Point
  • Convert canvas co-ordinates to the client's viewport.

    Parameters

    • origin: Point

      The canvas coordinates.

    Returns Point

    The corresponding co-ordinates relative to the client's viewport.

  • canvasCoordinatesFromClient(origin: Point): Point
  • Convert client viewport co-ordinates to canvas co-ordinates.

    Parameters

    • origin: Point

      The client coordinates.

    Returns Point

    The corresponding canvas co-ordinates.

  • isOffscreen(position: Point): boolean
  • Determine whether given canvas co-ordinates are off-screen.

    Parameters

    • position: Point

      The canvas co-ordinates.

    Returns boolean

    Is the coordinate outside the screen bounds?

  • _onClickLeft2(event: InteractionEvent): void
  • Handle double left-click events occurring on the Canvas.

    see

    {MouseInteractionManager#_handleClickLeft2}

    Parameters

    • event: InteractionEvent

    Returns void

  • _onDragLeftStart(event: InteractionEvent): any
  • Handle the beginning of a left-mouse drag workflow on the Canvas stage or its active Layer.

    see

    {MouseInteractionManager#_handleDragStart}

    internal

    Parameters

    • event: InteractionEvent

    Returns any

  • _onDragLeftMove(event: InteractionEvent): any
  • Handle mouse movement events occurring on the Canvas.

    see

    {MouseInteractionManager#_handleDragMove}

    internal

    Parameters

    • event: InteractionEvent

    Returns any

  • _onDragLeftDrop(event: InteractionEvent): any
  • Handle the conclusion of a left-mouse drag workflow when the mouse button is released.

    see

    {MouseInteractionManager#_handleDragDrop}

    internal

    Parameters

    • event: InteractionEvent

    Returns any

  • _onDragLeftCancel(event: PointerEvent): any
  • Handle the cancellation of a left-mouse drag workflow

    see

    {MouseInteractionManager#_handleDragCancel}

    internal

    Parameters

    • event: PointerEvent

    Returns any

  • _onDragCanvasPan(event: MouseEvent): Promise<any>
  • Pan the canvas view when the cursor position gets close to the edge of the frame

    Parameters

    • event: MouseEvent

      The originating mouse movement event

    Returns Promise<any>

  • addPendingOperation(name: string, fn: Function, scope: any, args: any): void
  • Add a pending canvas operation that should fire once the socket handling workflow concludes. This registers operations by a unique string name into a queue - avoiding repeating the same work multiple times. This is especially helpful for multi-object updates to avoid costly and redundant refresh operations. TODO: this should be deprecated

    Parameters

    • name: string

      A unique name for the pending operation, conventionally Class.method

    • fn: Function

      The unbound function to execute later

    • scope: any

      The scope to which the method should be bound when called

    • args: any

      Arbitrary arguments to pass to the method when called

    Returns void

  • triggerPendingOperations(): void
  • Fire all pending functions that are registered in the pending operations queue and empty it. TODO: this should be deprecated

    Returns void

  • #initializePlugins(): void
  • Initialize custom pixi plugins.

    Returns void

  • #createApplication(canvas: HTMLCanvasElement, config: any): void
  • Create the PIXI.Application and update references to the created app and stage.

    Parameters

    • canvas: HTMLCanvasElement

      The target canvas view element

    • config: any

      Desired PIXI.Application configuration options

    Returns void

  • #mapPremultipliedBlendModes(): void
  • Remap premultiplied blend modes/non premultiplied blend modes to fix PIXI bug with custom BM.

    Returns void

  • #displayPerformanceWarnings(): void
  • Display warnings for known performance issues which may occur due to the user's hardware or browser configuration.

    Returns void

  • #createGroups(parentName: string, parent: DisplayObject): void
  • Initialize the group containers of the game Canvas.

    Parameters

    • parentName: string
    • parent: DisplayObject

    Returns void

  • _initializeBlur(): void
  • TODO: Add a quality parameter Compute the blur parameters according to grid size and performance mode.

    Returns void

  • A special workflow to perform when rendering a blank Canvas with no active Scene.

    Returns Canvas

  • #initialize(): Promise<void>
  • Once the canvas is drawn, initialize control, visibility, and audio states

    Returns Promise<void>

  • #initializeCanvasLayer(): void
  • Initialize a CanvasLayer in the activation state

    Returns void

  • #initializeTokenControl(): void
  • Initialize a token or set of tokens which should be controlled. Restore controlled and targeted tokens from before the re-draw.

    Returns void

  • #measureFPS(): void
  • Measure average framerate per second over the past 30 frames

    Returns void

  • Get the constrained zoom scale parameter which is allowed by the maxZoom parameter

    Parameters

    Returns CanvasViewPosition

    The constrained position

  • updateBlur(strength: number): void
  • Update the blur strength depending on the scale of the canvas stage. This number is zero if "soft shadows" are disabled

    Parameters

    • strength: number

    Returns void

  • #addListeners(): void
  • Attach event listeners to the game canvas to handle click and interaction events

    Returns void

  • _onMouseMove(event: InteractionEvent): void
  • Handle mouse movement on the game canvas. This handler fires on both a throttle and a debounce, ensuring that the final update is always recorded.

    Parameters

    • event: InteractionEvent

    Returns void

  • _onClickLeft(event: InteractionEvent): void
  • Handle left mouse-click events occurring on the Canvas.

    see

    {MouseInteractionManager#_handleClickLeft}

    Parameters

    • event: InteractionEvent

    Returns void

  • _onLongPress(event: InteractionEvent, origin: Point): void
  • Handle long press events occurring on the Canvas.

    see

    {MouseInteractionManager#_handleLongPress}

    Parameters

    • event: InteractionEvent

      The triggering canvas interaction event.

    • origin: Point

      The local canvas coordinates of the mousepress.

    Returns void

  • _onClickRight(event: InteractionEvent): any
  • Handle right mouse-click events occurring on the Canvas.

    see

    {MouseInteractionManager#_handleClickRight}

    Parameters

    • event: InteractionEvent

    Returns any

  • _onClickRight2(event: InteractionEvent): void
  • Handle double right-click events occurring on the Canvas.

    see

    {MouseInteractionManager#_handleClickRight}

    Parameters

    • event: InteractionEvent

    Returns void

  • _onDragRightMove(event: InteractionEvent): void
  • Handle right-mouse drag events occurring on the Canvas.

    see

    {MouseInteractionManager#_handleDragMove}

    Parameters

    • event: InteractionEvent

    Returns void

  • _onDragRightDrop(event: InteractionEvent): void
  • Handle the conclusion of a right-mouse drag workflow the Canvas stage.

    see

    {MouseInteractionManager#_handleDragDrop}

    Parameters

    • event: InteractionEvent

    Returns void

  • _onDragSelect(event: InteractionEvent): void
  • Determine selection coordinate rectangle during a mouse-drag workflow

    Parameters

    • event: InteractionEvent

    Returns void

  • _onResize(event?: Event): boolean
  • Handle window resizing with the dimensions of the window viewport change

    Parameters

    • event: Event = null

      The Window resize event

    Returns boolean

  • _onMouseWheel(event: WheelEvent): void
  • Handle mousewheel events which adjust the scale of the canvas

    Parameters

    • event: WheelEvent

      The mousewheel event that zooms the canvas

    Returns void

  • _onDrop(event: DragEvent): any
  • Event handler for the drop portion of a drag-and-drop event.

    Parameters

    • event: DragEvent

      The drag event being dropped onto the canvas

    Returns any

  • clearContainer(displayObject: DisplayObject, destroy?: boolean): void
  • Remove all children of the display object and call one cleaning method: clean first, then tearDown, and destroy if no cleaning method is found.

    Parameters

    • displayObject: DisplayObject

      The display object to clean.

    • destroy: boolean = true

      If textures should be destroyed.

    Returns void

  • #configureWebGL(): void
  • Configure the usage of WebGL for the PIXI.Application that will be created.

    throws

    an Error if WebGL is not supported by this browser environment.

    Returns void

  • #createHTMLCanvas(): HTMLCanvasElement
  • Create the Canvas element which will be the render target for the PIXI.Application instance. Replace the template element which serves as a placeholder in the initially served HTML response.

    Returns HTMLCanvasElement

  • #configureCanvasSettings(): any
  • Configure the settings used to initialize the PIXI.Application instance.

    Returns any

    Options passed to the PIXI.Application constructor.