BGE

Static Methods

resolveAabbTileCollision( positionBefore: BGE.Math.Vector, currentPosition: BGE.Math.Vector, width: float, height: float, velocity: BGE.Math.Vector, tileCollider: BGE.RectangleCollider, isOneWay?: boolean, tolerancePx?: float, ): BGE.TileCollisionResult

Resolves an entity's axis-aligned hitbox against one static rectangular tile collider, using the entity's pre-move position to determine which side it approached from - the generic "solid tile world" resolution algorithm (landing on top, one-way-platform pass-through, head bumps, side pushes) needed by a tile-based platformer or top-down game's GameEntity.onCollision(). It does not replace BGE.Collider/CheckMultipleCollisions() for entity-vs-entity collision - use it only for collisions against static tile geometry.

The entity's own hitbox is assumed feet-anchored, matching GameEntity.addRectangleCollider()'s own convention: positionBefore is the bottom- center point (x = horizontal center, y = bottom edge), so the hitbox spans positionBefore.x -+ width/2 horizontally and positionBefore.y to positionBefore.y + height vertically.

Precondition: only call this when the entity's current (post-move) position is already known to overlap this tile - e.g. from inside onCollision(), which only fires on a genuine overlap. This function has no independent way to verify an overlap actually exists (it trusts positionBefore/currentPosition/velocity at face value); called with values that were never actually approaching/touching, its returned side is not meaningful (this mirrors the exact same precondition the hand-rolled onCollision() logic it replaces already had, implicitly, by virtue of only ever running inside onCollision()).

this frame, before this frame's own movement was applied (capture it at the top of onUpdate(), before integrating velocity) - used to tell which side of the tile the entity approached from. the moment onCollision() fires) - this is what gets returned unchanged on the axis that isn't resolved this call, and as the base every resolved axis's correction is applied on top of. Do NOT pass positionBefore here - by the time onCollision() runs, the engine has already integrated this frame's velocity into the entity's position (see Game.bs's processEntitiesPreDraw -> processEntitiesCollisions ordering), so currentPosition and positionBefore are genuinely different values whenever the entity moved at all this frame. addRectangleCollider()) matters for landing/head-bump detection) otherCollider passed to onCollision()) (this function reads tileCollider.offset.y as the tile's TOP edge and tileCollider.offset.x as its LEFT edge in world space - matching how examples/platformer's Level.bs actually constructs its tile colliders via addRectangleCollider(tileName, TileSize, TileSize, leftX, topY) - not RectangleCollider's own class doc, which describes offset as the shape's bottom-left corner; tileTop/tileBottom below are derived accordingly) passes through from below/the sides (e.g. a one-way platform) a side, absorbing floating-point/frame-step slack

Parameters

• positionBefore (BGE.Math.Vector) — the entity's position as of the start of
• currentPosition (BGE.Math.Vector) — the entity's actual position right now (at
• width (float) — the entity's hitbox width (matching the width passed to
• height (float) — the entity's hitbox height
• velocity (BGE.Math.Vector) — the entity's current velocity (only .y's sign
• tileCollider (BGE.RectangleCollider) — the tile's own collider (the
• isOneWay (boolean, optional, default: false) — true if this tile only blocks a from-above landing and
• tolerancePx (float, optional, default: "1.0") — how many pixels of overlap/gap still count as "touching"

Returns

• BGE.TileCollisionResult

newFullHeightParallaxLayer( owner: BGE.GameEntity, region: roRegion, canvasWidth: float, canvasHeight: float, factor: float, targetX?: float, targetY?: float, zOffset?: float, ): BGE.DrawableParallaxLayer

Builds a DrawableParallaxLayer scaled to fill the canvas vertically edge-to-edge and tiled to cover it on both axes, with its tile-repeat seam anchored at a chosen canvas position (targetX, targetY) rather than wherever computeEffectiveWorldPosition()'s own reference-position capture would otherwise put it - see that method's own derivation comment, and examples/platformer's MainRoom for a worked application (including staggering several stacked layers' seams via different targetX values so they don't all reinforce into one obvious seam).

This assumes owner sits at world (0,0,0) and the camera's target on the axis orthogonal to factor's own drift direction stays fixed for the object's lifetime (e.g. a side-scroller with a Y-locked camera) - it is not a general-purpose "anchor anywhere under any camera motion" solution. See examples/parallax's own hand-rolled newLayer() for a different derivation (owner co-located with a moving camera target, non-uniform per-axis factor) that this helper does not cover.

