Brighterscript Game Engine

Game

Main Game Engine class which runs everything The main game loop is as follows:

  1. Update - For each GameEntity:
  1. Collisions - For each GameEntity:
  • Run Entity's onPreCollision() function
  • For any collisions, runs Entity's onCollision() function
  • Runs entity's onPostCollision() function (At any time, the Entity in question may Delete() itself. Before every entity interaction, the entity is checked to make sure it is still valid in case it was deleted in the last interaction)
  1. Draw - For each GameEntity, sorted by zIndex
  • Runs the Entity onDrawBegin() function
  • For each drawable in the Entity, run the draw() function
  • Run the Entity onDrawEnd() function

  1. Draw all debug items in game space (e.g. colliders, screen safe zones, etc).

  2. UI - For the tree of widgets in the UI Container

  • Run onUpdate()
  • Run draw()
  1. Debug UI - Draw all debug windows in the tree of the Debug UI

Properties

  • sortedEntities (dynamic)
  • compositor (roCompositor)
  • screen (roScreen)
  • canvas (BGE.Canvas)
  • uiCanvas (BGE.Canvas)
  • dummyScreen (roScreen)
  • currentRoom (Room) — Reference to the current room in play
  • currentRoomArgs (dynamic) — Any special arguments for the current room
  • Entities (dynamic) — All of the GameEntities by room => => GameEntity
  • Statics (dynamic) — All static variables for a given object type
  • Rooms (dynamic) — The room definitions by name (the room creation functions)
  • Interfaces (dynamic) — The interface definitions by name
  • Bitmaps (dynamic) — The loaded bitmaps by name
  • Sounds (dynamic) — The loaded sounds by name
  • Fonts (dynamic) — The loaded fonts by name
  • Models (dynamic) — The loaded Models by name
  • gameUi (BGE.UI.UiContainer) — Container for all UI
  • debugUi (BGE.UI.UiContainer) — Container for Debug UI

Constructor

new Game( canvasWidth: integer, canvasHeight: integer, uiWidth?: integer, uiHeight?: integer, ): Game

Constructor for GameEngine

Parameters

  • canvasWidth (integer) — Width of the canvas the game is drawn to
  • canvasHeight (integer) — Height of the canvas the game is drawn to
  • uiWidth (integer, optional, default: 0) — Width of the UI canvas - if 0, will be same as screen
  • uiHeight (integer, optional, default: 0) — Height of the UI canvas - if 0, will be same as screen

Instance Methods

setCamera(cam: Camera): void

Parameters

Returns

  • void

setupUi(uiWidth: integer, uiHeight: integer): void

Sets up the Ui layer

Parameters

  • uiWidth (integer)
  • uiHeight (integer)

Returns

  • void

scaleCanvasToFillScreen(): void

Returns

  • void

getNextGameEntityId(): string

Gets the next valid id for a GameEntity

Returns

  • string

Play(): void

Starts the game engine. Run this function after setting up the game.

Returns

  • void

End(): void

Ends the Game

Returns

  • void

Pause(): void

Pauses the game Only entities marked as pausable = false will be processed in game loop For each entity, the onPause() function will be called

Returns

  • void

Resume(): integer

Resumes / unpauses the game For each entity, the onResume() function will be called, and any image in the entity will have its onResume() called

Returns

  • integer

isPaused(): boolean

Is the game paused?

Returns

  • boolean

setBackgroundColor(color: integer): void

Sets the default background color for the game Before any entities are drawn, the screen is cleared to this color

Parameters

  • color (integer)

Returns

  • void

getDeltaTime(): float

What's the time in seconds since last frame?

Returns

  • float

getTotalTime(): float

What's the total time in seconds since ths start

Returns

  • float

getRoom(): Room

Gets the current Room/Level the game is using

Returns

getCanvas(): ifDraw2D

Gets the bitmap the game is currently drawing to

Returns

  • ifDraw2D

getScreen(): roScreen

Gets the screen object

Returns

  • roScreen

getScreenSize(): BGE.Math.Vector

Returns

  • BGE.Math.Vector

getScreenCenter(): BGE.Math.Vector

Returns

  • BGE.Math.Vector

resetScreen(): void

Resets the screen Note: Important This function is here because of a bug with the Roku. If you ever try to use a component that displays something on the screen aside from roScreen, such as roKeyboardScreen, roMessageDialog, etc. the screen will flicker after you return to your game You should always call this method after using a screen that's outside of roScreen in order to prevent this bug.

Returns

  • void

getEmptyBitmap(): roBitmap

Gets a 1x1 bitmap image (used for collider compositing)

Returns

  • roBitmap

getUI(): BGE.Ui.UiContainer

Gets the UI Container to add new UI elements (which get drawn on top off Game Entities)

Returns

  • BGE.Ui.UiContainer

getDebugUI(): BGE.UI.UiContainer

