Ethanon Engine - 2D game development / Documentation: Ethpages

onSceneCreated and onSceneUpdate

There are two kinds of callback functions that may be related to a scene: onSceneCreated (also known as pre-loop funcion) and onSceneUpdate (also known as loop function).

onSceneCreated functions will be executed only once right after the scene is loaded but before it gets rendered for the first time. They are useful for procedures like adding NPC's randomly into the scene before a level starts, or adding custom data to entities.

onSceneUpdate functions will be executed at every repetition of the main game loop. This is important to manage menus, control entities or general game events (e.g.: checking if all conditions to finish a level are reached), controlling ambient sound effects or whatever the game needs.

To assign onSceneCreated and onSceneUpdate functions to a scene it is necessary to specify the exact names of the functions when calling the LoadScene function, for example:

void main()
{
    // loads my_scene.esc
    LoadScene("scenes/my_scene.esc", "NewGame", "GameLoop");
}

void NewGame()
{
    //do something...
}

void GameLoop()
{
    //do something...
}

Notice that LoadScene has the function names as second and third parameters. NewGame is going to be the pre-loop (onSceneCreated) function and GameLoop is the loop (onSceneUpdate) function. If any of these parameters aren't empty strings, the core engine will search for functions with exact names. If they cannot be found, the program will exit and output an error message.

If any of these parameters are set as an empty string, the engine will not execute the respective callback function, e.g.:

// this one won't have a pre-loop function
LoadScene("scenes/my_scene.esc", "", "onSceneUpdate");

// this one won't have a loop function
LoadScene("scenes/my_scene.esc", "onSceneCreated", "");

or even

// this one won't have any function
LoadScene("scenes/my_scene.esc", "", "");

Pre-loop and loop functions must be void and may not have parameters.

After loading the first scene and quitting the main() function, the application flow control will be up to the callback functions. The following example loads the first scene and while executing the first scene update function, checks whether the user presses the space key - it loads the next scene if it does:

void main()
{
   // loads my_scene.esc
   LoadScene("scenes/my_scene.esc", "onSceneCreated", "onSceneUpdate");
}

void onSceneUpdate()
{
    //checks if the space key is pressed
    ETHInput @input = GetInputHandle();
    if(input.KeyDown(K_SPACE))
    {
        // loads the next scene
        LoadScene("scenes/level_two.esc", "otherOnSceneCreated", "onSceneUpdate");
    }
}

void onSceneCreated()
{
    // this one will be called only for my_scene.esc
}

void otherOnSceneCreated()
{
    // this one will be called only for level_two.esc
}

Different onSceneCreated and onSceneUpdate (pre-loop and loop) functions were assigned to the next level. Different scenes may either share the same functions or use exclusive ones. It's up to the programmer to decide.