Brighterscript Game Engine

GameScene

Extends: GameEntity

A GameScene is a GameEntity that represents one distinct state of your game - a title screen, a menu, a level. Register scenes with Game.defineScene() and switch between them with Game.changeScene(). Only one GameScene is current at a time, and it gets the same per-frame hooks (onUpdate, onInput, ...) as any other entity.

Every scene change destroys all non-persistent entities, including "changing" to the current scene again with Game.resetScene(). When changing to a different scene, the outgoing scene's own drawables (anything added with addDrawable()/addImage()/etc. directly on the scene) are removed too, by this class's default onChangeScene(). On a resetScene() the scene's own drawables are left in place, since onCreate() runs again immediately and typically re-adds everything.

To keep some or all of a scene's own drawables across a change:

  • set persistDrawablesAcrossSceneChange = true to keep all of them, or
  • override onChangeScene() with your own cleanup. An override replaces the default cleanup unless it calls super.onChangeScene(newScene).

A scene is defined once and reused: leaving it (or resetting it) calls onChangeScene() then onDestroy() on it, and entering it again runs onLoad()/onCreate() again. Free whatever a visit set up (gameUi widgets, bitmaps loaded for it) in either hook.

Properties

  • persistDrawablesAcrossSceneChange (boolean) — Whether this scene's own directly-added drawables survive a change to a different

Constructor

new GameScene( gameEngine: Game, args?: roAssociativeArray, ): GameScene

Parameters

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

Instance Methods

onLoad(loader: BGE.AssetLoader, args: object): void

Called when this scene is changed to, before onCreate(). Queue anything that takes time on loader - asset loads (loader.loadBitmap(), loader.load3dModel(), ...), your own BGE.LoadTasks, or a function called once per step (loader.addStep()). The engine runs them a little each frame, showing a loading screen, then calls onCreate(args). Queue nothing (the default) and onCreate() runs straight away.

The previous scene's entities are already gone. This scene doesn't get onUpdate(), onInput() etc. until onCreate() has run - nor do entities added during onLoad().

Parameters

  • loader (BGE.AssetLoader) — queue this scene's loading work here
  • args (object) — the args passed to changeScene()

Returns

  • void

getLoadingScreen(): BGE.LoadingScreen

The loading screen to show while this scene loads. Return invalid (the default) to use game.loadingScreen, or the engine's default if that isn't set.

Returns

onChangeScene(newScene: GameScene): void

Parameters

Returns

  • void