Trigger API Reference\DCEI Events\Input

Trigger API Reference\DCEI Events\Input

void TriggerAddMouseDownEvent(int mouseButtonId, TypedCallback<Float2, unit> trigger)

void TriggerAddMouseDownEvent(int mouseButtonId, TypedCallback<Float2, unit> trigger)

Description

This event triggers when the specified mouse button down occurs. Using this event will disable unit selection as well as all other built-in mouse functions tied to the given mouse button id including any TriggerAddMouseUpEvent. This function can also pass the mouse cursor position as a parameter to the callback function.

Parameters

int mouseButtonId the mouse button; mouseButtonId 0: left mouse, mouseButtonId 1: right mouse.
TypedCallback<Float2, unit> trigger the callback function that is run when the event is triggered.

Callback Parameters

Float2 position
Unit target_unit

Example Usage

DCEI.TriggerAddMouseDownEvent(0, OnMouseDown)

function OnMouseDown(cursor_pos)
    DCEI.LogMessage("LMB Down")
end

void TriggerAddMouseUpEvent(int mouseButtonId, TypedCallback<Float2, unit> trigger)

void TriggerAddMouseUpEvent(int mouseButtonId, TypedCallback<Float2, unit> trigger)

Description

This event triggers when the specified mouse button up occurs. Using this event will disable unit commands as well as all other built-in mouse functions tied to the given mouse button id including any TriggerAddMouseDownEvent.

Parameters

int mouseButtonId the mouse button; mouseButtonId 0: left mouse, mouseButtonId 1: right mouse.
TypedCallback<Float2, unit> trigger the callback function that is run when the event is triggered.

Callback Parameters

Float2 position
Unit target_unit

Example Usage

DCEI.TriggerAddMouseUpEvent(1, OnMouseUp)

function OnMouseUp()
    DCEI.LogMessage("RMB Up")
end

void TriggerAddSwipeTouchDownEvent(TypedCallback<Float2> trigger)

void TriggerAddSwipeTouchDownEvent(TypedCallback<Float2> trigger)

Description

This event triggers when the start of a screen swipe input has been detected. Only works on mobile. Using this event will disable camera pan as well as all other built-in touch functions including TriggerAddTouchUpEvent.

Parameters

TypedCallback<Float2> trigger the trigger to run when this event occurs. Parameter point denotes the point in screenspace (not worldspace), where the Swipe input was started.

Callback Parameters

Float2 position

Example Usage

DCEI.TriggerAddSwipeTouchDownEvent(function(point)
  DCEI.LogMessage("Swipe down happens on screen point: " .. point.x .. ", " .. point.y)
end)

void TriggerAddSwipeTouchUpEvent(TypedCallback<Float2> trigger)

void TriggerAddSwipeTouchUpEvent(TypedCallback<Float2> trigger)

Description

This event triggers when the end of a screen swipe input has been detected. Only works on mobile. Using this event will disable camera pan as well as all other built-in touch functions including TriggerAddTouchUpEvent.

Parameters

TypedCallback<Float2> trigger the trigger to run when this event occurs. Parameter point denotes the point in screenspace (not worldspace), where the Swipe input has ended.

Callback Parameters

Float2 position

Example Usage

DCEI.TriggerAddSwipeTouchUpEvent(function(point)
  DCEI.LogMessage("Swipe up happens on screen point: " .. point.x .. ", " .. point.y)
end)

int RegisterControllerMap(int playerId, int categoryId, int layoutId, ControllerMapEntry controllerMap)

int RegisterControllerMap(int playerId, int categoryId, int layoutId, ControllerMapEntry controllerMap)

Description

This API is under development and may change without notice.

Parameters

Example Usage

This API is under development and may change without notice.

void RegisterControllerMapMode(string tag, int categoryId1, int layoutId1, int categoryId2 = -1, int layoutId2 = -1, int categoryId3 = -1, int layoutId3 = -1)

