JavaScript SDK

laptop.js connects a page from your resource to the laptop. It receives what your Lua sends, opens apps and addresses, shows notifications, keeps state while the laptop sleeps, matches the OS's look, and makes typing work on the laptop's own screen. It also gives the page what it can't do on its own: files from the OS's chooser, the signed-in account, payments, storage that follows the account, badges, sounds, casting, rooms and the share sheet. The page asks, the OS shows the player what is going on, and your server decides. It is plain JavaScript with no build step and no dependencies.

Include it in every page you register with RegisterApp or RegisterSite, and in pages you show in a Shroud message:

html
<script src="https://cfx-nui-zyke_laptop/nui/sdk/laptop.js"></script>

Load that address rather than a copy. The SDK is on protocol 2, and a page whose copy reports an older protocol gets an "Update Needed" screen instead of its page.

It adds window.Laptop:

js
Laptop.ready().then((context) => {
    console.log(context.kind, context.id, context.params);
});

Laptop.on("message", (data) => renderOrders(data.orders));

document.querySelector("#buy").addEventListener("click", async () => {
    const result = await Laptop.post("buyItem", { item: "lockpick" });

    Laptop.notify({ title: "Order placed", text: result.message, icon: "package" });
});

#Members

#Errors

Every call that talks to the laptop returns a promise. A refusal rejects with an Error whose code says why, which is what the page branches on; message is readable English for logs:

Calls the OS answers itself time out after 10 seconds, calls that go to the server, such as storage and rooms, after 15, and calls that wait for the player, such as the file chooser, the pay sheet or account(), never. Outside the laptop every call rejects with unsupported, except saveState, which only updates context.state there, and sound.play, which resolves without a sound. A mock can answer the calls of files, account, badge, clipboard, sound, pay, storage, rooms, cast, share and permissions there.

A page inside a Shroud message is someone else's content in the player's chat. It gets notify, close, setTitle, openUrl, openApp, getContext and the events, but files, account, badge, clipboard, sound, pay, storage, rooms, cast, share and permissions reject with unsupported there, and its capabilities list is empty.

#Capabilities

context.capabilities lists what the page may use on this laptop now, and Laptop.can(name) checks one. It changes with the capabilities event. A listed capability can still fail on a call, an unlisted one always does.

js
if (Laptop.can("pay")) buyButton.hidden = false;

#Files

The chooser is the player's consent: a page only ever gets the files the player picked there.

types is a list of {label?, extensions}, such as [{label: "Ledger", extensions: ["ledger"]}]. startIn is "documents", "persistent" or "stick". A handle is {id, name, path, kind, size, modified, location, readOnly}; calls take the handle or its id. It only works in the window that got it, until the window closes, the account changes or the stick it is on is pulled out. Files are text, 64 KiB by default (Config.Sdk.files.maxFileBytes).

An app that registered Document Types gets the file it was opened with from Files in context.files, or in the filesOpened event when its window was already open.

#Account

Laptop.account() resolves with the account the laptop is signed in to:

It needs the account permission. The first call asks the player, and the answer is kept per account. The account event fires when the OS signs in, out or switches account: file handles from before are gone, so read account() again.

#Notifications

Laptop.notify(options) shows a desktop notification and resolves with {id}, the id given or one the OS made. A string is the same as {title}.

Clicking the notification opens the app, or the site's address. A click on it or one of its buttons comes back to the page as the notificationAction event, {notificationId, action, data}, with action null for the notification itself. When the app isn't open, it opens with the event in context.launch.notificationAction.

Notifications chime as their banner shows, with the player's volume, UI-sounds switch and Do Not Disturb, and only while the laptop's screen is open. One that arrives with the laptop closed goes to the list silently. A player who turned the app's notifications off in Settings → Privacy makes notify reject with denied.

#Sounds

Laptop.sound.play(name) plays one of the OS's own sounds for the player at the laptop: click, send, receive, success or error, in the voice of the OS the page runs on, with the same volume, UI-sounds switch and Do Not Disturb. A page gets one sound per 60 ms, and faster calls reject with rateLimited. Pages bring no audio files through the SDK.

For a sound others near the player hear, such as a card reader, your server calls PlayAppSound.

#Payments

Laptop.pay(paymentId) shows the OS's pay sheet for a payment your server made with CreatePayment. The page never passes an amount. It resolves once the money moved with {paymentId, status: "settled", method, amount, coin?}, and rejects with cancelled when the player closes the sheet.

js
const { paymentId } = await Laptop.post("startCheckout", { plan: "premium" });

try {
    await Laptop.pay(paymentId);
    showThanks();
} catch (error) {
    if (error.code !== "cancelled") showError(error.code);
}

See Payments for the server side.

#Storage

Laptop.storage keeps the app's or site's data per account on the server, the same on every laptop the account signs in to. It needs storage in the registration. See Storage for the limits and the server exports that read and write the same data.

Keys are up to 64 letters, digits, _, -, . and :. When another laptop of the account, or your server, changes a key, the page gets the storage event with {key, value}, value null for a removed key.

#Rooms