Gets the main debug window to add other debug widgets to

Returns

  • BGE.UI.UiContainer

debugDrawColliders(enabled: boolean): void

Set if colliders should be drawn

Parameters

  • enabled (boolean)

Returns

  • void

debugDrawSafeZones(enabled: boolean): void

Set if Safe Zone should be drawn

Parameters

  • enabled (boolean)

Returns

  • void

debugDrawEntityDetails(enabled: boolean): void

Set GameEntity and SceneObject debug view on or off

Parameters

  • enabled (boolean)

Returns

  • void

debugShowUi(enabled: boolean, drawToScreen?: boolean): void

Set if Debug UI/Windows should be drawn

Parameters

  • enabled (boolean)
  • drawToScreen (boolean, optional, default: true) — Draw the debug UI to the screen instead of the canvas

Returns

  • void

isDebugUiEnabled(): boolean

Returns

  • boolean

getDebugValue(debugKey: string): dynamic

Parameters

  • debugKey (string)

Returns

  • dynamic

log(message: string, level?: BGE.Debug.LogLevel): void

Logs a message, printing it and recording it for on-screen debug display (e.g. BGE.Debug.LogDisplay)

Parameters

  • message (string)
  • level (BGE.Debug.LogLevel, optional, default: "BGE.Debug.LogLevel.info")

Returns

  • void

getLogHistory(): dynamic

Gets the history of messages logged via log()

Returns

  • dynamic — an array of {message: string, level: BGE.Debug.LogLevel}

debugSetColors(colors: DebugColors): void

Sets the colors for the debug items to be drawn colors = {colliders: integer, safe_action_zone: integer, safe_title_zone: integer}

Parameters

Returns

  • void

debugLimitFrameRate(limit_frame_rate: integer): void

Limit the frame rate to the given number of frames per second

Parameters

  • limit_frame_rate (integer)

Returns

  • void

getGarbageCollectionStats(): GarbageCollectionInfo

Gets the latest stats from automatic garbage collection https://developer.roku.com/en-ca/docs/references/brightscript/language/global-utility-functions.md#rungarbagecollector-as-object

Returns

raycastVector( sourceX: float, sourceY: float, vectorX: float, vectorY: float, ): object

Performs a raycast from a certain location along a vector to find any colliders on that line

Parameters

  • sourceX (float) — x position of ray start
  • sourceY (float) — y position of ray start
  • vectorX (float) — x value of vector
  • vectorY (float) — y value of vector

Returns

  • object — {collider: collider, entity: entity} of first collider along the vector, or invalid if no collisions

raycastAngle( sourceX: float, sourceY: float, angle: float, ): object

Performs a raycast from a certain location along a n angle to find any colliders on that line

Parameters

  • sourceX (float) — x position of ray start
  • sourceY (float) — y position of ray start
  • angle (float) — angle of ray

Returns

  • object — {collider: collider, entity: entity} of first collider along the angle, or invalid if no collisions

defineInterface( interfaceName: string, interfaceCreationFunction: function, ): void

TODO: work on interfaces

Parameters

  • interfaceName (string)
  • interfaceCreationFunction (function)

Returns

  • void

addEntity( entity: GameEntity, args?: roAssociativeArray, ): GameEntity

Adds a game entity to be processed by the game engine Only entities that have been added will be part of the game Calls the entity's onCreate() function with the args provided

Parameters

  • entity (GameEntity) — the entity to be added
  • args (roAssociativeArray, optional, default: "{}") — arguments to the entity's onCreate() method

Returns

getEntityByID(entityId: string | dynamic): GameEntity

Gets an entity by its unique id

Parameters

  • entityId (string | dynamic)

Returns

  • GameEntity — the entity with the given id, if found, otherwise invalid

getEntityByName(objectName: string): GameEntity

Gets the first entity with the given name

Parameters

  • objectName (string)

Returns

  • GameEntity — the entity with the given name, if found, otherwise invalid

getAllEntities(objectName: string): dynamic

Gets all the entities that match the given name

Parameters

  • objectName (string)

Returns

  • dynamic — an array with entities with the given name

getAllEntitiesWithInterface(interfaceName: string): dynamic

TODO: work on interfaces

Parameters

  • interfaceName (string)

Returns

  • dynamic

destroyEntity(entity: GameEntity, callOnDestroy?: boolean): void

Destroys an entity and all its colliders Clears its properties, so images, etc. won't get drawn anymore

Parameters

  • entity (GameEntity) — the entity to destroy
  • callOnDestroy (boolean, optional, default: true)

Returns

  • void

destroyAllEntities( objectName: string, callOnDestroy?: boolean, ): void

Destroys all entities with a given name

Parameters

  • objectName (string)
  • callOnDestroy (boolean, optional, default: true)

Returns

  • void

entityCount(objectName: string): integer

Gets the number of entities of a given name

Parameters

  • objectName (string)