Note: this function deliberately lives in its own file, separate from DrawableParallaxLayer.bs - a namespace-level free function whose return type self-references a class defined in the SAME file triggers a real BrighterScript compiler bug (confirmed via bisection: a trivial return invalid body with the same signature still fails, and changing only the return type to as object "fixes" it - the trigger is the self-referential return type, not this function's body). Keeping it in a separate file (importing DrawableParallaxLayer.bs) avoids the bug entirely while keeping full type fidelity on the return type.

nonzero; a fully camera-pinned layer (factor = 0) is not supported by this helper's offset math (it would divide by zero). canvasWidth/2 (its assumed rest position on this axis) target (canvasHeight/2 is the common "camera always centers vertically" case) draw order via BGE.DrawableParallaxLayer's normal Z-based sort

Parameters

• owner (BGE.GameEntity) — the entity this layer attaches to; must sit at world (0,0,0)
• region (roRegion) — the bitmap tile to scroll/repeat
• canvasWidth (float)
• canvasHeight (float)
• factor (float) — parallaxFactor applied uniformly to both axes - must be
• targetX (float, optional, default: "0.0") — on-canvas X the tile seam lands at while the camera sits at
• targetY (float, optional, default: "0.0") — on-canvas Y the tile seam lands at, given the camera's fixed Y
• zOffset (float, optional, default: "0.0") — Z offset for this layer, useful for stacking several layers'

Returns

• BGE.DrawableParallaxLayer

getNewMemoryScratchRegion( width: float, height: float, ): ScratchRegion

Parameters

• width (float)
• height (float)

Returns

• ScratchRegion

isBackFaceDrawMode(drawMode: SceneObjectDrawMode): boolean

Parameters

• drawMode (SceneObjectDrawMode)

Returns

• boolean

isDirectDrawMode(drawMode: SceneObjectDrawMode): boolean

Parameters

• drawMode (SceneObjectDrawMode)

Returns

• boolean

isOrientedDrawMode(drawMode: SceneObjectDrawMode): boolean

Parameters

• drawMode (SceneObjectDrawMode)

Returns

• boolean

isScreenAlignedDrawMode(drawMode: SceneObjectDrawMode): boolean

The draw modes that keep an object square to the screen rather than turning it in 3D - the billboard modes. directScaled belongs here even though isOrientedDrawMode groups it with the oriented modes: it faces the camera like directToCamera and only differs in taking its size from how far away it is (a Doom-style sprite).

Parameters

• drawMode (SceneObjectDrawMode)

Returns

• boolean

isWireFrameDrawMode(drawMode: SceneObjectDrawMode): boolean

Parameters

• drawMode (SceneObjectDrawMode)

Returns

• boolean

isSolidDrawMode(drawMode: SceneObjectDrawMode): boolean

Parameters

• drawMode (SceneObjectDrawMode)

Returns

• boolean

isFullDrawMode(drawMode: SceneObjectDrawMode): boolean

Parameters

• drawMode (SceneObjectDrawMode)

Returns

• boolean

getDrawModeName(drawMode: SceneObjectDrawMode): string

The name of a draw mode, as written in the SceneObjectDrawMode enum - handy for debug overlays and for examples that let you cycle through the draw modes.

Parameters

• drawMode (SceneObjectDrawMode)

Returns

• string — the mode's name, or "unknown" for a value outside the enum

getDrawModeBooleanLookupArray(defaultValue?: boolean): dynamic

Parameters

• defaultValue (boolean, optional, default: false)

Returns

• dynamic

getDotProductFromSurfaceToCamera( rendererObj: BGE.Renderer, facePoint: BGE.Math.Vector, faceNormal: BGE.Math.Vector, ): float

Parameters

• rendererObj (BGE.Renderer)
• facePoint (BGE.Math.Vector)
• faceNormal (BGE.Math.Vector)

Returns

• float

isNormalFacingCamera( rendererObj: BGE.Renderer, facePoint: BGE.Math.Vector, faceNormal: BGE.Math.Vector, ): boolean

Parameters

• rendererObj (BGE.Renderer)
• facePoint (BGE.Math.Vector)
• faceNormal (BGE.Math.Vector)

Returns

• boolean

HSVtoRGBA( hPercent: float, sPercent: float, vPercent: float, a?: integer, ): integer

Parameters

• hPercent (float)
• sPercent (float)
• vPercent (float)
• a (integer, optional, default: -1)

Returns

• integer

RGBAtoRGBA( red: integer, green: integer, blue: integer, alpha?: float, ): integer

Parameters

• red (integer)
• green (integer)
• blue (integer)
• alpha (float, optional, default: 1)

Returns

• integer

unpackRGB(rgb: integer): roAssociativeArray

Unpacks a packed RGB color (0xRRGGBB) into its R/G/B channels.

Parameters

• rgb (integer)

Returns

• roAssociativeArray — {r, g, b}, each 0-255

unpackRGBA(rgba: integer): roAssociativeArray

Unpacks a packed RGBA color (0xRRGGBBAA) into its R/G/B/A channels.

Parameters

• rgba (integer)

Returns

• roAssociativeArray — {r, g, b, a}, each 0-255

GetColor(name: string): integer

Looks up a BGE.Colors value by name (case-insensitive). Falls back to White for a name that isn't a known color.

Parameters

• name (string)

Returns

• integer

GetColorRGB(name: string): integer

Looks up a BGE.ColorsRGB value by name (case-insensitive). Falls back to White for a name that isn't a known color.

Parameters

• name (string)

Returns

• integer

getRandomColorRGB( r?: integer, g?: integer, b?: integer, ): integer

A random color as a packed RGB integer (0xRRGGBB, no alpha byte) - the format Drawable.color/Drawable.outlineRGBA expect. Use getRandomColorRGBA for the packed-RGBA format the Renderer.draw* calls take.

Parameters

• r (integer, optional, default: 255) — exclusive upper bound for the red channel
• g (integer, optional, default: 255) — exclusive upper bound for the green channel
• b (integer, optional, default: 255) — exclusive upper bound for the blue channel

Returns

• integer — packed RGB color

getRandomColorRGBA( r?: integer, g?: integer, b?: integer, a?: integer, ): integer

Parameters

• r (integer, optional, default: 255)
• g (integer, optional, default: 255)
• b (integer, optional, default: 255)
• a (integer, optional, default: 255)

Returns

• integer

colorBrightness(rgba: integer, brightness: float): integer

Parameters

• rgba (integer)
• brightness (float)

Returns

• integer

colorOpacity(rgba: integer, opacity: float): integer

Parameters

• rgba (integer)
• opacity (float)

Returns

• integer

lerpColorRGB( colorA: integer, colorB: integer, t: float, ): integer

Linearly interpolates between two packed RGB colors (0xRRGGBB), channel-wise.

Parameters

• colorA (integer) — start color, packed RGB (returned at t=0)
• colorB (integer) — end color, packed RGB (returned at t=1)
• t (float) — interpolation factor, clamped to 0-1

Returns

• integer — the interpolated packed RGB color

getDeviceRenderTier(): DeviceRenderTier

Determines this device's render tier via roDeviceInfo.

Not cached internally - CreateObject("roDeviceInfo") plus one or two native calls is cheap enough for the common case (called once, e.g. from a constructor), and this can't change at runtime. A call site that needs to avoid repeating the check across many calls (e.g. once per frame) should cache the returned value itself, the same way Camera3d.getMaxDrawDistanceDeviceCap() already caches its derived cap in an instance field.

Returns

• DeviceRenderTier

registryWrite( registry_section: string, key: string, value: dynamic, ): void

Parameters

• registry_section (string)
• key (string)
• value (dynamic)

Returns

• void

registryRead( registry_section: string, key: string, default_value?: dynamic, ): dynamic

Parameters

• registry_section (string)
• key (string)
• default_value (dynamic, optional, default: "invalid")

Returns

• dynamic

getNumberOfLinesInAString(text: string): integer

Gets the number of lines in a string by counting the newlines

Parameters

• text (string)

Returns

• integer

lastInStr(text: string, substring: string): integer

Finds the index of the last time a substring appears in a string

Parameters

• text (string)
• substring (string)

Returns

• integer

numberToFixed(num: float, precision: integer): string

Given a float number, returns the number with a fixed numbers of decimals as a string

Parameters

• num (float)
• precision (integer)

Returns

• string

arrayToStr(things: dynamic): string

Parameters

• things (dynamic)

Returns

• string

stringToFloat(input: string): float

Parameters

• input (string)

Returns

• float

TexturePacker_GetRegions( atlas: dynamic, bitmap: ifDraw2d, ): roAssociativeArray

TODO: figure this out... is useful for sprites with different size frames

Parameters

• atlas (dynamic)
• bitmap (ifDraw2d)

Returns

• roAssociativeArray

sliceGridRegions( bitmap: ifDraw2d, cellWidth: integer, cellHeight: integer, ): dynamic

Slices a bitmap into a row-major grid of cellWidth x cellHeight roRegions.

Parameters

• bitmap (ifDraw2d)
• cellWidth (integer)
• cellHeight (integer)

Returns

• dynamic

ArrayInsert( array: dynamic, index: integer, value: dynamic, ): dynamic

Parameters

• array (dynamic)
• index (integer)
• value (dynamic)

Returns

• dynamic

DrawCircleOutline( draw2d: ifDraw2d, line_count: integer, x: float, y: float, radius: float, rgba: integer, ): void

Parameters

• draw2d (ifDraw2d)
• line_count (integer)
• x (float)
• y (float)
• radius (float)
• rgba (integer)

Returns

• void

DrawRectangleOutline( draw2d: ifDraw2d, x: float, y: float, width: float, height: float, rgba: integer, ): void

Parameters

• draw2d (ifDraw2d)
• x (float)
• y (float)
• width (float)
• height (float)
• rgba (integer)

Returns

• void

isValidEntity(entity: EntityWithId): boolean

Parameters

• entity (EntityWithId)

Returns

• boolean

buttonNameFromCode(buttonCode: integer): string

Parameters

• buttonCode (integer)

Returns

• string

buttonAliasToName(buttonName: string): string

Resolves a button name or common alias to the (lowercased) BGE canonical button name, e.g. for use with GameInput.isButton(). Unrecognized names are returned lowercased, unchanged, so a caller checking a name BGE doesn't know about still gets consistent case-insensitive behavior.

Parameters

• buttonName (string) — a button name or alias (case insensitive)

Returns

• string

cloneArray(original?: Array.<dynamic>): dynamic

Clone an array (shallow)

Parameters

• original (Array.<dynamic>, optional, default: "[]") — the original array to be clones

Returns

• dynamic — A shallow copy of the original array

pointArraysEqual(a?: dynamic, b?: dynamic): boolean

Check if two arrays of points are teh same - that is, if each point, in order has same x and y values

Parameters

• a (dynamic, optional, default: "[]") — the first array
• b (dynamic, optional, default: "[]") — the second array

Returns

• boolean — true if both arrays have same number of points and x and y values are the same for each point

isTrue(value: dynamic): boolean

Parameters

• value (dynamic)

Returns

• boolean

bytesToInteger( bytes: dynamic, offset?: integer, isLittleEndian?: boolean, ): integer

Parameters

• bytes (dynamic)
• offset (integer, optional, default: 0)
• isLittleEndian (boolean, optional, default: true)

Returns

• integer

bytesToFloat( bytes: dynamic, offset?: integer, isLittleEndian?: boolean, ): float

Parameters

• bytes (dynamic)
• offset (integer, optional, default: 0)
• isLittleEndian (boolean, optional, default: true)

Returns

• float

hexStringToByteArray(hex: string): roByteArray

Decodes a hex-encoded string (e.g. from roEVPDigest.Process()) into its raw bytes. Processes hex characters in pairs; an odd-length input's trailing character is decoded as a single nibble (left-padded with implicit zero).

Parameters

• hex (string)

Returns

• roByteArray

subArray( array: ifArray, startIndex: integer, length: integer, ): roArray

Parameters

• array (ifArray)
• startIndex (integer)
• length (integer)

Returns

• roArray

decToHex(dec: integer): string

Parameters

• dec (integer)

Returns

• string

Enums

.TweenApplyMode

How a managed tween writes its interpolated value onto its target - internal, not part of the public API. "fields" is what to()/addManagedTween() uses for plain named-field targets; the color variants repack channels back into a single packed int instead.

Properties

• fields (default: "fields")
• colorRGB (default: "colorRGB")
• colorRGBA (default: "colorRGBA")

.TileCollisionSide

Which side of the tile (if any) resolveAabbTileCollision() resolved a collision against. "none" means the tile didn't block the entity at all this frame (e.g. rising through a one-way platform, or no overlap).

Properties

• none (default: "none")
• top (default: "top")
• bottom (default: "bottom")
• left (default: "left")
• right (default: "right")

.ParticleShape

The shape drawn for every particle spawned by a DrawableParticles emitter.

Properties

• Line (default: "line")
• Rectangle (default: "rectangle")
• Image (default: "image")

.PlaneFillMode

Which of the three composable ways a DrawablePlane fills its surface:

• color: a flat fill using the drawable's own color/alpha fields, no texture at all. Never "runs out" - the natural base/backdrop layer under the other two.
• tiledImage: region is treated as a single repeating tile, seamlessly covering the world-space footprint bounded by the camera's maxDrawDistance.
• staticImage: region is a one-off finite decal anchored at the plane's own world position (today's only historical behavior) - correct for e.g. a map texture, wrong for anything meant to repeat.

