Documentation

Exports & Events

The Devices import, client exports, and events for resources that build devices and screens.

General Information

Everything in Devices runs on the client. There are no server exports or events, and import.lua does nothing when loaded on the server. Check every press and result on your own server.

Screens and device sessions belong to the resource that created them. When that resource stops, its screens are removed and its session ends with "stopped". A screen's page is a file of that resource.

Positions are given in the prop's own space, in metres: x across, y forward, z up. A face, meaning a screen or the plane the buttons lie in, lies in the entity's XZ plane and looks along its +Y. Its rotation is in degrees: x tilts it back or forward, y rolls it, and z turns it around the entity's up axis. A face's right is the right of someone looking at it, so an unturned face has its right along the prop's -X. A face that looks along the prop's -Y is vector3(0.0, 0.0, 180.0), with its right along +X.

Types / Classes

import.lua is the only readable file in zyke_devices. It annotates Devices, DeviceScreen, DeviceSession, and DeviceUseOptions. The option fields are listed with each function below.

#Complete Export Index

ContextExports
Import: ScreensDevices.addScreen, screen:setState, screen:send, screen:isReady, screen:getCorners, screen:getEntity, screen:setEntity, screen:remove
Import: Device UseDevices.use, session:close, session:moveCamera, session:isOpen, Devices.close, Devices.isUsing, Devices.getHovered
Import: GeometryDevices.getAxes, Devices.toWorld
ClientaddScreen, setScreenState, sendToScreen, isScreenReady, getScreenCorners, getScreenEntity, setScreenEntity, removeScreen, start, closeSession, isSessionOpen, moveCamera, close, isUsing, getHovered, getAxes, toWorld

#Import

The import is a thin layer over the client exports and the main way to use Devices. It returns screen and session objects, makes Devices.use wait until the player leaves, and adds your screens again with their last state if zyke_devices restarts.

#Load the Import

Load the import before your own client files, list every page a screen shows in files, and list zyke_devices as a dependency. The import adds the global Devices table to your resource.

Example:

lua
client_scripts {
    "@zyke_devices/import.lua",
    "client/keypad.lua",
}

files {
    "html/keypad.html",
}

dependencies {
    "zyke_lib",
    "zyke_devices",
}

#Screens

#Add Screen

Puts a page of your resource on a prop and returns the screen. Every nearby player sees it while they are near. Send what the page shows with setState whenever your resource's synced state changes. See Screen Pages.

  • page is the page's path in your resource, such as "html/keypad.html", and must be listed in your files. url takes a full URL instead.
  • width and height are the DUI size in pixels. Keep the same aspect as size.
  • entity is the prop the screen is on. Without it, model and coords find a map prop of that model within 1 metre of coords.
  • offset is the entity-local middle of the screen, the origin by default. size is metres across and up, and is needed unless replace is set. rotation turns the face.
  • replace is {txd, txn} and draws the page on this texture of the prop's model instead. It changes every copy of the model, so use it only for props that stand once.
  • drawDistance is metres, 15 by default. The DUI is built inside it and removed 5 metres past it.
  • brightness is the 0-1 share of the page's colours shown, 1 by default.
  • state is sent to the page as soon as it is up.
  • onMessage(event, data) receives messages the page posts, other than ready and cursor.

Example:

lua
---@param options DeviceScreenOptions
---@return DeviceScreen screen
local screen = Devices.addScreen({
    entity = keypadProp,
    page = "html/keypad.html",
    width = 560, height = 200,
    offset = vector3(0.0, -0.02, 0.06),
    size = vector2(0.07, 0.025),
    rotation = vector3(0.0, 0.0, 180.0),
    state = {mode = "armed"},
})

#Set State

Keeps the state and sends it to the page now, or as soon as the page is up. The page receives it as a state message. Players who come near later receive the last state set.

Example:

lua
---@param state table
screen:setState({mode = "entry", entry = "12"})

#Send

Sends a message to the page. It is only sent while the page is up, and nothing is kept for later. Use setState for anything the page must always show.

Example:

lua
---@param event string
---@param data? table
---@return boolean sent
local sent = screen:send("flash", {colour = "red"})

#Is Ready

Returns whether the page is up on this client.

Example:

