BASIC languageStructures and functions

Lifecycle functions

Statement

Syntax

Gives a FUNCTION a reserved name so that the Engine calls it by itself: once at start, every frame, at a fixed rate, or when a collision, a trigger, a message or an animation event happens.

FUNCTION start()
FUNCTION update(<dt>)
FUNCTION fixedUpdate(<step>)
FUNCTION onCollisionEnter(<other>)
FUNCTION onCollisionStay(<other>)
FUNCTION onCollisionExit(<other>)
FUNCTION onTriggerEnter(<other>)
FUNCTION onTriggerExit(<other>)
FUNCTION onMessage(<message>, <data>, <sender>)
FUNCTION onAnimationEvent(<event>, <data>)
FUNCTION main()
ENDFUNCTION

Also written : start, update, fixedUpdate, lateUpdate, onCollision, onTrigger, onMessage, onDestroy

Parts

<dt>Seconds since the last frame, at most 0.1.
<step>The fixed physics step, 1/60 of a second.
<other>The other entity of the contact or the trigger.
<message>The message text sent by another script, for example with EntitySend("door", "open").
<data>The data sent with the message or the animation event.
<sender>The entity that sent the message.
<event>The name of the animation event.

Good to know

  • The lines outside any function run once, when the script loads, before start(). That is the place for GLOBAL declarations and setup.
  • Other accepted names: onStart, onUpdate, onFixedUpdate for the first three; onCollision and onTrigger mean onCollisionEnter and onTriggerEnter; onAnimEvent means onAnimationEvent. Case does not matter in BASIC: the Engine still receives the spelling it expects.
  • A lifecycle function cannot be overloaded. A second update is a compile error: "BASIC lifecycle function cannot be overloaded".
  • No Sync() in update: the frame ends when the function returns. To time something, add up dt, or count frames in a task with YieldTask().
  • An error in update does not stop it. The error is reported and update runs again on the next frame. An update that takes more than 200 ms for 5 frames in a row is switched off.
  • A program with a DO … LOOP is run as main(), and so is a program with Wait(), Sleep(), AWAITTASK, AWAITALL or AWAITANY anywhere outside a function, a task label included. The Engine then never calls start() or update(), and nothing tells you. Do not declare your own FUNCTION main() in such a program: it is replaced without a warning.
  • lateUpdate and onDestroy keep their reserved names, but the editor does not call them on an entity script at the time of writing. Do not rely on them.
  • You can still call these functions yourself, like any other function.

Example

GLOBAL elapsed# = 0GLOBAL frames AS integer = 0FUNCTION start()  Console("ready")          ' ready, printed secondENDFUNCTIONFUNCTION update(dt#)  elapsed# = elapsed# + dt#  frames = frames + 1ENDFUNCTIONFUNCTION onMessage(message$, data, sender)  IF message$ = "reset" THEN frames = 0ENDFUNCTIONConsole("loaded")           ' loaded, printed first
In the manual : Functions

See also