Scripts

Scripts

Located in the center panel, are used to add custom code that interact with the engine. In other words, it's how to create your actual game.

The same script file can be used as both global or scene scripts, but they are slightly different in how they are used inside the game.

Creating

To create a script, you can simply click on the 'Create Script' button after filling its name. The name shouldn't have spaces or special characters, and also doesn't need any extensions.

Examples of valid script names (you can use whatever convention you want, but ideally you should stick to one to ease discovery of them if you have lots):

global
global_script
script_global
main_menu
stage_1
intro_script

Editing

To edit a script, you can find the script under the src/scripts/ folder, double-click on the script to open it using the configured editor, or right-click and select 'Edit'.

Deleting

To delete a script, you have to right-click on the script and then select 'Delete'.

Functions

There are four functions on each script:

void scene_0_create();
short scene_0_tick();
void scene_0_display(display_context_t disp);
void scene_0_destroy();

Their usage varies if they are used as global or scene script, and also if the 'Display' module is available or not.

Global Scripts

Scripts that are used for every scene, and if you do not have the 'Scene Manager' module, they are the only way to add code to the game.

You configure it by setting the global script under 'Project/Global Script'. You can only have one global script.

The functions work as follows:

script_another_create

Will be called once after the game is initialized (will be the last function added) inside the 'setup' function in 'src/setup.gen.c'.

This function should allocate resources that will be used throughout the the whole game.

If you have the 'Memory Pool' module active, you should consider using the 'global_memory_pool' to allocate instead of 'malloc' by using 'mem_zone_alloc()' available inside 'mem_pool.h'.

script_another_tick

Will be called every frame after updating the controller state inside the 'tick' function in 'src/setup.gen.c'. This will be called before updating the scene.

The return value is not used.

script_another_display

Will be called every frame after rendering the scene (so this will render on top of everything else). If you are not using the scene module, you will need to clear the screen buffer by calling 'graphics_fill_screen()'.

This function is only called if the 'Display' module is available, and will be discarted otherwise.

script_another_destroy

Is not used in a global script.

Scene Scripts

Scripts that are used for a single scene, and require the 'Scene Manager' module to be available to be used.

You configure it by setting it as an 'Attached Script' inside a selected scene.

script_another_create

Will be called once (and only one time) the scene is activated (inside 'scene_SCENE_NAME_create()').

This function should allocate resources that will be used throughout the scene.

If you have the 'Memory Pool' module active, you should consider using the 'scene_memory_pool' to allocate instead of 'malloc' by using 'mem_zone_alloc()' available inside 'mem_pool.h'. If you use it, you do not need to 'free' your resources, as they will be freed once the scene changes automatically by the 'Scene Manager' module.

script_another_tick

Will be called every frame (inside 'scene_SCENE_NAME_tick()') right after the global script tick by 'scene_manager_tick()'.

Should return the 'scene_id' if you want to change scenes, or -1 if you do not.

The scene_id can be found inside the 'Scene Settings' when you select a scene.

script_another_display

Will be called every frame after calling 'graphics_fill_screen()' using the 'Background Fill Color' choosen and resetting the graphics color to white/black by calling 'graphics_set_color(0xfff, 0)'.

This function is only called if the 'Display' module is available, and will be discarted otherwise.

script_another_destroy

Will be used when the scene ends (and before creating the next scene). This function should 'free' any resources that did not use the 'scene_memory_pool' (eg.: any resources allocated with 'malloc').