Cursor

Use the cursor script to simplify user interaction such as clicking and dragging of game objects.

Usage

Attach the cursor.script to a game object that should act as a cursor. The game object must have either a kinematic or trigger collision object with a group and mask that matches other collision objects that should be able to interact with the cursor.

IMPORTANT: You must make sure to configure the cursor.script action_id field (see below) to match the binding you have in your input bindings for the left mouse button/mouse button 1. The script assumes that the binding has action set to touch.

Script properties

The script has the following script properties:

• action_id - (hash) The action_id that corresponds to a press/click/interact action (default: “touch”)
• drag - (boolean) If the cursor should be able to drag game objects
• drag_lock_x - (boolean) If a dragged game object should have movement locked to the horizontal axis
• drag_lock_y - (boolean) If a dragged game object should have movement locked to the vertical axis
• drag_threshold - (number) Distance the cursor has to move from a pressed object before it’s considered dragged
• collisionobject_filter - (hash) Id of a collision object component. If specified the cursor script will only accept collision messages from this id.
• acquire_input_focus - (boolean) Check if the script should acquire input and handle input events itself
• notify_own_gameobject - (boolean) Check if cursor messages should be sent not only to the interacting game object but also to the game object this script is attached to.

NOTE: If both drag_lock_x and drag_lock_y are set the game object will be locked to the nearest axis when the drag operation was started.

Input handling

You can let the cursor react to input in several ways:

• Enable the acquire_input_focus property. This will make the script automatically respond to input events. If this isn’t checked any on_input() calls are completely ignored.
• Pass input messages. This will feed input events from an external source. This is useful if the app uses a camera solution or render script where screen coordinates doesn’t translate to world coordinates and where conversion is required (using a screen_to_world function or similar). The input message is expected to have two fields; action_id and action in the same way as the on_input lifecycle function works.

Messages

The script will generate messages to game objects the cursor is interacting with and to the game object the cursor script is attached to for the following situations:

• cursor_over - The cursors moves over the game object (cursor.OVER)
• cursor_out - The cursor moves out from the game object (cursor.OUT)
• pressed - When cursor is pressed (on the game object) (cursor.PRESSED)
• released - When cursor is released (on the game object) (cursor.RELEASED)
• clicked - When cursor clicked (on the game object) (cursor.CLICKED)
• drag_start - When starting to drag the game object (cursor.DRAG_START)
• drag_end - When no longer dragging the game object (cursor.DRAG_END)

The messages sent to the game object where the cursor script is attached will have id and group as well as x and y (from action.x and action.y) passed in the message.

Drag objects

The cursor can drag game objects if the drag property is set. You can block drag operations on a single axis through drag_lock_x and drag_lock_y and you can set the drag threshold (ie how much the cursor needs to move before it is considered a drag event) using drag_threshold.

It is also possible to programmatically start a drag operation of a game object:

-- start dragging the game object with id '/go' vertically
msg.post("#cursor", cursor.START_DRAGGING, { id = hash("/go"), mode = cursor.DRAG_MODE_VERTICAL })

Blocking input events

You can listen for events generated by the cursor script and block execution of the events. This can be used to block drag, pressed and over events.

cursor.listen(cursor_script_url, cursor_event, callback_fn)

Set up a listener for a specific cursor event from a specific cursor script.

• cursor_script_url (url

  string) - URL to the script you wish to listen to

• cursor_event (hash) - The cursor message to listen for (see above)
• callback_fn (function) - Function to call. Signature (message_id, message). Return true from the function to block execution of a cursor.OVER, cursor.PRESSED or cursor.DRAG_START event.

Example:

local cursor = require "in.cursor"

cursor.listen("#cursor", cursor.DRAG_START, function(message_id, message)
	-- prevent dragging of blue aliens
	if message.group == hash("blue") then
		return true -- return true to block the event
	end
end)

Resetting cursor state

It is recommended to reset the cursor state when the screen is minimized and/or has lost focus. This can be done by sending a message to the cursor script:

local cursor = require "in.cursor"

msg.post("#cursor", cursor.RESET)

-- or

cursor.reset("#cursor")