{"id":"fadeluc-123/volt","name":"volt","scope":"fadeluc-123","platform":"roblox","description":"Buffer networking for Roblox: a schema compiler and a small runtime","version":"0.1.0","latest":"0.1.0","versions":["0.1.0"],"license":"Apache-2.0","licenseRating":"safe","licenseCaveats":["Modified files must carry a notice of changes. If the package ships a NOTICE file, its attributions must be preserved."],"licenseVerified":true,"dependencies":{},"integrity":"9cec2786d5ffdb5c0f6a01fdf57bcf4ea584be4449ed675c237a40ea2f81b8bf","likes":0,"downloads":0,"install":"forest install fadeluc-123/volt","url":"https://forest.dev/p/roblox/fadeluc-123/volt","files":"https://api.forest.dev/ai/package/roblox/fadeluc-123/volt/files","readme":"# Volt\n\nNetworking for Roblox games: one file describes every message, and a tool turns it into typed Luau modules.\n\n## Contents\n\n- [What Volt is](#what-volt-is)\n- [Why use it](#why-use-it)\n- [Install](#install)\n- [Your first schema](#your-first-schema)\n- [Compile](#compile)\n- [Use it in your scripts](#use-it-in-your-scripts)\n- [Types](#types)\n- [Choosing how a message travels](#choosing-how-a-message-travels)\n- [Sending less](#sending-less)\n- [Safety defaults](#safety-defaults)\n- [More tools](#more-tools)\n- [Colors in VS Code](#colors-in-vs-code)\n- [Options](#options)\n- [Troubleshooting](#troubleshooting)\n- [Versions](#versions)\n- [Working on Volt](#working-on-volt)\n- [License](#license)\n\n## What Volt is\n\nVolt is a networking library for Roblox. You describe every message your game sends between the server and its players in one text file, called a schema, and a command-line tool called `volt` turns that file into Luau modules. Your scripts call those modules instead of creating and firing RemoteEvents.\n\n## Why use it\n\nYour game sends less data. Volt writes each message into a buffer, which is a block of raw bytes, instead of sending Luau tables. A number from 0 to 255 takes one byte, and eight true or false values share one byte. The reliable messages fired during one frame go out together, in one remote call per player.\n\nThe code Volt writes reads and writes each value at a fixed place in the buffer, so turning a message into bytes and back takes little work.\n\nThe server checks every value. Before your code sees a message from a player, Volt checks each value against the type the schema gives it: its range, its length, its class. A message that fails is dropped and reported. Every message from a player also has a rate limit, so one player cannot flood the server.\n\nEvery message is listed in one place. The schema names each message, who sends it and what it carries, so all of your game's network traffic can be read in one file. The generated modules are fully typed, so your editor knows the type of every argument.\n\n## Install\n\nVolt has two parts. The first is `volt`, a compiler: a program that reads one kind of file and writes code from it. It runs on your computer while you work. The second is the runtime, a small Luau package that runs inside your game and does the sending and receiving. Rokit installs the compiler and Wally installs the runtime.\n\nThese steps assume your game is a Rojo project that already uses Rokit, which installs command-line tools, and Wally, which installs Luau packages.\n\n1. Install the compiler. In your game's folder, run:\n\n   ```sh\n   rokit add fadeluc-123/volt\n   ```\n\n   This pins `volt` in your `rokit.toml`, so everyone who works on the game gets the same version.\n\n2. Add the runtime to your `wally.toml`, under `[dependencies]`. Wally 0.3.2 has no `add` command, so you type the line yourself:\n\n   ```toml\n   [dependencies]\n   Volt = \"fadeluc-123/volt@0.1.0\"\n   ```\n\n   Then install it:\n\n   ```sh\n   wally install\n   ```\n\n   Keep the name on the left as `Volt`, with a capital V. Wally names the entry in `Packages/` after it, Roblox instance names are case sensitive, and every generated module requires `ReplicatedStorage.Packages.Volt` unless told otherwise, so a lowercase name fails at the first `require`. A different name works only if every schema sets a matching `option runtime`, and that only helps your game's own schemas. A package built on Volt that runs its own scope was compiled with `ReplicatedStorage.Packages.Volt` written into it, so a game that uses any such package installs Volt as `Volt`.\n\n   If your game uses a package that was compiled with `option yield = promise`, also install evaera's Promise library as `Promise`:\n\n   ```toml\n   Promise = \"evaera/promise@4.0.0\"\n   ```\n\n   That puts it at `ReplicatedStorage.Packages.Promise`, the path the package's client module requires. The package's own copy of Promise sits inside `Packages/_Index`, which that path never reaches.\n\n3. Map Wally's `Packages` folder to `ReplicatedStorage.Packages` in your Rojo project file. The examples in this README also put `src/Shared` at `ReplicatedStorage.Shared`, the server scripts in `ServerScriptService` and the client scripts in `StarterPlayerScripts`. A `default.project.json` that does all of that:\n\n   ```json\n   {\n   \t\"name\": \"MyGame\",\n   \t\"tree\": {\n   \t\t\"$className\": \"DataModel\",\n   \t\t\"ReplicatedStorage\": {\n   \t\t\t\"Packages\": { \"$path\": \"Packages\" },\n   \t\t\t\"Shared\": { \"$path\": \"src/Shared\" }\n   \t\t},\n   \t\t\"ServerScriptService\": {\n   \t\t\t\"Server\": { \"$path\": \"src/Server\" }\n   \t\t},\n   \t\t\"StarterPlayer\": {\n   \t\t\t\"StarterPlayerScripts\": {\n   \t\t\t\t\"Client\": { \"$path\": \"src/Client\" }\n   \t\t\t}\n   \t\t}\n   \t}\n   }\n   ```\n\n4. Give the type checker Volt's types. Each time you install packages, run all three commands, in this order:\n\n   ```sh\n   wally install\n   rojo sourcemap default.project.json --output sourcemap.json\n   wally-package-types --sourcemap sourcemap.json Packages/\n   ```\n\n   For each package, Wally writes a small file in `Packages/` that points at the package's real code, and those files leave the package's types out. The generated modules use Volt's types, such as `Volt.Runtime`, so in a game that uses `--!strict` the type checker reports `Unknown type 'Volt.Runtime'` and dozens of errors after it until this step runs. The second command writes a map of your project to `sourcemap.json`. The third uses that map to rewrite the small files with the types included. If you do not have `wally-package-types` yet, add it with `rokit add JohnnyMorganz/wally-package-types`.\n\n   The type checker here is luau-lsp, which also runs inside VS Code as the Luau Language Server extension. It has two checkers, the old one it runs by default and the new one, called `LuauSolverV2`, and the generated modules check clean under both. To use the new one in VS Code, put these lines in your game's `.vscode/settings.json`:\n\n   ```json\n   {\n   \t\"luau-lsp.fflags.enableNewSolver\": true,\n   \t\"luau-lsp.fflags.enableByDefault\": true,\n   \t\"luau-lsp.fflags.sync\": false\n   }\n   ```\n\n   Each line sets Luau flags, the switches that turn Luau's newer features on or off. `enableNewSolver` turns the new checker on. `enableByDefault` turns on every flag that is simply on or off, as `luau-lsp analyze` does on the command line. `sync: false` stops the extension from copying the flags Roblox has set today, so a change Roblox makes to them never reaches your editor unannounced. On the command line, pass `--flag:LuauSolverV2=true` to `luau-lsp analyze`, which otherwise runs the old checker.\n\n## Your first schema\n\nA schema is a text file whose name ends in `.volt`. It lists your messages and says where `volt` writes the modules. Save this as `Game.volt` in the root folder of your game's project:\n\n```\n-- Every message this game sends between the server and its players\noption clientOutput = \"src/Shared/Network/Client.luau\"\noption serverOutput = \"src/Shared/Network/Server.luau\"\noption typesOutput = \"src/Shared/Network/Types.luau\"\n\n-- A player sends the server a small number\nevent Ping {\n\tfrom: Client,\n\ttype: Reliable,\n\tcall: SingleAsync,\n\tdata: u8,\n}\n\n-- The server sends a small number back\nevent Pong {\n\tfrom: Server,\n\ttype: Reliable,\n\tcall: SingleAsync,\n\tdata: u8,\n}\n\n-- A player asks the server a question and waits for the answer\nfunction Echo {\n\tdata: string(0..32),\n\treturn: string(0..32),\n}\n```\n\nHere is what each line does.\n\n- A line that starts with `--` is a comment. Volt ignores it.\n- `option clientOutput = \"...\"` is where `volt` writes the module your LocalScripts use. The path is relative to the folder that holds `Game.volt`.\n- `option serverOutput = \"...\"` is where it writes the module your server Scripts use.\n- `option typesOutput = \"...\"` is where it writes a module of types for code that both sides share. It is optional; leave the line out if you do not need it.\n- `event Ping {` starts an event named `Ping`. An event is a one-way message: one side fires it, the other side listens, and nothing comes back.\n- `from: Client` says who fires it: `Client` for a player's LocalScripts, `Server` for the server, or `Both`.\n- `type: Reliable` means the message always arrives, exactly once, in the order it was fired. An `Unreliable` message can be lost. [Choosing how a message travels](#choosing-how-a-message-travels) says when to use each.\n- `call: SingleAsync` says how the listening side runs its listener. `Single` allows one listener, and `Async` runs each message on its own thread, so the listener may wait. The same section explains the other modes.\n- `data: u8` is what the message carries: one whole number from 0 to 255. `u8` is short for \"unsigned 8-bit\", a number that is never negative and fits in one byte. [Types](#types) lists every type.\n- `}` ends the event. Each key inside it ends with a comma.\n- `event Pong { ... }` is the same shape with `from: Server`, so the server fires it and the players listen.\n- `function Echo {` starts a function. A function is a question with an answer: a player calls it, the server runs a handler, and the handler's return value goes back to that player. A function goes from a client to the server unless it says otherwise; [When the server asks a player](#when-the-server-asks-a-player) shows one that goes the other way.\n- `data: string(0..32)` is what the player sends: a string from 0 to 32 bytes long.\n- `return: string(0..32)` is what the server answers with.\n\nThe schema leaves two options at their defaults. `option runtime` is where the modules find the Volt runtime, and it defaults to `ReplicatedStorage.Packages.Volt`, where Wally put it. `option scope` names the folder Volt makes for this schema's remotes, and it defaults to the schema's file name, so this schema's remotes live in `ReplicatedStorage.Volt.Game`. Two schemas with different names never see each other's messages.\n\n`data` can also be a list of named values, called a parameter pack. With `data: (x: f32, y: f32)` the sender calls `fire(x, y)` and the listener receives `x` and `y` as two arguments.\n\n## Compile\n\n`volt` does not create folders, so make the output folder once (in PowerShell, leave out `-p`):\n\n```sh\nmkdir -p src/Shared/Network\n```\n\nThen run the compiler on the schema:\n\n```sh\nvolt Game.volt\n```\n\nIt prints one line:\n\n```\nGame.volt: ok, schema hash 0x894D330D\n```\n\nThe schema hash is a fingerprint of the schema. Any change to a message or an option changes it, so yours will differ once your schema does.\n\nThese files now exist:\n\n| File | Required by |\n|---|---|\n| `src/Shared/Network/Client.luau` | your LocalScripts |\n| `src/Shared/Network/Server.luau` | your server Scripts |\n| `src/Shared/Network/Types.luau` | shared code that wants the types; written only when `typesOutput` is set |\n| the path `inspectorOutput` gives, such as `src/Shared/Network/Inspector.luau` | PacketProfiler, which shows what each packet holds; written only when `inspectorOutput` is set, which `Game.volt` does not do ([The packet inspector](#the-packet-inspector)) |\n\nEach one starts with a comment saying it was generated. Never edit them. Change the schema and run `volt` again instead.\n\nA schema too large for one client module and one server module also writes shard files beside them, such as `ServerShard1.luau`; [A schema too big for one module](#a-schema-too-big-for-one-module) explains them.\n\nRun `volt` again after every change to the schema. The client module and the server module must come from the same schema, or the server kicks every player (see [Safety defaults](#safety-defaults)).\n\nWhen the schema has a mistake, `volt` prints each one with its line, its column and a code, writes nothing and exits with code 1:\n\n```\nGame.volt:5:2: error V2003: unknown key \"form\" in event Ping; keys are from, type, call, data, queue, rate, timeout, channel\n    5 | \tform: Client,\n      | \t^^^^\n\nGame.volt:4:7: error V2004: missing key \"from\" in event Ping\n    4 | event Ping {\n      |       ^^^^\n```\n\nThe command takes four flags:\n\n```\nusage: volt <schema.volt | folder> [<file.volt> ...] [--check | --watch] [--ast] [--quiet]\n```\n\n- `--check` writes nothing. It compiles the schema and compares each file it would write with the one already on disk, line endings aside: the client and server modules, the types module, every shard and the packet inspector.\n- `--watch` keeps running and compiles the schema again each time you save it ([Compiling on every save](#compiling-on-every-save)).\n- `--ast` also prints the schema in its full form, with every default filled in.\n- `--quiet` leaves out the `ok` line.\n\n`--check` and `--watch` cannot be used together. Given both, `volt` prints the usage line above and exits with code 2. It does the same when it is given no schema, a folder with no `.volt` file directly inside it, or a further argument that is not an existing `.volt` file. A schema file that does not exist is named, and the command exits with code 1:\n\n```\nvolt: Game.volt is missing\n```\n\nUse `--check` in continuous integration (CI), the checks that run on every push, to prove the committed modules match the schema:\n\n```sh\nvolt Game.volt --check\n```\n\nWhen they match, it prints the usual `ok` line and exits with code 0. When they do not, it names each file and exits with code 1:\n\n```\nGame.volt: src/Shared/Network/Client.luau is out of date\nGame.volt: src/Shared/Network/Server.luau is out of date\n```\n\nA file that should exist and does not, such as a shard nobody committed or an inspector the schema has just asked for, is reported as missing:\n\n```\nGame.volt: src/Shared/Network/ServerShard2.luau is missing\n```\n\nA shard file the schema no longer writes is reported as no longer generated ([A schema too big for one module](#a-schema-too-big-for-one-module)):\n\n```\nGame.volt: src/Shared/Network/ServerShard3.luau is no longer generated\n```\n\nEach module's first comment names the Volt version that wrote it, so after you upgrade `volt` every module reads as out of date until you compile again.\n\n### A schema in several files\n\nA large game can split its schema across a folder. `volt` compiles every `.volt` file directly inside the folder, and none in its subfolders, as one schema. This example has one mode, `Arena`, that reuses a file the main game keeps elsewhere:\n\n```\nArena/\n  Network/          the generated modules go here\n  Schemas/\n    Arena.volt      the options\n    Round.volt\n    Types.volt\nGame/\n  Schemas/\n    Combat.volt\n    Types.volt\n```\n\nOne file in the folder sets the options. Here it is `Arena/Schemas/Arena.volt`, which may also hold declarations:\n\n```\noption clientOutput = \"../Network/Client.luau\"\noption serverOutput = \"../Network/Server.luau\"\noption typesOutput = \"../Network/Types.luau\"\n\nnamespace Arena {\n\tevent Ready {\n\t\tfrom: Client, type: Reliable, call: SingleSync,\n\t}\n}\n```\n\nThe other files hold only declarations. `Arena/Schemas/Round.volt` uses a type that `Arena/Schemas/Types.volt` declares:\n\n```\nnamespace Round {\n\tevent Start {\n\t\tfrom: Server, type: Reliable, call: SingleAsync,\n\t\tdata: (score: Score),\n\t}\n}\n```\n\n```\ntype Score = u16(0..1000)\n```\n\nCreate `Arena/Network` once, then compile the folder by naming it:\n\n```sh\nvolt Arena/Schemas\n```\n\nThe output paths are relative to the options file's folder, and the scope is the options file's name, `Arena`. To reuse a file kept in another folder, name it after the folder. Every path on the command line is relative to the folder you run the command in:\n\n```sh\nvolt Arena/Schemas Game/Schemas/Combat.volt\n```\n\nA reused file compiles only when every name it uses is declared somewhere in the schema. This is how a mode builds on a base layer of shared types. `Game/Schemas/Combat.volt` uses `Hit`:\n\n```\nnamespace Combat {\n\tevent Strike {\n\t\tfrom: Client, type: Reliable, call: SingleSync,\n\t\tdata: Hit,\n\t}\n}\n```\n\nand the game declares `Hit` in `Game/Schemas/Types.volt`:\n\n```\nstruct Hit { target: u16, amount: u16(1..999) }\n```\n\nSo the command above fails, because nothing in the schema declares `Hit`:\n\n```\nGame/Schemas/Combat.","readmeTruncated":true,"readmeFull":"https://api.forest.dev/v1/package/fadeluc-123/roblox/volt/0.1.0/readme"}