void RegisterControllerMapMode(string tag, int categoryId1, int layoutId1, int categoryId2 = -1, int layoutId2 = -1, int categoryId3 = -1, int layoutId3 = -1)

Description

This API is under development and may change without notice.

Parameters

Example Usage

This API is under development and may change without notice.

void ActivateControllerMapMode(string tag)

void ActivateControllerMapMode(string tag)

Description

This API is under development and may change without notice.

Parameters

Example Usage

This API is under development and may change without notice.

void SetUiNavigationExplicit(InGameUILayoutComponent ui, InGameUILayoutComponent up, InGameUILayoutComponent down, InGameUILayoutComponent left, InGameUILayoutComponent right)

void SetUiNavigationExplicit(InGameUILayoutComponent ui, InGameUILayoutComponent up, InGameUILayoutComponent down, InGameUILayoutComponent left, InGameUILayoutComponent right)

Description

Parameters

Example Usage

void SetUiControllerInputActionTrigger(InGameUILayoutComponent ui, int actionId)

void SetUiControllerInputActionTrigger(InGameUILayoutComponent ui, int actionId)

Description

Parameters

Example Usage

void TriggerAddInputActionEvent(TypedCallback trigger, int actionId)

void TriggerAddInputActionEvent(TypedCallback trigger, int actionId)

Description

This API is under development and may change without notice.

Parameters

Example Usage

This API is under development and may change without notice.

void TriggerAddTouchDownEvent(TypedCallback<Float2, unit> trigger)

void TriggerAddTouchDownEvent(TypedCallback<Float2, unit> trigger)

Description

This event triggers when the start of a touch input is detected. Only works on mobile. Using this event will disable unit selection as well as all other built-in touch functions including TriggerAddSwipeTouchDownEvent.

Parameters

TypedCallback<Float2, unit> trigger the trigger to run when this event occurs. Parameter point denotes the point in screenspace (not worldspace), where the Touch input occurred.

Callback Parameters

Float2 position
Unit target_unit

Example Usage

DCEI.TriggerAddTouchDownEvent(function(point)
  DCEI.LogMessage("Touch down happens on screen point: " .. point.x .. ", " .. point.y)
end)

void TriggerAddTouchUpEvent(TypedCallback<Float2, unit> trigger)

void TriggerAddTouchUpEvent(TypedCallback<Float2, unit> trigger)

Description

This event triggers when the end of a touch input is detected. Only works on mobile. Using this event will disable unit selection as well as all other built-in touch functions including TriggerAddSwipeTouchDownEvent.

Parameters

TypedCallback<Float2, unit> trigger the trigger to run when this event occurs. Parameter point denotes the point in screenspace (not worldspace), where the Touch input occurred.

Callback Parameters

Float2 position
Unit target_unit

Example Usage

DCEI.TriggerAddTouchUpEvent(function(point)
  DCEI.LogMessage("Touch up happens on screen point: " .. point.x .. ", " .. point.y)
end)

void TriggerAddJoystickEvent(TypedCallback trigger)

void TriggerAddJoystickEvent(TypedCallback trigger)

Description

Creates an on-screen joystick and that triggers this event when moved. Uses default JoystickOptions.

Parameters

TypedCallback trigger the trigger to run when this event occurs.

Example Usage

function OnJoystickMove()
    local axes = DCEI.TriggeringJoystickAxes
    DCEI.DirectionalMove(unit, axes.x, axes.y)
end

DCEI.TriggerAddJoystickEvent(OnJoystickMove)

void TriggerAddJoystickEventWithJoystickOptions(TypedCallback trigger, JoystickOptions options)

void TriggerAddJoystickEventWithJoystickOptions(TypedCallback trigger, JoystickOptions options)

Description

Creates an on-screen joystick and that triggers this event when moved. Uses default JoystickOptions.

By default, the joystick can be used with WASD, arrow keys, or by click-dragging the joystick button.

