Brighterscript Game Engine

Drawable

Abstract drawable class - all drawables extend from this

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()):
  • 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
  • anchor (dynamic) — Normalized anchor point (0-1 on each axis) this drawable pivots around, where (0,0) is
  • anchorIsSet (boolean) — Whether setAnchor() has ever been called. Image consults this to decide whether to keep
  • owner (GameEntity) — The GameEntity this drawable is attached to. May be invalid for a drawable used
  • width (float)
  • height (float)
  • sceneObjects (object)
  • noOwnerTransformationMatrix (Array.<Array.<float>>) — Lazily-created identity matrix returned by getOwnerTransformationMatrix() when there's no owner.
  • drawMode (SceneObjectDrawMode)
  • isShaded (boolean)
  • ambientBrightness (float) — The darkest an isShaded surface is ever allowed to get, as a 0-1 fraction of its

Constructor

new Drawable( owner: GameEntity, args?: roAssociativeArray, ): Drawable

Parameters

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

Instance Methods

addToRenderer(renderer: Renderer): BGE.SceneObject

Registers this Drawable with a Renderer, so it gets drawn each frame. The engine calls this for you when a drawable is added to an entity; call it yourself only for a standalone drawable. Subclasses override it to create their SceneObject.

Parameters

  • renderer (Renderer) — The renderer to draw this Drawable with

Returns

  • BGE.SceneObject — The SceneObject that represents this Drawable in the renderer, or invalid if it has none

getSceneObjects(): Array.<BGE.SceneObject>

Every SceneObject this Drawable currently represents - usually one (a Drawable added to just the game canvas), but can be more than one if the same Drawable instance was also added to a second renderer (e.g. the UI canvas). Useful for consumer code that needs to identify "my own" SceneObject out of a list the renderer hands back (e.g. Renderer.getOverlapClusters()) - comparing two custom class instances directly with = is not supported by BrightScript at runtime (a "Type Mismatch" error, regardless of any as-cast at the BrighterScript type- checker level, which only affects compile-time typing, not the underlying VM operator), so compare SceneObject.id (a string) instead.

Returns

removeFromRenderer(renderer: Renderer): void

Unregisters every SceneObject this Drawable added to the given Renderer, so it stops being drawn. The engine calls this for you when a drawable is removed from an entity or the entity is destroyed.

Parameters

  • renderer (Renderer) — The renderer to remove this Drawable from

Returns

  • void

computeTransformationMatrix(): void

Returns

  • void

hasPendingTransformChange(): boolean

Whether offset/rotation/scale changed since the transform was last computed. Read-only (doesn't touch the MotionChecker), so every renderer this drawable is registered with sees the same answer.

Returns

  • boolean

invalidateGeometry(): void

Marks this drawable's geometry as changed, so the renderer recomputes its world and canvas geometry on the next frame. Movement is dirty-checked automatically (see MotionChecker), but a change in shape - resizing a rectangle, replacing a polygon's points - isn't visible to that check and has to be declared.

Returns

  • void

getAnchor(): BGE.Math.Vector

Returns

  • BGE.Math.Vector

setAnchor(x: float, y: float): void

Sets the normalized anchor point this drawable pivots around. (0,0) is top left (the default), (0.5, 1) is bottom-center, etc. This isn't movement, so it can't be picked up by the per-frame MotionChecker dirty-check - invalidateGeometry() tells the renderer to recompute this drawable's projected geometry even though nothing moved.

Parameters

  • x (float)
  • y (float)

Returns

  • void

movedLastFrame(includeOwner?: boolean): boolean

Parameters

  • includeOwner (boolean, optional, default: false)

Returns

  • boolean

update(): void

Returns

  • void

onResume(pausedTimeMs: integer): void

Parameters

  • pausedTimeMs (integer)

Returns

  • void

isEnabled(): boolean

Returns

  • boolean

getGame(): BGE.Game

The Game this drawable's owner belongs to.

Returns

  • BGE.Game — the owner's Game, or invalid if this drawable has no owner (or its owner has no Game)

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

Logs a message through the owner's Game. Does nothing if there is no Game to log to.

Parameters

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

Returns

  • void

getOwnerTransformationMatrix(): Array.<Array.<float>>

The owner's transformation matrix, or the identity matrix if this drawable has no owner.

Returns

  • Array.<Array.<float>>

getOwnerPosition(): BGE.Math.Vector

The owner's position, or the world origin if this drawable has no owner.

Returns

  • BGE.Math.Vector

getOwnerRotation(): BGE.Math.Vector

The owner's rotation, or no rotation if this drawable has no owner.

Returns

  • BGE.Math.Vector

getOwnerScale(): BGE.Math.Vector

The owner's scale, or a scale of 1 on every axis if this drawable has no owner.

Returns

  • BGE.Math.Vector

getSize(): SizeWH

Returns

getDrawnSize(): SizeWH

Returns

getWorldPosition(): BGE.Math.Vector

Returns

  • BGE.Math.Vector

getPretranslation(): BGE.Math.Vector

Returns

  • BGE.Math.Vector

getFillColorRGBA(ignoreColor?: boolean): integer

Parameters

  • ignoreColor (boolean, optional, default: false)

Returns

  • integer

getOutlineColorRGBA(ignoreColor?: boolean): integer

Parameters

  • ignoreColor (boolean, optional, default: false)

Returns

  • integer

hasOutline(): boolean

Whether this drawable should be stroked with an outline, which is the case once outlineRGBA has been given a color. Setting outlineRGBA is what turns outline drawing on - there is no separate flag - so this is the check the renderer uses to skip all outline work for the (common) drawables that don't want one.

Returns

  • boolean — true if an outline should be drawn for this drawable

getSceneObjectName(extraBit?: string): string

protected

Parameters

  • extraBit (string, optional, default: "\"\"")

Returns

  • string

addSceneObjectToRenderer( sceneObj: SceneObject, renderer: Renderer, ): SceneObject

protected

Parameters

Returns

drawRegionToCanvas( region: ifDraw2d, additionalRotation?: BGE.Math.Vector, ignoreColor?: boolean, drawTo?: ifDraw2D, ): void

protected

Parameters

  • region (ifDraw2d)
  • additionalRotation (BGE.Math.Vector, optional, default: "invalid")
  • ignoreColor (boolean, optional, default: false)
  • drawTo (ifDraw2D, optional, default: "invalid")

Returns

  • void

forEachSceneObject( operation: function, context: roAssociativeArray, ): void

Parameters

  • operation (function)
  • context (roAssociativeArray)

Returns

  • void

isOnScreen(): boolean

Whether this drawable was actually drawn (not culled) in at least one of the renderers it's registered with, as of the last frame. True before this has ever been added to a renderer (nothing to say it's off-screen yet), so game code can use this to skip expensive per-frame work for an off-screen entity without it defaulting to "invisible" before the first frame ever draws. See GameEntity.isOnScreen() and issue #75.

Returns

  • boolean