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 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>

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

The calls that talk to the laptop (notify, close, setTitle, openUrl, pushUrl, openApp, getContext, saveState) return promises. They reject with an error when the laptop refuses the call or doesn't answer within 10 seconds. Outside the laptop they reject too, except saveState, which only updates context.state there.

#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 two 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 and OS.
• laptop-react.ts holds React hooks.

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, 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, and saveState only updates context.state.

js
Laptop.mock("getOrders", () => ({ orders: [{ id: 1, item: "lockpick", amount: 2 }] }))
    .mock("buyItem", (data) => ({ message: `Bought ${data.item}` }));

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.