Parameters

TypedCallback trigger the trigger to run when this event occurs.
JoystickOptions options see JoystickOptions

Example Usage

local unit = DCEI.CreateUnit(1, 1, "Standard MeleeUnit", 15, 15)

local function OnJoystickMove()
    local axes = DCEI.TriggeringJoystickAxes
    DCEI.DirectionalMove(unit, axes.x, axes.y)
end

local function CreateJoystick()
    local frame = DCEI.CreateFrame(DCEI.GetUiRootFrame())

    DCEI.SetFrameWidth(frame, 1500)
    DCEI.SetFrameHeight(frame, 1500)

    local joystick_options = {
        anchor = { x = 0, y = 0 },
        offset = { x = 0, y = 0 },
        disable_wasd = true,
        disable_arrow_keys = true,
        joystick_id = 1,
        dynamic_position = true,
        always_show = true,
        radius = 150,
        active_area_offset = {
            left = 500,
            right = 50,
            top = 500,
            bottom = 50,
            debug_draw_color = { r = 0, g = 1, b = 0, a = 0.5 },
        },
        handle_icon = DCEI.Texture("icon_arrow"),
        handle_icon_color = { r = 1, g = 0, b = 0, a = 0.5 },
        background_icon = DCEI.Texture("general_icon_wildsky_mall_light_circle"),
        background_icon_color = { r = 1, g = 0, b = 0, a = 0.5 },
        handle_rotation = true,
        parent = frame,
    }

    DCEI.TriggerAddJoystickEventWithJoystickOptions(OnJoystickMove, joystick_options)
end

CreateJoystick()

void TriggerAddJoystickTapEvent(TypedCallback trigger, int joystickId, float validDuration, float validRadius)

void TriggerAddJoystickTapEvent(TypedCallback trigger, int joystickId, float validDuration, float validRadius)

Description

This event triggers when a joystick is tapped.

Parameters

TypedCallback trigger the trigger to run when this event occurs.
int joystickId the ID of the joystick to register the event for.
float validDuration the time window where interacting with the joystick will register as a tap. This is also the time window before the joystick will accept input regularly. If the joystick tap location exits the deadzone given in the next parameter, this duration will immediately end.
float validRadius the deadzone where interacting with the joystick will register as a tap. Accepted values are from 0-1, corresponding to the radius of the joystick (measured from the center). Tapping the joystick outside this deadzone will not trigger the event.

Example Usage

function OnJoystickTap()
    DCEI.LogMessage("Joystick Tapped: " .. DCEI.TriggeringJoystickId)
end

DCEI.TriggerAddJoystickEventWithJoystickOptions(OnJoystickMove, joystickOptions)
DCEI.TriggerAddJoystickTapEvent(OnJoystickTap, 0, 0.25, 0.5)

void TriggerAddJoystickSwipeEvent(TypedCallback trigger, int joystickId, float validDuration)

void TriggerAddJoystickSwipeEvent(TypedCallback trigger, int joystickId, float validDuration)

Description

This event triggers when a joystick is swiped.

Parameters

TypedCallback trigger the trigger to run when this event occurs.
int joystickId the ID of the joystick to register the event for.
float validDuration the time window where interacting with the joystick will register as a swipe. This time window starts counting when the joystick is interacted with, even if it is within the deadzone of a TriggerAddJoystickTapEvent.

Example Usage

function OnJoystickTap()
    DCEI.LogMessage("Joystick Tapped: " .. DCEI.TriggeringJoystickId)
end

DCEI.TriggerAddJoystickEventWithJoystickOptions(OnJoystickMove, joystickOptions)
DCEI.TriggerAddJoystickSwipeEvent(OnJoystickSwipe, 0, 1)

void TriggerAddJoystickReleaseEvent(TypedCallback trigger)

void TriggerAddJoystickReleaseEvent(TypedCallback trigger)