Multiple DrawablePlanes (in any mix of modes) can be layered on the same entity or room via separate addDrawable() calls - draw order for planes at the same depth follows insertion order (SceneObject's existing depth-sort tie-break), so add the base layer (e.g. a color plane) first.

Properties

• color (default: "color")
• tiledImage (default: "tiledImage")
• staticImage (default: "staticImage")

.SpritePlayMode

Properties

• Loop (default: "loop")
• Forward (default: "forward")
• Reverse (default: "reverse")
• PingPong (default: "pingpong")

.CameraFrustumSide

Properties

• top (default: "top")
• bottom (default: "bottom")
• left (default: "left")
• right (default: "right")
• near (default: "near")

.SceneObjectType

Properties

• Line (default: "Line")
• Rectangle (default: "Rectangle")
• Text (default: "Text")
• Bitmap (default: "Bitmap")
• Polygon (default: "Polygon")
• Billboard (default: "Billboard")
• Model (default: "Model")
• Plane (default: "Plane")
• ParallaxLayer (default: "ParallaxLayer")
• Circle (default: "Circle")
• Particle (default: "Particle")
• Skybox (default: "Skybox")

.SceneObjectDrawMode

Properties

• matchCamera (default: 0) — Rotations are ignored
• directToCamera (default: 1) — Do not orient in 3d space
• directScaled (default: 2) — Do not orient in 3d space, but scale in relation to distance from camera
• oriented (default: 3) — Orient in 3d space
• orientedDrawBackFace (default: 4) — Orient the object, and draw any back faces
• wireFrame (default: 5) — Just draw a wire frame
• wireFrameDrawBackFace (default: 6) — Just draw a wire frame, including back faces
• solid (default: 7) — Draw a solid polygon
• solidDrawBackFace (default: 8) — Draw a solid polygon, including back faces

.Colors

Named colors as packed RGBA integers (0xRRGGBBAA), fully opaque. Values match RGBAtoRGBA(r, g, b) for the same named color.

Properties

• Black (default: 255)
• White (default: 4294967295)
• Red (default: 4278190335)
• Lime (default: 16711935)
• Blue (default: 65535)
• Yellow (default: 4294902015)
• Cyan (default: 16777215)
• Aqua (default: 16777215)
• Magenta (default: 4278255615)
• Pink (default: 4278255615)
• Fuchsia (default: 4278255615)
• Silver (default: 3233857791)
• Gray (default: 2155905279)
• Grey (default: 2155905279)
• Maroon (default: 2147483903)
• Olive (default: 2155872511)
• Green (default: 8388863)
• Purple (default: 2147516671)
• Teal (default: 8421631)
• Navy (default: 33023)

.ColorsRGB

Named colors as packed RGB integers (0xRRGGBB, no alpha byte) - the same values as BGE.Colors, right-shifted by 8.

Properties

• Black (default: 0)
• White (default: 16777215)
• Red (default: 16711680)
• Lime (default: 65280)
• Blue (default: 255)
• Yellow (default: 16776960)
• Cyan (default: 65535)
• Aqua (default: 65535)
• Magenta (default: 16711935)
• Pink (default: 16711935)
• Fuchsia (default: 16711935)
• Silver (default: 12632256)
• Gray (default: 8421504)
• Grey (default: 8421504)
• Maroon (default: 8388608)
• Olive (default: 8421376)
• Green (default: 32768)
• Purple (default: 8388736)
• Teal (default: 32896)
• Navy (default: 128)

.DeviceRenderTier

Roku hardware performance tier, derived from roDeviceInfo. Every device-tiered branch in the engine (scratch bitmap sizing, low-end draw-quality checks, texture size caps, far-clip distance caps) should switch on this instead of independently re-deriving it from HasFeature("simulation_engine")/GetUIResolution().name.

Properties

• simulator (default: "simulator")
• sd (default: "SD")
• hd (default: "HD")
• fhd (default: "FHD")

Other

Canvas

Contains a roku roBitmap which all game objects get drawn to.

Parameters

• gameEngine (Game)
• canvasWidth (integer) — width of canvas
• canvasHeight (integer) — height of canvas
• options (RendererOptions, optional, default: "{useBitmapPooling: true}")

Properties

• bitmap (ifDraw2D) — bitmap GameEntity images get drawn to
• offset (BGE.Math.Vector) — Position offset from screen coordinates (z value ignored)
• scale (BGE.Math.Vector) — Scale (z value ignored)
• renderer (Renderer) — Renderer for this canvas
• rendererOptions (RendererOptions)

Returns

• BGE.Canvas

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

2. 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)

3. 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

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

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

• Run onUpdate()
• Run draw()

6. Debug UI - Draw all debug windows in the tree of the Debug UI

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

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
• tweenManager (BGE.TweenManager) — Ticks every live tween once per frame and writes interpolated values onto arbitrary ' target fields - see BGE.TweenManager.to().
• gameUi (BGE.UI.UiContainer) — Container for all UI
• debugUi (BGE.UI.UiContainer) — Container for Debug UI
• focusManager (BGE.UI.FocusManager) — The single, global focused-widget/cursor state shared by gameUi and any ' of its focusEnabled descendants - see BGE.UI.FocusManager.
• defaultTheme (BGE.UI.Theme) — Default theme for all UI widgets, set in new()
• controls (BGE.Controller.ControlMap) — Unified remote+controller input mapping - see enableControllerInput() ' and BGE.Controller.ControlMap.

Returns

• BGE.Game

GameEntity

Every thing (character, player, object, etc) in the game should extend this class. This class has a number of empty methods that are designed to be overridden in subclasses. For example, override onInput() to handle input event, and onUpdate() to handle updating each frame

Parameters

• game (Game) — The game engine that this entity is going to be assigned to
• gameEngine (Game)
• args (roAssociativeArray, optional, default: "{}") — Any extra properties to be added to this entity

Properties

• name (string) — Constant - name of this Entity
• id (dynamic) — Constant - Unique Id
• game (Game)
• enabled (boolean) — Is this GameEntity enabled
• persistent (boolean) — Does this entity persist across room changes?
• pauseable (boolean) — When the game is paused, does this entity pause too?
• position (dynamic) — position of where this entity is in game world
• velocity (dynamic) — Speed of this entity, in units/second (not units/frame) - added to position each frame scaled by elapsed time
• rotation (dynamic) — Rotation of entity - applies to all images
• scale (dynamic) — Scale of entity - applies to all images
• colliders (roAssociativeArray) — The colliders for this entity by name
• drawables (dynamic) — The array of drawables to draw for this entity
• drawablesByName (roAssociativeArray) — Associative array of drawables by name
• tagsList (dynamic) — Game Entities can be tagged with any number of tags so they can be easily identified (e.g. "enemy", "wall", etc.)
• transformationMatrix (dynamic) — The Current Transformation Matrix
• motionChecker (MotionChecker)
• isDying (boolean) — True once invalidateAfter() has been called - lets game code (collision ' handlers, scoring logic, etc.) check whether this entity is already in its ' death sequence and skip re-triggering effects/logic on it, without needing ' to know about the underlying timer mechanism.
• dyingTimer (GameTimer) — Timer/delay backing invalidateAfter()'s grace period. Public (rather than ' private) so tests can fast-forward it via GameTimer.addTime() the same way ' other engine timers are tested - see checkDyingTimeout().
• dyingDelayMs (integer)

Returns

• BGE.GameEntity

CONTROLLER_BUTTON_CODE_PRESS_BASE

Numeric bands for controller-originated buttonCodes (see BGE.Controller. ControllerRegistry/Game.drainControllerInput, which construct these) - deliberately far above the remote's own 0-99 (press) / 100-999 (release) / 1000+ (held) ranges (see the button-code table below) so a controller event's code can never be misclassified as a remote one. A controller button's identity is a name, not a code (see explicitButtonName below) - these bands exist only to classify press/release/held, so every controller-originated GameInput uses the band's base value as-is.

Default: 100000

CONTROLLER_BUTTON_CODE_RELEASE_BASE

Default: 200000

CONTROLLER_BUTTON_CODE_HELD_BASE

Default: 300000

GameInput

Class that contains all information about the current input during a given frame from the remote

Parameters

• buttonCode (integer) — button to use for the data
• heldTimeMs (integer) — how long was this button held for
• playerIndex (integer, optional, default: -1) — 1 for the remote, 0+ for a controller
• explicitButtonName (string, optional, default: "invalid") — overrides buttonNameFromCode, used for controller buttons

Properties

