event

The event section sets up an event handler – a procedure that gets called when an event is triggered. Events include initialization, start of a new frame, and user inputs, such as a keyboard press or mouse click. This allows creation of interactive scripts, as well as simple games.

The syntax is as follows:

event <event type>(<argument1, argument2, ...>) = <procedure>;

procedure is either the name of a procedure, or, since in some cases texture data need to be processed, a GLSL function. In the latter case, state variables may also be modified, and relevant builtin constants can be used, but invoking the event is more expensive, as synchronization between CPU and GPU takes place. Because of that, it is recommended to use procedures where possible.

Event handlers triggered by keyboard and mouse may override some keyboard shortcuts and other functionality, such as drag and drop. Holding the reserved Ctrl key should reenable most of the affected features.

The event's arguments, as well as the procedure's argument types, depend on the event type. The procedure's return type should be void.

Event types

List of available event types along with their arguments.

  • initialize() – triggered once at the very beginning, has no input arguments. Since images and animations are not yet evaluated at this point, attempting to sample them will yield blank pixels.
  • update() – triggered at the beginning of each frame except the first one, when initialize is triggered instead. Therefore, all images are already evaluated at this point. The procedure may have zero arguments, or one float argument, which is the elapsed time since the previous frame, in seconds.
  • press(<keys, mouse buttons>) – one or more keyboard keys and mouse buttons must be specified (separated by commas). It is then triggered whenever one of those is pressed. procedure has no arguments. The complete list of keys and mouse buttons can be found below.
  • release(<keys, mouse buttons>) – triggered when one of the specified keys or mouse buttons is released. procedure has no arguments.
  • mouse_press(<mouse buttons>) – unlike press, only left_button, middle_button, or right_button may be specified, but also reports mouse position to procedure. If procedure's argument type is vec2, mouse position will be reported as texture coordinate (between [0, 0] and [1, 1]). If it is ivec2, it will be reported in pixels from the bottom left corner. If this information is not needed, use press instead.
  • mouse_release(<mouse buttons>) – same as mouse_press, but triggered when a button is released.
  • mouse_position(<mouse button (optional)>) – triggered when the mouse position changes. If a mouse button is specified, it is only triggered while the button is held. If procedure's argument type is vec2, mouse position will be reported as texture coordinate. If it is ivec2, it will be reported in pixels from the bottom left corner. Keep in mind that if mouse is dragged outside the window, the reported coordinate may be outside the expected range.
  • mouse_delta(<mouse button (optional)>) – same as mouse_position, but reports the difference from the previous mouse position instead of an absolute coordinate.
  • button(<label>) – creates a button element in the GUI with a string label, triggered when the button is pressed. procedure has no arguments.

Example

var int clickCounter = 0;

procedure click(vec2 mousePos) {
    if (distance(itemPos, mousePos) < r)
        ++clickCounter;
}

event mouse_press(left_button) = click;

Keys and buttons

  • left_button, middle_button, right_button – mouse buttons
  • scroll_up, scroll_down – mouse wheel
  • A, B, C, ... – letter keys
  • 0, 1, 2, ... – number keys (top row)
  • left_arrow, right_arrow, up_arrow, down_arrow
  • shift
  • space
  • enter
  • tab
  • num_0, num_1, num_2, ... – numeric keypad
  • num_add, num_subtract, num_multiply, num_divide, num_decimal
  • minus
  • plus
  • backspace
  • insert
  • delete
  • home, end
  • page_up, page_down
  • tilde
  • comma
  • period
  • slash
  • semicolon
  • quote
  • left_bracket, right_bracket
  • backslash

Other keys not listed here (specifically Ctrl, Alt, and function keys such as F1, ...) cannot be captured by an event handler.