Scripting

    Contents

    Introduction

    Scripting is used to provide all kinds of fun in-game interactions. If there’s anything special you want to happen based on some event (Kart smashing into another kart, driving over a big red button, hitting a wooden box with an explosive cake), then scripting is just the thing for you!

    You can use AngelScript for scripting in version higher than 0.8.1. If you want to learn how to add your own scripts, you should refer the AngelScript documentation.

    Scripting API

    The API can be found at https://doxygen.supertuxkart.net/group__Scripting.html

    Triggers for scripts

    Action Triggers

    Action Triggers are point based triggers with a radius. Think of it as a big bubble that pops when you enter it, triggering some action. This is probably the best method of triggering location-based events. By default the trigger is disabled right after it is activated. They can be activated or deactivated as you wish, using other scripts.

    Relevant Methods:

    On Collision

    Collision-based triggering revolves around providing collision based interactions. Several different types of callbacks are defined.

    At present the different callbacks are

    To detect collision between a kart and a physical object (track object), the “on-kart-collision” property should be defined on the object in the scene.xml file, containing the name of the scripting function to call

    To detect collision between an item (a powerup/weapon) and a physical object (track object), the “on-item-collision” property should be defined on the object in the scene.xml file, containing the name of the scripting function to call

    On Start

    Start-up scripts will run exactly once, during the track loading process. As such, they are ideal for setting the initial states of any animations, creating new action triggers, etc.

    Library objects can also declare an onStart callback, it should be placed in a namespace that has the same name as the library object (it is recommended to put all library object code in its own namespace to avoid conflicts

    On Update (currently disabled in track.cpp)

    WARNING: Inefficient. Use sparingly.

    Update scripts will keep running throughout the race and as such, will cause performance issues if used carelessly. They are ideal, however, for testing out scripts during testing. Whenever possible, these scripted actions should be moved into one of the other types (most probably the action-trigger driven type) so as to improve performance.