Description

This event triggers when a joystick is released.

Parameters

TypedCallback trigger the trigger to run when this event occurs.

Example Usage

function OnJoystickRelease()
    DCEI.LogMessage("Joystick Released: " .. DCEI.TriggeringJoystickId)
end
DCEI.TriggerAddJoystickReleaseEvent(OnJoystickRelease)

void TriggerAddJoystickReleaseEventWithId(TypedCallback trigger, int joystickId)

void TriggerAddJoystickReleaseEventWithId(TypedCallback trigger, int joystickId)

Description

This event triggers when the given joystick is released.

Parameters

TypedCallback trigger the trigger to run when this event occurs.
int joystickId the ID of the joystick to register the event for.

Example Usage

DCEI.TriggerAddJoystickReleaseEventWithId(OnJoystickRelease, 0)

function OnJoystickRelease()
    DCEI.LogMessage("Joystick Released: " .. DCEI.TriggeringJoystickId)
end

void TriggerAddTextCommandEvent(TypedCallback<string> trigger)

void TriggerAddTextCommandEvent(TypedCallback<string> trigger)

Description

This event triggers when a text command is entered.

Parameters

TypedCallback<string> trigger the callback function for the chat command. Parameter text_command is the text command entered.

Callback Parameters

String command

Example Usage

DCEI.TriggerAddTextCommandEvent(OnTextCommand)

function OnTextCommand(text_command)
    DCEI.ShowFeedbackMessage(text_command)
end

void TriggerAddMappedKeyDownEvent(string keyEventName, TypedCallback<string> trigger)

void TriggerAddMappedKeyDownEvent(string keyEventName, TypedCallback<string> trigger)

Description

This event triggers when the corresponding key is pressed. Key mappings are defined in input settings.

Parameters

string keyEventName the mapped key event that will trigger this event.
TypedCallback<string> trigger the trigger to run when this event occurs.

Callback Parameters

String key event name

Example Usage

function OnPressKeyShoot()
  -- shoot a projectile
end

-- for a key mapped to the name "Shoot"
DCEI.TriggerAddMappedKeyDownEvent("Shoot", OnPressKeyShoot)

void TriggerAddMappedKeyUpEvent(string keyEventName, TypedCallback<string> trigger)

void TriggerAddMappedKeyUpEvent(string keyEventName, TypedCallback<string> trigger)

Description

This event triggers when the corresponding key is released. Key mappings are defined in input settings.

Parameters

string keyEventName the mapped key event that will trigger this event.
TypedCallback<string> trigger the trigger to run when this event occurs.

Callback Parameters

String key event name

Example Usage

function OnReleaseKeyShoot()
  -- shoot a projectile
end

-- for a key mapped to the name "Shoot"
DCEI.TriggerAddMappedKeyUpEvent("Shoot", OnReleaseKeyShoot)

TriggerHandle TriggerAddOnMouseWorldPositionTrackingEvent(TypedCallback<int, Float2> trigger)

TriggerHandle TriggerAddOnMouseWorldPositionTrackingEvent(TypedCallback<int, Float2> trigger)

Description

Tracks mouse position every frame when StartMouseTracking is called. StopMouseTracking will end it.

Parameters

TypedCallback<int, Float2> trigger function to run when event is called

Callback Parameters

Int32 player_id
Float2 mouse_position

Example Usage

function OnMouseTracking(player_id, mouse_position)
    local current_mouse_position = mouse_position --current mouse position
end
TriggerAddOnMouseWorldPositionTrackingEvent(OnMouseTracking)

void StartMouseTracking(int playerId)

void StartMouseTracking(int playerId)

Description

Start tracking mouse. Notice this is very costy especially in multiplayer mode. So only use it for short time (follow mouse laser for example)

Parameters

int playerId id of player to track

Example Usage

DCEI.StartMouseTracking(1)
DCEI.TriggerAddOnMouseTrackingEvent(MouseTrack)

