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.luadoes 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'spageis 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
rotationis 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 isvector3(0.0, 0.0, 180.0), with its right along +X.
Types / Classes
import.luais the only readable file inzyke_devices. It annotatesDevices,DeviceScreen,DeviceSession, andDeviceUseOptions. The option fields are listed with each function below.
#Complete Export Index
| Context | Exports |
|---|---|
| Import: Screens | Devices.addScreen, screen:setState, screen:send, screen:isReady, screen:getCorners, screen:getEntity, screen:setEntity, screen:remove |
| Import: Device Use | Devices.use, session:close, session:moveCamera, session:isOpen, Devices.close, Devices.isUsing, Devices.getHovered |
| Import: Geometry | Devices.getAxes, Devices.toWorld |
| Client | addScreen, 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 listzyke_devicesas a dependency. The import adds the globalDevicestable to your resource.Example:
luaclient_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
setStatewhenever your resource's synced state changes. See Screen Pages.
pageis the page's path in your resource, such as"html/keypad.html", and must be listed in yourfiles.urltakes a full URL instead.widthandheightare the DUI size in pixels. Keep the same aspect assize.entityis the prop the screen is on. Without it,modelandcoordsfind a map prop of that model within 1 metre ofcoords.offsetis the entity-local middle of the screen, the origin by default.sizeis metres across and up, and is needed unlessreplaceis set.rotationturns the face.replaceis{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.drawDistanceis metres,15by default. The DUI is built inside it and removed 5 metres past it.brightnessis the0-1share of the page's colours shown,1by default.stateis sent to the page as soon as it is up.onMessage(event, data)receives messages the page posts, other thanreadyandcursor.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
statemessage. 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
setStatefor 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
nilwhen the prop does not exist or the screen has nosize.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
niltakes 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:
luascreen: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.
entityis the device's prop.camerais{offset, target, fov?, easeIn?, easeOut?}, the entity-local eye and look-at point.fovdefaults to40,easeInto600ms, andeaseOutto500ms.labelsis{leave, press?}, the key panel's texts, translated by your resource.pressis shown only when the device has buttons.standis the entity-local floor spot the player walks to first. Leave it out to use the device from where the player stands.headingis the degrees they face there, relative to the prop's heading, and defaults to facing the camera target.animis{dict, idle, enter?, exit?}, played on the ped so other players see it.idleloops while the device is in use.faceis the rotation of the plane the buttons lie in.buttonsis a list of{id, offset, size, key?, sound?}.offsetis the button's entity-local middle andsizeits metres across and up.keyis 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'ssoundreplaces the device's, andfalsemutes it.screenis a screen fromDevices.addScreenthat takes the mouse while the cursor is over it, like a touch screen. It needs asize. Buttons take the click before the screen where they overlap it.keyboard = truesends typed keys to the screen's page askeymessages. Backspace then no longer leaves the device.soundis{name, set}played on every press, orfalsefor none. It defaults to the ATM keypad beep,PIN_BUTTONinATM_SOUNDS.highlightis{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}.hidePlayerhides the player's own ped from their camera, for a camera by their head.exposureis"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.targetis the linear luminance (0-1) to hold,0.06by default.pointsare 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. Returningfalseleaves 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_devicesor 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()orDevices.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":canContinuereturnedfalse."unreachable": the walk tostandfailed."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
falsefrom 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
niland"busy"or"gone". It does not wait; listen for Session Ended to learn when the player leaves.options.screenis a screen id, andonPress(button, sessionId)andonReady(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_devicesstops, 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_devicesitself stops; treat itsonClientResourceStopas 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)