Brighterscript Game Engine

BGE/ShapeComponentHelpers

Alias: BGE.ShapeComponentHelpers

Static Methods

getCacheUri(shapeType: string, cacheKey: string): string

static

Hashes a shape type plus its field values into a stable cachefs:/ filename - a cache hit for repeated/discrete values, but a continuously-varying value (e.g. an Animation-driven tween) hashes differently every frame. cachefs:/ (not tmp:/) is deliberate: the filename is a pure function of the shape's inputs, so it's always safe to keep permanently across app relaunches - unlike tmp:/, which is cleared every session, cachefs:/ persists until the OS evicts it under storage pressure (checked for existence on every use regardless, since the OS can evict it at any time - see checkShapeCache()).

Parameters

  • shapeType (string) — distinguishes shape components from each other (e.g. "Circle")
  • cacheKey (string) — a string uniquely identifying this shape's current field values

Returns

  • string — a cachefs:/bge_shape_<hash>.png file URI

startRoundTripTimer(): roTimespan

static

Wall-clock timer for a full field-change-to-visible round trip - bracket a component's whole redraw() with this and logRoundTrip().

Returns

  • roTimespan

logRoundTrip(shapeType: string, timer: roTimespan): integer

static

Prints and returns the elapsed time since startRoundTripTimer() - see there.

Parameters

  • shapeType (string) — distinguishes shape components from each other (e.g. "Circle")
  • timer (roTimespan) — the result of startRoundTripTimer()

Returns

  • integer — elapsed milliseconds

checkShapeCache( shapeType: string, cacheKey: string, ): ShapeCacheCheck

static

Synchronous cache-hit check - computes the cache URI and reports whether it already exists, with no bitmap/renderer creation either way. Safe to call from a component's own script (the render thread) before ever touching a render Task - only spin up (or re-run) a ShapeRenderTask on a miss.

Parameters

  • shapeType (string) — distinguishes shape components from each other (e.g. "Circle")
  • cacheKey (string) — a string uniquely identifying this shape's current field values

Returns

createShapeRenderState( shapeType: string, uri: string, width: integer, height: integer, ): ShapeRenderState

static

Begins a cache-miss render: creates a fresh roBitmap/BGE.Renderer pair for the caller to draw into. Intended to run inside a ShapeRenderTask (off the render thread) after checkShapeCache() has already reported a miss - call finishShapeRender() with the result after drawing.

invalid when width/height are non-positive or the bitmap couldn't be created

Parameters

  • shapeType (string) — distinguishes shape components from each other (e.g. "Circle")
  • uri (string) — the cache file URI to render into (from checkShapeCache())
  • width (integer) — bitmap width in pixels
  • height (integer) — bitmap height in pixels

Returns

  • ShapeRenderState — {uri, renderer, bitmap, shapeType, timer} - renderer/bitmap are

finishShapeRender(renderState: ShapeRenderState): boolean

static

Finishes a cache-miss render started by createShapeRenderState(): Finish() (sufficient alone - no roScreen needed, confirmed on hardware), encodes to PNG, writes to the cache URI.

Parameters

Returns

  • boolean — true if the file was written successfully

verticesFromField(verticesField: object): dynamic

static

Converts a SceneGraph vertices field value into BGE.Math.Vector[], as every Renderer.draw* polygon/triangle call expects. Accepts a vector2darray field (each point a 2-element Float array, index [0]/[1] - this is the XML-settable form, e.g. vertices="[[0,0],[100,0]]") as well as a plain roArray of {x, y} associative arrays (for callers setting it imperatively).

Parameters

  • verticesField (object) — the raw field value (may be invalid or empty)

Returns

  • dynamic — converted points, empty if the field was empty/invalid

defaultTriangleVertices(width: float, height: float): dynamic

static

A right triangle with its right angle at the bottom-left, sized to fill the given width/height - used by Triangle's render dispatch whenever its vertices field is empty.

Parameters

  • width (float)
  • height (float)

Returns

  • dynamic — the three triangle points

Other

INodeShapeRenderTask

static

Extends: roSGNodeTask

Node-level interface for the shared ShapeRenderTask node (see ShapeRenderTask.xml) - declared here (not in ShapeRenderTask.bs) so every shape component's own renderTask field can be typed precisely too, without each one re-declaring it.

Properties

  • shapeType (string)
  • uri (string)
  • width (float)
  • height (float)
  • color (integer)
  • outlineColor (integer)
  • outlineWidth (integer)
  • cornerRadius (float)
  • outlineSegments (integer)
  • vertices (object)
  • resultUri (string)
  • resultRoundTripMs (integer)

ShapeCacheCheck

static

Result of checkShapeCache() - see there.

Properties

  • uri (string)
  • hit (boolean)

ShapeRenderState

static

Result of createShapeRenderState() - see there. renderer/bitmap may be invalid.

Properties

  • uri (string)
  • renderer (BGE.Renderer)
  • bitmap (roBitmap)
  • shapeType (string)
  • timer (roTimespan)