Prompts

Create easy to use prompts for your REDM resource.

Example

Notes

The order of created prompts is the order of showing them (top to bottom).
If you show multiple groups at the same time then pages/tabs are created automatically.
If you use multiple keys per prompt then hold/hold complete modes are not supported.
Consider how many pages/tabs are able to shown at the same time by the client.
Consider how many prompts per page/tab are able to shown at the same time by the client.
If your resource stops or restarts all groups and prompts are automatically destroyed.
Per default prompt groups are not shown during the player is dead. You can change this with showOnDeath().

------------------------------------------------------------------------------
-- Step 1: Get Prompts API
------------------------------------------------------------------------------

---@type NssLibsPromptsApi
local prompts_api = exports.nss_libs:getPromptsApi(GetCurrentResourceName())

------------------------------------------------------------------------------
-- Step 2: Create a group (page/tab) of prompts
------------------------------------------------------------------------------

---@type NssLibsPromptsGroupApi
local group = prompts_api.createGroup('GROUP_LABEL')

------------------------------------------------------------------------------
-- Step 3A: Create Prompt with one key
------------------------------------------------------------------------------

local SPACEBAR = 0xD9D0E1C0

---@type NssLibsPromptsPromptApi
local prompt_spacebar = group.addJustPressedPrompt('PROMPT_LABEL', SPACEBAR, function()
    print('Spacebar just pressed')
    -- DO YOUR STUFF HERE
end)

------------------------------------------------------------------------------
-- Step 3B: Create Prompt with multiple keys
------------------------------------------------------------------------------

local KEY_LEFT = 0xA65EBAB4
local KEY_RIGHT = 0xDEB34313

---@type NssLibsPromptsPromptApi
local prompt_left_right = group.addJustPressedPrompt('PROMPT_LABEL', KEY_LEFT, function()
    print('Left just pressed')
    -- DO YOUR STUFF HERE
end)

prompt_left_right:addKey(KEY_RIGHT, function()
    print('Right just pressed')
    -- DO YOUR STUFF HERE
end)

------------------------------------------------------------------------------
-- Step 3C: Create Prompt with on-press and on-release callbacks
------------------------------------------------------------------------------

-- This example works only with addJustPressedPrompt, addPressedPrompt,
-- addStandardHoldPrompt, addStandardizedHoldPrompt and only safe for single key prompts.

local KEY_DOWN = 0x05CA7C52

local on_press = function()
    print('Down key pressed')
    -- DO YOUR STUFF HERE
end

local on_release = function()
    print('Down key released')
    -- DO YOUR STUFF HERE
end

---@type NssLibsPromptsPromptApi
local prompt_down = group.addJustPressedPrompt('PROMPT_LABEL', KEY_DOWN, on_press, on_release)

------------------------------------------------------------------------------
-- Step 4: Show the group ;)
------------------------------------------------------------------------------
group.show()

Methods

`exports.nss_libs:getPromptsApi(resource_name)`

Returns a prompts API NssLibsPromptsApi for the given resource.

resource_name - The name of the resource that wants to use the API.

`NssLibsPromptsApi`

`.createGroup(label)`

Returns a group API NssLibsPromptsGroupApi.

label - The label of the group.

`.setLinkChunkModeNearest()`

Affects only NssLibsPromptsGroupApi.linkToCoords.

Sets the reaction mode for chunk grid linked prompt groups to nearest. Only the nearest result will be shown.

Returns NssLibsPromptsApi.

`.setLinkChunkModeAll()`

Affects only NssLibsPromptsGroupApi.linkToCoords.

Sets the reaction mode for chunk grid linked prompt groups to all. All results will be shown.

This is the default mode.

Returns NssLibsPromptsApi.

`colors` (table)

Table of color functions. Each function has an optional str attribute. If str is not given only the color code will be returned.

colors.Red(str)
colors.Yellow(str)
colors.Orange(str)
colors.Grey(str)
colors.White(str)
colors.LightGrey(str)
colors.Black(str)
colors.Pink(str)
colors.Blue(str)
colors.Purple(str)
colors.LightBlue(str)
colors.Yellow(str)
colors.LightPink(str)
colors.Green(str)
colors.DarkBlue(str)
colors.LightRedIsh(str)

`NssLibsPromptsGroupApi`

`.addJustPressedPrompt(label, key, callback, release_callback)`

Returns a prompt API NssLibsPromptsPromptApi. Calls the callback if the key is just pressed.

label - The label of the prompt.
key - The key of the prompt (see key names and hashes or named keys)
callback - The callback of the prompt.
release_callback (optional) - Change the behaviour: If set then the callback will be fired if key is pressed like an on press event and release_callback is fired if key is released.

