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

Properties

name (string) — Constant - name of this Entity
id (string | dynamic) — Constant - Unique Id
game (Game)
enabled (boolean) — Is this GameEntity enabled
persistent (boolean) — Does this entity persist across scene changes?
pauseable (boolean) — When the game is paused, does this entity pause too?
isStatic (boolean) — Marks this entity's drawables as static geometry (walls, props) that never moves
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 (Array.<Drawable>) — 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
dyingTimer (GameTimer) — Timer/delay backing invalidateAfter()'s grace period. Public (rather than
dyingDelayMs (integer)

Constructor

new GameEntity(
game: Game,
gameEngine: Game,
args?: roAssociativeArray,
): GameEntity

Creates a new GameEntity

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

Instance Methods

`isValid(): boolean`

Is this still a valid entity?

Returns

boolean

`isOnScreen(): boolean`

Whether this entity had at least one drawable actually drawn (not culled by the camera frustum) as of the last frame. True for an entity with no drawables at all, since there's no geometry to say it's off-screen - a purely logical entity (a spawner, a game-state controller) shouldn't get silently treated as "off-screen" by code using this to skip work.

This is a signal only - nothing in the engine uses it to skip an entity's own onUpdate()/collision checks automatically, since a culled entity can still be relevant to gameplay (e.g. approaching from off-screen). It's meant for game code that wants to opt in to skipping its own expensive, purely-visual per-frame work for an entity that isn't currently visible. See issue #75.

Returns

boolean

`invalidate(): void`

Marks this entity as invalid, so it will be cleared/destroyed at the end of the frame

Returns

void

`invalidateAfter(delayMs: integer): void`

Marks this entity as dying: it stays fully alive, valid, and processed normally (still updates, still draws, still collides) for delayMs milliseconds, then invalidate() is called automatically. Use this instead of calling invalidate() directly when an entity needs to trigger a one-shot effect (e.g. a particle burst) that should have a chance to actually render before the entity disappears - invalidate() removes all of this entity's drawables from the scene immediately, which would cut off that effect on its very first frame.

Sets isDying = true immediately, so other game code (e.g. a collision handler) can check it to avoid re-triggering logic on an entity that's already in its death sequence. Colliders are NOT removed during the grace period - a dying entity can still register collisions until it's actually invalidated, so guard on isDying at the very top of onCollision() (before any score/sound/effect side effect) to avoid double-firing.

Parameters

delayMs (integer) — how long to wait, in milliseconds, before this entity is actually invalidated

Returns

void

`checkDyingTimeout(): void`