function MouseTrack(player_id, position)
    if game.mouse_down then
        game.player_mouse_pos = position or DCEI.GetMousePosition2D()
    end
end

void StopMouseTracking(int playerId)

void StopMouseTracking(int playerId)

Description

Stop mouse tracking for certain player.

Parameters

int playerId id of player to track

Example Usage

DCEI.StartMouseTracking(1)
DCEI.TriggerAddOnMouseTrackingEvent(MouseTrack)

function MouseTrack(player_id, position)
    if game.mouse_down then
        game.player_mouse_pos = position or DCEI.GetMousePosition2D()
    end
end

DCEI.Wait(10)

DCEI.StopMouseTracking(1)

void SetBackButton(TypedCallback callback)

void SetBackButton(TypedCallback callback)

Description

This event triggers when the back button on mobile devices is used.

Parameters

TypedCallback callback lua function to run when the back button is pressed.

Example Usage

function OnBackButton()
    DCEI.LogMessage("Back Button pressed.")
end

DCEI.SetBackButton(OnBackButton)

void SetOnMouseEnterCallback(InGameUILayoutComponent ui, TypedCallback trigger)

void SetOnMouseEnterCallback(InGameUILayoutComponent ui, TypedCallback trigger)

Description

Parameters

InGameUILayoutComponent ui the UI frame that will trigger the mouse enter callback.
TypedCallback trigger the callback function for when the mouse enters the ui frame.

Example Usage

local button = DCEI.CreateButtonFrame(DCEI.GetUiRootFrame())
DCEI.SetFrameSize(button, 100, 100)
DCEI.SetOnMouseEnterCallback(button, function()
    DCEI.LogMessage("Mouse has entered button")
end)

void SetOnMouseExitCallback(InGameUILayoutComponent ui, TypedCallback trigger)

void SetOnMouseExitCallback(InGameUILayoutComponent ui, TypedCallback trigger)

Description

Parameters

InGameUILayoutComponent ui the UI frame that will trigger the mouse exit callback.
TypedCallback trigger the callback function for when the mouse leaves the ui frame.

Example Usage

local button = DCEI.CreateButtonFrame(DCEI.GetUiRootFrame())
DCEI.SetFrameSize(button, 100, 100)
DCEI.SetOnMouseExitCallback(button, function()
    DCEI.LogMessage("Mouse has left button")
end)

void SetOnDownCallback(InGameUILayoutComponent ui, object callback)

void SetOnDownCallback(InGameUILayoutComponent ui, object callback)

Description

This event triggers when the given button is pressed down. This can feel more responsive than SetOnUpCallback.

Parameters

InGameUILayoutComponent ui the button that triggers the event.
object callback the callback function that is called when the event is triggered.

Example Usage

local button = DCEI.CreateButtonFrame(DCEI.GetUiRootFrame())
DCEI.SetFrameSize(button, 100, 100)
DCEI.SetOnDownCallback(
    button, 
    function()    
        DCEI.LogMessage("Button is pressed down")
    end
)

CreateButtonFrame()

void SetOnUpCallback(InGameUILayoutComponent ui, object callback)

void SetOnUpCallback(InGameUILayoutComponent ui, object callback)

Description

This event triggers when the given button press is released. This is functionally similar to SetOnClickCallback but the event will fire regardless of input position when the button is released.

This can be combined with SetOnDownCallback to make something happen when a button is held down.

Parameters

InGameUILayoutComponent ui the button that triggers the event.
object callback the callback function that is called when the event is triggered.

Example Usage

local button = DCEI.CreateButtonFrame(DCEI.GetUiRootFrame())
DCEI.SetFrameSize(button, 100, 100)
DCEI.SetOnUpCallback(
    button, 
    function()    
        DCEI.LogMessage("Button is released")
    end
)

CreateButtonFrame()

