nss_libs - 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().
---@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)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)-- 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) local KEY_E = 0xCEFD9220
---@type NssLibsPromptsPromptApi
local prompt_hold = group.addDuringPressedPrompt('HOLD ACTION', KEY_E, function()
-- Called every frame (or every interval_ms) while key is held
print('Still holding...')
end, {
on_press = function() print('Key pressed') end,
on_release = function() print('Key released') end,
interval_ms = 100, -- Fire every 100ms instead of every frame (0 = per frame)
})group.show()Methods
exports.nss_libs:getPromptsApi(resource_name)
| Param | Type | Default | Description |
|---|---|---|---|
resource_name | string | — | The name of the resource that wants to use the API |
Returns NssLibsPromptsApi — A prompts API for the given resource.
NssLibsPromptsApi
.createGroup(label)
| Param | Type | Default | Description |
|---|---|---|---|
label | string | — | The label of the group |
Returns NssLibsPromptsGroupApi — A group API.
.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?)
Calls the callback if the key is just pressed.
| Param | Type | Default | Description |
|---|---|---|---|
label | string | — | The label of the prompt |
key | number|string | — | The key of the prompt (see key names and hashes or named keys) |
callback | function | — | The callback of the prompt |
release_callback | function? | — | If set then callback fires on press and release_callback fires on release |
Returns NssLibsPromptsPromptApi
.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:
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)WARNING
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.
WARNING
If you use multiple keys per prompt then "hold"/"hold complete" modes are not supported.
.addDuringPressedPrompt(label, key, during_pressed_callback, options?)
Creates a prompt that repeatedly fires a callback while the key is held down. Useful for continuous actions like chopping, fishing, or filling progress bars.
| Param | Type | Default | Description |
|---|---|---|---|
label | string | — | The label of the prompt |
key | number|string | — | The key of the prompt (see key names and hashes or named keys) |
during_pressed_callback | function | — | Called repeatedly while the key is held |
options | NssLibsDuringPressedOptions? | — | Configuration table (see below) |
Options (NssLibsDuringPressedOptions):
| Param | Type | Default | Description |
|---|---|---|---|
on_press | function? | — | Called once when the key is first pressed |
on_release | function? | — | Called once when the key is released |
interval_ms | number? | 0 | Interval in ms between during_pressed_callback calls. 0 means every frame |
Returns NssLibsPromptsPromptApi
local KEY_E = 0xCEFD9220
group.addDuringPressedPrompt('Fill', KEY_E, function()
progress = progress + 1
end, {
on_press = function()
progress = 0
print('Started filling')
end,
on_release = function()
print('Stopped filling at ' .. tostring(progress))
end,
})group.addDuringPressedPrompt('Reel In', KEY_E, function()
reel_in_one_step()
end, {
interval_ms = 200,
on_press = function()
start_fishing_animation()
end,
on_release = function()
stop_fishing_animation()
end,
}).setLabel(label)
Sets the label of the group.
| Param | Type | Default | Description |
|---|---|---|---|
label | string | — | 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 its 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.
| Param | Type | Default | Description |
|---|---|---|---|
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
---@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')
end)
local x, y, z, radius = 0.0, 0.0, 0.0, 2.0
---@type NssLibsPromptsLinkerGroupToCoordsApi
local linker_api = group.linkToCoords(x, y, z, radius)
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.
| Param | Type | Default | Description |
|---|---|---|---|
entity_id | number | — | The entity id of the entity |
radius | number | — | The radius of the coords |
inject_entity_id_cb | function? | — | A callback that injects/returns the entity id each time the script checks the distance |
Returns NssLibsPromptsLinkerGroupToCoordsApi
---@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')
end)
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()
return 14 -- Example of changed entity id
end
---@type NssLibsPromptsLinkerGroupToCoordsApi
local linker_api = group.linkToEntity(entity_id, radius, inject_entity_id_cb)
linker_api.activate().linkToEntityModels(model_names_or_hashes, radius)
Add logic to show/hide prompt group if player reaches radius of given entity.
| Param | Type | Default | Description |
|---|---|---|---|
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
---@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')
end)
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)
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.
| Param | Type | Default | Description |
|---|---|---|---|
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.
WARNING
This affects only existing prompts during the call. If you add new prompts after the call then the new prompts are not affected by this call.
Returns NssLibsPromptsGroupApi
.allowInWater() / .forbidInWater()
Allows/forbids all prompts of the group to be shown while player is in water.
WARNING
This affects only existing prompts during the call. If you add new prompts after the call then the new prompts are not affected by this call.
Returns NssLibsPromptsGroupApi
.allowInVehicle() / .forbidInVehicle()
Allows/forbids all prompts of the group to be shown while player is in vehicle.
WARNING
This affects only existing prompts during the call. If you add new prompts after the call then the new prompts are not affected by this call.
Returns NssLibsPromptsGroupApi
.allowOnFloor() / .forbidOnFloor()
Allows/forbids all prompts of the group to be shown while player is on floor.
WARNING
This affects only existing prompts during the call. If you add new prompts after the call then the new prompts are not affected by this call.
Returns NssLibsPromptsGroupApi
.allowInAir() / .forbidInAir()
Allows/forbids all prompts of the group to be shown while player is in air.
WARNING
This affects only existing prompts during the call. If you add new prompts after the call then the new prompts are not affected by this call.
Returns NssLibsPromptsGroupApi
.allowDuringDeath() / .forbidDuringDeath()
Allows/forbids all prompts of the group to be shown while player is dead.
WARNING
This affects only existing prompts during the call. If you add new prompts after the call then the new prompts are not affected by this call.
Returns NssLibsPromptsGroupApi
.allowDuringMovement() / .forbidDuringMovement()
Allows/forbids all prompts of the group to be shown while player is moving.
WARNING
This affects only existing prompts during the call. If you add new prompts after the call then the new prompts are not affected by this call.
Returns NssLibsPromptsGroupApi
.setMovementDetectionSensitivity(sensitivity_in_meters)
- New since version 0.29.0
| Param | Type | Default | Description |
|---|---|---|---|
sensitivity_in_meters | float | 0.005 | The sensitivity in meters for movement measuring |
TIP
The sensitivity is measured in all axis (x, y, z). So if the player stands in water or floats in the water then it is possible that a movement is detected if the player goes up and down by the waves of the water. In this case set the sensitivity to a higher value.
WARNING
This affects all current and future prompts of the group.
Returns NssLibsPromptsGroupApi
group.forbidDuringMovement() -- Enables the prompts only on stand still
group.setMovementDetectionSensitivity(0.5) -- Set sensitivity to 0.5 meters.allowDuringHogtied() / .forbidDuringHogtied()
Allows/forbids all prompts of the group to be shown while player is hogtied.
WARNING
This affects only existing prompts during the call. If you add new prompts after the call then the new prompts are not affected by this call.
Returns NssLibsPromptsGroupApi
.setAllPromptsToStandardRestrictionsOnFoot()
Set standard restrictions for all prompts of the group while player is on foot.
WARNING
This affects only existing prompts during the call. If you add new prompts after the call then the new prompts are not affected by this call.
Returns NssLibsPromptsGroupApi
.showOnMovement() / .hideOnMovement()
- New since version 0.30.0
Show (default) / hides the group if it is usually visible and the player moves.
TIP
This affects all current and future prompts of the group.
Returns NssLibsPromptsGroupApi
.isHideOnMovement()
- New since version 0.30.0
Returns boolean — true if the group should be hidden if it is usually visible but the player moves.
NssLibsPromptsPromptApi
.addKey(key, callback, release_callback?)
Adds additional key to the prompt.
| Param | Type | Default | Description |
|---|---|---|---|
key | number|string | — | The key of the prompt (see key names and hashes or named keys) |
callback | function | — | The callback of the prompt |
release_callback | function? | — | If set then callback fires on press and release_callback fires on release. Works only for specific prompt types |
WARNING
If you use multiple keys per prompt then hold/hold complete modes are not supported.
Returns NssLibsPromptsPromptApi
.setLabel(label)
Sets the label of the prompt.
| Param | Type | Default | Description |
|---|---|---|---|
label | string | — | The label of the prompt |
Returns NssLibsPromptsPromptApi
.enable()
Enables the prompt. This is the default state.
Returns NssLibsPromptsPromptApi
.disable()
Disables the prompt.
Returns NssLibsPromptsPromptApi
.show()
Shows the prompt. This is the default state.
Returns NssLibsPromptsPromptApi
.hide()
Hides the prompt.
Returns NssLibsPromptsPromptApi
.destroy()
Destroys the prompt. This prompt is never usable again.
.consumeGroupFrame(consume)
Controls whether this prompt "consumes" the group frame when fulfilled. If true (default), no other prompts in the group are checked after this prompt fires. If false, other prompts in the same group can also fire in the same frame.
| Param | Type | Default | Description |
|---|---|---|---|
consume | boolean | true | true to consume, false to allow other prompts to fire |
Returns NssLibsPromptsPromptApi
-- Allow multiple prompts to fire in the same frame
prompt_a.consumeGroupFrame(false)
prompt_b.consumeGroupFrame(false).executeCallbackInThread(execute_in_thread)
Controls whether the prompt callback runs in a new Citizen.CreateThread (default) or synchronously in the current frame. Synchronous execution avoids the one-frame delay but blocks the main loop during callback execution.
| Param | Type | Default | Description |
|---|---|---|---|
execute_in_thread | boolean | true | true for threaded, false for synchronous |
Returns NssLibsPromptsPromptApi
-- Run callback synchronously (no frame delay)
prompt.executeCallbackInThread(false).allowOnMount() / .forbidOnMount()
Allows/forbids the prompt to be shown while player is mounted.
Returns NssLibsPromptsPromptApi
.allowInWater() / .forbidInWater()
Allows/forbids the prompt to be shown while player is in water.
Returns NssLibsPromptsPromptApi
.allowInVehicle() / .forbidInVehicle()
Allows/forbids the prompt to be shown while player is in vehicle.
Returns NssLibsPromptsPromptApi
.allowOnFloor() / .forbidOnFloor()
Allows/forbids the prompt to be shown while player is on floor.
Returns NssLibsPromptsPromptApi
.allowInAir() / .forbidInAir()
Allows/forbids the prompt to be shown while player is in air.
Returns NssLibsPromptsPromptApi
.allowDuringDeath() / .forbidDuringDeath()
Allows/forbids the prompt to be shown while player is dead.
Returns NssLibsPromptsPromptApi
.allowDuringMovement() / .forbidDuringMovement()
Allows/forbids the prompt to be shown while player is moving.
Returns NssLibsPromptsPromptApi
.allowDuringHogtied() / .forbidDuringHogtied()
Allows/forbids the prompt to be shown while player is hogtied.
Returns NssLibsPromptsPromptApi
NssLibsPromptsLinkerGroupToCoordsApi
.activate()
Activates the linker.
Returns NssLibsPromptsLinkerGroupToCoordsApi
.deactivate()
Deactivates the linker. This is the default state.
Returns NssLibsPromptsLinkerGroupToCoordsApi
.isActive()
Returns boolean — true if the linker is active.
.destroy()
Destroy (removes) the link between group and coords.
Named keys
Instead of key hashes you can use key names since version v0.26.1 of nss_libs. The following key names are available:
- All alphabetical characters except
,K,N,T,Y,Ü,Ö, andÄß 1,2,3,4,5,6,7,8RIGHTBRACKET,LEFTBRACKETMOUSE1,MOUSE2,MOUSE3,MWUPCTRL,TAB,SHIFT,LALTSPACEBAR,ENTER,BACKSPACE,DELPGUP,PGDNF1,F4,F6DOWN,UP,LEFT,RIGHT
TIP
Sometimes keys not working as expected. This is a limitation of the game. In other cases the keys are used by other resources.
Dev notes
UiPromptHasHoldModeCompleted is currently tricky. It fires during the hold mode is fulfilled. But this is not so good if we have to check if the hold mode is fulfilled and when it was released after hold. So two callbacks, one for "hold started" and one for "hold stopped", are good.