Laptop.rooms.join(name, data?) joins a room of this app or site and resolves with it. It needs rooms in the registration, and the room's limits and join check come from there. See Rooms. The name is up to 48 letters, digits, _ and -.

js
const room = await Laptop.rooms.join("lobby", { ready: true });

room.on("message", ({ from, data }) => addMessage(from, data));
room.on("join", (member) => addMember(member));
room.on("leave", (member) => removeMember(member.id));
room.on("close", ({ reason }) => showClosed(reason));

await room.send({ text: "Hello" });

Member ids are random per room and never a server id. A message from your server comes from "server". Joining rejects with quota when the room or the player's rooms are full, offline without a network, and denied or noAccess when your join check refuses.

#Casting

An app registered with cast can show its own viewer page on the screens the laptop casts to:

A message over the cast's size limit rejects with tooLarge, and one sent while the app isn't casting with notFound. The cast event says when the cast started or stopped, or that the screen wants a fresh snapshot (wantSnapshot). Your server's snapshot, delta and signal functions check every message before a viewer sees it.

The viewer page loads https://cfx-nui-zyke_laptop/nui/sdk/laptop-cast.js and listens with LaptopCast.on("snapshot" | "delta" | "signal" | "setup", handler). setup and LaptopCast.context give {locale, width, height}, the screen's picture in pixels. Messages that came before the page listened go to the first listener. Every player who looks at the screen runs the viewer page, so keep it still between messages: no animation loops, timers or polling.

#Share

Laptop.share({title?, text?, url?, file?}) shows the OS's Share sheet. The player picks Mail, Natter, Shroud, Files or the clipboard, and the app they pick only gets a prefilled draft; nothing is sent until they send it. file is a handle from Laptop.files, and a share with a file offers only Mail, which attaches it. It needs text, url or file. It resolves with {target}, "mail", "messenger", "chat", "files" or "clipboard", or rejects with cancelled.

#Racks

Laptop.racks reads and runs the player's laptop racks, as the Hive app shows them. Changes made elsewhere are not pushed: read them again with get, or send them from your resource with SendAppMessage.

A refusal rejects with the server's code, such as noAccess, notYourWorkload, overAllocated, unknownWorkload or rateLimited. See Workloads for registering a workload.

#Context

#Events

#Devices

context.devices holds one entry per filled port of the laptop the OS runs on: {port, kind, side, type, item, label}, such as {port: "usba", kind: "usba", side: "right", type: "data_stick", item: "usb_drive", label: "USB Drive"}. kind is usbc, usba, hdmi or audio, and side is "rear" on a desktop computer. type is the device type, built in or registered by a resource. The list is empty on a screen opened without a laptop prop.

A page that needs a device, such as a scanner that only works with an antenna your resource registered as a device type, checks it and listens to devices:

js
const hasAntenna = (devices) => devices.some((device) => device.type === "wifi_antenna");

Laptop.ready().then((context) => setScanner(hasAntenna(context.devices)));
Laptop.on("devices", (devices) => setScanner(hasAntenna(devices)));

The list comes from the client, so check the device again on the server with the GetSessionDevices export before anything that pays out. See Ports & Devices for the devices themselves.

#Theming

The SDK styles the page to match the OS. It sets data-laptop-theme (light or dark), data-laptop-accent and data-laptop-os on <html>, sets its color-scheme, and exposes the palette and shapes as CSS variables. They update when the player changes the style or accent.

The font and shapes follow the OS:

css
body { font-family: var(--laptop-font); background: var(--laptop-window-bg); color: var(--laptop-window-fg); }
.card { border-radius: var(--laptop-radius); background: var(--laptop-card-bg); }
button { height: var(--laptop-control-height); border-radius: var(--laptop-radius-control); }
[data-laptop-os="facade"] button { font-weight: 400; }

The fonts load from the laptop's own files, and the browser only downloads the ones the page uses.

#Keyboard

Keys pressed in your page never reach the laptop on their own, so the SDK passes some on:

• Escape closes the laptop's topmost dialog or popover, or the screen.
• The browser's Keyboard Shortcuts, such as Ctrl+T, Ctrl+W, Ctrl+L, Ctrl+Tab and Alt+Left, go to the browser your site is open in. The SDK calls preventDefault() on the ones it passes on. In an app's window they do nothing.

To keep one of these keys for your page, call preventDefault() on it in your own keydown listener, on an element, on document or on window. The SDK checks this after all of them have run.

#Wheel Scrolling

The SDK eases the mouse wheel the way the laptop's own pages do: a notch glides over about 200 ms instead of jumping, and quick notches run into one motion. Everything that scrolls through CSS overflow gets it, the page itself included.

• To keep the wheel for a handler of your own, such as a map that zooms, call preventDefault() on the wheel event.
• An element with scroll-snap-type or scroll-behavior: smooth keeps the browser's own scrolling.
• Ctrl with the wheel, and the wheel over a focused number field, are left to the browser.
• A page opened on its own outside the laptop keeps its browser's scrolling.

#On the Laptop's Own Screen