lua
---@return boolean ready
local ready = screen:isReady()

#Get Corners

Returns the screen's corners in the world: top left, bottom left, bottom right, top right. Returns nil when the prop does not exist or the screen has no size.

Example:

lua
---@return vector3[]? corners
local corners = screen:getCorners()

#Get Entity

Returns the prop the screen is on, or nil.

Example:

lua
---@return integer? entity
local entity = screen:getEntity()

#Set Entity

Moves the screen onto another prop, such as one your resource placed again. Passing nil takes the screen off its prop and removes its DUI.

Example:

lua
---@param entity? integer
screen:setEntity(newProp)

#Remove

Removes the screen and its DUI.

Example:

lua
screen:remove()

#Device Use

#Use

Walks the player up to the device and lets them use it until they leave. Yields until then and returns the leave reason. Call it from a thread, such as an interaction's callback. Only one device can be in use at a time.

  • entity is the device's prop.
  • camera is {offset, target, fov?, easeIn?, easeOut?}, the entity-local eye and look-at point. fov defaults to 40, easeIn to 600 ms, and easeOut to 500 ms.
  • labels is {leave, press?}, the key panel's texts, translated by your resource. press is shown only when the device has buttons.
  • stand is the entity-local floor spot the player walks to first. Leave it out to use the device from where the player stands. heading is the degrees they face there, relative to the prop's heading, and defaults to facing the camera target.
  • anim is {dict, idle, enter?, exit?}, played on the ped so other players see it. idle loops while the device is in use.
  • face is the rotation of the plane the buttons lie in.
  • buttons is a list of {id, offset, size, key?, sound?}. offset is the button's entity-local middle and size its metres across and up. key is a key name or a list of them that also press it: "0"-"9" (number row and numpad), "A"-"Z", "ENTER", "DELETE", "STAR" (numpad *), and "HASH" (numpad +). A button's sound replaces the device's, and false mutes it.
  • screen is a screen from Devices.addScreen that takes the mouse while the cursor is over it, like a touch screen. It needs a size. Buttons take the click before the screen where they overlap it.
  • keyboard = true sends typed keys to the screen's page as key messages. Backspace then no longer leaves the device.
  • sound is {name, set} played on every press, or false for none. It defaults to the ATM keypad beep, PIN_BUTTON in ATM_SOUNDS.
  • highlight is {hover?, press?}, the RGBA drawn over the button under the cursor and over a pressed one. They default to {255, 255, 255, 40} and {255, 255, 255, 120}.
  • hidePlayer hides the player's own ped from their camera, for a camera by their head.
  • exposure is "auto" or {target?, points?} and holds the device's face at one brightness while the camera is on it. It reads a grid of points over the buttons, or over the screen on a device without buttons, and the middle reading counts. target is the linear luminance (0-1) to hold, 0.06 by default. points are entity-local points read instead, such as the body of a card reader.
  • onPress(button, session) runs for each press. Presses run one after another in a thread of their own, so a press that waits on the server never drops the next one.
  • onReady(session) runs once the camera has settled and input starts.
  • canContinue() is asked four times a second. Returning false leaves the device.

The exposure starts once the camera has settled and is let go as the camera eases off. It is let go at once when the player dies or is hurt, when zyke_devices or the resource using the device stops, or when another resource takes the extra timecycle modifier slot. A face that does not follow the exposure is left alone for the rest of the close-up.

The leave reason is one of:

  • "left": the player pressed Backspace, Esc, or the right mouse button.
  • "closed": session:close() or Devices.close() without a reason.
  • "dead": the player died.
  • "hurt": the player was ragdolled, fell, or lost health or armour. The exit animation is skipped and the camera cuts back at once.
  • "gone": the prop was removed, or did not exist.
  • "interrupted": canContinue returned false.
  • "unreachable": the walk to stand failed.
  • "busy": a device was already in use, so this one never started.
  • "stopped": zyke_devices, or the resource that started the session, stopped.

Example:

