wtclaude
4e2c2dc439
Completes the uMod mirror beyond the Rust hook table, and adds agent/ — the same facts in TSV/JSONL at ~46% of the tokens. New prose: - OXIDE_API.md: the 19 developer pages under umod.org/documentation/api/ — plugin structure, hooks, commands, IPlayer, permissions, config, data files, database, localization, timers, web requests, dependencies, integration, preprocessor directives, security, style guide, CI, review. This is the framework our plugin is a guest in, where HOOKS.md is what the game says. - OPERATING.md: the 6 operator pages — installing Oxide on a server, then installing, configuring and permissioning plugins. New machine-readable set (agent/): - hooks.tsv 477 rows, ~31% of HOOKS.md - items.tsv 678 rows, ~80% of DEFINITIONS.md's item table - skins.tsv 104 rows covering 2,590 skins, ~77% - api.jsonl 150 code examples, ~47% of the two prose docs Generated in the same pass as the markdown, so the two cannot drift. HOOKS.md gains the universal-hook split: 34 of the 477 are uMod's own Covalence hooks, raised identically on every game uMod supports. Verified against /documentation/games/universal in the same capture - all 34 are in the Rust set and the Rust page adds none of its own, so the overlap is exact. The distinction is architectural: a universal hook is the portable part of the surface. Two things worth recording from building it: - The first skins.tsv was one row per skin and came out 11% LARGER than the markdown it replaces. Grouping it one row per item is what made it a saving. The token win is real for prose (3.2x on hooks) and small for tables that were already dense - agent/README.md says so plainly rather than claiming a flat number. - Signature extraction by brace depth silently captured body lines (a nested '}' in OnUserConnected's example ended the block early). It now matches on the hook's own name; all 477 rows verified to carry a real signature. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016wDDVXWMDz82WqE1i969r4
372 lines
11 KiB
Markdown
372 lines
11 KiB
Markdown
# Running Oxide: the operator's side
|
|
|
|
What a **server owner** does — install the mod framework onto a game server, then install,
|
|
configure and permission plugins. This is the surface our own deployment story has to sit on top
|
|
of, the way [`installer/INSTALL.md`](../../installer/INSTALL.md) sits on top of ServUO.
|
|
|
|
> **Mirrored verbatim from uMod on 2026-09-15** — 6 pages. uMod is upstream and normative.
|
|
|
|
---
|
|
|
|
## Contents
|
|
|
|
- [Getting Started](#getting-started-getting-started) — Installing uMod/Oxide onto a game server
|
|
- [Plugins - Getting Started](#plugins-getting-started-plugins-getting-started) — What a plugin is, from the server owner's side
|
|
- [Plugin installation](#plugin-installation-plugins-installation) — Installing, updating and removing a plugin
|
|
- [Plugin configuration](#plugin-configuration-plugins-configuration) — Editing a plugin's config file
|
|
- [Data Files](#data-files-plugins-data-files) — Where plugin data lives on disk
|
|
- [Permissions](#permissions-plugins-permissions) — Granting permissions and managing groups in-game
|
|
|
|
---
|
|
|
|
<a id="getting-started-getting-started"></a>
|
|
|
|
## Getting Started
|
|
|
|
<sub>Source: <https://umod.org/documentation/getting-started></sub>
|
|
|
|
---
|
|
|
|
### Installation
|
|
|
|
### Server requirements
|
|
|
|
The Oxide platform requirements vary depending on the game server.
|
|
|
|
More information about Oxide support for specific games may be found on the [Game Support](https://umod.org/documentation/umod/game-support) page.
|
|
|
|
### Installing Oxide
|
|
|
|
**Via Direct Download**
|
|
|
|
1. Download the Oxide version [specific to your game](https://umod.org/games).
|
|
2. Copy the files over your existing server installation
|
|
|
|
### Plugins
|
|
|
|
Plugins are self-contained bits of code which modify game server behavior.
|
|
|
|
For more information about plugins, view the [Plugins - Getting Started](https://umod.org/documentation/umod/plugins/getting-started) page.
|
|
|
|
[View all available plugins](https://umod.org/plugins)
|
|
|
|
### Extensions
|
|
|
|
Extensions are generally large projects which add functionality to Oxide or make substantial changes to a server.
|
|
|
|
[View all available extensions](https://umod.org/extensions)
|
|
|
|
---
|
|
|
|
<a id="plugins-getting-started-plugins-getting-started"></a>
|
|
|
|
## Plugins - Getting Started
|
|
|
|
<sub>Source: <https://umod.org/documentation/plugins/getting-started></sub>
|
|
|
|
Plugins are self-contained bits of code which modify game server behavior.
|
|
|
|
---
|
|
|
|
### Code files
|
|
|
|
Plugins are code files distributed as CSharp (C#) files and will have a `.cs` file extension.
|
|
|
|
#### Installing a code file
|
|
|
|
More information about installing plugins may be found at [Plugins - Installation](https://umod.org/documentation/umod/plugins/installation).
|
|
|
|
### Configuring a plugin
|
|
|
|
Many plugins generate a `JSON` configuration file that a server administrator may use to change how the plugin works.
|
|
|
|
More information about configuring plugins may be found at [Plugins - Configuration](https://umod.org/documentation/umod/plugins/configuration).
|
|
|
|
### Plugin permissions
|
|
|
|
Many plugins have permissions which must be assigned in order to use plugin features.
|
|
|
|
More information about access control may be found at [Plugins - Permissions](https://umod.org/documentation/umod/plugins/permissions).
|
|
|
|
### Plugin commands
|
|
|
|
Many plugins have commands that may be used by players or server administrators. Not every game will have both console commands and chat commands (check [Game Support](https://umod.org/documentation/game-support) for availability of commands). By default commands should be available by console and in-game.
|
|
|
|
#### Console commands
|
|
|
|
A console command is a command which is run from...
|
|
|
|
1. In-game console (if game has one)
|
|
2. Server application window (if platform supports it)
|
|
3. RCON console (if game supports RCON)
|
|
|
|
#### Chat commands
|
|
|
|
Chat commands are prefixed with a `/` and run by players using in-game chat.
|
|
|
|
For example: `/help`
|
|
|
|
---
|
|
|
|
<a id="plugin-installation-plugins-installation"></a>
|
|
|
|
## Plugin installation
|
|
|
|
<sub>Source: <https://umod.org/documentation/plugins/installation></sub>
|
|
|
|
Installing Oxide plugins usually only takes a few mouse clicks.
|
|
|
|
---
|
|
|
|
### Server requirements
|
|
|
|
To install the plugin on the server, the server provider must support Oxide 2.0 or higher, else the plugins will not load or do anything.
|
|
|
|
If the server is not online, start it. Then, check that Oxide is fully installed by testing the `oxide.version` chat or console command.
|
|
|
|
### Download the source code
|
|
|
|
Download a plugin from the [plugins page](https://umod.org/plugins);
|
|
|
|
> **Warning.**
|
|
> **Do **not** rename the plugin or change the file extension.**
|
|
|
|
### Remote server
|
|
|
|
If the server is not hosted locally, connect to the server via an FTP client. If unsure of the FTP details, please contact the server host.
|
|
|
|
### Plugins directory
|
|
|
|
Find the `plugins` folder which is located by default at `oxide/plugins` if it has not been changed by the server host
|
|
|
|
### Upload the source code
|
|
|
|
Upload the plugin file into the "plugins" folder and it will be loaded automatically if Oxide is currently installed
|
|
|
|
Continue to [configuring the plugin](https://umod.org/documentation/umod/plugins/configuration)...
|
|
|
|
### Updating
|
|
|
|
If a plugin is already installed and an update is available simply overwrite the original (.cs) file and the new version will be loaded automatically.
|
|
|
|
---
|
|
|
|
<a id="plugin-configuration-plugins-configuration"></a>
|
|
|
|
## Plugin configuration
|
|
|
|
<sub>Source: <https://umod.org/documentation/plugins/configuration></sub>
|
|
|
|
Most plugins will generate a JSON configuration file once loaded. With this file, a server owner may change how a plugin works.
|
|
|
|
---
|
|
|
|
### Config directory
|
|
|
|
Configuration files are found in the `config` folder which is located by default in `oxide/config` (unless the server host has moved it).
|
|
|
|
### File name
|
|
|
|
A plugin configuration file will have the same name as the plugin itself.
|
|
|
|
For example, a plugin that is installed as `MyPlugin.cs` (if it is configurable) will be accompanied by a JSON file named `MyPlugin.json`
|
|
|
|
> **Warning.**
|
|
> **Do **not** rename the configuration file or change the file extension.**
|
|
|
|
If a plugin is installed but not configurable, no configuration file will be present.
|
|
|
|
If a plugin is configurable but no configuration file is available, the plugin may be broken; in this case, check the log files under the `oxide/logs` directory for errors.
|
|
|
|
### Valid JSON
|
|
|
|
All plugin configuration files are saved as JSON (JavaScript Object Notation). Configuration files *must* be valid JSON. Use a validator such as [jsonlint.com](https://jsonlint.com) to ensure the configuration is valid JSON.
|
|
|
|
### Applying changes
|
|
|
|
After making changes to a plugin configuration file, reload the plugin in the server console by using the `oxide.reload` command. For example:
|
|
|
|
```
|
|
oxide.reload MyPlugin
|
|
```
|
|
|
|
Continue to [setting permissions](https://umod.org/documentation/umod/plugins/permissions)...
|
|
|
|
---
|
|
|
|
<a id="data-files-plugins-data-files"></a>
|
|
|
|
## Data Files
|
|
|
|
<sub>Source: <https://umod.org/documentation/plugins/data-files></sub>
|
|
|
|
Data files are `JSON` files that plugins may use to store arbitrary data.
|
|
|
|
### Data directory
|
|
|
|
Data files may be found in the `data` folder which located by default in `oxide/data` (unless the server host has moved it).
|
|
|
|
### File names
|
|
|
|
Data files do not follow any naming convention, a plugin author may specify any name when creating a data file.
|
|
|
|
It is recommended to plugin authors, when creating a large number of data files, to create them in a subdirectory specific to their plugin.
|
|
|
|
### Valid JSON
|
|
|
|
All plugin data files are saved as JSON (JavaScript Object Notation). Data files *must* be valid JSON. If editing a data file manually, use a validator such as [jsonlint.com](https://jsonlint.com) to ensure the data file is valid JSON.
|
|
|
|
---
|
|
|
|
<a id="permissions-plugins-permissions"></a>
|
|
|
|
## Permissions
|
|
|
|
<sub>Source: <https://umod.org/documentation/plugins/permissions></sub>
|
|
|
|
Permissions allows server owners to give players unique abilities and benefits on their servers.
|
|
|
|
---
|
|
|
|
Administering permissions is easy; simply enter the desired command and you're done! If your server does not have a console, you can use any compatible RCON tool or remote console to send the commands to the server. Most Oxide-supported games also support the permission commands in the chat, or will soon.
|
|
|
|
For this guide, the permission `epicstuff.use` will be used as an example. Keep in mind that permissions only exist if provided by a plugin or Oxide itself.
|
|
|
|
By default, the groups that are created by Oxide are: admin and default. These can be changed by editing those under the oxide.config.json file. The admin group will automatically be assigned to players that are recognized as admin (via ownerid) by the server. The "default" group will automatically be assigned to ALL players that connect to the server.
|
|
|
|
### Players
|
|
|
|
#### Grant a permission to an individual player
|
|
|
|
```
|
|
oxide.grant user Wulf epicstuff.use
|
|
```
|
|
|
|
#### Revoke a permission from an individual player
|
|
|
|
```
|
|
oxide.revoke user Wulf epicstuff.use
|
|
```
|
|
|
|
#### Show a player's permissions
|
|
|
|
```
|
|
oxide.show user Wulf
|
|
```
|
|
|
|
#### Showing which player or group has a permission
|
|
|
|
Sometimes this command is helpful when tracking down who has a permission.
|
|
|
|
```
|
|
oxide.show perm epicstuff.use
|
|
```
|
|
|
|
### Groups
|
|
|
|
#### Grant a permission to an entire group
|
|
|
|
```
|
|
oxide.grant group admin epicstuff.use
|
|
```
|
|
|
|
#### Revoke a permission from a group
|
|
|
|
```
|
|
oxide.revoke group admin epicstuff.use
|
|
```
|
|
|
|
#### Adding a player to an existing group
|
|
|
|
Adding a player to a group will give them all of the permissions assigned to that group.
|
|
|
|
```
|
|
oxide.usergroup add Wulf admin
|
|
```
|
|
|
|
#### Removing a player from an existing group
|
|
|
|
Removing a player from a group will remove from them all of the permissions assigned to that group.
|
|
|
|
```
|
|
oxide.usergroup remove Wulf admin
|
|
```
|
|
|
|
#### Adding an entirely new group
|
|
|
|
```
|
|
oxide.group add vip
|
|
```
|
|
|
|
```
|
|
oxide.group add vip VIP 0
|
|
```
|
|
|
|
#### Removing an existing group
|
|
|
|
```
|
|
oxide.group remove vip
|
|
```
|
|
|
|
#### Setting the title or rank of a group
|
|
|
|
The group title is usually a short description of a group, sometimes used for chat titles. The rank is a number which sorts a group based on its importance.
|
|
|
|
```
|
|
oxide.group set vip "[VIP Member]"
|
|
```
|
|
|
|
```
|
|
oxide.group set vip "[VIP Member]" 1
|
|
```
|
|
|
|
#### Setting the parent group of another group
|
|
|
|
A group will inherit all permissions from its parent group.
|
|
|
|
```
|
|
oxide.group parent admin default
|
|
```
|
|
|
|
#### Showing a group's members and permissions
|
|
|
|
```
|
|
oxide.show group admin
|
|
```
|
|
|
|
### Showing all groups or permissions
|
|
|
|
To show all of the permission groups, simple use the command below.
|
|
|
|
```
|
|
oxide.show groups
|
|
```
|
|
|
|
The show all of the registered permissions from plugins and Oxide, use the command below.
|
|
|
|
```
|
|
oxide.show perms
|
|
```
|
|
|
|
### Using wildcards
|
|
|
|
A wildcard is something that covers multiple things at once time. For permissions, this is the * symbol. You can use the wildcard (*) to grant multiple permissions at one time. This can be done with all permissions or per plugin based on prefix.
|
|
|
|
```
|
|
oxide.grant group admin *
|
|
```
|
|
|
|
```
|
|
oxide.grant user Wulf oxide.*
|
|
```
|
|
|
|
### Conclusion
|
|
|
|
The same commands are also available with the "o." prefix (ex. "o.grant").
|
|
|
|
That's the basics to permissions for Oxide. Permissions give you a fantastic way to manage staff without worrying about them abusing powers from the game's admin functionality (such as flight, noclip, super speed, etc.) so they can still enjoy the game but also help monitor your server at the same time.
|
|
|
|
---
|
|
|
|
<sub>Mirrored from uMod, 2026-09-15.</sub>
|