Util

Index

Namespaces

• DrawUtil

Enumerations

• LogLevel

Classes

• ConsoleAppender
• EasingFunctions
• Logger
• Observable
• ScreenAppender
• Serializer

Interfaces

• Appender
• EasingFunction
• Message
• Observer
• ScreenAppenderOptions

Type Aliases

• MaybeObserver

Functions

• addItemToArray
• contains
• delay
• fail
• getMinIndex
• getPosition
• isLegacyEasing
• isObject
• mergeDeep
• omit
• removeItemFromArray

Namespaces

DrawUtil

DrawUtil:

BorderRadius

BorderRadius:

Represents border radius values

bl

bl: number

Bottom-left

br

br: number

Bottom-right

tl

tl: number

Top-left

tr

tr: number

Top-right

LineCapStyle

LineCapStyle: butt | round | square

A canvas linecap style. "butt" is the default flush style, "round" is a semi-circle cap with a radius half the width of the line, and "square" is a rectangle that is an equal width and half height cap.

circle

• circle(ctx: CanvasRenderingContext2D, x: number, y: number, radius: number, stroke?: Color, fill?: Color): void

• Parameters

  • ctx: CanvasRenderingContext2D

  • x: number

  • y: number

  • radius: number

  • stroke: Color = Color.White

  • fill: Color = null

  Returns void

line

• line(ctx: CanvasRenderingContext2D, color?: Color, x1: number, y1: number, x2: number, y2: number, thickness?: number, cap?: LineCapStyle): void

• Draw a line on canvas context

  ---

  Parameters

  • ctx: CanvasRenderingContext2D

    The canvas context

  • color: Color = Color.Red

    The color of the line

  • x1: number

    The start x coordinate

  • y1: number

    The start y coordinate

  • x2: number

    The ending x coordinate

  • y2: number

    The ending y coordinate

  • thickness: number = 1

    The line thickness

  • cap: LineCapStyle = 'butt'

    The LineCapStyle (butt, round, or square)

  Returns void

point

• point(ctx: CanvasRenderingContext2D, color?: Color, point: Vector): void

• Draw the vector as a point onto the canvas.

  ---

  Parameters

  • ctx: CanvasRenderingContext2D

  • color: Color = Color.Red

  • point: Vector

  Returns void

roundRect

• roundRect(ctx: CanvasRenderingContext2D, x: number, y: number, width: number, height: number, radius?: number | BorderRadius, stroke?: Color, fill?: Color): void

• Draw a round rectangle on a canvas context

  ---

  Parameters

  • ctx: CanvasRenderingContext2D

    The canvas context

  • x: number

    The top-left x coordinate

  • y: number

    The top-left y coordinate

  • width: number

    The width of the rectangle

  • height: number

    The height of the rectangle

  • radius: number | BorderRadius = 5

    The border radius of the rectangle

  • stroke: Color = Color.White

    The Color to stroke rectangle with

  • fill: Color = null

    The Color to fill rectangle with

  Returns void

vector

• vector(ctx: CanvasRenderingContext2D, color: Color, origin: Vector, vector: Vector, scale?: number): void

• Parameters

  • ctx: CanvasRenderingContext2D

  • color: Color

  • origin: Vector

  • vector: Vector

  • scale: number = 1.0

  Returns void

Enumerations

LogLevel

LogLevel:

Logging level that Excalibur will tag

Debug

Debug: 0

Error

Error: 3

Fatal

Fatal: 4

Info

Info: 1

Warn

Warn: 2

Classes

ConsoleAppender

ConsoleAppender:

Console appender for browsers (i.e. console.log)

constructor

• new ConsoleAppender(): ConsoleAppender

• Returns ConsoleAppender

publiclog

• log(level: LogLevel, args: any[]): void

• Implementation of Appender.log

  Logs a message at the given LogLevel

  ---

  Parameters

  • level: LogLevel

    Level to log at

  • args: any[]

    Arguments to log

  Returns void

EasingFunctions

EasingFunctions:

Standard easing functions for motion in Excalibur, defined on a domain of [0, duration] and a range from [+startValue,+endValue] Given a time, the function will return a value from positive startValue to positive endValue.

function Linear (t) {
   return t * t;
}

// accelerating from zero velocity
function EaseInQuad (t) {
   return t * t;
}