lua
---@param options DeviceUseOptions
---@return DeviceLeaveReason reason
local reason = Devices.use({
    entity = keypadProp,
    stand = vector3(0.0, -0.6, -1.5),
    camera = {offset = vector3(0.0, -0.32, 0.03), target = vector3(0.0, 0.0, 0.03), fov = 40.0},
    anim = {dict = "anim@heists@keypad@", enter = "enter", idle = "idle_a", exit = "exit"},
    face = vector3(0.0, 0.0, 180.0),
    buttons = {
        {id = "1", offset = vector3(-0.025, -0.02, 0.02), size = vector2(0.02, 0.018), key = "1"},
        {id = "enter", offset = vector3(0.025, -0.02, -0.046), size = vector2(0.02, 0.018), key = {"HASH", "ENTER"}},
    },
    screen = screen,
    exposure = "auto",
    labels = {press = "Press", leave = "Close"},
    onPress = function(button, session)
        local result = Z.callback.request("my_resource:PressKey", nil, button.id)
        if (result == "opened") then session:close() end
    end,
    canContinue = function() return isStillRobbable() end,
})

#Close Session

Leaves this session from a press or from anywhere else in your resource. A late call never ends a newer session.

Example:

lua
---@param reason? DeviceLeaveReason @ Defaults to "closed"
session:close()

#Move Camera

Eases the camera onto another view of the device, such as the part the player has to use next. Buttons keep working from the new view. Does nothing once the session is ending.

Example:

lua
---@param camera DeviceCamera @ {offset, target, fov?, easeIn?, easeOut?}
---@param ms? integer @ Milliseconds the ease takes, defaults to the camera's easeIn
session:moveCamera({offset = vector3(0.1, -0.3, 0.0), target = vector3(0.1, 0.0, 0.0)}, 400)

#Is Session Open

Returns whether the session still runs. It is false from the moment the player starts to leave.

Example:

lua
---@return boolean isOpen
local isOpen = session:isOpen()

#Close

Leaves the device in use, whichever resource started it.

Example:

lua
---@param reason? DeviceLeaveReason @ Defaults to "closed"
Devices.close()

#Is Using

Returns whether the player is using a device, including the walk up and the camera easing back.

Example:

lua
---@return boolean isUsing
local isUsing = Devices.isUsing()

#Get Hovered

Returns the id of the button under the cursor in the device in use, such as for a hint about what it does.

Example:

lua
---@return string? buttonId
local buttonId = Devices.getHovered()

#Geometry

#Get Axes

Returns the right, up, and normal axes of a face turned by rotation, in the entity's own space. Use it while laying out a new device.

Example:

lua
---@param rotation? vector3 @ Degrees
---@return vector3 right
---@return vector3 up
---@return vector3 normal
local right, up, normal = Devices.getAxes(vector3(0.0, 0.0, 180.0))

#To World

Returns an entity-local point in world coordinates.

Example:

lua
---@param entity integer
---@param point vector3
---@return vector3 coords
local coords = Devices.toWorld(keypadProp, vector3(0.0, -0.02, 0.06))

#Client Sided Exports

The import wraps these exports. Use them directly only if you do not load the import. Each export does the same as the import function or method of the same name, with the screen's string id or the session's integer id as its first argument. Callbacks receive the session id instead of an object.

#Start

Starts using a device and returns its session id at once, or nil and "busy" or "gone". It does not wait; listen for Session Ended to learn when the player leaves. options.screen is a screen id, and onPress(button, sessionId) and onReady(sessionId) receive the id.

Example:

lua
---@param options DeviceStartOptions
---@return integer? sessionId
---@return DeviceLeaveReason? reason
local sessionId, reason = exports["zyke_devices"]:start(options)

#Add Screen Without the Import

Returns the screen's id. Screens are removed when zyke_devices stops, so add them again when it starts.

Example:

lua
---@param options DeviceScreenOptions
---@return string screenId
local screenId = exports["zyke_devices"]:addScreen(options)

AddEventHandler("onClientResourceStart", function(resource)
    if (resource == "zyke_devices") then screenId = exports["zyke_devices"]:addScreen(options) end
end)

#Client Local Events

#Session Ended

Fires on the client when a session ends, with its id and leave reason. It does not fire when zyke_devices itself stops; treat its onClientResourceStop as the end instead. The import handles both.

Example:

lua
---@param sessionId integer
---@param reason DeviceLeaveReason
AddEventHandler("zyke_devices:SessionEnded", function(sessionId, reason)
    print(sessionId, reason)
end)