Brighterscript Game Engine

SceneObject

Properties

  • name (string)
  • id (string) — Unique Id
  • drawable (Drawable)
  • type (SceneObjectType)
  • negDistanceFromCamera (float) — The negative distance from the camera, used for depth sorting
  • worldPosition (dynamic)
  • transformationMatrix (dynamic) — The Current Transformation Matrix
  • lastFrameWasCulled (boolean) — Whether the last frame's draw was skipped because the frustum rejected this object. ' Only a genuine cull latches: 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 must not latch - findCanvasPosition() and ' performDraw() both already retry on the following frame, and treating their failure ' as a cull is what made one bad frame permanent. See issue #48.
  • lastFrameDidDraw (boolean) — Whether the last frame's draw actually happened. Distinct from lastFrameWasCulled ' because a frame has three possible outcomes, not two: drew, was culled by the ' frustum, or entered the draw path and failed. Only a cull may latch; a failure must ' retry; and the failure state is also 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()

Constructor

new SceneObject( name: string, drawableObj: Drawable, objType: SceneObjectType, ): SceneObject

Parameters

Instance Methods

setId(id: string): void

Parameters

  • id (string)

Returns

  • void

update(cameraObj: Camera): void

Update the scene object for the current frame. Updates the world position and checks if the object should be drawn. Updates negDistanceFromCamera for depth sorting. Do not override this function.

Parameters

Returns

  • void

getPositionForCameraDistance( drawMode: SceneObjectDrawMode, ): BGE.Math.Vector

Get the position of the object for the camera distance calculation Override this function in subclasses to provide specific behavior

Parameters

Returns

  • BGE.Math.Vector

isEnabled(): boolean

Check if the object is enabled

Returns

  • boolean — true if this sceneObject should be drawn or updated

updateWorldPosition(drawMode: SceneObjectDrawMode): boolean

protected

Update the world position of the object Override this function in subclasses to provide specific behavior

Parameters

Returns

  • boolean

draw(rendererObj: Renderer): void

Draw the object with the current renderer Calculates if the object is on screen and if it should be drawn. Do not override this function!

Parameters

Returns

  • void

drawModeChanged(drawMode: SceneObjectDrawMode): boolean

protected

Whether this object is drawing in a different draw mode than it last drew in.

Changing draw mode has to force a recompute, because the modes don't want the same geometry as each other - directScaled wants a quad built facing the camera, while the oriented modes want the object's own quad projected. World and canvas geometry are otherwise only recomputed when the object or camera moves, so without this a stationary object switched between modes would keep drawing from geometry computed for the mode it was in before, and (since nothing is moving) would never recover.

Parameters

Returns

  • boolean — true if it differs from the last drawn mode

geometryChanged(): boolean

protected

Whether the drawable changed shape since this object last drew. Movement is dirty-checked via MotionChecker, but a change in shape - a resized rectangle, a polygon's points being replaced - isn't movement, so it's declared explicitly by Drawable.invalidateGeometry() and picked up here. Tracked as a version number rather than a flag so that one Drawable registered with more than one Renderer (the game canvas and the UI canvas, say) can't have one of its SceneObjects clear the flag before the other has seen it.

Returns

  • boolean — true if the drawable's geometry changed since the last draw

projectionChanged(cameraObj: Camera): boolean

protected

Whether the camera's projection - its frame size or field of view - changed since this object last drew. Neither counts as camera movement, so the motion dirty-check can't see them, and both change where a world point lands on the canvas and what the frustum accepts. Tracked as a version number rather than a flag for the same reason geometryVersion is: one camera serves every SceneObject in its renderer, so no single object may clear it.

Parameters

Returns

  • boolean — true if the camera's projection changed since the last draw

findCanvasPosition( rendererObj: Renderer, drawMode: SceneObjectDrawMode, ): boolean

protected

Updates any properties that specify the final canvas position of the object Override this function in subclasses to provide specific behavior

Parameters

Returns

  • boolean — True if there is a valid canvas position for the final draw call

performDraw( rendererObj: Renderer, drawMode: SceneObjectDrawMode, ): boolean

protected

Perform any drawing logic for the object Override this function in subclasses to provide specific behavior

Parameters

Returns

  • boolean — True if the draw call was successful

afterDraw(): void

protected

Handle any logic after the object has been drawn Override this function in subclasses to provide specific behavior

Returns

  • void

objMovedInRelationToCamera(cameraObj: Camera): boolean

protected

Check if the object has moved since it was last drawn

Parameters

Returns

  • boolean

isPotentiallyOnScreen(cameraObj: Camera): boolean

protected

Check if the object is potentially on screen.

Repeats last frame's answer for free when nothing has changed, and otherwise runs the real frustum check. The frustum check is deliberately reachable from the "entered the draw path and failed" state as well as from movement: it is what puts an object into the culled state at all, and what lets a failed object discover it is still on screen and retry. Latching on any non-draw - which is what the old framesSinceDrawn counter did - is what made a single failed frame permanent. See issue #48.

Parameters

Returns

  • boolean

getPositionsForFrustumCheck( drawMode: SceneObjectDrawMode, ): dynamic

protected

Get the bounding positions of the object for frustum checks

Parameters

Returns

  • dynamic