// decelerating to zero velocity
function EaseOutQuad (t) {
   return t * (2 - t);
}

// acceleration until halfway, then deceleration
function EaseInOutQuad (t) {
   return t < .5 ? 2 * t * t : -1 + (4 - 2 * t) * t;
}

// accelerating from zero velocity
function EaseInCubic (t) {
   return t * t * t;
}

// decelerating to zero velocity
function EaseOutCubic (t) {
   return (--t) * t * t + 1;
}

// acceleration until halfway, then deceleration
function EaseInOutCubic (t) {
   return t < .5 ? 4 * t * t * t : (t - 1) * (2 * t - 2) * (2 * t - 2) + 1;
}

@deprecated

constructor

• new EasingFunctions(): EasingFunctions

• Returns EasingFunctions

publicstaticEaseInCubic

EaseInCubic: EasingFunction<number> = ...

@deprecated

ex.easeInCubic

publicstaticEaseInOutCubic

EaseInOutCubic: EasingFunction<number> = ...

@deprecated

use ex.easeInOutCubic

publicstaticEaseInOutQuad

EaseInOutQuad: EasingFunction<number> = ...

@deprecated

ex.easeInOutQuad

publicstaticEaseInQuad

EaseInQuad: EasingFunction<number> = ...

@deprecated

use ex.easeInQuad

publicstaticEaseOutCubic

EaseOutCubic: EasingFunction<number> = ...

@deprecated

ex.easeOutCubic

publicstaticEaseOutQuad

EaseOutQuad: EasingFunction<number> = ...

@deprecated

ex.easeOutQuad

publicstaticLinear

Linear: EasingFunction<number> = ...

@deprecated

use ex.linear

publicstaticCreateReversibleEasingFunction

• CreateReversibleEasingFunction(easing: EasingFunction<number>): EasingFunction<number>

• @deprecated

  ---

  Parameters

  • easing: EasingFunction<number>

  Returns EasingFunction<number>

publicstaticCreateVectorEasingFunction

• CreateVectorEasingFunction(easing: EasingFunction<number>): EasingFunction<Vector>

• @deprecated

  ---

  Parameters

  • easing: EasingFunction<number>

  Returns EasingFunction<Vector>

Logger

Logger:

Static singleton that represents the logging facility for Excalibur. Excalibur comes built-in with a ConsoleAppender and ScreenAppender. Derive from Appender to create your own logging appenders.

constructor

• new Logger(): Logger

• Returns Logger

publicdefaultLevel

defaultLevel: LogLevel = LogLevel.Info

Gets or sets the default logging level. Excalibur will only log messages if equal to or above this level. Default: LogLevel.Info

publicaddAppender

• addAppender(appender: Appender): void

• Adds a new Appender to the list of appenders to write to

  ---

  Parameters

  • appender: Appender

  Returns void

publicclearAppenders

• clearAppenders(): void

• Clears all appenders from the logger

  ---

  Returns void

publicdebug

• debug(...args: any[]): void

• Writes a log message at the LogLevel.Debug level

  ---

  Parameters

  • rest...args: any[]

    Accepts any number of arguments

  Returns void

publicdebugOnce

• debugOnce(...args: any[]): void

• Writes a log message once at the LogLevel.Fatal level, if it sees the same args again it wont log

  ---

  Parameters

  • rest...args: any[]

    Accepts any number of arguments

  Returns void

publicerror

• error(...args: any[]): void

• Writes a log message at the LogLevel.Error level

  ---

  Parameters

  • rest...args: any[]

    Accepts any number of arguments

  Returns void

publicerrorOnce

• errorOnce(...args: any[]): void

• Writes a log message once at the LogLevel.Error level, if it sees the same args again it won't log

  ---

  Parameters

  • rest...args: any[]

    Accepts any number of arguments

  Returns void

publicfatal

• fatal(...args: any[]): void

• Writes a log message at the LogLevel.Fatal level

  ---

  Parameters

  • rest...args: any[]

    Accepts any number of arguments

  Returns void

publicfatalOnce

• fatalOnce(...args: any[]): void

• Writes a log message once at the LogLevel.Fatal level, if it sees the same args again it won't log

  ---

  Parameters

  • rest...args: any[]

    Accepts any number of arguments

  Returns void

