01 · FIRST HOUR
A print statement
Install Node, run four commands, and change one greeting. You do not write Lua or a manifest. Create writes tsconfig.json for the editor.
Docs / TypeScript / Plugins
TS77 is how you build an OPEN//77 multiplayer plugin in TypeScript. A plugin is a resource: a named folder the server starts, with code for the player's machine and code for the dedicated server. The game runs Lua 5.4. It does not run TypeScript, and a web page cannot call natives. TS77 compiles the client and the server, writes the open77.lua manifest, and leaves React and Node as themselves.
01 · FIRST HOUR
Install Node, run four commands, and change one greeting. You do not write Lua or a manifest. Create writes tsconfig.json for the editor.
02 · NEXT
The same project can grow a typed client/server event, a React page inside the game, and a Node process for npm packages such as RethinkDB.
CLIENT LUA
Input, HUD, camera, and messages to the server. This code is on the player's machine. Do not put secrets here.
SERVER LUA
Money, items, permissions, bans, and vehicles. If a player can gain it, the server decides it.
REACT PAGE
window.Open77 has four calls: ready, on, emit, invoke. The page cannot spawn a vehicle or read a file.
NODE
Databases and npm require. The server talks to it over signed HTTP. A basic plugin never starts it.
You need Node.js 20 or newer. If a plugin has a Node companion, use Node.js 22 or newer for that process. You also need an OPEN//77 server if you want to deploy. Reading this page and compiling a plugin do not require the game to be open.
node -v. A number of 20 or higher is enough to start.tsconfig.json yourself. ts2077 create writes it, and that is the file the editor reads.my_plugin is valid. my-plugin is not, because of the hyphen.npx ts2077 create my_plugin --template basic --no-install cd my_plugin npm install npm run dev
npx ts2077 downloads the package. It provides the ts77 and open77-ts commands. --no-install skips an extra install during creation. npm install then installs the package into the plugin. npm run dev watches src/ and rebuilds Lua when you save.
npx ts2077 installs this package from the npm registry. The commands it provides are ts77 and open77-ts.
In a terminal, ts77 create with no name asks four questions: the name, the template, an optional server folder, and whether to install dependencies. In a script, pass the flags so it does not wait.
| Template | Use it when |
|---|---|
basic | You want the smallest plugin. It prints a greeting when the resource starts. It has no network permission and no Node process. |
gameplay | You want a client and a server that exchange one typed event, demo:ping. |
webui | You want a React page inside the game's Chromium surface. |
fullstack | You want gameplay, React, and a Node companion. Only this template starts Node. |
Open the folder in Cursor or VS Code. tsconfig.json selects tsconfig.client.json or tsconfig.server.json for the file you have open. That is how @open77/sdk/client and the native declarations are found. Hover a native such as GetCurrentResourceName. The declaration shows the summary, the parameters, the permission, and the catalogue version. That text comes from the OPEN//77 Devkit index, not from a guess.
npm run build
Build writes open77.lua, dist/client/main.lua, and dist/server/main.lua. Leave those files alone. Change the TypeScript and build again.
| Path | What it is |
|---|---|
open77-ts.json | The resource name, version, entries, and permissions. The directory name must match name. |
package.json | Scripts: dev, build, deploy, validate. |
src/client | TypeScript that becomes client Lua. This runs on each player's machine. |
src/server | TypeScript that becomes server Lua. This runs on the dedicated server and is the authority for money, items, permissions, and vehicles. |
src/shared | TypeScript copied into each side that imports it. Do not put secrets here. The client copy is delivered to players. |
src/modules | Optional extra client Lua files. src/modules/tools.ts becomes modules/tools.lua. Load it with loadModule("modules.tools"). |
src/backend | Optional Node program. It is not loaded into the Lua sandbox. |
src/webui or ui/ | Optional React page. It stays JavaScript. |
ts77.config.json | Optional overlay. It changes the build in memory and does not rewrite open77-ts.json. |
The basic template already does this. src/shared/greeting.ts returns a string. Both sides print it when the resource starts.
export function greet(name: string): string {
return "Hello from " + name;
}
Client:
import { onClientResourceStart } from "@open77/sdk/client";
import { greet } from "../shared/greeting";
onClientResourceStart(() => {
print(greet(GetCurrentResourceName()));
});
Server:
import { onResourceStart } from "@open77/sdk/server";
import { greet } from "../shared/greeting";
onResourceStart(() => {
print(greet(GetCurrentResourceName()));
});
print writes to that side's log. GetCurrentResourceName is a real native. Save the file while npm run dev is running and the Lua is rebuilt.
A class, async, await, Map, Promise, and Node's require("rethinkdb") are rejected in client and server TypeScript. The server sandbox has no require. Put npm packages in src/backend.
ts77 and open77-ts are the same program. ts77 --version prints the version. ts77 help prints examples. --quiet hides the success banner.
| Command | What you get |
|---|---|
ts77 create | A new plugin. Refuses a bad name, and refuses a folder that already has files unless you pass --force. |
ts77 init | Adds the basic template to an existing folder and skips files that are already there. |
ts77 dev | Rebuilds on save. Starts Vite only if the WebUI dependencies are installed. Starts Node only if dist/backend exists. |
ts77 build | Typechecks, emits Lua, writes the manifest, and builds the page when that target is on. |
ts77 watch | Same rebuild loop without Vite. |
ts77 deploy | Builds and copies the resource. Stops if no server directory is configured. |
ts77 validate | Checks that the manifest files exist and that the Lua parses. |
ts77 doctor | Reports Node, TypeScriptToLua, the catalogue build, and missing entries. |
ts77 types | Regenerates declarations from the local Devkit index. If the index is missing, it keeps the declarations already generated and says so. |
ts77 docs | Prints the path of this page. --open opens it. |
ts77 update | Prints the catalogue build. It does not download a new index and it does not publish. |
ts77 map file line | Turns a generated Lua line into a TypeScript file and line, using the source map on your machine. |
Each resource has its own Lua VM. The client VM runs on the player's PC. The server VM runs on the dedicated server. A function that exists only on the server is a compile error in a client file, and the reverse is also an error.
Namespace calls use a dot: Open77.webui.create(...), TriggerServerEvent(...), Open77.http.request(...). Page methods use a colon in the generated Lua: page:send, page:on, page:destroy. You write them as method calls in TypeScript. The declaration's this decides the punctuation.
Many natives return a value and a reason. Read both:
const [page, reason] = Open77.webui.create({ entry: "web/index.html", layer: "hud" });
undefined and null both become Lua nil. The scheduler is CreateThread and Wait, not JavaScript promises. SetTimeout with a capital S is a real server native. The banned name is the JavaScript setTimeout.
Create the gameplay template when you want a client and a server to talk. The shared file describes the payload. Both sides refuse anything else.
export function isPing(value: unknown): value is Ping {
return isRecord(value) && isShortString(value.text, 96);
}
The client sends when it starts, then listens for the answer:
onClientResourceStart(() => {
onNet("demo:pong", (payload) => {
if (!isPing(payload)) return;
print(greet(payload.text));
});
const ok = emitServer("demo:ping", { text: "Night City" });
if (!ok) print("demo:ping was not sent");
});
The server ignores the message unless the caller is a connected player. During that callback the runtime sets the global source. authenticatedPlayer() reads it and returns the id only when it is 1 or greater. A player id inside the payload is not that check.
onNet("demo:ping", (payload) => {
const player = authenticatedPlayer();
if (player === undefined || !isPing(payload)) {
print("rejected demo:ping");
return;
}
const ok = emitClient(player, "demo:pong", { text: greet(payload.text) });
if (!ok) print("demo:pong was not sent");
});
emitClient refuses target 0. Use a player id of 1 or more, or -1 for everyone.
Names that start with a reserved prefix, including open77: families such as open77:dash:, are refused. Payloads must be JSON-like: nil, booleans, finite numbers, strings, and tables without cycles. The host limit is 32 arguments and 48 KiB.
A command handler receives the player and a string array. Lua command arguments are 1-based. The SDK presents them as a normal TypeScript array, so args[0] is the first word the player typed.
The page runs in OPEN//77's Chromium surface. TS77 does not open a second browser as the game UI. window.Open77 is a message bridge with four calls. It is not the native catalogue. The page cannot spawn a vehicle or grant money.
| Call | Direction |
|---|---|
Open77.ready() | Tell Lua the page finished loading. A page:send before this is dropped. |
Open77.on(event, handler) | Receive what Lua sent with page:send. |
Open77.emit(event, payload) | Raise an event Lua receives with page:on. |
Open77.invoke(event, payload) | Ask Lua for a result. Lua answers with page:reply. |
Create the page from client Lua. createPage uses layer hud or menu, which do not need a WebUI permission. On resource stop it calls page:destroy(). The webui template waits for the page, then sends state:
const page = createPage({ entry: webuiEntry, layer: "hud", transparent: true, visible: true });
if (page === undefined) return;
page.on("ui:ready", () => {
page.send("hud:state", { text: greet("Night City") });
});
page.on("hud:ping", (payload: unknown) => {
if (!isPing(payload)) return;
emitServer("hello:ping", { text: payload.text });
});
The React page listens, then tells Lua it is ready. A button sends a message back. That message is not a native call. Client Lua turns it into emitServer.
api.on("hud:state", (payload) => {
const state = payload as Partial<HudState>;
if (typeof state.text === "string") setText(state.text);
});
api.ready();
bridge()?.emit("hud:ping", { text: "Night City" });
For the React template, install the UI dependencies too: npm install --prefix ui or, for fullstack, npm install --prefix src/webui. Dev mode serves Vite at http://127.0.0.1:5173/. In the game, that address is the player's computer, not the dedicated server.
A message through the page bridge is capped at 2 MiB. A game event is still capped at 48 KiB. Production build writes files under web/ and lists each one as web_file in the manifest.
Node is a separate operating-system process. It is how you require("rethinkdb") or require("chalk"). Install the package in the plugin directory, then import it from src/backend. A basic plugin never starts this process.
npm install rethinkdb chalk
const chalk = require("chalk");
const db = require("rethinkdb");
The game reaches Node with Open77.http.request. Node reaches the game with POST /<resource>/bridge, which the server registers with Open77.http.listen. There is no Lua WebSocket client in this catalogue, so the Lua side does not open one. WebSockets on Node are for a process that can sign the envelope.
Set OPEN77_BRIDGE_SECRET to 16–256 characters before the companion listens. The game reads open77_bridge_secret from a convar or this resource's tunable. Do not put the secret in client TypeScript, the React page, or server.jsonc. The default in source is empty, and an empty secret refuses the call.
Outbound HTTP stays off until server.jsonc sets http.enabled and lists the host in http.allowedHosts. The list is a hostname without a port, so 127.0.0.1 covers http://127.0.0.1:11782. Inbound handlers are a separate switch, httpHandlers, loopback by default.
createResourceRequire(directory) is Node's loader rooted at the plugin. It refuses an absolute path, a relative path that leaves the plugin, and the gameplay packages @open77-ts/client, @open77-ts/server, @open77-ts/webui, and @open77/sdk.
npx ts2077 deploy --server D:\open77-server
The server directory is the folder that contains server.jsonc. TS77 copies into resources/<plugin> inside it. The copy includes the manifest, dist, web, modules, and files. It does not include node_modules, src, or .env.
If you have not named a server, deploy stops and tells you. It does not pick a folder on its own. After the copy, restart that resource on the server. TS77 does not reload the dedicated server.
The wizard looks for server.jsonc in the current directory, parent directories, OPEN77_SERVER, and folders next to the toolchain.
Required fields are name and version. autoStart defaults to true. Entries default to src/client/main.ts and src/server/main.ts.
If you omit targets, TS77 builds the client and the server, adds webui when web.root is set, and adds node when backend is set. An explicit targets array is used as written.
{
"name": "my_plugin",
"version": "1.0.0",
"client": "src/client/main.ts",
"server": "src/server/main.ts",
"permissions": []
}
ts77.config.ts must export an object. The compiler transpiles it in memory. Keep gameplay code out of it. ts77 deploy --server is the command that writes serverResourcesDir into open77-ts.json.
open77.lua is a manifest DSL. It is not a Lua program. auto_start true is legal there and illegal as Lua, so do not parse the manifest with a Lua parser. The build rewrites the file.
Permissions are the union of what you listed and the natives the compiler actually found in the Lua. A native mentioned only in a comment or a string is not treated as a call. Client and server permissions are resource-wide. files/ becomes file lines. web/ becomes web_file lines. Source maps are not shipped as game files.
These are the helpers TS77 adds. The natives underneath keep their official names. Import the side you are on.
| Function | Behavior |
|---|---|
onClientResourceStart(handler) | Runs the handler when this resource starts on the client. Returns a handler id. |
onClientResourceStop(handler) | Runs when this resource stops. The handler receives the reason. |
clearHandlers() | Removes handlers this SDK registered. |
onNet(event, handler) | Listens for a server event. Refuses a reserved name. |
emitServer(event, payload) | Sends a payload to the server after a structural check and a size check. Returns false if it refused. |
loadModule(name) | Client sandbox require. modules.tools reads modules/tools.lua. @library reads a declared dependency. This is not Node. |
createPage(options) | Opens a hud or menu page and destroys it when the client resource stops. |
| Function | Behavior |
|---|---|
onResourceStart / onResourceStop | Server lifecycle for this resource. |
clearHandlers() | Removes handlers this SDK registered on the server. |
onNet(event, handler) | Receives a client event. The player is source during the callback. |
authenticatedPlayer() | The caller id when it is a number of 1 or more. Otherwise undefined. |
emitClient(playerId, event, payload) | Sends to one player or to -1. Refuses 0, reserved names, and payloads that are not serializable. |
onCommand(name, restricted, handler) | Registers a command. The handler gets the player and a string array. |
Import this only from server code that should talk to Node. Importing it adds http.request and http.serve.
| Function | Behavior |
|---|---|
serveBackend() | Listens on /<resource>/bridge. |
onBackendCall(method, handler) | Handles a signed call from Node. |
callNode(method, payload, callback, idempotent?) | Signs and posts to the companion. An empty secret returns bridge_secret_missing without HTTP. Status 0 or a timeout retries once when the call is idempotent. Other failures include backend_offline, timeout, bad_response, and resource_stopped. |
emitPage, onPage, and readyPage wrap window.Open77. They throw if the bridge is missing, which is what happens in a desktop browser that is not the game. backendHealth is a GET to the companion /health route. It does not send the secret.
| Export | Behavior |
|---|---|
startCompanion(options) | Fastify on 127.0.0.1 and port 11782 unless you change them. Body limit 16 KiB. Closes jobs and sockets on close(). |
callGame(options) | Posts a signed envelope to the game listener. Connection failure is game_offline. Timeout is timeout. |
MemoryNoteStore, SqlNoteStore, RedisNoteStore | Drivers for notes.save. The same request id returns the first row. |
safePath, readWithin | Read a file inside a root. Rejects .., NUL, and files over 16 KiB. |
JobRunner.every | A timer. stop clears it. ms must be at least 1. |
createResourceRequire | Sandboxed require for the plugin directory. |
Every row is a native in catalogue 2.50.0+op77.148. Click a row for the signature, the return, and the failure reasons. Those lines come from that native's declaration. Three await methods are reserved words in TypeScript, so their text comes from the catalogue card and names the declared stand-in where one exists. An empty permission cell means the card lists none.
Client rows: 701. Server rows: 894. A summary was attached to 1595 rows.
| Side | Native | Since | Permission | Summary |
|---|
NOT ON THIS BUILD
These cards are in the Devkit index and are not declared. Each one has no since build, or its since build is newer than 2.50.0+op77.148. Calling one is not offered as safe on this catalogue. Do not invent a replacement version.
| Side | Native | Since |
|---|
Default companion: http://127.0.0.1:11782. Default game listener in the server schema: http://127.0.0.1:11781. The signature is a JSON field, not a header. The HMAC covers the resource, id, method, timestamp, nonce, and the canonical payload, joined by newlines. Empty objects and empty arrays both sign as {}, because Lua has one kind of table.
No signature. 200 { "ok": true }. CORS allows GET from http://127.0.0.1:5173. POST from the browser is not allowed.
Body limit 16 KiB. /v1/webhook uses the same parser. It is not an open third-party webhook.
| Status | error | When |
|---|---|---|
| 200 | { ok, id, result } | |
| 400 | invalid_envelope | Not an envelope, or the signature is not 64 lowercase hex characters. |
| 400 | invalid_payload | The method schema rejected the body. |
| 400 | path_rejected | files.read left the root. |
| 400 | files_disabled | files.read and no filesRoot. |
| 400 | file_too_large | File over 16 KiB. |
| 401 | unauthorized | Clock skew over 30 seconds, bad HMAC, or a replayed nonce. |
| 404 | unknown_method | No handler. |
| 429 | rate_limited | More than 30 accepted calls per resource per 10 seconds. A bad signature does not consume a token. |
| 500 | other | The handler threw. |
Built-in methods: notes.save (playerId and text of 1–96 characters; the row id is the request id), files.read, bridge.disconnect (result { cleared: true }), notes.ping (result { pong: true }), and webhook.receive. Idempotent methods remember a success for 60 seconds.
The first message must be a signed envelope with method bridge.hello. A bad first message closes with code 4001. After that, { "type": "ping" } is answered with { "type": "pong" }.
Node calls this on the game listener. The Lua resource must have called serveBackend(). The body limit on the way in is 16 KiB. Sixteen requests can be in flight. A route disappears when the resource stops.
| What you see | What to do |
|---|---|
node is not recognized | Install Node.js 20 or newer and open a new terminal. |
| The name is rejected | Use my_plugin, not spaces, capitals, or hyphens. The folder name must match. |
| The folder already has files | Pick a new folder, or pass --force. Force copies template files over files of the same name. It does not delete the rest. |
| Deploy says it is not configured | Pass --server with the folder that contains server.jsonc. |
| A native is missing from autocomplete | Check the omitted table. If it is listed, this catalogue does not declare it. |
Client file imports fs or rethinkdb | Move that import to src/backend. The Lua sandbox cannot run it. |
| Node companion exits at once | The secret must be 16 to 256 characters. |
host_not_allowed | Add the companion hostname to http.allowedHosts and turn HTTP on. |
http_handlers_unavailable | Turn on httpHandlers in server.jsonc. |
| The React page is blank in game | Call Open77.ready(). Send state after that. Confirm the dev URL is reachable from the player's PC. |
| Vite did not start | Run npm install inside ui/ or src/webui/. |
| A Lua line has no TypeScript location | ts77 map needs the .lua.map file on the machine that built the resource. The game has no debug library. |
| Windows path with spaces | Quote the path. The resource slug itself still cannot contain a space. |
The dedicated server sandbox has no require, os, io, debug, package, load, or collectgarbage. The client also removes setmetatable. Bundles inline their helpers and do not fall back to a global require.
Declarations in this package follow catalogue 2.50.0+op77.148. A native added in a later server build is not declared until that catalogue is updated.