`.addJustReleasedPrompt(label, key, callback)`

Like addJustPressedPrompt but executes the callback if the key is just released.

`.addPressedPrompt(label, key, callback, release_callback)`

Like addJustPressedPrompt but executes the callback if the key is pressed.

`.addReleasedPrompt(label, key, callback)`

Like addJustPressedPrompt but executes the callback if the key is released.

`.addStandardHoldPrompt(label, key, callback, release_callback)`

Like addJustPressedPrompt but executes the callback repeatedly while the button has been pressed since the start pressing if no release_callback is set.

If the release_callback is set then the callback will be fired only once after the button indicator is filled (like a press event with delay to prevent press by mistake). If you want this behaviour and do not want to use the release_callback for actions then use an empty function for release_callback, see example:

---------------------------------------------------------------------------------------------
-- Delayed press event example
---------------------------------------------------------------------------------------------

local SPACEBAR = 0xD9D0E1C0

local callback = function()
    print('Spacebar pressed after delay')
    -- DO YOUR STUFF HERE
end

local release_callback = function()
    -- Do nothing
end

---@type NssLibsPromptsPromptApi
local prompt_spacebar = group.addStandardHoldPrompt('PROMPT_LABEL', SPACEBAR, callback, release_callback)

Important If you use multiple keys per prompt then "hold"/"hold complete" modes are not supported.

`.addStandardizedHoldPrompt(label, key, callback, release_callback)`

Like addJustPressedPrompt but executes the callback if the key is standardized hold.

Important If you use multiple keys per prompt then "hold"/"hold complete" modes are not supported.

`.setLabel(label)`

Sets the label of the group.

label - The label of the group.

`.show()`

Shows the group.

If multiple groups are shown at the same time then pages/tabs are created automatically.

`.hide()`

Hides the group.

`.destroy()`

Destroys the group and all it's prompts. This group is never usable again.

`.showOnDeath()`

Shows the group during the player is dead, too.

`.linkToCoords(x, y, z, radius)`

Add logic to show/hide prompt group if player reaches radius of given coords.

x (number) - The x coordinate of the coords.
y (number) - The y coordinate of the coords.
z (number) - The z coordinate of the coords.
radius (number) - The radius of the coords.

Returns NssLibsPromptsLinkerGroupToCoordsApi.

------------------------------------------------------------------------------
-- Step 1-3: Get API and create group and prompt
------------------------------------------------------------------------------
---@type NssLibsPromptsApi
local prompts_api = exports.nss_libs:getPromptsApi(GetCurrentResourceName())

---@type NssLibsPromptsGroupApi
local group = prompts_api.createGroup('GROUP_LABEL')

local SPACEBAR = 0xD9D0E1C0

---@type NssLibsPromptsPromptApi
local prompt_spacebar = group.addJustPressedPrompt('PROMPT_LABEL', SPACEBAR, function()
    print('Spacebar just pressed')
    -- DO YOUR STUFF HERE
end)

------------------------------------------------------------------------------
-- Step 4: Link to coords
------------------------------------------------------------------------------
local x = 0.0
local y = 0.0
local z = 0.0
local radius = 2.0

---@type NssLibsPromptsLinkerGroupToCoordsApi
local linker_api = group.linkToCoords(x, y, z, radius)

------------------------------------------------------------------------------
-- Step 5: Activate link
------------------------------------------------------------------------------
linker_api.activate()

`.linkToEntity(entity_id, radius, inject_entity_id_cb)`

Add logic to show/hide prompt group if player reaches radius of given entity.

entity_id (number) - The entity id of the entity.
radius (number) - The radius of the coords.
inject_entity_id_cb (function, optional) - A callback that injects/returns the entity id each time the script checks the distance.

Returns NssLibsPromptsLinkerGroupToCoordsApi.

------------------------------------------------------------------------------
-- Step 1-3: Get API and create group and prompt
------------------------------------------------------------------------------
---@type NssLibsPromptsApi
local prompts_api = exports.nss_libs:getPromptsApi(GetCurrentResourceName())

---@type NssLibsPromptsGroupApi
local group = prompts_api.createGroup('GROUP_LABEL')

local SPACEBAR = 0xD9D0E1C0

---@type NssLibsPromptsPromptApi
local prompt_spacebar = group.addJustPressedPrompt('PROMPT_LABEL', SPACEBAR, function()
    print('Spacebar just pressed')
    -- DO YOUR STUFF HERE
end)

------------------------------------------------------------------------------
-- Step 4: Link to entity
------------------------------------------------------------------------------
local entity_id = 12 -- Example entity
local radius = 2.0

-- Optional callback
-- Sometimes entity ids changes because entity was out of sight, so this callback injects the current entity id.
local inject_entity_id_cb = function()
    -- You can inject the entity id here
    return 14 -- Example of changed entity id 