publicinfo

• info(...args: any[]): void

• Writes a log message at the LogLevel.Info level

  ---

  Parameters

  • rest...args: any[]

    Accepts any number of arguments

  Returns void

publicinfoOnce

• infoOnce(...args: any[]): void

• Writes a log message once at the LogLevel.Info level, if it sees the same args again it wont log

  ---

  Parameters

  • rest...args: any[]

    Accepts any number of arguments

  Returns void

publicwarn

• warn(...args: any[]): void

• Writes a log message at the LogLevel.Warn level

  ---

  Parameters

  • rest...args: any[]

    Accepts any number of arguments

  Returns void

publicwarnOnce

• warnOnce(...args: any[]): void

• Writes a log message once at the LogLevel.Warn level, if it sees the same args again it won't log

  ---

  Parameters

  • rest...args: any[]

    Accepts any number of arguments

  Returns void

publicstaticgetInstance

• getInstance(): Logger

• Gets the current static instance of Logger

  ---

  Returns Logger

Observable

Observable<T>:

Simple Observable implementation

---

Type parameters

• T

  is the typescript Type that defines the data being observed

constructor

• new Observable<T>(): Observable<T>

• Type parameters

  • T

  Returns Observable<T>

publicobservers

observers: Observer<T>[] = []

publicsubscriptions

subscriptions: (val: T) => any[] = []

clear

• clear(): void

• Removes all observers and callbacks

  ---

  Returns void

notifyAll

• notifyAll(message: T): void

• Broadcasts a message to all observers and callbacks

  ---

  Parameters

  • message: T

  Returns void

register

• register(observer: Observer<T>): void

• Register an observer to listen to this observable

  ---

  Parameters

  • observer: Observer<T>

  Returns void

subscribe

• subscribe(func: (val: T) => any): void

• Register a callback to listen to this observable

  ---

  Parameters

  • func: (val: T) => any

  Returns void

unregister

• unregister(observer: Observer<T>): void

• Remove an observer from the observable

  ---

  Parameters

  • observer: Observer<T>

  Returns void

unsubscribe

• unsubscribe(func: (val: T) => any): void

• Remove a callback that is listening to this observable

  ---

  Parameters

  • func: (val: T) => any

  Returns void

ScreenAppender

ScreenAppender:

On-screen (canvas) appender

constructor

• new ScreenAppender(options: ScreenAppenderOptions): ScreenAppender

• Parameters

  • options: ScreenAppenderOptions

  Returns ScreenAppender

publiccanvas

canvas: HTMLCanvasElement

publiclog

• log(level: LogLevel, args: any[]): void

• Implementation of Appender.log

  Logs a message at the given LogLevel

  ---

  Parameters

  • level: LogLevel

    Level to log at

  • args: any[]

    Arguments to log

  Returns void

Serializer

Serializer:

Central serialization system for ExcaliburJS Handles all serialization/deserialization with extensible registry

constructor

• new Serializer(): Serializer

• Returns Serializer

staticactorFromJSON

• actorFromJSON(json: string): Actor

• Parameters

  • json: string

  Returns Actor

staticactorToJSON

• actorToJSON(actor: Actor, pretty?: boolean): string

• Parameters

  • actor: Actor

  • pretty: boolean = false

  Returns string

staticclearComponents

• clearComponents(): void

• Clear all registered components

  ---

  Returns void

staticclearCustomActors

• clearCustomActors(): void

• Returns void

staticclearGraphics

• clearGraphics(): void

• Clear all registered graphics

  ---

  Returns void

staticdeserializeActor

• deserializeActor(data: EntityData): Actor

• Parameters

  • data: EntityData

  Returns Actor

staticdeserializeComponent

• deserializeComponent(data: ComponentData): Component

• Deserialize a component

  ---

  Parameters

  • data: ComponentData

  Returns Component

staticdeserializeEntity

• deserializeEntity(data: EntityData): Entity<any>

• Parameters

  • data: EntityData

  Returns Entity<any>

staticentityFromJSON

• entityFromJSON(json: string): Entity<any>

• Deserialize entity from JSON string

  ---

  Parameters

  • json: string

  Returns Entity<any>

staticentityToJSON

• entityToJSON(entity: Entity<any>, pretty?: boolean): string

