Scene API Reference


b5.Scene

A Scene is a container for game objects. You should create scenes to hold your content (Actors and resources etc..) then add them to TheApp to be processed. You can add logic to the actor via its update() method and or by attaching an onTick event handler. A Scene has the following features:

  • Manages scene local resources
  • Manages scene local Timeline animations using a TimelineManager
  • Managed a collection of local action lists using an ActionsListManager
  • Manages a collection of Actors
  • Supports a camera
  • Camera can target actors and follow them on x and y axis
  • Position and scaling
  • Touch panning (user can drag the camera around)
  • Box2D world physics
  • Extents which limit camera movement
  • Can detect when an actor in the scene has been touched
  • Clipping of child actors against scene, also supports clipping shapes
  • Scene wide opacity
  • Layer ordering

Public properties

  • name – Name of the scene (used to find actors in the scene)
  • tag – Tag (used to find groups of actors in the scene)
  • active – Active state, inactive scenes will not be updated
  • visible – Visible state, invisible scenes will not be drawn
  • layer – The visible layer that this object sits on
  • x – Scene x axis position
  • y – Scene y axis position
  • w – Scene canvas width
  • h – Scene canvas height
  • clip_children – If set to true then actors will be clipped against extents of this scene
  • clip_shape – If none null and clipping is enabled then children will be clipped against shape (clip origin is at centre of canvas)
  • camera_x – Camera x position
  • camera_y – Camera y position
  • camera_vx – Camera x velocity
  • camera_vy – Camera y velocity
  • vx_damping – Damping to apply to camera_vx
  • vy_damping – Damping to apply to camera_vy
  • panning – Set to true when user is panning the scene
  • min_panning – A minimum distance that the user must pan for panning to be set to true (this value is the squared distance)
  • follow_speed_x – Camera target follow speed x axis
  • follow_speed_y – Camera target follow speed y axis
  • target_x – Camera actor target on x axis
  • target_y – Camera actor target on y axis
  • touch_pan_x – If true then scene will be touch panned on x axis
  • touch_pan_y – If true then scene will be touch panned on y axis
  • world_scale – Scaling from graphical world to Box2D world
  • time_step – Physics time step in milliseconds (1/60 for 60 fps), setting to 0 will run physics at a variable rate based on frame update speed
  • extents – Scene camera extents [left, top, width, height]
  • opacity – Scene opacity

Internal properties

  • app – Parent app
  • actors – Array of actors
  • removals – Array of actors that were deleted last frame
  • frame_count – Number of frames that this scene has been running
  • world – Box2D world
  • touching – Set to true when user touching in the scene
  • touchmove – Set to true when touch is moving in this scene
  • timelines – Scene local animation TimelineManager
  • actions – Scene local  ActionsListManager
  • bitmaps – Array of Bitmap resources
  • brushes – Array of ImageAtlas (other brush types will be added in future) resources
  • shapes – Array of Shape resources
  • materials – Array of Material resources
  • sounds – Array of Sound resources
  • order_changed – When layer changes this property is marked as true to let the system know to resort all objects on the layer

Setters

  • _layer – Changes the scenes layer, note that visual ordering of scenes does not take place until the end of the game frame
  • _focus_scene – Sets the current focus scene, can use path to scene or instance of scene
  • _focus_scene2 – Sets the current secondary focus scene, can use path to scene or instance of scene
  • _clip_shape – Sets the clip shape, can use path to scene or instance of scene

Events

  • onCreate() – Called just after the scene has been created
  • onDestroy() – Called just before the scene is destroyed
  • onTick(delta_time) – Called each time the scene is updated (every frame)
  • onBeginTouch(touch_pos) – Called when the scene is touched
  • onEndTouch(touch_pos) – Called when the scene has top being touched
  • onMoveTouch(touch_pos) – Called when a touch is moved over the scene
  • onKeyPress(e) – Called when a key is pressed, e is key event
  • onKeyDown(e) – Called when a key is down, e is key event
  • onKeyUp(e) – Called when a key is up, e is key event

Methods

Scene() – Creates an instance of a Scene object. Once a scene has been created it should be added to the main app object to be processed and drawn

release() –  Releases the scene, this is called by the app system when an scene has been destroyed

destroy() – Begins the destruction of a scene and its content, note that the scene will not actually be destroyed until the end of the apps processing

addActor(actor) – Adds the specified actor to the scene, returns the added actor

removeActor(actor) – Removes the specified actor from the scene, destroying it

removeActorsWithTag(tag) – Removes all actors from the scene that are tagged with the specified tag

cleanupDestroyedActors() – Cleans up all destroyed scenes, this is called by the app to clean up any removed scenes at the end of its update cycle

findActor(name, recursive) – Searches this scenes child list for the named actor.

  • name: The name of the actor
  • recursive – If true then the complete child hierarchy will be searched
  • returns the found actor or null if not found

bringToFront() – Moves the scene to the end of the scenes list, bringing it to the front of all other scenes in the app.

sendToBack() – Moves the scene to the start of the scenes list, pushing it to the back of all other scenes in the app.

initWorld(gravity_x, gravity_y, allow_sleep) – Initialises a Box2D world and attaches it to the scene. Note that all scenes that contain Box2D physics objects must also contain a Box2D world

  • gravity_x – X axis gravity
  • gravity_y – Y axis gravity
  • allow_sleep – If set to true then actors with physics attached will be allowed to sleep

draw() – Draws this scene and its children, this method can be overriden by derived scenes

baseUpdate(dt) – Base update function (used internally) that should be called by all derived scenes that wish to use base scene functionality, this is usually called from your update() method.

  • dt – The amount of time that has passed since this scene was last updated

update(dt) – Updates the scene (used internally), this method can be overriden by derived scenes

  • dt – The amount of time that has passed since this scene was last updated
  • returns true if active

updateCamera(dt) – Updates the scenes camera

  • dt – The amount of time that has passed since this scene was last updated
  • returns true if active

findHitActor(position) – Searches all touchable actors in the scene to see if the supplied position hits them

  • position – The position to hit test
  • returns the actor that was hit or null for no hit

addResource(resource, type) – Adds a resource to the scenes resource manager

  • resource – The resource to add
  • type – Type of resource to add (brush, sound, shape, material, bitmap or geometry)

removeResource(resource, type) – Removes a resource from the scenes resource manager

  • resource – The resource to remove
  • type – Type of resource to remove (brush, sound, shape, material, bitmap or geometry)

findResource(name, type) – Searches the scenes resource manager for the named resource, if the resource is not found in this scene then the apps global resources will be searched

  • resource – Name of resource to search for
  • type – Type of resource to search for (brush, sound, shape, material, bitmap or geometry)
  • returns the found resource or null if not found

areResourcesLoaded() – Returns true if all scene resources have been loaded, otherwise false

Examples

Creating a scene

Adding clipping to a scene

Adding touch panning to a scene

Adding a physics world to a scene

Adding an onTick event handler to a scene

Adding touch event handlers to a scene

Make the scene camera follow a target actor

1,434 total views, 3 views today