The OS runs on the laptop's own screen and the camera zooms onto it. Your page runs in a browser that has no keyboard of its own: the laptop catches what the player types and hands it to the page. The mouse works, but that browser can't show a <select>'s list, has no double clicks and never starts a drag. context.display is "dui" there.

A page with the SDK gets almost everything it would get in a normal browser, with no changes:

• Typing into inputs, text areas and contenteditable elements, with the caret keys, Backspace, Delete, Ctrl+Backspace, Enter, Tab and undo. Your keydown, keyup, beforeinput and input listeners and React's onChange see it all.
• Ctrl+C, Ctrl+X and Ctrl+A. Ctrl+V pastes the player's real clipboard and raises a paste event you can handle.
• Japanese, Chinese and other input methods: the text being composed shows in the field and is replaced by the final text once, with compositionstart, compositionupdate and compositionend events.
• Ctrl, Shift and Alt on mouse events, and dblclick.
• A <select> opens a list in the OS's colours under it. The arrow keys, Home, End, Enter and Escape work on it, and choosing an option raises input and change. A <select multiple> or one with size is a plain list box and needs no popup.
• Dragging a range slider's thumb or a scrollbar.
• The arrow keys on sliders, Space on check boxes, and Space or Enter on buttons and links.
• The player sees the cursor your CSS asks for, such as the text cursor over a field or the hand over a link.

What a page has to keep in mind:

• The keys it gets are events your script can see, not ones the browser types for: isTrusted is false on them. Don't ignore untrusted key events.
• HTML5 drag and drop (draggable, dragstart, drop) doesn't start. Build drags from pointerdown, pointermove and pointerup, which work.
• Date, time and colour inputs can't open their pickers. Use your own.
• Reading the clipboard with navigator.clipboard is blocked. Handle the paste event instead.

A page without the SDK only gets the mouse: clicks, scrolling and hovering work, but nothing can be typed into it, and the cursor stays an arrow over it. Escape and the browser's shortcuts, such as Ctrl+W, still reach the laptop. Include laptop.js in any page that has a text field.

#TypeScript and React

The laptop serves more files next to laptop.js, at https://cfx-nui-zyke_laptop/nui/sdk/. They are in the resource at nui/sdk/:

• laptop.d.ts declares the window.Laptop global and its types in the ZykeLaptop namespace: the context, the events and their data, the notify options, the theme, palette, shape, devices, OS, error codes, files, account, storage, rooms, casting and racks. It also declares window.LaptopCast in the ZykeLaptopCast namespace.
• laptop-react.ts holds React hooks.
• laptop-cast.js is the script for an app's cast viewer page.

For a ready Vite, React and TypeScript setup using these, start from zyke_laptop_react_template in the app templates repository.

Copy both files into your page's source, for example src/laptop/, so your build doesn't depend on where zyke_laptop is installed. laptop.d.ts is a global declaration, so it only has to be inside your tsconfig's include, which src already covers:

json
{
    "include": ["src"]
}

A file outside include can be added by path, such as "include": ["src", "../../zyke_laptop/nui/sdk/laptop.d.ts"], or referenced with /// <reference path="./laptop.d.ts" />.

Load laptop.js with a <script> tag before your bundle in index.html, as above, so window.Laptop is there when your code runs:

tsx
import { useState } from "react";
import { laptopPost, useLaptopContext, useLaptopMessage } from "./laptop/laptop-react";

const Orders = () => {
    const context = useLaptopContext();
    const [orders, setOrders] = useState<Order[]>([]);

    useLaptopMessage<{ orders: Order[] }>((data) => setOrders(data.orders));

    if (!context) return null;

    return <OrderList orders={orders} compact={context.os === "facade"} onBuy={(id) => laptopPost<BuyResult>("buyItem", { id })} />;
};

#Developing in a Browser

A page can be worked on in a normal browser, outside the game. There Laptop.ready() resolves with a standalone context in Veil's dark style, with an empty capabilities list, and Laptop.post answers from the mocks you register instead of your resource. A post without a mock rejects. Calls that need the laptop, such as notify and openApp, reject with unsupported, and saveState only updates context.state.

A mock named "sdk:<feature>.<op>" answers an SDK call instead, such as "sdk:pay.show" for Laptop.pay, "sdk:storage.get" for Laptop.storage.get or "sdk:account.get" for Laptop.account(). The handler gets the call's arguments.

js
Laptop.mock("getOrders", () => ({ orders: [{ id: 1, item: "lockpick", amount: 2 }] }))
    .mock("buyItem", (data) => ({ message: `Bought ${data.item}` }))
    .mock("sdk:pay.show", ({ paymentId }) => ({ paymentId, status: "settled", method: "bank", amount: 2500 }))
    .mock("sdk:storage.get", ({ key }) => (key === "plan" ? { tier: "premium" } : null));

Mocks are ignored in game, so they can stay in the page. The https://cfx-nui-zyke_laptop/... script address only resolves in game; while working in a browser, point the script tag at nui/sdk/laptop.js inside the laptop's folder. See Working on a Page in a Browser for how the examples do it.