void SetOnClickCallback(InGameUILayoutComponent ui, object callback)

void SetOnClickCallback(InGameUILayoutComponent ui, object callback)

Description

This event triggers when the specified UI button frame is clicked. This is functionally similar to DCEI.SetOnUpCallback() with one key difference--this event will only fire if the input position is still over the button when released.

Parameters

InGameUILayoutComponent ui the button that triggers the event.
object callback the callback function that is called when the event is triggered.

Example Usage

local button = DCEI.CreateButtonFrame(DCEI.GetUiRootFrame())
DCEI.SetFrameSize(button, 100, 100)
DCEI.SetOnClickCallback(
    button, 
    function()    
        DCEI.LogMessage("Button is clicked")
    end
)

CreateButtonFrame()

void SetTextLinkOnClickCallback(InGameUILayoutComponent ui, string linkId, object callback)

void SetTextLinkOnClickCallback(InGameUILayoutComponent ui, string linkId, object callback)

Description

Parameters

Example Usage

void SetOnClickOutsideCallback(InGameUILayoutComponent ui, object callback)

void SetOnClickOutsideCallback(InGameUILayoutComponent ui, object callback)

Description

Registers a callback to run when a click/touch happens outside of the specified UI frame while the frame is active. Unlike DCEI.SetOnClickCallback(), this API works on any frame type. You can enable "Custom UI Inspector" in the in-game dev panel to check what UI frames are under the current mouse position to better understand what's considered outside of a frame by the engine.

Parameters

InGameUILayoutComponent ui the ui that triggers the event.
object callback the callback function that is called when the event is triggered.

Example Usage

local button = DCEI.CreateButtonFrame(DCEI.GetUiRootFrame())
DCEI.SetFrameSize(button, 100, 100)
DCEI.SetOnClickOutsideCallback(
    button, 
    function()    
        DCEI.LogMessage("Somewhere besides the button has been clicked")
    end
)

void SetPauseMenuCallback(TypedCallback<bool> callback)

void SetPauseMenuCallback(TypedCallback<bool> callback)

Description

This event is triggered when a custom pause menu is opened or closed. Setting this callback will overwrite the default pause menu functionality of stopping game time, so you will need to re-add that in your own implementation if desired.

Parameters

TypedCallback<bool> callback the callback function that is called when the pause menu is opened or closed.

Callback Parameters

Boolean pause

Example Usage

-- create a custom pause menu
local menu = DCEI.CreateFrame(DCEI.GetUiRootFrame())
DCEI.SetFrameSize(menu, 400, 600)
DCEI.SetFrameImage(menu, DCEI.Texture("frame01_purple"))
DCEI.SetPauseMenuFrame(menu)

-- the pause menu is inactive by default but we can update it safely with UpdateFrame
DCEI.UpdateFrame(
    menu,
    function()
        local resume_button = DCEI.CreateButtonFrame(menu)
        DCEI.SetFrameSize(resume_button, 200, 100)
        DCEI.SetOnClickCallback(
            resume_button, 
            function()
                DCEI.HidePauseMenuFrame(menu)
            end
        )
    end
)

-- create a custom pause menu button
local pause_button = DCEI.CreateButtonFrame(DCEI.GetUiRootFrame())
DCEI.SetFrameImage(pause_button, DCEI.Texture("btn_red"))
DCEI.SetFrameTopAlignmentInParent(pause_button)
DCEI.SetFrameLeftAlignmentInParent(pause_button)
DCEI.SetFrameSize(pause_button, 200, 200)

-- hookup the pause menu button callback
DCEI.SetOnClickCallback(
    pause_button,
    function()
        DCEI.ShowPauseMenuFrame(menu)
    end
)

-- add custom pause menu callback
DCEI.SetPauseMenuCallback(
    function(pause)
        if pause then
            Core.GameSpeed.Set(0)
        else
            Core.GameSpeed.Set(1)
        end
    end
)