TS77 2.50.0+op77.148

Docs / TypeScript / Plugins

Write plugins.
The city runs Lua.

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.

src/*.ts // TS77 // Lua 5.4 // OPEN//77

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.

02 · NEXT

A real plugin

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.

What runs where

CLIENT LUA

The player's PC

Input, HUD, camera, and messages to the server. This code is on the player's machine. Do not put secrets here.

SERVER LUA

The authority

Money, items, permissions, bans, and vehicles. If a player can gain it, the server decides it.

REACT PAGE

Chromium, not the game

window.Open77 has four calls: ready, on, emit, invoke. The page cannot spawn a vehicle or read a file.

NODE

A separate process

Databases and npm require. The server talks to it over signed HTTP. A basic plugin never starts it.

Install

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.

  1. Install Node.js from the official Node website. Open a terminal and run node -v. A number of 20 or higher is enough to start.
  2. TypeScript is a way to write JavaScript with declared types. TS77 installs it for you. You do not install TypeScriptToLua, and you do not write tsconfig.json yourself. ts2077 create writes it, and that is the file the editor reads.
  3. Create a plugin. The folder name and the resource name are the same slug: a lowercase letter, then letters, digits, or underscores, 3 to 64 characters. 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.

Your first plugin

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.

TemplateUse it when
basicYou want the smallest plugin. It prints a greeting when the resource starts. It has no network permission and no Node process.
gameplayYou want a client and a server that exchange one typed event, demo:ping.
webuiYou want a React page inside the game's Chromium surface.
fullstackYou 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.

Where the files are

PathWhat it is
open77-ts.jsonThe resource name, version, entries, and permissions. The directory name must match name.
package.jsonScripts: dev, build, deploy, validate.
src/clientTypeScript that becomes client Lua. This runs on each player's machine.
src/serverTypeScript that becomes server Lua. This runs on the dedicated server and is the authority for money, items, permissions, and vehicles.
src/sharedTypeScript copied into each side that imports it. Do not put secrets here. The client copy is delivered to players.
src/modulesOptional extra client Lua files. src/modules/tools.ts becomes modules/tools.lua. Load it with loadModule("modules.tools").
src/backendOptional Node program. It is not loaded into the Lua sandbox.
src/webui or ui/Optional React page. It stays JavaScript.
ts77.config.jsonOptional overlay. It changes the build in memory and does not rewrite open77-ts.json.

Edit the greeting

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.

Commands

ts77 and open77-ts are the same program. ts77 --version prints the version. ts77 help prints examples. --quiet hides the success banner.

CommandWhat you get
ts77 createA new plugin. Refuses a bad name, and refuses a folder that already has files unless you pass --force.
ts77 initAdds the basic template to an existing folder and skips files that are already there.
ts77 devRebuilds on save. Starts Vite only if the WebUI dependencies are installed. Starts Node only if dist/backend exists.
ts77 buildTypechecks, emits Lua, writes the manifest, and builds the page when that target is on.
ts77 watchSame rebuild loop without Vite.
ts77 deployBuilds and copies the resource. Stops if no server directory is configured.
ts77 validateChecks that the manifest files exist and that the Lua parses.
ts77 doctorReports Node, TypeScriptToLua, the catalogue build, and missing entries.
ts77 typesRegenerates declarations from the local Devkit index. If the index is missing, it keeps the declarations already generated and says so.
ts77 docsPrints the path of this page. --open opens it.
ts77 updatePrints the catalogue build. It does not download a new index and it does not publish.
ts77 map file lineTurns a generated Lua line into a TypeScript file and line, using the source map on your machine.

Client and server

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.

Events

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.

React and the Chromium page

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.

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

The Node companion

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.

Deploy

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.

Configuration

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.

The manifest

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.

TS77 SDK

These are the helpers TS77 adds. The natives underneath keep their official names. Import the side you are on.

@open77/sdk/client and @open77-ts/client

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

@open77/sdk/server and @open77-ts/server

FunctionBehavior
onResourceStart / onResourceStopServer 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.

@open77-ts/server/bridge

Import this only from server code that should talk to Node. Importing it adds http.request and http.serve.

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

@open77-ts/webui

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.

@open77-ts/node

ExportBehavior
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, RedisNoteStoreDrivers for notes.save. The same request id returns the first row.
safePath, readWithinRead a file inside a root. Rejects .., NUL, and files over 16 KiB.
JobRunner.everyA timer. stop clears it. ms must be at least 1.
createResourceRequireSandboxed require for the plugin directory.

Native API

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.

SideNativeSincePermissionSummary

Omitted natives

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.

SideNativeSince

Companion endpoints

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.

GET /health

No signature. 200 { "ok": true }. CORS allows GET from http://127.0.0.1:5173. POST from the browser is not allowed.

POST /v1/call and POST /v1/webhook

Body limit 16 KiB. /v1/webhook uses the same parser. It is not an open third-party webhook.

StatuserrorWhen
200{ ok, id, result }
400invalid_envelopeNot an envelope, or the signature is not 64 lowercase hex characters.
400invalid_payloadThe method schema rejected the body.
400path_rejectedfiles.read left the root.
400files_disabledfiles.read and no filesRoot.
400file_too_largeFile over 16 KiB.
401unauthorizedClock skew over 30 seconds, bad HMAC, or a replayed nonce.
404unknown_methodNo handler.
429rate_limitedMore than 30 accepted calls per resource per 10 seconds. A bad signature does not consume a token.
500otherThe 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.

WebSocket /v1/events

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" }.

POST /<resource>/bridge

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.

Troubleshooting

What you seeWhat to do
node is not recognizedInstall Node.js 20 or newer and open a new terminal.
The name is rejectedUse my_plugin, not spaces, capitals, or hyphens. The folder name must match.
The folder already has filesPick 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 configuredPass --server with the folder that contains server.jsonc.
A native is missing from autocompleteCheck the omitted table. If it is listed, this catalogue does not declare it.
Client file imports fs or rethinkdbMove that import to src/backend. The Lua sandbox cannot run it.
Node companion exits at onceThe secret must be 16 to 256 characters.
host_not_allowedAdd the companion hostname to http.allowedHosts and turn HTTP on.
http_handlers_unavailableTurn on httpHandlers in server.jsonc.
The React page is blank in gameCall Open77.ready(). Send state after that. Confirm the dev URL is reachable from the player's PC.
Vite did not startRun npm install inside ui/ or src/webui/.
A Lua line has no TypeScript locationts77 map needs the .lua.map file on the machine that built the resource. The game has no debug library.
Windows path with spacesQuote the path. The resource slug itself still cannot contain a space.

Limits

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.

TS77 · catalogue 2.50.0+op77.148 · declarations generated from the OPEN//77 Devkit index · 1595 declared natives · 164 omitted