Module scene

The logical encapsulation of a single game space and everything in it.

Scene is comparable to the idea of a "level" or "screen", but could be either of the two.

The Scene renders its contents in ascending Z order, back to front.

Z values are in the range -256.0 (back) to 0.0 (front)

Scene extends BoundObject

Properties

bg_color An {r, g, b, a} vector of the background color.
bg_z The z value for the Scene's background color rectangle.
camera (read only) The Scene's Camera.
canvas A Canvas that is rendered with the Scene.
debug_camera (bool) Whether to render camera debug outlines.
draw_grid (bool) Whether to render a debug wireframe tile grid.
cover_color An {r, g, b, a} vector of the background color.
gravity An {x, y} vector of the Scene's gravity in meters per seconds squared.
music The Music bound to the Scene.
parallax A Parallax that is rendered with the Scene.
started_at When the Scene started, in "ticks" (milliseconds since the engine booted).
entities The Collection of the Scene's Entities
overlays The Collection of the Scene's Overlays
recorders The Collection of the Scene's Recorders

Class Methods

Scene:new () Create a new Scene

Instance Methods

scene:fade_in (more_update, completion) Perform a 500ms fade-in transition.
scene:fade_out (more_update, completion) Perform a 500ms fade-out transition
scene:start () Start the scene.
scene:stop () Stop the scene.
scene:load_map (map, meters_per_tile, z) Load a TMX tile map.

Configuration

kind The Scene prototype to use.
pixels_per_meter The ratio by which the screen space (pixels) relates to the physics space (meters).

Hooks

started (self) Called by the game engine when the scene starts.
main (self) Called by the game engine once per frame, after any physics solving and before the individual main functions on Entities.
cleanup (self) Called by the game engine when the scene stops.
reset_camera (self) Called by the game engine when the scene needs to reset its camera.
fade_in_effect (scene, easer) Called every update during a fade_in transition.
fade_out_effect (scene, easer) Called every update during a fade_out transition.


Properties

Properties. Significant fields on an instance.
bg_color
An {r, g, b, a} vector of the background color.

Default {0, 0, 0, 1} (solid black)

bg_z
The z value for the Scene's background color rectangle.

Default -256.0

camera
(read only) The Scene's Camera. This is implicit (constructed automatically).
canvas
A Canvas that is rendered with the Scene.
debug_camera
(bool) Whether to render camera debug outlines.
draw_grid
(bool) Whether to render a debug wireframe tile grid.
cover_color
An {r, g, b, a} vector of the background color.

Modified by fade_in and fade_out

Default {0, 0, 0, 0}

gravity
An {x, y} vector of the Scene's gravity in meters per seconds squared. This doesn't do anything in static scenes, but the property can still be used.
music
The Music bound to the Scene. Use this property if you want the Music to be managed along with the Scene. e.g. Stop the music automatically when the Scene disappears.
parallax
A Parallax that is rendered with the Scene.
started_at
When the Scene started, in "ticks" (milliseconds since the engine booted).

see also:

entities
The Collection of the Scene's Entities
overlays
The Collection of the Scene's Overlays
recorders
The Collection of the Scene's Recorders

Class Methods

Class Methods. Must be called on Class, with a capital leading character. e.g. Class:method("foo")
Scene:new ()
Create a new Scene

Returns:

    Scene

Instance Methods

Instance Methods. Must be called on an instance of Class. e.g. instance:method("foo")
scene:fade_in (more_update, completion)
Perform a 500ms fade-in transition.

This actually just animates the cover from {0, 0, 0, 1} (black) to {0, 0, 0, 0} (clear).

Parameters:

  • more_update function An update callback, of type function(Scene, Easer)
  • completion function A completion callback of type function(Scene)

Returns:

    nil
scene:fade_out (more_update, completion)
Perform a 500ms fade-out transition This actually just animates the cover from {0, 0, 0, 0} (clear) to {0, 0, 0, 1} (black).

Parameters:

  • more_update function An update callback, of type function(Scene, Easer)
  • completion function A completion callback of type function(Scene)

Returns:

    nil
scene:start ()
Start the scene. Usually called automatically by SceneManager.

Returns:

    nil
scene:stop ()
Stop the scene. Usually called automatically by SceneManager.

Returns:

    nil
scene:load_map (map, meters_per_tile, z)
Load a TMX tile map.

Parameters:

  • map string The filename of the .tmx file. Map must be base64/gzip encoded!
  • meters_per_tile number Length of the edge of a single tile in meters
  • z number The z value of the map. Default -150.0

Returns:

    nil

Configuration

Configuration. Required by subclass declarations. Used when instantiating concrete subclasses.
kind
The Scene prototype to use.

Must be one of these values:

  • "static" - A scene not backed by a physics engine. Any updates happen purely in script hooks.

  • "chipmunk" - A scene backed by the Chipmunk physics engine. It behaves in a side-scroller style like Mario or Sonic.

Default "static"

pixels_per_meter
The ratio by which the screen space (pixels) relates to the physics space (meters). Units are important!

Default 32

Hooks

Hooks. Callbacks implemented in subclasses to customize behavior. Hooks are called on individual instances.
started (self)
Called by the game engine when the scene starts. Overload this to do things like add entities, parallax layers, maps, etc.

Configure may be called multiple times in the Scene's lifecycle. If you want to create objects that persist across stopping and starting, create them in init

Parameters:

  • self Scene The Scene instance
main (self)
Called by the game engine once per frame, after any physics solving and before the individual main functions on Entities.

Parameters:

  • self Scene The Scene instance
cleanup (self)

Called by the game engine when the scene stops.

This has a default implementation. If you overload this, call the Scene implementation explicitly:

 Scene.cleanup(scene)

Parameters:

  • self Scene The Scene instance
reset_camera (self)
Called by the game engine when the scene needs to reset its camera.

This has a default implementation, but if you overload it you are not required to call the default implementation.

Parameters:

  • self Scene The Scene instance
fade_in_effect (scene, easer)
Called every update during a fade_in transition.

This can be used to add more effects to a fade in.

Parameters:

  • scene Scene The Scene instance
  • easer Easer The Easer controlling the transition
fade_out_effect (scene, easer)
Called every update during a fade_out transition.

This can be used to add more effects to a fade out.

Parameters:

  • scene Scene The Scene instance
  • easer Easer The Easer controlling the transition
generated by LDoc 1.3.12