App API Reference


b5.App

The App is the main app controller and is responsible for general housekeeping and Scene processing, You should create a single instance of The App object and assign it to window.app. Scenes should then be created to hold your content then added to this instance of the app. The App has the following features:

  • Manages global resources
  • Manages a collection of Scenes
  • Handles touch input
  • Finds which Actor was touched
  • Main loop processing
  • Manages global animation Timelines via a TimelineManager
  • Controls rescaling of canvas to best fit to different display sizes
  • Tracks loading of resources and displays a loading screen whilst loading

Public properties

  • scenes – An array of Scenes
  • canvas – The HTML5 canvas
  • allow_touchables – if true then app will search to find Actor that was touched
  • target_frame_rate – Frame rate at which to update the game logic
  • adaptive_physics –  When true physics update will be ran more than once if frame rate falls below target
  • focus_scene – Scene that has current input focus
  • focus_scene2 – Scene that has secondary input focus
  • clear_canvas – If true then canvas will be cleared each frame
  • touch_focus – The Actor that has the current touch focus
  • debug – Can be used to enable / disable debug trace info
  • timelines – Global animation TimelineManager
  • pixel_ratio – Device pixel ratio
  • canvas_width – Virtual canvas width
  • canvas_height -Virtual canvas height
  • display_width – Width of display (client area)
  • display_height – Height of display (client area)
  • canvas_scale_method – Method of scaling used to scale virtual canvas to display
  • touch_supported – True if touch is supported
  • loading_screen – An object that contains the following properties that affect how the loading screen appears:
    • background_fill – Loading screen background colour
    • background_image – An image that will be displayed for the loading screen
    • bar_background_fill – Loading bar background colour
    • bar_fill – Loading bar colour

Internal properties

  • removals – Array of scenes that were deleted last frame
  • touched – true if the screen is being touched, false otherwise
  • touch_pos – Position of last screen touch {x, y}
  • touch_drag_x – Amount touch position was last dragged on x axis
  • touch_drag_y – Amount touch position was last dragged on y axis
  • last_time – Time of last frame update in milliseconds
  • dt –  Time period that has passed since the last update of the app in seconds
  • avg_time – Total time since last average time measurement
  • avg_fps – Frames per second of last average time measurement
  • avg_frame – Counter used to take average time measurements
  • canvas_fill_window – If set to true then canvas will be scaled to fit window
  • canvas_scale – The amount that the virtual canvas is scaled to fit the screen
  • canvas_cx – Canvas x-axis centre
  • canvas_cy – Canvas y-axis centre
  • total_loaded – Total resources that have been loaded so far (only resources that have been marked as preload)
  • total_load_errors – Total number of resources that were not loaded due to errors
  • order_changed – Set to true when scene order changes, causes a re-sort
  • 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

Constants

  • App.FitNone- No scaling or resizing of the HTML5 canvas will occur
  • App.FitX – The HTML5 canvas will be resized to the full size of the display and the virtual canvas will be scaled so that the entire x-axis is fit onto the display
  • App.FitY – The HTML5 canvas will be resized to the full size of the display and the virtual canvas will be scaled so that the entire y-axis is fit onto the display
  • App.FitBest – The HTML5 canvas will be resized to the full size of the display and the virtual canvas will be scaled either on the X or Y axis depending on which axis keeps the most of the information on the display
  • App.FitSize – The HTML5 canvas will be resized to the full size of the display and the virtual canvas will be set to the same size as the display (no scaling will be performed)

Events

  • onResourcesLoaded(resource, error) – Called when a resource has been loaded

Methods

App(canvas) – Creates and instance of the app

  • canvas – The HTML5 canvas object that will be drawn to

onTouchStart(e) – Event handler that is called by the system when the user begins touching the display (this includes mouse button down) (used internally)

  • e – A mouse touch event

onTouchEnd(e) – Event handler that is called by the system when the user stops touching the display (this includes mouse button up) (used internally)

  • e – A mouse touch event

onTouchMove(e) – Event handler that is called by the system when the user moves a touch around the display (this includes mouse move) (used internally)

  • e – A mouse touch event

onKeyPress(e) – Event handler that is called by the system registers a key press (used internally)

  • e – A key event

onKeyDown(e) – Event handler that is called by the system receives a key down event (used internally)

  • e – A key event

onKeyUp(e) – Event handler that is called by the system receives a key up event (used internally)

  • e – A key event

onResourceLoadedBase(resource, error) – Base event handler for onResourceLoaded. If you override onResourceLoaded then ensure that you call this base to ensure correct operation

  • resource – Resource that was loaded
  • error – true if an error occurred whilst loading

addScene(scene) – Adds a scene to the app

  • scene – The scene to add

removeScene(scene) – Removes the specified scene from the app destroying it. Note that the scene is not removed immediately, instead it is removed when the end of the frame is reached.

  • scene – The scene to remove

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

findScene(name) – Searches the app for the named scene

  • name – Name of the scene to find
  • returns the found scene object or null for scene not found

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

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

removeResource(resource, type) – Removes a resource from the global app 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 global app resource manager for the named resource

  • 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

countResourcesNeedLoading(include_scenes) – Counts and returns how many resources that need to be loaded

  • include_scenes – if set to true then resources in all loaded scenes will also be counted

findHitActor(position) – Searches all touchable actors in all app scenes 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

draw() – Draws the app and all of its contained scenes

update(dt) – Updates the app and all of its contained scenes

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

mainLoop() – The apps main loop (used internally)

start() – Starts the app going

dirty() – Dirties the scene and all child actors transforms

setCanvasScalingMethod(method) – Sets the method of scaling the virtual canvas to the HTML5 canvas

  • method – The method of scaling to use, can be FitNone, FitX, FitY, FitBest or FitSize

areResourcesLoaded(include_scenes) – Removed

waitForResources() – Waits for all preload resources to load before starting the app, also displays a loading screen and loading bar. Use this in place of calling app.start() directly.

parseAndSetScene(scene_name) – Parses the named scene and sets it as the current focus scene

  • scene-name = The name of the scene, note that the scene name and the exported name of the scene must match

Examples

Setting up the main app

Setting up the main app using a loading screen

762 total views, 1 views today