• Serialize entity to JSON string

  ---

  Parameters

  • entity: Entity<any>

  • pretty: boolean = false

  Returns string

staticgetCustomActor

• getCustomActor(typeName: string): typeof Actor

• Parameters

  • typeName: string

  Returns typeof Actor

staticgetCustomSerializer

• getCustomSerializer(typeName: string): { deserialize: (data: any) => any; serialize: (obj: any) => any }

• Parameters

  • typeName: string

  Returns { deserialize: (data: any) => any; serialize: (obj: any) => any }

  • deserialize: (data: any) => any

    • • (data: any): any

      • Parameters

        • data: any

        Returns any

  • serialize: (obj: any) => any

    • • (obj: any): any

      • Parameters

        • obj: any

        Returns any

staticgetGraphic

• getGraphic(id: string): any

• Parameters

  • id: string

  Returns any

staticgetRegisteredComponents

• getRegisteredComponents(): string[]

• Get all registered component types

  ---

  Returns string[]

staticgetRegisteredCustomActors

• getRegisteredCustomActors(): string[]

• Returns string[]

staticgetRegisteredGraphics

• getRegisteredGraphics(): string[]

• Get all registered graphic IDs

  ---

  Returns string[]

staticgetRegistry

• getRegistry(registry: graphics | actors | components): Map<string, any>

• Parameters

  • registry: graphics | actors | components

  Returns Map<string, any>

staticinit

• init(autoRegisterComponents?: boolean): void

• Parameters

  • autoRegisterComponents: boolean = true

  Returns void

staticisComponentRegistered

• isComponentRegistered(typeName: string): boolean

• Check if a component type is registered

  ---

  Parameters

  • typeName: string

  Returns boolean

staticisCustomActorRegistered

• isCustomActorRegistered(typeName: string): boolean

• Parameters

  • typeName: string

  Returns boolean

staticisGraphicRegistered

• isGraphicRegistered(id: string): boolean

• Check if a graphic is registered

  ---

  Parameters

  • id: string

  Returns boolean

staticisInitialized

• isInitialized(): boolean

• Returns boolean

staticregisterComponent

• registerComponent<T>(ctor: ComponentCtor<T>): void

• Type parameters

  • T: Component

  Parameters

  • ctor: ComponentCtor<T>

  Returns void

staticregisterComponents

• registerComponents(ctors: ComponentCtor[]): void

• Parameters

  • ctors: ComponentCtor[]

  Returns void

staticregisterCustomActor

• registerCustomActor(ctor: typeof Actor): void

• Parameters

  • ctor: typeof Actor

  Returns void

staticregisterCustomActors

• registerCustomActors(ctors: typeof Actor[]): void

• Parameters

  • ctors: typeof Actor[]

  Returns void

staticregisterCustomSerializer

• registerCustomSerializer(typeName: string, serialize: (obj: any) => any, deserialize: (data: any) => any): void

• Register a custom serializer for a specific type Useful for types like Vector, Color, BoundingBox, etc.

  ---

  Parameters

  • typeName: string

  • serialize: (obj: any) => any

  • deserialize: (data: any) => any

  Returns void

staticregisterGraphic

• registerGraphic(id: string, graphic: any): void

• Parameters

  • id: string

  • graphic: any

  Returns void

staticregisterGraphics

• registerGraphics(graphics: Record<string, any>): void

• Parameters

  • graphics: Record<string, any>

  Returns void

staticreset

• reset(): void

• Reset all registrations (useful for testing)

  ---

  Returns void

staticserializeActor

• serializeActor(actor: Actor): EntityData

• Parameters

  • actor: Actor

  Returns EntityData

staticserializeComponent

• serializeComponent(component: Component): ComponentData

• Serialize a component

  ---

  Parameters

  • component: Component

  Returns ComponentData

staticserializeEntity

• serializeEntity(entity: Entity<any>): EntityData

• Parameters

  • entity: Entity<any>

  Returns EntityData

staticunregisterComponent

• unregisterComponent(typeName: string): boolean

• Unregister a component type

  ---

  Parameters

  • typeName: string

  Returns boolean

staticunregisterCustomActor

• unregisterCustomActor(typeName: string): boolean

• Parameters

  • typeName: string

  Returns boolean

staticunregisterGraphic