Called once per frame (from Game's entity-processing loop) for every valid entity, regardless of whether it overrides onUpdate() - checks whether an invalidateAfter() grace period has elapsed and, if so, calls the real invalidate(). A no-op for an entity that isn't dying.

Returns

void

`onCreate(args: roAssociativeArray): void`

Method to be called when this entity is added to a Game. Override in subclass

Parameters

args (roAssociativeArray)

Returns

void

`onUpdate(deltaTime: float): void`

Method for handling any updates based on time since previous frame

Parameters

deltaTime (float) — milliseconds since last frame

Returns

void

`onCollision( myCollider: Collider, otherCollider: Collider, otherEntity: GameEntity, ): void`

Called every frame, for each pair of colliders that overlap that frame - not just when an overlap starts (use onCollisionEnter() for that).

Colliders that only touch edge to edge don't overlap, so they don't collide. If you resolve a collision by moving this entity so it sits exactly against the other collider (e.g. snapping a player's feet to the top of the ground), it won't collide again next frame unless it moves back into it. So don't reset a "grounded"-style flag every frame and wait for onCollision() to set it again. Either keep applying gravity while grounded, so the player sinks slightly back into the ground each frame, or check for ground some other way, e.g. a thin feet collider that reaches a pixel below the player.

Parameters

myCollider (Collider) — the collider of this entity that collided
otherCollider (Collider) — the collider of the other entity in the collision
otherEntity (GameEntity) — the entity that owns the other collider

Returns

void

`onCollisionEnter( myCollider: Collider, otherCollider: Collider, otherEntity: GameEntity, ): void`

Called once when one of this entity's colliders starts overlapping another collider, just before that frame's onCollision(). Use it for one-shot reactions - a trigger zone, a pickup, taking a hit - instead of tracking "was I already touching this?" yourself.

Parameters

myCollider (Collider) — the collider of this entity that started colliding
otherCollider (Collider) — the collider of the other entity
otherEntity (GameEntity) — the entity that owns the other collider

Returns

void

`onCollisionExit( myCollider: Collider, otherCollider: Collider, otherEntity: GameEntity, ): void`

Called once when one of this entity's colliders stops overlapping a collider it overlapped last frame - including when the other entity was destroyed or changed scene, in which case otherCollider and otherEntity are invalid. Also called for every current overlap when myCollider is disabled.

Parameters

myCollider (Collider) — the collider of this entity that stopped colliding
otherCollider (Collider) — the collider of the other entity, or invalid if it's gone
otherEntity (GameEntity) — the entity that owns the other collider, or invalid if it's gone

Returns

void

`onDrawBegin( Renderer: renderer, gameRenderer: Renderer, uiRenderer: Renderer, ): void`

Method called each frame before drawing any images of this entity

Parameters

Renderer (renderer) — the Renderer images will be drawn to
gameRenderer (Renderer)
uiRenderer (Renderer)

Returns

void

`onDrawEnd( canvas: Renderer, gameRenderer: Renderer, uiRenderer: Renderer, ): void`

Method called each frame after drawing all images of this entity

Parameters

canvas (Renderer) — the Renderer images were drawn to
gameRenderer (Renderer)
uiRenderer (Renderer)

Returns

void

`onInput(input: GameInput): void`

Method to process input per frame

Parameters

input (GameInput) — GameInput object for the last frame

Returns

void

`onControls(controls: BGE.Controller.ControlMap): void`

Called once per frame, before onUpdate(), with the game's ControlMap - the same object as m.game.controls, just without the boilerplate of reaching through m.game each frame.

IMPORTANT: only called when the game has bound at least one action/axis via ControlMap.bindAction()/bindAxis() (ControlMap.hasBindings()). A game that never binds anything never gets this callback at all - not with an empty ControlMap, not with an error, just silently never called. This preserves ControlMap's zero-cost guarantee: binding nothing costs nothing, including this dispatch. If your entity overrides onControls() but never sees it fire, check that something in the game calls bindAction/bindAxis.

Parameters

controls (BGE.Controller.ControlMap)

Returns

void

`onECPKeyboard(char: integer): void`

Method to process an ECP keyboard event

Parameters

char (integer)

Returns

void

See:
- https://developer.roku.com/en-ca/docs/developer-program/debugging/external-control-api.md

`onECPInput(data: roInputEvent): void`

Method to process an External Control Protocol event

Parameters

data (roInputEvent)

Returns

void

See:
- https://developer.roku.com/en-ca/docs/references/brightscript/events/roinputevent.md

`onAudioEvent(msg: roAudioPlayerEvent): void`

Method to handle audio events

Parameters

msg (roAudioPlayerEvent) — roAudioPlayerEvent

Returns

void

See:
- https://developer.roku.com/en-ca/docs/references/brightscript/events/roaudioplayerevent.md

`onPause(): void`

Called when the game pauses

Returns

void

`onResume(pauseTimeMs: integer): void`

Called when the game unpauses

Parameters

pauseTimeMs (integer) — The number of milliseconds the game was paused

Returns

void

`onUrlEvent(msg: roUrlEvent): void`

Called on url event

Parameters

msg (roUrlEvent) — roUrlEvent

Returns

void

See:
- https://developer.roku.com/en-ca/docs/references/brightscript/events/rourlevent.md

`onGameEvent(eventName: string, data: roAssociativeArray): void`

General purpose event handler for in-game events.

Parameters

eventName (string) — Event name that describes the event type
data (roAssociativeArray) — Any extra data to go along with the event

Returns

void

`onQualityChanged(level: integer): void`

Called when the game's render quality level changes (see Game.setQualityLevel() and Game.enableAdaptiveQuality()). Override it to scale your own content with quality, e.g. particle counts or effects.

Parameters

level (integer) — the new BGE.RenderQualityLevel

Returns

void

`onChangeScene(newScene: GameScene): void`

Called on every entity added with Game.addEntity(), and on the outgoing scene, whenever a Game.changeScene()/resetScene() takes effect - just before non-persistent entities are destroyed. Override it to save state or clean up.

Parameters

newScene (GameScene) — The scene being changed to

Returns

void

`onDestroy(): void`

Method called when this entity is destroyed

Returns

void

`addCircleCollider( colliderName: string, radius: float, offset_x?: float, offset_y?: float, enabled?: boolean, ): CircleCollider`

Adds a circle collider to this entity

Parameters

colliderName (string) — Name of the collider (only one collider with the same name can be added)
radius (float) — radius of the circle
offset_x (float, optional, default: 0) — horizontal offset from entity position of centre of the circle
offset_y (float, optional, default: 0) — vertical offset from entity position of centre of the circle
enabled (boolean, optional, default: true) — is this collider enabled?

Returns

CircleCollider

`addRectangleCollider( colliderName: string, width: float, height: float, offset_x?: float, offset_y?: float, enabled?: boolean, ): RectangleCollider`

Adds a rectangle collider to this entity

Parameters

colliderName (string) — Name of the collider (only one collider with the same name can be added)
width (float) — Width of rectangle
height (float) — Height of rectangle
offset_x (float, optional, default: 0) — horizontal offset from entity position of left edge of rectangle
offset_y (float, optional, default: 0) — vertical offset from entity position of top edge of rectangle (world +y is up, so the bottom edge is at offset_y - height)
enabled (boolean, optional, default: true) — is this collider enabled?

Returns

RectangleCollider

`addSphereCollider3d( colliderName: string, radius: float, offset_x?: float, offset_y?: float, offset_z?: float, enabled?: boolean, ): SphereCollider3d`

Adds a sphere collider to this entity, for true 3D overlap detection (not just an XY-space projection) - see BGE.SphereCollider3d.

Parameters

colliderName (string) — Name of the collider (only one collider with the same name can be added)
radius (float) — radius of the sphere
offset_x (float, optional, default: 0) — horizontal offset from entity position of centre of the sphere
offset_y (float, optional, default: 0) — vertical offset from entity position of centre of the sphere
offset_z (float, optional, default: 0) — depth offset from entity position of centre of the sphere
enabled (boolean, optional, default: true) — is this collider enabled?

Returns

SphereCollider3d

`addBoxCollider3d( colliderName: string, width: float, height: float, depth: float, offset_x?: float, offset_y?: float, offset_z?: float, enabled?: boolean, ): BoxCollider3d`

Adds a box collider to this entity, for true 3D overlap detection - see BGE.BoxCollider3d. Note offset is the box's CENTER, unlike addRectangleCollider()'s corner-based offset.

Parameters

colliderName (string) — Name of the collider (only one collider with the same name can be added)
width (float) — width of the box (x axis)
height (float) — height of the box (y axis)
depth (float) — depth of the box (z axis)
offset_x (float, optional, default: 0) — horizontal offset from entity position of the box's center
offset_y (float, optional, default: 0) — vertical offset from entity position of the box's center
offset_z (float, optional, default: 0) — depth offset from entity position of the box's center
enabled (boolean, optional, default: true) — is this collider enabled?

Returns

BoxCollider3d

`addCollider(colliderToAdd: Collider): Collider`

Adds a collider that has already been constructed

Parameters

colliderToAdd (Collider) — the collider to add (only one collider with the same name can be added)

Returns

Collider

`getCollider(colliderName: string): Collider`

Gets a collider based on its name

Parameters

colliderName (string) — The name of the collider to find

Returns

Collider

`removeCollider(colliderName: string): void`

Removes a collider by its name

Parameters

colliderName (string) — the name of the collider to remove

Returns

void

`clearAllColliders(): void`

Remove all colliders from this entity

Returns

void

`addImage( regionName?: string, imageName: string, region: roRegion, args?: roAssociativeArray, insertPosition?: integer, ): Image`

Adds a basic image (non-animated) to be drawn for this entity

Parameters

regionName (string, optional, default: "\"\"") — an optional unique name for the region, used for caching image data
imageName (string) — Name of the image
region (roRegion) — an roRegion of a bitmap to draw
args (roAssociativeArray, optional, default: "{}") — any extra properties to set (e.g. offset_x, offset_y, rotation, scale_x, scale_y, etc.)
insertPosition (integer, optional, default: -1) — the position/order in the images array where the image should be added (defaults to being added at the end)

Returns

Image

`addAnimatedImage( imageName: string, regions: Array.<roRegion>, args?: roAssociativeArray, insertPosition?: integer, ): AnimatedImage`

Adds a animated image to be drawn for this entity. Animated images cycle through regions of a bitmap (e.g. spritesheet)

Parameters

imageName (string) — Name of the image
regions (Array.<roRegion>) — an array of roRegion of a bitmap to draw
args (roAssociativeArray, optional, default: "{}") — any extra properties to set (e.g. offset_x, offset_y, rotation, scale_x, scale_y, etc.)
insertPosition (integer, optional, default: -1) — the position/order in the images array where the image should be added (defaults to being added at the end)

Returns

AnimatedImage

`addSprite( bitmap: roBitmap, imageName: string, spriteSheet: roBitmap, cellWidth: integer, cellHeight: integer, args?: roAssociativeArray, insertPosition?: integer, ): Sprite`

Adds a Sprite to be drawn for this entity. Sprites can have specific animations configured buy choosing series of cells from a sprite sheet

Parameters

bitmap (roBitmap) — the bitmap object to use for teh SpriteSheet (e.g response from game.getBitmap("bitmap_name"))
imageName (string) — Name of the image
spriteSheet (roBitmap)
cellWidth (integer) — the height in pixels of a dingle cell in the sprite
cellHeight (integer) — the height in pixels of a dingle cell in the sprite
args (roAssociativeArray, optional, default: "{}") — any extra properties to set (e.g. offset_x, offset_y, rotation, scale_x, scale_y, etc.)
insertPosition (integer, optional, default: -1) — the position/order in the images array where the image should be added (defaults to being added at the end)

Returns

Sprite

`addOrientedSprite( imageName: string, spriteSheet: roBitmap, cellWidth: integer, cellHeight: integer, numAngles?: integer, numElevationBands?: integer, args?: roAssociativeArray, insertPosition?: integer, ): DrawableOrientedSprite`

Adds a DrawableOrientedSprite to be drawn for this entity - a Sprite that swaps which named animation is active based on the angle between the camera and this entity, faking a full-3D Doom/Duke3D-style billboard sprite. See docs/drawables-and-scene-objects.md for a full walkthrough.

Parameters

imageName (string) — Name of the image
spriteSheet (roBitmap) — Sprite sheet to pick cells from
cellWidth (integer) — Width of each animation cell in pixels
cellHeight (integer) — Height of each animation cell in pixels
numAngles (integer, optional, default: 8) — Number of horizontal (azimuth) view buckets
numElevationBands (integer, optional, default: 1) — Number of vertical (elevation) view bands
args (roAssociativeArray, optional, default: "{}") — any extra properties to set (e.g. offset_x, offset_y, rotation, scale_x, scale_y, etc.)
insertPosition (integer, optional, default: -1) — position among this entity's other drawables to insert at (-1 appends)

Returns

DrawableOrientedSprite

`addRectangle( rectangleName: string, width: float, height: float, args?: roAssociativeArray, insertPosition?: integer, ): DrawableRectangle`

Adds a rectangle to be drawn for this entity. The rectangle's top left corner sits at the entity's position (plus the drawable's own offset), and it extends width to the right and height downwards in world space.

Parameters

rectangleName (string) — Name of the rectangle
width (float) — width of the rectangle in world units
height (float) — height of the rectangle in world units
args (roAssociativeArray, optional, default: "{}") — any extra properties to set (e.g. color, outlineRGBA, outlineWidth, filled, offset, rotation, scale, drawMode)
insertPosition (integer, optional, default: -1) — the position/order in the drawables array where the rectangle should be added (defaults to being added at the end)

Returns

DrawableRectangle

`addCircle( circleName: string, radius: float, args?: roAssociativeArray, insertPosition?: integer, ): DrawableCircle`

Adds a filled circle to be drawn for this entity, via the renderer's shared circle texture. The circle's top left (of its bounding square) sits at the entity's position (plus the drawable's own offset), extending radius * 2 right and down in world space - like DrawableRectangle, it foreshortens into an ellipse in the oriented 3D draw modes. Use addSphere() instead for a circle that never does this.

Parameters

circleName (string) — Name of the circle
radius (float) — radius of the circle in world units
args (roAssociativeArray, optional, default: "{}") — any extra properties to set (e.g. color, outlineRGBA, outlineWidth, outlineSegments, offset, rotation, scale, drawMode)
insertPosition (integer, optional, default: -1) — the position/order in the drawables array where the circle should be added (defaults to being added at the end)

Returns

DrawableCircle

`addSphere( sphereName: string, radius: float, args?: roAssociativeArray, insertPosition?: integer, ): DrawableSphere`

Adds a filled circle that always renders as an undistorted circle regardless of camera angle - because a sphere looks the same from every direction. See DrawableSphere.

Parameters

sphereName (string) — Name of the sphere
radius (float) — radius of the sphere in world units
args (roAssociativeArray, optional, default: "{}") — any extra properties to set (e.g. color, outlineRGBA, outlineWidth, outlineSegments, offset, scale)
insertPosition (integer, optional, default: -1) — the position/order in the drawables array where the sphere should be added (defaults to being added at the end)

Returns

DrawableSphere

`addParticles( particlesName: string, shape: BGE.ParticleShape, args?: roAssociativeArray, insertPosition?: integer, ): DrawableParticles`

Adds a particle emitter to be drawn for this entity. See DrawableParticles for the full set of configurable behavior (spawnRate, lifetime, velocity/spread, acceleration, color/alpha/size-over-lifetime, maxParticles) and its start()/stop()/ burst() control API.

Parameters

particlesName (string) — Name of the particle emitter drawable
shape (BGE.ParticleShape) — see DrawableParticles.shape
args (roAssociativeArray, optional, default: "{}") — any extra properties to set (e.g. spawnRate, lifetime, velocity, acceleration, startColor, endColor, startAlpha, endAlpha, startSize, endSize, maxParticles)
insertPosition (integer, optional, default: -1) — the position/order in the drawables array where the emitter should be added (defaults to being added at the end)

Returns

DrawableParticles

`addDrawable( imageName: string, drawableObject: Drawable, insertPosition?: integer, ): Drawable`

Adds any Drawable/Image object to this entity

Parameters

imageName (string) — Name of the image
drawableObject (Drawable) — The image to be added
insertPosition (integer, optional, default: -1) — the position/order in the images array where the image should be added (defaults to being added at the end)

Returns

Drawable

`getDrawable(imageName: string, drawableName: string): Drawable`

Gets a drawable by its name from the lookup table

Parameters

imageName (string) — Name of drawable to get
drawableName (string)

Returns

Drawable

`removeDrawable(drawableName: string): void`

Removes a drawable from the entity

Parameters

drawableName (string) — Name of drawable to remove

Returns

void

`updateTransformationMatrix(): void`

Returns

void

`movedLastFrame(): boolean`

Returns

boolean

`getStaticVariable(staticVariableName: string): dynamic`

TODO: work on statics

Parameters

staticVariableName (string)

Returns

dynamic

`setStaticVariable( staticVariableName: string, staticVariableValue: dynamic, ): void`

TODO: work on statics

Parameters

staticVariableName (string)
staticVariableValue (dynamic)

Returns

void

`addInterface(interfaceName: string): void`

TODO: work on Interfaces

Parameters

interfaceName (string)

Returns

void

`hasInterface(interfaceName: string): boolean`

TODO: work on Interfaces

Parameters

interfaceName (string)

Returns

boolean

`debugDraw( renderObj: Renderer, drawAxes?: boolean, drawName?: boolean, ): void`

Draws the entity's axes and/or its name

Parameters

renderObj (Renderer)
drawAxes (boolean, optional, default: false)
drawName (boolean, optional, default: false)

Returns

void