Technical reference

Capabilities and the adapter contract

Every capability: its side, arguments and what it returns.

A capability is one thing the studio and the project’s mechanics ask the server for, without naming a framework or a resource: “give an item”, “show a notification”. The adapter of a resource that can do it provides it (chapter What the project can do, your own adapter: Your own adapter).

Current contract version: 2. Adapters written for an earlier version keep working.

How an adapter provides a capability

An adapter is a folder adapters/<id>/ with adapter.json, server.lua and client.lua (the adapter.json format is on Project files). Its server and client lists say which capabilities it gives. The code registers them with StudioAdapter(id, { ['<capability>'] = function(...) end }).

A capability runs on one side. A server function gets the player’s server id (src) first, then the arguments from the tables below, in that order. A client function gets only the arguments.

Player

Capability Side Arguments Returns
player.get
Player character
server — { id, name, job { name, label, grade, gradeLabel, onDuty }, gang { … }, money { account: amount } }, or nil before a character is chosen
player.job
Player job (in their game)
client — job name
player.setJob
Set job
server job Job (job)
grade Grade (number)
—
player.setDuty
On duty / off duty
server onDuty On duty (boolean) —
player.setGang
Set gang
server gang Gang (gang)
grade Grade (number)
—
character.list
Player’s characters
server — [{ id, name }] of the characters on the player’s license
character.login
Log in as character
server id Character (id from character.list) (string) true once the character is loaded (by the server alone or by a click on the character select)
character.create
Create a character and enter it
server data { firstname, lastname, birthdate, gender } (json) id of the new character
character.prepare
Add characters to the account before the character select reads them
server characters [{ firstname, lastname, birthdate, gender }] (json) number of characters added
character.selectOpen
Character select is open
client — true while the player sees the character select
character.spawn
Entering the game after the server loaded the character (closes character select)
client — —
character.prepareSpawn
Prepare the character to spawn without start screens (e.g. apartment choice)
server — what it prepared (e.g. the apartment’s name), or false when nothing was needed

Money

Capability Side Arguments Returns
player.addMoney
Add money
server account Account (account)
amount Amount (number)
reason? Reason (string)
—
player.removeMoney
Remove money
server account Account (account)
amount Amount (number)
reason? Reason (string)
true when the account had that much
player.setMoney
Set account balance
server account Account (account)
amount Amount (number)
—
bank.open
Bank
client — —

Catalog

Capability Side Arguments Returns
catalog.jobs
Jobs
server — [{ name, label, grades: [{ grade, label }] }]
catalog.gangs
Gangs
server — [{ name, label, grades }]
catalog.accounts
Money accounts
server — [“cash”, “bank”, …]
catalog.items
Items
server — [{ name, label, weight?, kind? (item|weapon|ammo|component), studio?, imageDir? }]

Inventory

Capability Side Arguments Returns
inventory.list
Player inventory
server — [{ name, count }]
inventory.add
Give item
server item Item (item)
count Count (number)
metadata? Item metadata (json)
—
inventory.remove
Take item
server item Item (item)
count Count (number)
true when the player had it
inventory.count
How many of an item
server item Item (item) number
inventory.clear
Clear inventory
server — —
inventory.defineItem
New item (inventory resource file)
server def { name, label, weight, description, stack, image, usable } (json) { file, content }: the new content of the package’s file; the studio writes it and restarts the package
inventory.itemInfo
Item data (for editing)
server name Item (item) { name, label, weight, description, stack, image, usable, studio }
inventory.removeItem
Delete item (inventory resource file)
server name Item (item) { file, content }: the new content of the package’s file
inventory.registerStash
Create stash
server id Stash name (string)
label Label (string)
slots Slots (number)
weight Max weight (g) (number)
personal? Separate for each player (boolean)
job? Only for job (job)
—
inventory.openStash
Open stash
client id Stash name (string) —
inventory.openTrunk
Open vehicle trunk
client netId Vehicle (network id) (number) —
inventory.addToTrunk
Put in trunk
server plate Plate (string)
item Item (item)
count Count (number)
true when it fitted

Trade

Capability Side Arguments Returns
shop.register
Create shop
server id Shop name (string)
label Label (string)
items Goods [{ name, price }] (json)
job? Only for job (job)
—
shop.open
Open shop
client id Shop name (string) —

Vehicles

Capability Side Arguments Returns
vehicle.giveKeys
Give keys
server netId Vehicle (network id) (number) —
vehicle.hasKeys
Has keys
server netId Vehicle (network id) (number) —
vehicle.setFuel
Set fuel
server netId Vehicle (network id) (number)
level Fuel (0–100) (number)
—
garage.register
Create garage
server id Garage name (string)
label Label (string)
coords Entrance (coords)
spawn Where vehicles come out (coords)
job? Only for job (job)
—

Interface

Capability Side Arguments Returns
ui.notify
Notification
client text Text (string)
type? Kind (inform, success, error) (string)
—
ui.textShow
Show hint (e.g. [E] Open)
client text Text (string) —
ui.textHide
Hide hint
client — —
ui.progress
Progress bar
client label Text (string)
duration Time (ms) (number)
canCancel? Can be cancelled (boolean)
true when it ran to the end
ui.confirm
Confirmation
client title Title (string)
text Text (string)
true when confirmed
ui.input
Input dialog
client title Title (string)
fields Fields [{ label, type }] (json)
the field values, or nil
ui.menu
Choice menu
client title Title (string)
options Options [{ label, value }] (json)
the chosen option’s value, or nil
ui.skillCheck
Skill check
client difficulty? Difficulty (easy, medium, hard) (string) true on success

Targeting

Capability Side Arguments Returns
target.addEntity
Option on an object
client netId Object (network id) (number)
options Options (json)
—
target.addModel
Option on a model (whole world)
client models Models (json)
options Options (json)
—
target.addGlobal
Option on every vehicle, ped, player or object
client kind vehicle, ped, player, object (string)
options Options (with bones for vehicle parts) (json)
—
target.addSphere
Option at a place
client coords Place (coords)
radius Radius (number)
options Options (json)
zone id
target.listOptions
Targeting options on an object
client entity Object (handle) (number) [{ label, icon }] of the options the player will see on this object
target.remove
Remove options
client handle What adding returned (json) —

Job

Capability Side Arguments Returns
job.openBossMenu
Boss menu
client kind? job or gang (string) —

Appearance

Capability Side Arguments Returns
appearance.openClothing
Clothing shop
client — —
appearance.openBarber
Barber
client — —
appearance.save
Save current character appearance
client — name of the script that saved the appearance
appearance.addTattoo
Add tattoo to appearance and save
client tattoo Tattoo: name, label, hashMale, hashFemale, zone, collection (json) name of the script that saved the appearance

Server

Capability Side Arguments Returns
session.secondPlayer
Second player with the same license (development server)
server — true when Player 2 with the same Rockstar license gets onto the studio’s server
server.saveAll
Save data before a restart (players, inventories, vehicles)
server — —
db.query
Database query
server sql SQL (string)
params? Parameters (json)
rows or the query’s result

World

Capability Side Arguments Returns
world.set
Time and weather for everyone
server hour Time (number)
minute Minute (number)
weather Weather (string)
frozen? Time stopped (boolean)
—

A question this page does not answer? Ask it on Discord.

Webexe Studio

Click to see it at 100%.