end

---@type NssLibsPromptsLinkerGroupToCoordsApi
local linker_api = group.linkToEntity(entity_id, radius, inject_entity_id_cb)

------------------------------------------------------------------------------
-- Step 5: Activate link
------------------------------------------------------------------------------
linker_api.activate()

`.linkToEntityModels(model_names_or_hashes, radius)`

Add logic to show/hide prompt group if player reaches radius of given entity.

model_names_or_hashes (number|string|table<string|number>) - The model name(s) or hash(es) of the entity/entities.
radius (number) - The radius of the coords.

Returns NssLibsPromptsLinkerGroupToCoordsApi.

------------------------------------------------------------------------------
-- Step 1-3: Get API and create group and prompt
------------------------------------------------------------------------------
---@type NssLibsPromptsApi
local prompts_api = exports.nss_libs:getPromptsApi(GetCurrentResourceName())

---@type NssLibsPromptsGroupApi
local group = prompts_api.createGroup('GROUP_LABEL')

local SPACEBAR = 0xD9D0E1C0

---@type NssLibsPromptsPromptApi
local prompt_spacebar = group.addJustPressedPrompt('PROMPT_LABEL', SPACEBAR, function()
    print('Spacebar just pressed')
    -- DO YOUR STUFF HERE
end)

------------------------------------------------------------------------------
-- Step 4: Link to entity models
------------------------------------------------------------------------------
local entity_herbs_model_hashes = { 477619010, 85102137, -1707502213 } -- Some bushes
local radius = 2.0

---@type NssLibsPromptsLinkerGroupToCoordsApi
local linker_api = group.linkToEntityModels(entity_herbs_model_hashes, radius)

------------------------------------------------------------------------------
-- Step 5: Activate link
------------------------------------------------------------------------------
linker_api.activate()

`.linkToPlayer(player_server_id, radius)` (not working currently)

Add logic to show/hide prompt group if player reaches radius of given player.

player_server_id (number) - The server id of the player.
radius (number) - The radius of the coords.

Returns NssLibsPromptsLinkerGroupToCoordsApi.

`.disable()` / `.enable()`

Disables/enables all prompts of the group.

Returns NssLibsPromptsGroupApi.

`.allowOnMount()` / `.forbidOnMount()`

Allows/forbids all prompts of the group to be shown while player is mounted.

Returns NssLibsPromptsGroupApi.

`.allowInWater()` / `.forbidInWater()`

Allows/forbids all prompts of the group to be shown while player is in water.

Returns NssLibsPromptsGroupApi.

`.allowInVehicle()` / `.forbidInVehicle()`

Allows/forbids all prompts of the group to be shown while player is in vehicle.

Returns NssLibsPromptsGroupApi.

`.allowOnFloor()` / `.forbidOnFloor()`

Allows/forbids all prompts of the group to be shown while player is on floor.

Returns NssLibsPromptsGroupApi.

`.allowInAir()` / `.forbidInAir()`

Allows/forbids all prompts of the group to be shown while player is in air.

Returns NssLibsPromptsGroupApi.

`.allowDuringDeath()` / `.forbidDuringDeath()`

Allows/forbids all prompts of the group to be shown while player is dead.

Returns NssLibsPromptsGroupApi.

`.allowDuringMovement()` / `.forbidDuringMovement()`

Allows/forbids all prompts of the group to be shown while player is moving.

Returns NssLibsPromptsGroupApi.

`.setMovementDetectionSensitivity(sensitivity_in_meters)`

New since version 0.29.0
sensitivity_in_meters (float) - The sensitivity in meters for movement measuring. Default is 0.005.

Returns NssLibsPromptsGroupApi.

group.forbidDuringMovement() -- Enables the prompts only on stand still
group.setMovementDetectionSensitivity(0.5) -- Set the movement sensitivity to 0.5 meters. If the player moves more than 0.5 meters in any direction then the prompts are disabled.

`.allowDuringHogtied()` / `.forbidDuringHogtied()`

Allows/forbids all prompts of the group to be shown while player is hogtied.

Returns NssLibsPromptsGroupApi.

`.setAllPromptsToStandardRestrictionsOnFoot()`

Set standard restrictions for all prompts of the group while player is on foot.

Returns NssLibsPromptsGroupApi.

`.showOnMovement()` / `.hideOnMovement()`

New since version 0.30.0

Show (default) / hides the group if it is usually visible and the player moves.

Returns NssLibsPromptsGroupApi.

`.isHideOnMovement()`

New since version 0.30.0

Returns true if the group should be hidden if it is usually visible but the player moves.

`NssLibsPromptsPromptApi`