Returns

  • integer

defineRoom(room: Room, newRoom: Room): void

Defines a room (like a level) in the game TODO: work on rooms

Parameters

Returns

  • void

isRoomChanging(): boolean

Returns

  • boolean

changeRoom(roomName: string, args?: roAssociativeArray): boolean

Changes the active room to the one with the given name Calls the room's onCreate() method with the args given TODO: work on rooms

Parameters

  • roomName (string)
  • args (roAssociativeArray, optional, default: "{}")

Returns

  • boolean — true if room change was successful

resetRoom(): void

Resets the current room to its state at when it was first created

Returns

  • void

getRoomNames(): dynamic

Returns

  • dynamic

loadBitmap(bitmapName: string, path: dynamic): boolean

Loads an image file (png/jpg) to be used as an image in the game

Parameters

  • bitmapName (string) — the name this bitmap will be referenced by later
  • path (dynamic) — The path to the bitmap, or an associative array {width: integer, height: integer, alphaEnable:boolean}

Returns

  • boolean — true if image was loaded

getBitmap(bitmapName: string): roBitmap

Gets a bitmap image (roBitmap) by the name given to it when loadBitmap() was called

Parameters

  • bitmapName (string)

Returns

  • roBitmap

unloadBitmap(bitmapName: string): void

Invalidates a bitmap name, so it can't be loaded again

Parameters

  • bitmapName (string)

Returns

  • void

load3dModel( bitmapName: string, path: dynamic, modelName: string, modelPath: string, ): boolean

Loads an image file (png/jpg) to be used as an image in the game

Parameters

  • bitmapName (string) — the name this bitmap will be referenced by later
  • path (dynamic) — The path to the bitmap, or an associative array {width: integer, height: integer, alphaEnable:boolean}
  • modelName (string)
  • modelPath (string)

Returns

  • boolean — true if image was loaded

get3dModel(modelName: string): Model3d

Gets a 3d Model (Model3d) by the name given to it when load3dModel() was called

Parameters

  • modelName (string)

Returns

unload3dModel(modelName: string): void

Invalidates a 3d Model name, so it can't be loaded again

Parameters

  • modelName (string)

Returns

  • void

registerFont(path: string): boolean

Registers a font by its path

Parameters

  • path (string)

Returns

  • boolean — true if font was registered

loadFont( fontName: string, font: string, size: integer, italic: boolean, bold: boolean, ): void

Loads a font from the registry, and assigns it the given name

Parameters

  • fontName (string) — the lookup name to assign to this font
  • font (string) — the font to load
  • size (integer)
  • italic (boolean)
  • bold (boolean)

Returns

  • void

unloadFont(fontName: string): void

Unloads a font so it can't be used again

Parameters

  • fontName (string)

Returns

  • void

getFont(fontName: string): roFont

Gets a font object, to be used for writing text to the screen For example, in BGE.DrawText()

Parameters

  • fontName (string)

Returns

  • roFont

fitCanvasToScreen(): void

Scales and positions the current canvas to fit the screen

Returns

  • void

centerCanvasToScreen(): void

Centers the canvas on the screen

Returns

  • void

musicPlay(path: string, loop?: boolean): boolean

Plays an audio file at the given path This is designed for music, where only one file can play at a time.

Parameters

  • path (string) — the path of the music file
  • loop (boolean, optional, default: false)

Returns

  • boolean

musicStop(): void

Stops the currently playing music file

Returns

  • void

musicPause(): void

Pauses the currently playing music

Returns

  • void

musicResume(): void

Resumes / unpauses the current music

Returns

  • void

loadSound(soundName: string, path: string): void

Loads a sound file from the given path to be played later

Parameters

  • soundName (string) — the name to assign this sound to, to be referenced later
  • path (string) — the path to load

Returns

  • void

playSound(soundName: string, volume?: integer): boolean

Plays the given sound

Parameters

  • soundName (string) — the name of the sound to play
  • volume (integer, optional, default: 100) — volume (0-100) to play the sound at

Returns

  • boolean

newAsyncUrlTransfer(): roUrlTransfer

Creates a new URL Async Transfer object, which is handled by the game loop Events from this URL transfer will be set to entities via the onUrlEvent() method

Returns

  • roUrlTransfer

setInputEntity(entity: GameEntity): void

Set only one entity to receive onInput() calls Useful for when a menu/pause screen should handle all input

Parameters

Returns

  • void

unsetInputEntity(): void

Unset that only one entity will receive onInputCalls()

Returns

  • void

postGameEvent( eventName: string, data?: roAssociativeArray, ): void

General purpose event dispatch method Game entities can listen for events via the onGameEvent() method

Parameters

  • eventName (string) — identifier for the event, eg. "hit", "win", etc.
  • data (roAssociativeArray, optional, default: "{}") — any data that needs to be be passed with the event

Returns

  • void