{"id":"fadeluc-123/decree","name":"decree","scope":"fadeluc-123","platform":"roblox","description":"Whiteoak's fork of Cmdr, on Volt","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":{"evaera/promise":{"version":"^4.0.0","alias":"Promise"}},"integrity":"0dab182b6eeeeaa11295d0b1b4f990ecd808637d0420ed95c0340a082036efeb","likes":0,"downloads":0,"install":"forest install fadeluc-123/decree","url":"https://forest.dev/p/roblox/fadeluc-123/decree","files":"https://api.forest.dev/ai/package/roblox/fadeluc-123/decree/files","readme":"# Decree\n\nDecree is an admin command console for Roblox games, rewritten from Cmdr 1.13.1 onto Volt, Whiteoak's networking library. The server decides everything. Each player's console holds only the commands the game grants that player, every command that reaches the server passes the game's `beforeRun` hook first, and the server parses and checks every line again, whatever the client checked.\n\nDecree is published on Wally as `fadeluc-123/decree`. This README covers version 0.1.0.\n\n## Install\n\n### wally.toml\n\nDecree's generated network modules require the game's own Volt and Promise at `ReplicatedStorage.Packages.Volt` and `ReplicatedStorage.Packages.Promise`, so the game installs both itself. Add these sections beside the game's own `[package]` section:\n\n```toml\n[place]\nshared-packages = \"game.ReplicatedStorage.Packages\"\n\n[dependencies]\nPromise = \"evaera/promise@4.0.0\"\nVolt = \"fadeluc-123/volt@0.1.0\"\n\n[server-dependencies]\nDecree = \"fadeluc-123/decree@0.1.0\"\n```\n\n- The aliases must be exactly `Volt` and `Promise`. Wally names each installed module after its alias, and instance names are case sensitive.\n- Decree's manifest sets `realm = \"server\"`, so it goes under `[server-dependencies]`, installs into `ServerPackages/`, and its server code never replicates.\n- Decree depends on Promise, and the game lists Promise too, so Wally installs Promise once in `Packages/` and links Decree to it through `shared-packages`. Without the `[place]` block, `wally install` stops with \"A server or dev dependency is depending on a shared dependency\" and leaves a half-written tree.\n- Decree 0.1.0 was compiled by Volt 0.1.0, and the game's Volt must be on the same 0.1 line. Wally can't check that pairing, since Volt is only a dev dependency of Decree, and it would install a second Volt line beside the first instead of refusing it. Under Wally's rules `0.1.0` means `>=0.1.0, <0.2.0`. A Volt runtime on another line errors at the first require, for example `Volt: Decree's schema was compiled by Volt 0.1.0 and the runtime is 0.2.0`.\n\n### Rojo\n\nMap `Packages` to `ReplicatedStorage.Packages` and `ServerPackages` to a server container:\n\n```json\n{\n\t\"name\": \"Game\",\n\t\"tree\": {\n\t\t\"$className\": \"DataModel\",\n\t\t\"ReplicatedStorage\": {\n\t\t\t\"Packages\": { \"$path\": \"Packages\" }\n\t\t},\n\t\t\"ServerScriptService\": {\n\t\t\t\"ServerPackages\": { \"$path\": \"ServerPackages\" }\n\t\t}\n\t}\n}\n```\n\nThe server requires Decree as `ServerScriptService.ServerPackages.Decree`. That require sets Decree up: it binds Decree to Volt and moves the client half to `ReplicatedStorage.DecreeClient`, where the client requires it.\n\n### Typed install\n\nWally replaces each package with a one-line link module that loses the package's exported types. After every `wally install`, run these four commands in this order, with the project file your game builds with:\n\n```sh\nwally install\nrojo sourcemap default.project.json --output sourcemap.json\nwally-package-types --sourcemap sourcemap.json Packages/\nwally-package-types --sourcemap sourcemap.json ServerPackages/\n```\n\n`wally-package-types` 1.6.2 exits 1 on a second pass over links it has already typed (`'REQUIRED_MODULE' is not a function call`) and on a link the sourcemap doesn't hold, so it always runs on a fresh install with a fresh sourcemap.\n\nDecree is written for luau-lsp's new type checker. Analyze with `--flag:LuauSolverV2=true`, since without it the command line runs the old checker:\n\n```sh\nluau-lsp analyze --platform=roblox --flag:LuauSolverV2=true --sourcemap=sourcemap.json --definitions=globalTypes.d.luau src\n```\n\nIn VS Code, turn the same checker on with `\"luau-lsp.fflags.enableNewSolver\": true` in the workspace settings. This release was built and checked with Rojo 7.7.0, Wally 0.3.2, wally-package-types 1.6.2 and luau-lsp 1.70.0.\n\n## Quick start\n\nThese four files give every player an `echo` command. The server script is `ServerScriptService/Admin.server.luau`:\n\n```luau\n--!strict\nlocal ServerScriptService = game:GetService(\"ServerScriptService\")\n\nlocal Decree = require(ServerScriptService.ServerPackages.Decree)\n\nlocal OPEN_GROUP: string = \"Player\" -- The command group every player holds\n\ntype CommandDefinition = Decree.CommandDefinition\ntype Context = Decree.Context\n\nDecree.registry:registerHook(\"beforeRun\", function (context: Context): string?\n\tif context.group ~= OPEN_GROUP then\n\t\treturn `{context.name} is not open to you.`\n\tend\n\n\treturn nil\nend)\n\nDecree.registry:registerCommandsIn(ServerScriptService.Commands)\n\nDecree:start({\n\trate = { perSecond = 1, burst = 4 },\n\n\tcanAccess = function (_: Player, command: CommandDefinition): boolean\n\t\treturn command.group == OPEN_GROUP\n\tend,\n})\n```\n\nThe command is a folder, `ServerScriptService/Commands/Echo/`, holding its definition, `Echo.luau`:\n\n```luau\n--!strict\nreturn {\n\tname = \"echo\",\n\tdescription = \"Replies with the text you give it.\",\n\tgroup = \"Player\",\n\targs = {\n\t\t{ name = \"text\", type = \"string\", description = \"What to reply with\" },\n\t},\n}\n```\n\nand its server half, `EchoServer.luau`:\n\n```luau\n--!strict\nlocal ServerScriptService = game:GetService(\"ServerScriptService\")\n\nlocal Decree = require(ServerScriptService.ServerPackages.Decree)\n\ntype Context = Decree.Context\ntype Kind = Decree.Kind\n\nreturn function (_: Context, text: string): (string, Kind)\n\treturn text, \"Ok\"\nend\n```\n\nThe client script goes in `StarterPlayer/StarterPlayerScripts`:\n\n```luau\n--!strict\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\nlocal ServerScriptService = game:GetService(\"ServerScriptService\")\n\n-- The server moves the client half to ReplicatedStorage at run time, so its type comes from where Wally installs it\ntype DecreeClient = typeof(require(\n\tServerScriptService.ServerPackages._Index[\"fadeluc-123_decree@0.1.0\"].decree.DecreeClient\n))\n\nlocal DecreeClient: DecreeClient = (require :: any)(ReplicatedStorage:WaitForChild(\"DecreeClient\"))\n\nDecreeClient:start()\n```\n\nIn a play test, press F2 and type `echo hello`. The console prints `hello` in the Ok color. [Typing notes](#typing-notes) explains the client's two require lines.\n\n## The server\n\n### start\n\n`Decree:start(settings)` runs once, after the game has registered its hooks and commands. Its settings are:\n\n- `rate = { perSecond: number, burst: number? }`, required. Each player's allowance for typed lines and, separately, for list requests, both applied through Volt. `burst` is `perSecond` when left out, and both must be numbers above 0. Until `start` runs, the rates in Decree's schema apply, and every line is refused anyway.\n- `canAccess: (player: Player, command: CommandDefinition) -> boolean`, optional, but without it no player holds any command. It must answer at once, without yielding. Only `true` grants the command, and an error answers `false` with a warning.\n- `confirmSeconds: number`, required once any registered command or subcommand has a `confirm` key. How long a line that asks for confirmation waits for `confirm`. It must be above 0.\n- `onFailure: (player: (Player | Bot)?, kind: string, detail: string) -> ()`, optional. Hears every failure Volt reports on Decree's scope, each on a thread of its own. `Bot` is Volt's `{ Name: string }`. See [Volt failures](#volt-failures).\n\n`start` raises an error on a second call, on settings that aren't a table, on a missing `rate` or a `perSecond` or `burst` that isn't a number above 0, on a `confirmSeconds` that isn't a number above 0, on a `canAccess` or `onFailure` that isn't a function, and on no `confirmSeconds` while a registered command asks for confirmation. Each message starts with `[Decree]`.\n\nIt warns once when no `beforeRun` hook is registered yet (`[Decree] No beforeRun hook is registered, so every command is refused until one is.`) and once when `canAccess` is missing (`[Decree] start was given no canAccess, so no player holds any command.`).\n\nUntil `start` runs, every typed line is refused with \"Decree has not started\" and every console gets an empty list, which `start` then replaces.\n\n### Registering commands, types and hooks\n\nThe server object's `registry` holds the commands, the argument types and the hooks:\n\n| Call | What it does |\n|---|---|\n| `registerCommandsIn(container)` | Registers every command in a container and the folders inside it. See [A command's modules](#a-commands-modules). |\n| `registerCommand(module, serverModule?, clientModule?)` | Registers the command a definition module returns, with the run its server half returns and its device half. |\n| `registerCommandObject(definition)` | Registers a definition table directly. It has no device half. |\n| `registerHook(name, callback, priority?)` | Registers a `beforeRun` or `afterRun` hook on the server. See [Hooks](#hooks). |\n| `registerType(name, definition)` | Registers an argument type. See [Your own types](#your-own-types). |\n| `registerTypesIn(container)` | Registers every type of every ModuleScript in a container and its folders, each module returning `{ [string]: TypeDefinition }`. |\n| `registerTypeAlias(name, union)` | Names a whole union of types, such as `\"string # integer\"`, which an argument's `type` can then name. |\n| `registerTypePrefix(name, union)` | Adds a prefixed type after a type's name, such as `\"# positiveInteger\"`, so a prefix typed before a value picks another type. |\n| `getCommand(name)` | The definition a name or alias finds, in any case. |\n| `getCommands()` | Every definition once, in registration order. |\n| `getCommandNames(includeAliases?, executor?)` | Every command's name, with aliases when asked. With an executor, only the commands that player holds. |\n| `getDeviceHalf(name)` | The `{Name}Client` module a command registered with. |\n| `getType(name)`, `getTypeName(name)`, `getTypeNames()`, `hasType(typeName)` | Type lookups: a definition, the union a name expands to, every registered name, and whether every type in a name's union is registered. |\n| `hasHook(name)` | Whether any hook of that name is registered. |\n\nA command registered after `start` reaches the joined players' lists on the next deferred step.\n\n### Gating by rank\n\n`canAccess` decides which commands a player's console holds, and with them which device halves are cloned to that player. The `beforeRun` hook decides each run. They should agree, but the hook is the gate: a player's client can send any text, and the server refuses it there.\n\nDecree asks `canAccess` about every command when `start` runs, when a player joins, when a command registers after `start`, and when the game calls `Decree:refreshAccess(player)`. When the answer changes a player's list, Decree clones or destroys that player's device halves to match and pushes them the whole new list once their console has asked for one, so a rank that arrives after the player joins shows without a rejoin.\n\nThis gate gives each command group a lowest rank and reads each player's rank from an attribute the game sets:\n\n```luau\n--!strict\nlocal ServerScriptService = game:GetService(\"ServerScriptService\")\n\nlocal Decree = require(ServerScriptService.ServerPackages.Decree)\n\nlocal RANK: string = \"Rank\" -- The player attribute the game sets to each player's rank\nlocal RANK_MISSING: string = \"Your rank is still loading, so try again in a moment.\"\n\n-- The lowest rank that holds each command group, by the group a definition names\nlocal GROUP_RANKS: { [string]: number } = {\n\tPlayer = 0,\n\tAdmin = 255,\n}\n\ntype CommandDefinition = Decree.CommandDefinition\ntype Context = Decree.Context\n\nlocal function holds(rank: number?, group: string?): boolean\n\tif rank == nil or group == nil then\n\t\treturn false\n\tend\n\n\tlocal needed: number? = GROUP_RANKS[group]\n\n\treturn needed ~= nil and rank >= needed\nend\n\nDecree.registry:registerHook(\"beforeRun\", function (context: Context): string?\n\tlocal rank = context.executor:GetAttribute(RANK) :: number?\n\n\tif rank == nil then\n\t\treturn RANK_MISSING\n\telseif not holds(rank, context.group) then\n\t\treturn `{context.name} needs a higher rank than yours.`\n\tend\n\n\treturn nil\nend)\n\nDecree.registry:registerCommandsIn(ServerScriptService.Commands)\n\nDecree:start({\n\trate = { perSecond = 1, burst = 4 },\n\tconfirmSeconds = 30,\n\n\tcanAccess = function (player: Player, command: CommandDefinition): boolean\n\t\treturn holds(player:GetAttribute(RANK) :: number?, command.group)\n\tend,\n})\n```\n\nWherever the game sets a player's rank, once it knows it and again whenever it changes, it calls `refreshAccess` after:\n\n```luau\nplayer:SetAttribute(RANK, rank)\nDecree:refreshAccess(player)\n```\n\nHooks and `canAccess` never yield, so a rank that takes a web call, such as a group rank, is looked up when the player joins. Until it arrives the player holds nothing, and the hook refuses their lines.\n\n### Hooks\n\n`Decree.registry:registerHook(name, callback, priority?)` registers a hook on the server, the only place hooks run. `name` is `\"beforeRun\"` or `\"afterRun\"`, and a hook is `(context: Context) -> string?`. Hooks run from the lowest `priority` up, 0 when left out, and hooks of one priority run in the order they registered. A hook is called synchronously.\n\n- `beforeRun` hooks run before every command that reaches the server, after its line has parsed and validated. A hook returns `nil` to pass the command, and any other value refuses it, as text with the Refused kind. The first refusal ends the run.\n- With no `beforeRun` hook registered, every command that reaches the server is refused with \"No permission hook is registered\", in Studio too.\n- `afterRun` hooks run once the command has an answer, with that answer in `context.response`. This covers a server half that raised, rejected or ran past its time limit, whose answer is the Error reply, and the question a `confirm` command asks. The first hook that returns text replaces the reply, as Info. They don't run for a line a `beforeRun` hook or a guard refused.\n\nThis `afterRun` hook prints an audit line for every command that reached its run:\n\n```luau\nDecree.registry:registerHook(\"afterRun\", function (context: Context): string?\n\tprint(`{context.executor.Name} ran \"{context.rawText}\" and got \"{tostring(context.response)}\"`)\n\n\t-- Any text returned here would replace the reply\n\treturn nil\nend)\n```\n\nOn the server a typed line goes through these steps: Volt's packet, decode and rate checks; Decree's refusals of a bot, a line before `start` and a second line while one runs; a `confirm` line, which Decree answers itself; parsing and validating every argument again; the `beforeRun` hooks; the definition's guards; the confirmation question; the server half; the `afterRun` hooks; and the reply, once the lines the command sent have gone out.\n\n### Other server calls\n\n- `Decree:refreshAccess(player)` asks `canAccess` about every command again for one player. See [Gating by rank](#gating-by-rank).\n- `Decree.dispatcher:evaluateAndRun(text, player)` runs a line as that player from server code, through the same hooks and guards, and returns a Promise of the reply's text and kind that never rejects. With no player it answers \"A command run from the server needs the player who runs it.\" as Refused.\n- `Decree.dispatcher:sendEvent(player, \"AddLine\", text, kind?)` prints a line in a player's console from the game's own code. `AddLine` is the only event the server sends, and a line sent this way has no caller, so it isn't filtered.\n- `Decree.util` holds the text helpers and the type builders, and `Decree.guards` the guard factories.\n\n### Volt failures\n\nWhen the game passes `onFailure`, Decree registers one handler with Volt. A `handshake` failure first goes to Volt's own default handler, which kicks a player whose client schema doesn't match with Volt's message and only warns about a bot. Then every failure, `handshake` included, goes to `onFailure` on a thread of its own. For every other kind Volt's default handler no longer runs, so its warnings stop and `onFailure` takes their place.\n\nWithout `onFailure`, Volt's default handler handles every kind: `departed` and `budget` are silent, `handshake` kicks the player (never a bot), and any other kind warns, at most once a minute","readmeTruncated":true,"readmeFull":"https://api.forest.dev/v1/package/fadeluc-123/roblox/decree/0.1.0/readme"}