Skip to content

Features guide

How to use the /interactions panel of Cuxial Interactions: NPCs, dialogues, button actions, shops, limits and conditions.

The /interactions panel is where staff build every NPC of the server without touching files. What you save is stored in the database and reaches every connected player at once.

The list ​

The first screen lists every NPC created in the panel, with its status, category, whether it has a shop or a blip, and a warning when one of its actions points at a resource that is not started.

ControlWhat it does
SearchFilters by name, id or model.
FiltersAll, active or off, and by category.
NewCreates an NPC at your current position. You choose its id, which cannot be changed later.
GoTeleports you to the NPC.
MarkSets a waypoint on the NPC.
SwitchTurns the NPC on or off for everyone. An NPC that is off is not visible to anyone.
DuplicateCopies the NPC with a new id. The copy starts switched off.
Export SQLGives two SQL lines that install this NPC on another server. Paste them at the end of the seed file (seed.file) of that server.
DeleteRemoves the NPC for everyone. A deleted NPC is not installed again from the seed.

Two more views sit next to the list:

  • From scripts. NPCs and shops registered by other resources through the exports. They are read only: edit them in their own resource.
  • Import. The rows installed from the seed file, with their status. An NPC whose conversion lost something shows it in "To review" until you mark it as reviewed.

Editing an NPC ​

The editor has six tabs. Nothing changes in the world until you press Save. If another staff member saved the same NPC while you were editing, the panel warns you: reload to see their version, or copy your changes first.

General ​

FieldWhat it does
IdLetters, numbers, _ and -, up to 64 characters. Fixed after creation.
TextText of the target option. Empty shows "Talk".
CategoryFree label to group NPCs in the list.
ActiveSwitches the NPC on or off.
Internal noteOnly visible in the panel.
How it triggersTarget, sprite (key prompt, needs bl_sprites) or none. With none the NPC only opens from a script through the Interact export.
Target iconFont Awesome class of the target option. Empty uses target.icon.
DistanceMetres from which the player can interact.
Camera while talkingFocuses the NPC's face during the dialogue.

NPC ​

SectionWhat you set
PositionCoordinates and heading. Here takes your position. Place opens a gizmo to move and rotate the NPC (needs object_gizmo).
NPCType: a model, a player skin (the look of a random active character, with a model as fallback) or no NPC (a target zone at the position).
IdleStill, a scenario, or an animation with dictionary, clip, speed, blend out, duration and flag.
BehaviourInvincible, frozen, ignores what happens around.
ClothingComponent, drawable and texture per piece. Copy my outfit fills it with what you wear. Ignored when a player skin is applied.
Map blipSprite, colour, scale, name and whether it is only shown at short range.
Spawn distanceMetres at which the ped is created.

Preview spawns the NPC in front of you with the current draft, so you can check model, clothing and idle before saving.

Dialog ​

Pages are shown one at a time; the page marked as initial opens first. Defaults sets the name, title and icon used by every page that leaves them empty. Each page has its id, the NPC name and title, the text, the typing speed and up to admin.limits.buttons buttons (9 by default).

Each button has a text, an icon, its own conditions and a list of actions, run in order:

ActionWhat it does
Go to pageShows another page of the dialogue.
Close dialogCloses the window.
Open shopOpens the shop of this NPC. Needs the shop switched on in its tab.
NPC speechPlays a speech line on the NPC (GENERIC_HI, GENERIC_BYE...).
TeleportMoves the player to some coordinates, with an optional fade to black.
CommandRuns a command as the player, with their own permissions. Written without /.
Client exportCalls exports[resource]:name(...) on the player's client.
Client eventTriggers a client event on the player's client.
Server exportCalls exports[resource]:name(source, ...) on the server.
Server eventTriggers a local server event; the handler receives the player first.
ReviveRevives the player for a fee: cost, account and whether to ignore the paramedics on duty.

A button can hold only one action that changes or closes the window (go to page, close or open shop). The arguments of exports and events are written as JSON. Client exports and events can also append the context { id, dialogId, buttonId, entity } at the end.

Test runs an export, event or command action from the panel, so you can check it without talking to the NPC.

Fields asked to the player ​

A command, export or event action can ask the player for up to four values before it runs: text or number, with label, placeholder, minimum, maximum and whether it is required. Only one action per button can ask for fields.

The values are checked on the server (text trimmed to actions.inputLength characters without line breaks, numbers inside their range) and appended at the end of the saved arguments, in order. In a command they are appended separated by spaces, and cannot contain ; or ". An empty optional field arrives as ''. If the player cancels, nothing runs.

Shop ​

Switching the shop on lets the dialogue open it with the "Open shop" action. With no pages in the dialogue, talking to the NPC opens the shop directly.

FieldWhat it does
Name, title, iconHeader of the shop.
Shop idEmpty uses the id of the NPC.
AccountAccount the money goes to or comes from. Default uses shop.account. The list comes from admin.accounts.
DistanceMetres from the NPC within which the server accepts a trade. 0 uses shop.maxDistance.
Default modePlayer sells (the NPC pays) or Player buys (the NPC charges). Used by the items set to "Default".
ItemsItem, mode, price, name and image. Empty name and image take those of the inventory. The same item can be in both modes with different prices.
Shop limitsLimits that count every item of the shop together.

Reset limits deletes the records of this shop for every player.

Limits ​

Each item and the whole shop can have up to admin.limits.limits limits (4 by default). A limit has:

FieldValues
AmountWhole number from 1 to 1 000 000.
Window15 min, 1 hour, 6 hours, 1 day, 1 week, or any number of minutes up to limits.maxWindow.
ScopePer player (each character has its own count) or Global (shared by all players; works as stock).
MeasureUnits or Money moved.
ModeOnly in shop limits: both, when buying or when selling.

Windows slide: "30 / 1 day" means 30 in the last 24 hours, not 30 per calendar day. The shop shows the player how many are left and, when the limit is reached, how long until it frees up.

Conditions ​

Players who do not meet them do not see the NPC. The server checks them again on every button, purchase, sale and revive.

ConditionHow it works
JobsEmpty means anyone. One match is enough. Each job can require a minimum grade.
ItemsThe player must carry every item on the list, each with a minimum amount.
ScheduleHours from and to, by game time or real time, and days of the week. None selected means every day. The same hour in from and to means open 24 h.

Buttons have the same conditions, set in the button itself.

Advanced ​

SectionWhat it does
Extra dataJSON object passed as-is to scripts in ctx.extraData.
HistoryWho created, edited, switched, duplicated, tested or reset each NPC and when. Kept for admin.auditDays days.
To reviewWhat the seed conversion could not carry over. Rebuild it with actions and press Mark reviewed.
ToolsDuplicate, export SQL and delete.

How buttons run ​

Buttons that only change page, close or play a speech line, and have no conditions, run on the player's client at once. Every other button goes through the server, which checks that the NPC has not changed since the window opened, the distance, the conditions and a per-player cooldown (actions.cooldown). Then it runs the server actions with the player's source and sends back the client steps. The client never decides what runs.

Server exports are called while the player's lock is held. Make them answer fast and never wait for something from the client. An export that returns false counts as a failure.

What the player sees in a shop ​

ElementWhat it does
Buy / Sell tabsShown when the shop has items in both modes.
BalanceMoney in the shop account, when buying.
QuantityUp to the units the player carries when selling, and never more than shop.maxQuantity per trade.
Left / Sold outRemaining amount of the limit that restricts the most.
BackReturns to the dialogue, when the shop was opened from a button.

© Cuxial