• button (string) — The name of the button associated with the current input
• buttonCode (integer) — The code for the input
• press (boolean) — Was the button pressed since the last frame
• held (boolean) — Was the button held down since last frame
• release (boolean) — Was the button released this frame
• heldTimeMs (integer) — How many milliseconds was the current input held for
• playerIndex (integer) — Which controller this input came from - -1 for the physical remote, ' 0+ for a connected browser controller (see BGE.Controller.ControlMap).
• consumed (boolean) — Set by a UiWidget/UiContainer that acted on this event - once set, the ' owning UiContainer stops this event from also reaching GameEntity.onInput() ' for the rest of this frame (see Game.setInputEntity()).
• x (float) — Current horizontal directional input: left -> -1, right -> 1
• y (float) — Current vertical directional input, in world space (+y is up, matching ' the engine's world coordinate convention - the renderer flips this when ' projecting to raster/canvas space): up -> 1, down -> -1

Returns

• BGE.GameInput

Example

' -------Button Code Reference--------
' Button  Pressed Released  Held
' ------------------------------
' Back         0      100   1000
' Up           2      102   1002
' Down         3      103   1003
' Left         4      104   1004
' Right        5      105   1005
' OK           6      106   1006
' Replay       7      107   1007
' Rewind       8      108   1008
' FastForward  9      109   1009
' Options     10      110   1010
' Play        13      113   1013

GameTimer

Wrapper for Roku's roTimeSpan that allows time adjustment

Returns

• BGE.GameTimer

Room

Extends: GameEntity

A Room is just a GameEntity that represents a distinct scene/level - see Game.defineRoom()/changeRoom(). Only one Room can be "current" at a time; the current Room is processed like any other entity (its onUpdate/onInput/etc. hooks fire every frame) but is never itself placed in Game.sortedEntities, so Game.handleRoomChange()'s automatic non-persistent-entity cleanup never applies to a Room's own drawables.

To compensate, Room provides a default onChangeRoom(): any drawable this room added directly to itself (via addDrawable()/addImage()/etc.) is removed whenever the game changes to a different room. This mirrors what already happens automatically to every other non-persistent GameEntity. Nothing happens when "changing" to this same room (e.g. Game.resetRoom()), since onCreate() runs again immediately after and typically re-adds everything anyway.

A room that wants some or all of its own drawables to survive a transition can opt out two ways:

• set persistDrawablesAcrossRoomChange = true to keep every directly-added drawable, or
• override onChangeRoom() with custom cleanup logic; overriding replaces this default entirely unless the override calls super.onChangeRoom(newRoom).

Parameters

• gameEngine (Game)
• args (roAssociativeArray, optional, default: "{}")

Properties

• persistDrawablesAcrossRoomChange (boolean) — Whether this room's own directly-added drawables should survive a change to a ' different room, instead of being removed by this class's default onChangeRoom().

Returns

• BGE.Room

ManagedTween

One tween TweenManager is tracking - internal bookkeeping, not part of the public API a consumer touches directly (that's to()/toColorRGB()/toColorRGBA()/cancel()).

Properties

• tweenObj (BGE.Tweens.TweenObject)
• target (object) — The object setAnchor()-style consumers pass to to()/toColorRGB()/toColorRGBA() - ' genuinely arbitrary (a Vector, a Drawable, a plain associative array), so there's no ' narrower type to give it.
• applyMode (TweenApplyMode)
• fieldName (string) — Only set (to the field on target holding the packed color) when applyMode is ' colorRGB/colorRGBA - invalid for applyMode = fields.
• owner (BGE.GameEntity) — The GameEntity to validate every tick via isValidEntity(), or invalid for a tween ' with no automatic cleanup - see TweenManager's class doc.
• onComplete (function) — Called once, with this tween's own target, when it retires - see to()'s doc for why ' it takes targetObj as a parameter instead of relying on m/closure state. invalid if no ' onComplete was given.
• loopMode (BGE.Tweens.TweenLoopMode)
• delayMs (integer)
• delayTimer (BGE.GameTimer) — Only non-invalid while a nonzero delay hasn't elapsed yet.
• originalStart (roAssociativeArray) — The tween's original start/dest fields, before any pingPong ChangeTweenDest() calls ' have swapped tweenObj's own start/dest - pingPong alternates between these two fixed ' endpoints forever, rather than drifting based on whatever the current leg left behind.
• originalDest (roAssociativeArray)
• pingPongForwardNext (boolean)

TweenManager

Ticks every live tween once per frame (see Game.tweenManager) and writes interpolated values straight onto arbitrary target object fields - no manual per-frame HandleTween() bookkeeping required. Wraps BGE.Tweens.CreateTweenObject()/HandleTween() per managed tween rather than reimplementing interpolation.

CircleCollider

Extends: Collider

Collider with the shape of a circle centered at (offset.x, offset.y), with given radius

Parameters

• colliderName (string) — name of this collider
• args (roAssociativeArray, optional, default: "{}") — additional properties (e.g {radius: 10})

Properties

• radius (integer) — Radius of the collider

Returns

• BGE.CircleCollider

Collider

Colliders are attached to GameEntities and when two colliders intersect, it triggers the onCollision() method in the GameEntity

Parameters

• colliderName (string) — the name this collider will be identified by
• args (roAssociativeArray, optional, default: "{}") — additional properties to be added to this collider

Properties

• colliderType (string) — The type of this collider - should be defined in sub classes (eg. "circle", "rectangle")
• name (string) — Name this collider will be identified by
• enabled (boolean) — Does this collider trigger onCollision() ?
• offset (BGE.Math.Vector) — Offset from the GameEntity it is attached to
• memberFlags (integer) — Bitflag for collision detection: this collider is in this group - https://developer.roku.com/en-ca/docs/references/brightscript/interfaces/ifsprite.md#setmemberflagsflags-as-integer-as-void
• collidableFlags (integer) — Bitflag for collision detection: this collider will only collider with colliders in this group - https://developer.roku.com/en-ca/docs/references/brightscript/interfaces/ifsprite.md#setcollidableflagsflags-as-integer-as-void
• compositorObject (roSprite) — Used internal to Game - should not be modified manually
• tagsList (dynamic) — Colliders can be tagged with any number of tags so they can be easily identified (e.g. "enemy", "wall", etc.)

Returns

• BGE.Collider

RectangleCollider

Extends: Collider

Collider with the shape of a rectangle with bottom left at (offset.x, offset.y) - i.e. top left is at (offset.x, offset.y - height) - with given width and height

Parameters

• colliderName (string) — name of this collider
• args (roAssociativeArray, optional, default: "{}") — additional properties (e.g {width: 10, height: 20})

Properties

• width (float)
• height (float)

Returns

• BGE.RectangleCollider

TileCollisionResult

The result of resolveAabbTileCollision(): the corrected position/velocity to apply this frame, and which side of the tile (if any) was resolved. When side = none, both position and velocity are returned exactly as the currentPosition/velocity inputs were - nothing to apply, safe to write back unconditionally either way.

Parameters

• position (BGE.Math.Vector)
• velocity (BGE.Math.Vector)
• side (BGE.TileCollisionSide)

Properties

• position (BGE.Math.Vector)
• velocity (BGE.Math.Vector)
• side (BGE.TileCollisionSide)

Returns

• BGE.TileCollisionResult

FreeFlyCameraController

A reusable free-fly camera control scheme: yaw/pitch relative to the camera's current (roll-adjusted) orientation, forward/back drive, roll, and a ground-plane clamp so driving forward can't cross the ground. Not a GameEntity - a Room (or any owner) constructs one and forwards its own onInput/onUpdate calls to it. Extracted from examples/terrain's original FreeFlyCameraController (issue #148); that example now layers its own room-switching/debug-toggle/hint-text glue on top of this.

Parameters

• camera (BGE.Camera3d) — the camera to drive
• groundPlane (BGE.Math.Plane) — the plane clampAboveGround() keeps the camera above

Properties

• camera (BGE.Camera3d)
• groundPlane (BGE.Math.Plane)
• turnSpeed (float) — radians/sec
• driveSpeed (integer) — radians/sec
• rollSpeed (integer) — units/sec
• pitchSpeed (float) — degrees/sec
• maxDownwardTilt (float) — Bounds the pitch input accumulator to reduce (not eliminate) how close repeated ' pitch input can drive the camera toward Camera3d.getLevelUpVector()'s degenerate ' near-vertical case; under sustained roll+pitch combinations the actual world-space ' angle isn't strictly bounded by this alone.
• minHeightAboveGround (float) — radians (~69 degrees)
• lastInput (BGE.GameInput) — Protected, not private: a subclass adding its own per-frame button handling (e.g. ' examples/terrain's hold-to-toggle-debug) needs to see the same input this frame.

Returns

• BGE.FreeFlyCameraController

AnimatedImage

Extends: Image

Parameters

• owner (GameEntity)
• regions (dynamic)
• args (roAssociativeArray, optional, default: "{}")

Properties

• index (integer) — The current index of image - this would not normally be changed manually, but if you wanted to stop on a specific image in the spritesheet this could be set.
• animationDurationMs (float) — The time in milliseconds for a single cycle through the animation to play.
• animationTween (string) — The name of the tween to use for choosing the next image
• regions (dynamic) — ------------Never To Be Manually Changed----------------- ' These values should never need to be manually changed.
• animationTimer (dynamic)
• tweensReference (dynamic)

Returns

• BGE.AnimatedImage

Drawable

Abstract drawable class - all drawables extend from this

Parameters

• owner (GameEntity)
• args (roAssociativeArray, optional, default: "{}")

Properties

• name (string) — -------------Values That Can Be Changed------------
• offset (dynamic) — The offset of the image from the owner's position
• scale (dynamic) — The image scale
• rotation (dynamic) — Rotation of the image
• banksWithCameraRoll (boolean) — directScaled only (see SceneObjectBillboard.updateCanvasPointsForCameraFacingQuad()): ' directScaled's whole point is to face the camera "by construction" and ignore 3D ' orientation entirely (see DrawableSphere, which forces this mode specifically so a ' sphere never tilts) - so it's screen-aligned and immune to camera roll by default, ' same as every other direct/billboard mode. Setting this true opts a single drawable ' back into visually banking with the camera's roll, the way a real object planted in ' the world would (matching how the ground plane/skybox already rotate with roll), by ' building the quad from the camera's level right/up vectors instead of its ' (roll-cancelling) rolled ones. Has no effect under a Camera2d, or in any other draw ' mode. Changing this after construction on an otherwise-stationary drawable needs an ' explicit invalidateGeometry() call, same as any other in-place shape change - nothing ' auto-detects a plain field write here.
• color (integer) — This can be used to tint the image with the provided color if desired. White makes no change to the original image.
• outlineRGBA (integer) — RGB color for the outline stroke. Leave invalid for no outline at all.
• outlineWidth (integer) — Thickness of the outline stroke, in pixels. Only used when outlineRGBA is set.
• alpha (float) — Change the image alpha (transparency).
• enabled (boolean) — Whether or not the image will be drawn.
• transformationMatrix (dynamic)
• motionChecker (MotionChecker)
• shouldRedraw (boolean)
• geometryVersion (integer) — Bumped every time this drawable's geometry changes in a way the ' position/rotation/scale dirty-checking can't see - a rectangle being resized, for ' instance. SceneObject compares against it to know it has to recompute projected ' geometry even though nothing moved. Bump it via invalidateGeometry().
• anchor (dynamic) — Normalized anchor point (0-1 on each axis) this drawable pivots around, where (0,0) is ' the top left corner (today's default behavior for every existing drawable) and (1,1) is ' the bottom right. Change it via setAnchor(), not by assigning directly - the renderer ' needs to know the geometry changed.
• anchorIsSet (boolean) — Whether setAnchor() has ever been called. Image consults this to decide whether to keep ' honoring whatever pretranslation is already on its region (e.g. from a sprite atlas ' pivot) or to override it - see Image.applyAnchorToRegion().
• owner (GameEntity) — owner GameEntity
• width (float)
• height (float)
• sceneObjects (dynamic)
• drawMode (SceneObjectDrawMode)
• isShaded (boolean)
• ambientBrightness (float) — The darkest an isShaded surface is ever allowed to get, as a 0-1 fraction of its ' own color - a face at a glancing/edge-on angle to the camera would otherwise darken ' all the way to pure black (0), which looks like a rendering glitch (a missing ' texture) rather than shading, especially right as a face rotates into view. Defaults ' to 0.25 (25% grey). Raise it for a flatter, more washed-out look; lower it (down to ' 0) to allow true black.

Returns

• BGE.Drawable

DrawableCircle

Extends: Drawable

Draws a filled circle via the renderer's shared circle texture (see Renderer.getCircleResource()), with an optional outline stroked as a regular polygon inscribed in the circle's own quad - see SceneObjectCircle.

Like DrawableRectangle, the circle's top left (of its bounding square) sits at the drawable's own world position, extending radius * 2 right and down - so it anchors and composes with the rest of the engine the same way every other drawable does. In the oriented/solid/wireFrame 3D draw modes it foreshortens into an ellipse when viewed at an angle, the same as any other billboard (see DrawableSphere for a circle that never does this).

Parameters

• owner (GameEntity)
• radius (float)
• args (roAssociativeArray, optional, default: "{}")

Properties

• radius (float)
• outlineSegments (integer) — Regular-polygon segment count used only for the outline - the fill is a texture ' blit, not a polygon, so this has no effect on fill smoothness.

Returns

• BGE.DrawableCircle

DrawableLine

Extends: Drawable

Parameters

• owner (GameEntity)
• startPos (BGE.Math.Vector)
• endPos (BGE.Math.Vector)
• args (roAssociativeArray, optional, default: "{}")

Properties

• startPosition (BGE.Math.Vector)
• endPosition (BGE.Math.Vector)

Returns

• BGE.DrawableLine

DrawableParallaxLayer

Extends: Drawable

Scrolls a tiled/non-tiled bitmap layer at a configurable per-axis fraction of the camera's movement (parallax). {1,1} is the default and behaves exactly like an ordinary drawable; {0,0} pins the layer to the camera; 0 < factor < 1 is a background layer that drifts slower than the world; factor > 1 is a foreground layer that scrolls faster. See SceneObjectParallaxLayer for the actual per-frame math.

Combines with the owning entity's position/offset exactly like every other Drawable - there is no special "independent of owner" positioning mode. Attach this to a dedicated static entity if you want a fixed background anchor.

This is also the right tool for a 2D sky-like background (issue #145): BGE.Skybox is a yaw/pitch-driven cylindrical panorama, Camera3d-only. For a Camera2d scene, a wide region with a small parallaxFactor (e.g. {x: 0.1, y: 0.1}) gives the same "shifts slowly with the camera" feel without needing any dedicated skybox-for-2D mechanism.

Parameters

• owner (BGE.GameEntity)
• region (roRegion)
• args (roAssociativeArray, optional, default: "{}")

Properties

• region (roRegion) — The bitmap tile to scroll/repeat.
• parallaxFactor (BGE.Math.Vector) — Per-axis fraction of camera movement this layer scrolls at. See the class doc for ' what different values mean.
• repeatX (boolean) — Whether this layer tiles to cover the canvas along each axis. repeatX defaults true ' (the common side-scroller case); repeatY defaults false.
• repeatY (boolean)

Returns

• BGE.DrawableParallaxLayer

ParticleRecord

One live particle spawned by a DrawableParticles emitter.

Properties

• position (BGE.Math.Vector)
• velocity (BGE.Math.Vector)
• age (float)
• lifetime (float)
• startColor (integer)
• endColor (integer)
• startAlpha (float)
• endAlpha (float)
• startSize (float)
• endSize (float)
• rotation (float)

DrawableParticles

Extends: Drawable

Emits and simulates lightweight particles (lines, rectangles, or images) with randomized velocity, constant acceleration, and lifetime-driven fade/color/size interpolation. Draws through a single SceneObjectParticle per emitter rather than one SceneObject per particle, so spawning/expiring particles never touches Renderer.addSceneObject/removeSceneObject - see specs/2026-08-18-particle-system-design.md for why that matters for depth-sort performance.

Parameters

• owner (GameEntity)
• shape (ParticleShape)
• args (roAssociativeArray, optional, default: "{}")

Properties

• shape (ParticleShape) — Shape drawn for every particle. See BGE.ParticleShape.
• image (dynamic) — Bitmap or region drawn for each particle when shape = BGE.ParticleShape.Image. ' Ignored for other shapes.
• cellWidth (integer) — Width/height (pixels) of one animation cell if image is a sprite sheet, the ' BGE.ParticleShape.Image shape only. When both are >0, image is sliced into a ' row-major grid of frames and ' each particle's current frame is driven by its own age/lifetime - a fade-style sheet ' (bright to transparent) reproduces its own fade this way, with no extra frame-rate ' config needed. 0 (the default) means image is drawn as a single static bitmap, ' unchanged from previous behavior.
• cellHeight (integer)
• regions (dynamic)
• spawnRate (float) — Particles spawned per second while emitting (see start()/stop()).
• lifetime (float) — Base lifetime in seconds each particle survives, randomized by +/- lifetimeSpread.
• lifetimeSpread (float)
• velocity (BGE.Math.Vector) — Base emission velocity (world units/second) shared by every particle before ' randomization is applied.
• velocitySpreadAngleDegrees (float) — Randomizes each particle's velocity direction by +/- this many degrees around ' velocity.
• velocitySpreadMagnitude (float) — Randomizes each particle's velocity magnitude by +/- this amount. If velocity ' is zero, particles instead radiate outward in a uniformly random direction at this ' magnitude - this is what makes a stationary emitter usable for an explosion/burst ' effect.
• acceleration (BGE.Math.Vector) — Constant acceleration (world units/second^2) applied to every particle every ' frame, e.g. gravity.
• startColor (integer) — Packed RGB (0xRRGGBB) color interpolated over each particle's lifetime.
• endColor (integer)
• startAlpha (float) — Alpha (0-255) interpolated over each particle's lifetime.
• endAlpha (float)
• startSize (float) — Size interpolated over each particle's lifetime - a line's length, a rectangle's ' side length, or an image's scale multiplier (1.0 = the image's native size), ' depending on shape.
• endSize (float)
• rotationSpeed (float) — Degrees/second of rotation applied to each particle. Only used when ' shape = BGE.ParticleShape.Image - see the design spec for why line/rectangle ' particles never rotate.
• maxParticles (integer) — Hard cap on live particles. Once reached, further spawns (continuous emission or ' burst()) are silently dropped until a slot frees up via natural expiry.
• particles (dynamic) — Live particle records. See BGE.ParticleRecord.
• emitting (boolean)
• spawnAccumulator (float)
• timer (dynamic)

Returns

• BGE.DrawableParticles

DrawablePlane

Extends: BGE.Image

Used to draw a "infinite" plane in 3d space Ideally used for a ground or floor

Parameters

• owner (BGE.GameEntity)
• region (roRegion) — the texture tile to use for tiledImage/staticImage
• plane (BGE.Math.Plane)
• args (object, optional, default: "{}") — pass fillMode here to select a mode other than the

Properties

• plane (BGE.Math.Plane)
• fillMode (PlaneFillMode)

Returns

• BGE.DrawablePlane

DrawablePolygon

Extends: Drawable

Parameters

• owner (GameEntity)
• points (dynamic, optional, default: "[]")
• args (roAssociativeArray, optional, default: "{}")

Properties

• points (dynamic) — the set of points defining a convex polygon

Returns

• BGE.DrawablePolygon

DrawableRectangle

Extends: Drawable

Draws a rectangle, filled and/or outlined.

The rectangle's top left corner sits at the drawable's own world position (its offset transformed by the owning entity), extending width to the right and height downwards on screen - the same anchoring an Image uses, so the two are interchangeable.

In the direct (billboard) draw modes - which is what a 2D game gets, since a Camera2d resolves matchCamera to directToCamera - this is a plain axis-aligned rectangle. In the oriented/solid/wireFrame draw modes it becomes a quad that rotates and foreshortens in 3D like any other billboard (see examples/3d's RectanglesRoom).

Set color for the fill and outlineRGBA for the outline (both packed RGB, no alpha byte - alpha is separate). Leaving outlineRGBA unset means no outline at all; set filled = false for an outline-only rectangle.

Parameters

• owner (GameEntity)
• width (float)
• height (float)
• args (roAssociativeArray, optional, default: "{}")

Properties

• filled (boolean) — Whether the rectangle's interior is filled with color. Set false for an outline-only ' rectangle, which needs outlineRGBA set too or nothing is drawn at all.

Returns

• BGE.DrawableRectangle

DrawableSkybox

Extends: BGE.Image

Draws a cylindrical panorama that tracks the camera's yaw/pitch (and, via a render-then-rotate composite, roll), giving a Camera3d scene a sky/horizon background instead of a flat fill. See SceneObjectSkybox for the draw algorithm.

Parameters

• owner (BGE.GameEntity)
• region (roRegion) — a cylindrical panorama texture
• args (object, optional, default: "{}") — pass degreesPerFullWidth/verticalDegreesCovered here to override the defaults

Properties

• degreesPerFullWidth (float) — How many degrees of camera yaw the texture's full width covers. Default wraps a ' full circle - the horizontal texture offset loops seamlessly at any yaw.
• verticalDegreesCovered (float) — How many degrees of camera pitch the texture's full height covers, centered on ' the texture's vertical middle (pitch 0 = horizon). Looking past this range shows ' the renderer's background, same as a finite ground decal running out.

Returns

• BGE.DrawableSkybox

DrawableSphere

Extends: DrawableCircle

A circle that always looks the same from any camera angle, because a sphere looks the same from every direction. Everything about the fill/outline is identical to DrawableCircle (which this extends unchanged, including addToScene) - the only difference is forcing drawMode to directScaled in the constructor, which billboards (never rotates/foreshortens) while still scaling with camera distance in 3D. See SceneObject.getActualDrawMode(): it only resolves the matchCamera default through the camera, so any other explicit drawMode - this one included - is used as-is.

Deliberately does NOT re-append args after forcing drawMode (DrawableCircle's own constructor already applied them once) - a caller passing {drawMode: ...} here should not be able to silently defeat a DrawableSphere's entire reason for existing. A caller who genuinely wants a different draw mode can still assign sphere.drawMode = ... directly after construction.

Parameters

• owner (GameEntity)
• radius (float)
• args (roAssociativeArray, optional, default: "{}")

Returns

• BGE.DrawableSphere

MIN_TEXT_REGION_SIZE

Default: 256

DrawableText

Extends: Drawable

Class to draw text

Parameters

• owner (GameEntity)
• text (string, optional, default: "\"\"")
• font (roFont, optional, default: "invalid")
• args (roAssociativeArray, optional, default: "{}")

Properties

• text (string) — The text to write on the screen
• font (roFont) — The Font object to use ( get this from the font registry)
• alignment (BGE.UI.HorizAlignment) — The Horizontal alignment for the text
• textColor (integer) — The color the text is drawn in
• lastTextValue (string)
• lastTextColor (integer)
• tempCanvas (roBitmap)
• tempRegion (roRegion)
• lastAlignment (BGE.UI.HorizAlignment)

Returns

• BGE.DrawableText

Image

Extends: BGE.Drawable

Used to draw a bitmap image to the screen

Parameters

• owner (BGE.GameEntity)
• region (roRegion)
• args (roAssociativeArray, optional, default: "{}")

Properties

• regionId (string) — An optional unique name for the region, used for caching image data. If not provided, the name of the drawable will be used as the region name.
• region (roRegion) — ------------Never To Be Manually Changed----------------- ' These values should never need to be manually changed.

Returns

• BGE.Image

Model3dTexture

Parameters

• srcRegionWithId (BGE.RendererHelpers.RegionWithId)
• points (dynamic)

Properties

• srcRegionWithId (BGE.RendererHelpers.RegionWithId)
• points (dynamic)

Returns

• BGE.Model3dTexture

Model3dLoadOptions

The options accepted by Game.load3dModel() for an .obj model's texture.

Properties

• texturePath (string)

Model3dFace

Properties

• vertices (dynamic)
• normal (BGE.Math.Vector)
• Texture (Model3dTexture)
• brightness (float)
• priority (float)
• color (integer)
• faceIndex (integer) — This face's position in the model's own, never-reordered face list - set on the ' per-frame canvas-space copy (SceneObjectModel.updateCanvasPosition) so a face keeps ' a stable identity across frames even though modelCanvasFaces itself is filtered ' (backface culling) and re-sorted (depth) every frame. Used to key SceneObjectModel's ' per-face raster reuse cache - see issue #163.

Model3d

Parameters

• faces (dynamic)

Properties

• faces (dynamic)
• name (string)
• texturePath (string)

Returns

• BGE.Model3d

DrawableModel

Extends: Drawable

Parameters

• owner (BGE.GameEntity)
• model (Model3d)
• args (roAssociativeArray, optional, default: "{}")

Properties

• model (Model3d)
• maxStaleFrames (integer) — How many consecutive frames a face may reuse its own last-rendered raster ' (repositioned, content unchanged) before a real redraw, when the model moves - ' see SceneObjectModel's per-face reuse (issue #163). 0 disables reuse entirely ' (always redraw every visible face every frame); higher values trade a larger ' bound on visual staleness (a stale frame shows a face at its last-redrawn ' orientation, correctly positioned) for fewer expensive per-face redraws.
• maxFaceDriftDistance (float) — How far (in canvas pixels, Manhattan distance - same measure the engine's other ' temp-bitmap-reuse tolerance checks use) any one of a face's 3 vertices may drift ' from where it was at its last real redraw before reuse is refused even if still ' within maxStaleFrames. Lower this if reused frames look visibly wrong (a ' fast-rotating or fast-approaching model can drift a lot in a single frame); raise ' it to permit more reuse at the cost of more visible staleness.

Returns

• BGE.DrawableModel

AnimationFrameDescription

Properties

• startFrame (integer)
• frameCount (integer)

SpriteAnimation

CReate a new SpriteAnimation

Parameters

• name (string) — Name of the animation
• frameList (dynamic) — Wither an array of cell indexes, or an object {startFrame, frameCount}
• frameRate (integer) — Frames per second the animation should play at
• playMode (SpritePlayMode, optional, default: "SpritePlayMode.Loop") — Play mode for the sprite: loop, forward, reverse, pingpong

Properties

• name (string) — Name of the animation
• frameRate (integer) — Frames per second the animation should play at
• frameList (dynamic) — Array of the regions of the each cell of this animation
• playMode (SpritePlayMode) — Play mode for the sprite: loop, forward, reverse, pingpong

Returns

• BGE.SpriteAnimation

Sprite

Extends: AnimatedImage

Parameters

• owner (GameEntity)
• spriteSheet (ifDraw2d)
• cellWidth (integer)
• cellHeight (integer)
• args (roAssociativeArray, optional, default: "{}")

Properties

• spriteSheet (ifDraw2d) — roBitmap to pick cells from
• cellWidth (integer) — Width of each animation cell in the sprite image in pixels
• cellHeight (integer) — Height of each animation cell in the sprite image in pixels
• animations (roAssociativeArray) — Lookup map of animation name -> SpriteAnimation object
• activeAnimation (SpriteAnimation) — The current animation being played

Returns

• BGE.Sprite

RoomChangeInfo

Properties

• room (Room)
• args (roAssociativeArray)

GarbageCollectionInfo

Properties

• count (integer)
• orphaned (integer)
• root (integer)

DebugColors

Properties

• colliders (integer)
• safe_action_zone (integer)
• safe_title_zone (integer)

EntityWithId

Properties

• id (dynamic)

PositionXY

Properties

• x (float)
• y (float)

SizeWH

Properties

• width (float)
• height (float)

RendererResourceSize

Default: 400

TriangleDrawThreshold

Default: 4

TriangleQuickDrawThreshold

Default: 64

TriangleQuickDrawThresholdForSimulator

Default: 32

DEPTH_TIE_EPSILON

Default: 0.5

LevelOfDetailOptions

Properties

• levelOffset (integer)
• levelOfDetail (integer)

RendererOptions

Properties

• useBitmapPooling (boolean)

Renderer

Wrapper for Draw2D calls, so that we can keep track of how much is being drawn per frame

Parameters

• draw2d (ifDraw2d)
• mainGame (BGE.Game, optional, default: "invalid")
• cam (BGE.Camera, optional, default: "invalid")
• options (RendererOptions, optional, default: "{useBitmapPooling: true}")

Properties

• nextSceneObjectId (integer)
• minimumFrameRateTarget (integer) — Frame rate target - the game will reduce quality if this target is not met
• onlyDrawWhenInFrame (boolean)
• drawDebugCells (boolean)
• drawDebugTrianglePoints (boolean)
• computeOverlapClusters (boolean) — Whether drawScene() computes overlap clusters (BGE.DepthSort.groupIntoClusters) ' this frame. Off by default: nothing in the engine's actual draw path consumes ' getOverlapClusters() yet (that's a future follow-up - see #59's Plan 2), the cost ' of the O(n^2)-ish broad phase across every scene object hasn't been measured ' on-device, and the design's own requirement is that a solo (non-overlapping) ' scene sees zero regression from today's cost. Set this true to opt in (see ' examples/depthsort's ClusterVisualizerRoom, which visualizes the result) - ' TieBreakRoom deliberately does NOT opt in, since it only demonstrates the ' tie-break fix, not clustering. ' ' Known limitation: see drawPendingClusterPrimitives()'s doc comment for a ' disclosed draw-order gap affecting objects excluded from cluster candidacy ' entirely (lines, planes, or anything else with a degenerate bounding-point set).
• camera (Camera)
• triangleCache (dynamic)
• frameCount (integer)
• bmpPool (BGE.ScratchBitmapPool)
• game (BGE.Game)
• name (string)
• statsString (string)
• resources (dynamic)
• dummyScreen (roScreen)

Returns

• BGE.Renderer

DrawPinnedCornersOptions

Properties

• splitIntoFour (boolean)
• alwaysUseTLtoBR (boolean)

ScratchBitmap

Parameters

• id (string)
• w (integer)
• h (integer)

Properties

• bitmap (roBitmap)
• id (string)

Returns

• BGE.ScratchBitmap

ScratchRegion

Parameters

• region (roRegion)
• scratchBmp (ScratchBitmap)

Properties

• region (roRegion)
• scratchBmp (ScratchBitmap)
• scale (dynamic)

Returns

• BGE.ScratchRegion

ScratchBitmapPool

Parameters

• doPooling (boolean, optional, default: true)
• initialCount (integer, optional, default: 10)
• forcePoolingRegardlessOfDevice (boolean, optional, default: false)

Returns

• BGE.ScratchBitmapPool

TriangleCacheEntry

Parameters

• triangle (BGE.RendererHelpers.TriangleBitmap)

Properties

• triangle (BGE.RendererHelpers.TriangleBitmap)
• timeLastUsed (integer)

Returns

• BGE.TriangleCacheEntry

TriangleCache

Parameters

• cacheKeepSeconds (integer, optional, default: 60)

Returns

• BGE.TriangleCache

Camera

Properties

• orientation (dynamic) — A vector pointed in the direction of the camera
• position (BGE.Math.Vector)
• motionChecker (MotionChecker)
• frameSize (BGE.Math.Vector)
• projectionVersion (integer) — Bumped whenever something about the camera's projection - as opposed to its ' position or orientation - changes. MotionChecker watches only position and ' orientation, so without this a frame-size or field-of-view change is invisible to ' every dirty check in the renderer, and a stationary culled object stays culled ' through a projection change that should have brought it back into view.
• zoom (float) — TODO: do something with zoom!
• worldToCamera (dynamic)
• name (string)

Returns

• BGE.Camera

Camera2d

Extends: Camera

Properties

• top (float)
• bottom (float)
• right (float)
• left (float)
• near (float)
• far (float)
• name (string)

CameraFrustumNormals

Properties

• top (BGE.Math.Vector)
• bottom (BGE.Math.Vector)
• left (BGE.Math.Vector)
• right (BGE.Math.Vector)
• near (BGE.Math.Vector)

CameraFrustumRays

Properties

• topLeft (BGE.Math.Ray)
• topRight (BGE.Math.Ray)
• bottomLeft (BGE.Math.Ray)
• bottomRight (BGE.Math.Ray)

Camera3d

Extends: Camera

Properties

• fieldOfViewDegrees (float)
• rollDegrees (float) — Rotation about the camera's own forward/view axis, in degrees. Positive = right ' side down (aviation convention). getUpVector()/getRightVector() apply this on ' top of the "level" vectors - see getLevelUpVector()/getLevelRightVector().
• maxDrawDistance (float) — How far (world units) in front of the camera a point can be and still be ' considered visible - applied everywhere isInView() is checked, including ' SceneObjectPlane's far-render-distance and tiled-texture cache sizing (issue #124). ' Silently capped per-device (see getMaxDrawDistanceDeviceCap()), re-applied every ' frame via checkMovement() - reading this back may show the capped value, not what ' was set.
• frustumNormals (CameraFrustumNormals)
• frustrumConvergence (BGE.Math.Vector)
• frustumRays (CameraFrustumRays)
• name (string)

MAX_DRAW_MODE

Default: 8

SceneObject

Parameters

• name (string)
• drawableObj (Drawable)
• objType (SceneObjectType)

Properties

• name (string)
• id (string) — Unique Id
• clusterMemberCount (integer) — How many members are in this object's overlap cluster this frame (see ' Renderer.getOverlapClusters()) - 1 means solo (the common case, and the only ' value possible when Renderer.computeOverlapClusters is false). Set once per frame ' by Renderer, right after it computes clusters - not meant to be set directly by ' game code.
• drawable (Drawable)
• type (SceneObjectType)
• negDistanceFromCamera (float) — The negative distance from the camera, used for depth sorting. Measured from ' getPositionForCameraDistance()'s point, so it's unreliable as an "is this behind ' the camera" check for a type whose position is a fixed anchor rather than ' something that tracks actual visibility (see SceneObjectPlane and Renderer.drawScene()'s ' plane-drawing loop, which deliberately doesn't gate on this for that reason).
• worldPosition (dynamic)
• transformationMatrix (dynamic) — The Current Transformation Matrix
• lastFrameWasCulled (boolean) — Whether the last frame's draw was skipped because the frustum rejected this object, ' or because a subsequent draw attempt failed deterministically (see ' isDeterministicDrawFailure()). Both latch: nothing moved, so re-running the check ' would give the same answer, and skipping it is what makes a static off-screen object ' free. A draw that was attempted and failed for a reason that could change without ' anything moving (e.g. a transient scratch-bitmap-pool exhaustion) must not latch - ' findCanvasPosition() and performDraw() both already retry on the following frame, ' and treating that kind of failure as a cull is what made one bad frame permanent. ' See issue #48 (the original cull-latch fix) and issue #73 (extending it to ' deterministic draw failures, like a backface or an off-canvas rejection, which used ' to re-run the full frustum check every single frame with no latch at all).
• lastFrameDidDraw (boolean) — Whether the last frame's draw actually happened. Distinct from lastFrameWasCulled ' because a frame has four possible outcomes, not two: drew, was culled by the ' frustum, entered the draw path and failed deterministically, or entered the draw ' path and failed transiently. Only the first kind of failure may latch (folded into ' lastFrameWasCulled); a transient failure must retry; and reaching a failure at all is ' what makes the frustum check reachable, which is what puts an object into the culled ' state in the first place.
• hasValidWorldPosition (boolean)
• hasValidCanvasPosition (boolean)
• wasEnabledLastFrame (boolean)
• isFirstFrameSinceEnabled (boolean)
• isLowEndDevice (boolean)
• lastGeometryVersion (integer) — The drawable's geometryVersion as of the last completed draw - see geometryChanged()
• lastDrawMode (integer) — The draw mode this object last drew in - see drawModeChanged()
• lastProjectionVersion (integer) — The camera's projectionVersion as of the last draw - see projectionChanged()
• depthChangedThisFrame (boolean) — True for exactly the frame this object's negDistanceFromCamera was recomputed - ' Renderer.updateSceneObjects() ORs these together to decide whether the whole ' scene needs a re-sort this frame, instead of always resorting even when nothing ' that could change draw order actually happened.
• stableSortKey (float) — What Renderer actually sorts by - negDistanceFromCamera quantized into ' DEPTH_TIE_EPSILON-wide buckets, combined with this object's sort position from ' the previous frame, so two objects whose depths quantize into the same bucket ' keep their previous relative order instead of swapping from floating-point jitter ' alone. This is bucket quantization, not a true epsilon-tolerance comparison - ' two depths closer together than the epsilon can still straddle a bucket boundary ' and swap order. A genuine depth crossover still swaps order correctly, since the ' quantized depth term dominates the combined key.

Returns

• BGE.SceneObject

TransformTempBitmapDetails

Properties

• origin (BGE.Math.Vector)
• rotation (float)
• scaleX (float)
• scaleY (float)

TempBitmapDrawResult

Properties

• worked (boolean)
• didFastDraw (boolean)

SceneObjectBillboard

Extends: SceneObject

Parameters

• name (string)
• drawableObj (Drawable)
• objType (SceneObjectType)

Properties

• worldPoints (BGE.Math.CornerPoints)
• canvasPoints (BGE.Math.CornerPoints)
• canvasPosition (BGE.Math.Vector)
• useTempBitmapMap (dynamic)
• usedTransformedFastDrawLastFrame (boolean) — Whether the most recent oriented/solid draw took the cheap rotate+scale fast path ' (drawRegionAsRotatedQuad, below) instead of the exact drawPinnedCorners warp - see ' canUseTransformedFastDraw() below. Exposed read-only for tests/telemetry via ' usedTransformedFastDraw(). Shared by every single-quad billboard subclass that opts ' into the fast-draw check (SceneObjectCircle/#105, SceneObjectImage+SceneObjectText/#163).

Returns

• BGE.SceneObjectBillboard

SceneObjectCircle

Extends: SceneObjectBillboard

Draws a DrawableCircle. The fill is inherited, unmodified SceneObjectBillboard machinery (pinned-corners texture warp, tinting, temp-bitmap caching) blitting the renderer's shared circle resource (Renderer.getCircleResource(), built lazily on first use) - exactly like SceneObjectImage, just with a fixed texture instead of one supplied by the drawable. Only the outline differs from a plain Image: it's stroked as an N-gon inscribed in this object's own already-transformed canvasPoints quad (via the generic getOutlineCanvasPoints() hook), which is far cheaper than rasterizing the fill itself as a many-sided polygon and needs no new Renderer draw method.

Parameters

• name (string)
• drawableObj (DrawableCircle)

Properties

• drawable (DrawableCircle)

Returns

• BGE.SceneObjectCircle

SceneObjectImage

Extends: SceneObjectBillboard

Parameters

• name (string)
• drawableObj (Image)

Properties

• drawable (Image)
• frameNumber (integer)

Returns

• BGE.SceneObjectImage

SceneObjectLine

Extends: SceneObject

Parameters

• name (string)
• drawableObj (DrawableLine)

Properties

• drawable (DrawableLine)

Returns

• BGE.SceneObjectLine

SceneObjectModel

Extends: SceneObjectBillboard

Parameters

• name (string)
• drawableObj (DrawableModel)

Properties

• drawable (DrawableModel)

Returns

• BGE.SceneObjectModel

SceneObjectParallaxLayer

Extends: SceneObject

Parameters

• name (string)
• drawableObj (DrawableParallaxLayer)

Properties

• drawable (DrawableParallaxLayer)

Returns

• BGE.SceneObjectParallaxLayer

SceneObjectParticle

Extends: SceneObject

Draws an entire DrawableParticles emitter's live particles with a single SceneObject

• not one SceneObject per particle. See specs/2026-08-18-particle-system-design.md ("Why one SceneObjectParticle per emitter, not per particle") for why: per-particle SceneObjects would call Renderer.addSceneObject/removeSceneObject every frame during continuous emission, permanently defeating the depth-sort skip-optimization for the whole renderer.

Parameters

• name (string)
• drawableObj (DrawableParticles)

Properties

• drawable (DrawableParticles)

Returns

• BGE.SceneObjectParticle

PerspectiveCalculationResult

Properties

• actual (BGE.Math.CornerPoints)
• mapped (BGE.Math.CornerPoints)

PerspectiveSlice

Properties

• srcWidth (float)
• srcHeight (float)
• srcTopLeft (BGE.PositionXY)
• scaleX (float)

SCENE_OBJECT_PLANE_NEAR_DISTANCE

Default: 0

SCENE_OBJECT_PLANE_SLICE_COUNT

Default: 50

SCENE_OBJECT_PLANE_TILES_PER_AXIS_WARNING_THRESHOLD

Above this, the supertexture build's tilesPerAxis^2 blit count is worth a runtime warning (63x63 = ~4k blits) - see buildSuperTextureIfNeeded().

Default: 63

SceneObjectPlane

Extends: SceneObject

Parameters

• name (string)
• drawableObj (DrawablePlane)

Properties

• drawable (DrawablePlane)

Returns

• BGE.SceneObjectPlane

SceneObjectPolygon

Extends: SceneObjectBillboard

Parameters

• name (string)
• drawableObj (DrawablePolygon)

Properties

• drawable (DrawablePolygon)

Returns

• BGE.SceneObjectPolygon

SceneObjectRectangle

Extends: SceneObjectBillboard

Draws a DrawableRectangle. Extends SceneObjectBillboard, so a rectangle orients and foreshortens in 3D in the oriented draw modes and stays screen-aligned in the direct ones, exactly like an image does.

Unlike an image, though, a rectangle has no texture to sample: it's a single flat color. So it never needs the inherited pinned-corners path - filling the projected quad produces identical pixels for far less work, and DrawableRectangle never has to hold a bitmap of its own. This is how SceneObjectPolygon draws, for the same reason.

It does still cache that fill into a temp bitmap in the oriented draw modes, exactly like a polygon: filling a rotated quad means rasterizing two triangles through scratch bitmaps, which is far too expensive to repeat every frame for an object that hasn't moved. In the direct (billboard) draw modes there's nothing worth caching - the draw is already a single DrawRect - so those skip the temp bitmap entirely.

Parameters

• name (string)
• drawableObj (DrawableRectangle)

Properties

• drawable (DrawableRectangle)

Returns

• BGE.SceneObjectRectangle

SceneObjectSkybox

Extends: SceneObject

Parameters

• name (string)
• drawableObj (DrawableSkybox)

Properties

• drawable (DrawableSkybox)

Returns

• BGE.SceneObjectSkybox

SceneObjectText

Extends: SceneObjectBillboard

Parameters

• name (string)
• drawableObj (DrawableText)

Properties

• drawable (DrawableText)

Returns

• BGE.SceneObjectText

CountdownTimer

A simple dt-driven countdown: start it with a duration, tick() it once per frame (typically from GameEntity.onUpdate()'s own dt), and check isActive() to see if time remains. Replaces a hand-rolled "duration constant + live timer field + manual decrement-and-clamp block" pattern - the same shape used for coyote time, jump/input buffering, invulnerability windows, hit-flash timers, cooldowns, etc.

This is not the same as BGE.GameTimer, which wraps a wall-clock roTimespan (mark()/totalMilliseconds()) for measuring real elapsed time - CountdownTimer is purely dt-driven and has no idea what real time it is.

Returns

• BGE.CountdownTimer

MotionChecker

Properties

• previousTransform (dynamic)
• movedLastFrame (boolean)

SomeConst

Default: 23

TagList

Returns

• BGE.TagList