Scene System - hikawi/cc-sakura GitHub Wiki

This project has a simple scene system, provided in scene.h. The idea is that multiple scenes can be active (or also called "in-play" scenes), at various locations on the screen. For example: a HUD scene that only has the job to reflect the current player's status, a gameplay scene with the map and the player, and a random text box scene that can appear out of nowhere.

Each scene has its own colliders map to handle collisions, and its own sprites map to easily access relevant sprites. A scene is always a dynamically allocated pointer, as we don't know how many scenes can be in play at compile time.

To initialize a scene, refer to scene_init(void), which would return a well-behaved Scene *, where it's zeroed out various fields. Replace fields with data you need to handle, before pushing it into the Scene Manager.

Lifecycle

A scene manager manages all the active scenes, and does the job of delegating layers and rendering to each scene in an order based on the scenes stack. Here is the life of a scene being added to a scene manager:

  • If done via a transition, oninit function is invoked on the scene. You may use this function to initialize any data the scene needs to render at all. Because on the next tick that scene will be required to render to animate a transition.
  • Once the transition is finished, onstart function is invoked. You may use this function to bootstrap the scene, and start working the gears. If it was not added via a transition, onstart is invoked immediately after oninit.
  • During its active phase, ontick will be invoked on every frame. This requests the scene to update any animation-related data, most data that do not concern physics. After ontick, at some point during the same frame, ondraw
  • Once every few milliseconds, depending on the application's max fps settings (once every 16ms at 60FPS), the scene's onphystick will be invoked. This requests the scene to update and apply any physics-related data (movements, gravity, etc.).
  • If an event is caught by the engine, the scene's onsignal will be invoked. This requests the scene to handle the event gracefully. It is not sure that this will be invoked on the main thread, so make sure to be cautious with this function.
  • When the scene is finally unloaded, either by removing or replacing with a transition, ondestroy will be invoked. This function should clean up any resources the scene is using. The scene manager will clean up the hash maps and the scene pointer. Only items allocated by the scene itself shall be cleaned up.

Scene Transitions

Scene Transitions are managed by the scene manager. When a scene is requested to be transition in (to_scene), there needs to be a scene to be transitioned out (from_scene), be present within the active scenes stack.

Scene Transitions are coded from a scene manager's point of view, that means it is not the scene's concern itself to aid the animation progress. Using transitions are as simple as invoking scene_mgr_start_transition with the corresponding SceneTransition values.