• unregisterGraphic(id: string): boolean

• Unregister a graphic

  ---

  Parameters

  • id: string

  Returns boolean

staticvalidateEntityData

• validateEntityData(data: any): data is EntityData

• Validate entity data structure

  ---

  Parameters

  • data: any

  Returns data is EntityData

Interfaces

Appender

Appender:

Contract for any log appender (such as console/screen)

log

• log(level: LogLevel, args: any[]): void

• Logs a message at the given LogLevel

  ---

  Parameters

  • level: LogLevel

    Level to log at

  • args: any[]

    Arguments to log

  Returns void

EasingFunction

• EasingFunction(currentTime: number, startValue: TValueToEase, endValue: TValueToEase, duration: number): TValueToEase

• Parameters

  • currentTime: number

  • startValue: TValueToEase

  • endValue: TValueToEase

  • duration: number

  Returns TValueToEase

Message

Message<T>:

Defines a generic message that can contain any data

---

Type parameters

• T

  is the typescript Type of the data

data

data: T

type

type: string

Observer

Observer<T>:

Defines an interface for an observer to receive a message via a notify() method

---

Type parameters

• T

notify

• notify(message: T): void

• Parameters

  • message: T

  Returns void

ScreenAppenderOptions

ScreenAppenderOptions:

optionalcolor

color?: Color

Provide a text color

engine

engine: Engine<any>

optionalheight

height?: number

Optionally set the height of the overlay canvas

optionalwidth

width?: number

Optionally set the width of the overlay canvas

optionalxPos

xPos?: number

Adjust the text offset from the left side of the screen

optionalzIndex

zIndex?: number

Optionally set the CSS zindex of the overlay canvas

Type Aliases

MaybeObserver

MaybeObserver<T>: Partial<Observer<T>>

Defines an interface for something that might be an observer if a notify() is present

---

Type parameters

• T

Functions

addItemToArray

• addItemToArray<T>(item: T, array: T[]): boolean

• Add an item to an array list if it doesn't already exist. Returns true if added, false if not and already exists in the array.

  @deprecated

  Will be removed in v0.26.0

  ---

  Type parameters

  • T

  Parameters

  • item: T

  • array: T[]

  Returns boolean

contains

• contains(array: any[], obj: any): boolean

• See if an array contains something

  ---

  Parameters

  • array: any[]

  • obj: any

  Returns boolean

delay

• delay(milliseconds: number, clock?: Clock): Promise<void>

• Create a promise that resolves after a certain number of milliseconds

  It is strongly recommended you pass the excalibur clock so delays are bound to the excalibur clock which would be unaffected by stop/pause.

  ---

  Parameters

  • milliseconds: number

  • optionalclock: Clock

  Returns Promise<void>

fail

• fail(message: never): never

• Used for exhaustive checks at compile time

  ---

  Parameters

  • message: never

  Returns never

getMinIndex

• getMinIndex(array: number[]): number

• Parameters

  • array: number[]

  Returns number

getPosition

• getPosition(el: HTMLElement): Vector

• Find the screen position of an HTML element

  ---

  Parameters

  • el: HTMLElement

  Returns Vector

isLegacyEasing

• isLegacyEasing(x?: Function): x is EasingFunction<number>

• Parameters

  • optionalx: Function

  Returns x is EasingFunction<number>

isObject

• isObject(item: any): item is object

• Simple object check.

  ---

  Parameters

  • item: any

  Returns item is object

mergeDeep

• mergeDeep<T>(target: T, ...sources: T[]): T

• Deep merge two objects.

  ---

  Type parameters

  • T: object

  Parameters

  • target: T

  • rest...sources: T[]

  Returns T

omit

• omit<TObject, Keys>(object: TObject, keys: Keys[]): Omit<TObject, Keys>

• Remove keys from object literals

  ---

  Type parameters

  • TObject: Object
  • Keys: string | number | symbol

  Parameters

  • object: TObject

  • keys: Keys[]

  Returns Omit<TObject, Keys>

removeItemFromArray

• removeItemFromArray<T>(item: T, array: T[]): boolean

• Remove an item from an list

  @deprecated

  Will be removed in v0.26.0

  ---

  Type parameters

  • T

  Parameters

  • item: T

  • array: T[]

  Returns boolean