Game

BGE. Game

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

  1. Update - For each GameEntity:
  • Process Input from roku remote
  • Process Audio Events (https://developer.roku.com/en-ca/docs/references/brightscript/events/roaudioplayerevent.md)
  • Process ECP input (https://developer.roku.com/en-ca/docs/developer-program/debugging/external-control-api.md)
  • Process URL events (https://developer.roku.com/en-ca/docs/references/brightscript/events/rourlevent.md)
  • Runs the Entity's onUpdate() function
  • Moves Entity based on velocity
  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

Constructor

new Game(canvas_width, canvas_height, canvas_as_screen_if_possibleopt) → {void}

Constructor for GameEngine

Parameters:
Name Type Attributes Default Description
canvas_width integer

Width of the canvas the game is drawn to
canvas_height integer

Height of the canvas the game is drawn to
canvas_as_screen_if_possible boolean <optional>
 false

If true, the game will draw to the roScreen directly if the canvas dimensions are the same as the screen dimensions, this improves performance but makes it so you can't do various canvas manipulations (such as screen shake or taking screenshots)
Properties:
Name Type Description
currentRoom Room

Reference to the current room in play
currentRoomArgs object

Any special arguments for the current room
Entities object

All of the GameEntities => GameEntity[]
Statics object

All static variables for a given object type
Rooms object

The room definitions by name (the room creation functions)
Interfaces object

The interface definitions by name
Bitmaps object

The loaded bitmaps by name
Sounds object

The loaded sounds by name
Fonts object

The loaded fonts by name
Source:

Methods

addEntity(entity, argsopt) → {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:
Name Type Attributes Default Description
entity GameEntity

the entity to be added
args object <optional>
 {}

arguments to the entity's onCreate() method
Source:

centerCanvasToScreen() → {void}

Centers the canvas on the screen

Source:

changeRoom(roomName, argsopt) → {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:
Name Type Attributes Default Description
roomName string
args object <optional>
 {}
Source:

debugDrawColliders(enabled) → {void}

Set if colliders should be drawn

Parameters:
Name Type Description
enabled boolean
Source:

debugDrawSafeZones(enabled) → {void}

Set if Safe Zone should be drawn

Parameters:
Name Type Description
enabled boolean
Source:

debugLimitFrameRate(limit_frame_rate) → {void}

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

Parameters:
Name Type Description
limit_frame_rate integer
Source:

debugSetColors(colors) → {void}

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

Parameters:
Name Type Description
colors object
Source:

debugShowUi(enabled, drawToScreenopt) → {void}

Set if Debug UI/Windows should be drawn

Parameters:
Name Type Attributes Default Description
enabled boolean
drawToScreen boolean <optional>
 false

Draw the debug UI to the screen instead of the canvas
Source:

defineInterface(interfaceName, interfaceCreationFunction) → {void}

TODO: work on interfaces

Parameters:
Name Type Description
interfaceName string
interfaceCreationFunction callable
Source:

defineRoom(room) → {void}

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

Parameters:
Name Type Description
room Room
Source:

destroyAllEntities(objectName, callOnDestroyopt) → {void}

Destroys all entities with a given name

Parameters:
Name Type Attributes Default Description
objectName string
callOnDestroy boolean <optional>
 true
Source:

destroyEntity(entity, callOnDestroyopt) → {void}

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

Parameters:
Name Type Attributes Default Description
entity GameEntity

the entity to destroy
callOnDestroy boolean <optional>
 true
Source:

End() → {void}

Ends the Game

Source:

entityCount(objectName) → {integer}

Gets the number of entities of a given name

Parameters:
Name Type Description
objectName string
Source:

fitCanvasToScreen() → {void}

Scales and positions the current canvas to fit the screen

Source:

getAllEntities(objectName) → {object}

Gets all the entities that match the given name

Parameters:
Name Type Description
objectName string
Source:

getAllEntitiesWithInterface(interfaceName) → {dynamic}

TODO: work on interfaces

Parameters:
Name Type Description
interfaceName string
Source:

getBitmap(bitmapName) → {object}

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

Parameters:
Name Type Description
bitmapName string
Source:

getCanvas() → {object}

Gets the bitmap the game is currently drawing to

Source:

getDebugUI() → {BGE.Debug.DebugWindow}

Gets the main debug window to add other debug widgets to

Source:

getDeltaTime() → {float}

What's the time in seconds since last frame?

Source:

getEmptyBitmap() → {object}

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

Source:

getEntityByID(entityId) → {GameEntity}

Gets an entity by its unique id

Parameters:
Name Type Description
entityId string
Source:

getEntityByName(objectName) → {GameEntity}

Gets the first entity with the given name

Parameters:
Name Type Description
objectName string
Source:

getFont(fontName) → {object}

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

Parameters:
Name Type Description
fontName string
Source:

getGarbageCollectionStats() → {object}

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

Source:

getNextGameEntityId() → {string}

Gets the next valid id for a GameEntity

Source:

getRoom() → {Room}

Gets the current Room/Level the game is using

Source:

getScreen() → {object}

Gets the screen object

Source:

getTotalTime() → {float}

What's the total time in seconds since ths start

Source:

getUI() → {BGE.Ui.UiContainer}

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

Source:

isPaused() → {boolean}

Is the game paused?

Source:

isRoomChanging() → {boolean}

Source:

loadBitmap(bitmapName, path) → {boolean}

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

Parameters:
Name Type Description
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}
Source:

loadFont(fontName, font, size, italic, bold) → {void}

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

Parameters:
Name Type Description
fontName string

the lookup name to assign to this font
font string

the font to load
size integer
italic boolean
bold boolean
Source:

loadSound(soundName, path) → {void}

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

Parameters:
Name Type Description
soundName string

the name to assign this sound to, to be referenced later
path string

the path to load
Source:

musicPause() → {void}

Pauses the currently playing music

Source:

musicPlay(path, loopopt) → {boolean}

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

Parameters:
Name Type Attributes Default Description
path string

the path of the music file
loop boolean <optional>
 false
Source:

musicResume() → {void}

Resumes / unpauses the current music

Source:

musicStop() → {void}

Stops the currently playing music file

Source:

newAsyncUrlTransfer() → {object}

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

Source:

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

Source:

Play() → {void}

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

Source:

playSound(soundName, volumeopt) → {boolean}

Plays the given sound

Parameters:
Name Type Attributes Default Description
soundName string

the name of the sound to play
volume integer <optional>
 100

volume (0-100) to play the sound at
Source:

postGameEvent(eventName, dataopt) → {void}

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

Parameters:
Name Type Attributes Default Description
eventName string

identifier for the event, eg. "hit", "win", etc.
data object <optional>
 {}

any data that needs to be be passed with the event
Source:

raycastAngle(sourceX, sourceY, angle) → {object}

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

Parameters:
Name Type Description
sourceX float

x position of ray start
sourceY float

y position of ray start
angle float

angle of ray
Source:

raycastVector(sourceX, sourceY, vectorX, vectorY) → {object}

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

Parameters:
Name Type Description
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
Source:

registerFont(path) → {boolean}

Registers a font by its path

Parameters:
Name Type Description
path string
Source:

resetRoom() → {void}

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

Source:

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.

Source:

Resume() → {dynamic}

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

Source:

setBackgroundColor(color) → {void}

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

Parameters:
Name Type Description
color integer
Source:

setInputEntity(entity) → {void}

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

Parameters:
Name Type Description
entity GameEntity
Source:

unloadBitmap(bitmapName) → {void}

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

Parameters:
Name Type Description
bitmapName string
Source:

unloadFont(fontName) → {void}

Unloads a font so it can't be used again

Parameters:
Name Type Description
fontName string
Source:

unsetInputEntity() → {void}

Unset that only one entity will receive onInputCalls()

Source: