RunicNPC

Runic Gateway's own NPC plugin for Rust, on Oxide and Carbon.

Other plugins drive it through an API, and admins use it directly in game through chat commands. It works on its own, and on a Runic Gateway server the website authors its NPC profiles and events use its NPCs. The plan of record, stage by stage, is docs/runicnpc/PLAN.md.

Status: stage 2. The NPC, its profiles, placements and routes, and the API other plugins call. The in-game /rnpc commands arrive in stage 3; until then profiles are edited in data/RunicNPC/profiles.json (then rnpc.reload), and placements and routes are made through the API.

Requirements

• Kits — required. A profile names kits, and that is how every RunicNPC NPC is equipped (D217). The plugin declares // Requires: Kits, so neither framework loads it without Kits.
• Oxide 2.0.7726 or Carbon 2.0.259, or newer: the builds it has been loaded on (plugin.toml).

Installing it

On a Runic Gateway server, the installer and the Pterodactyl egg will install it from the Rust bundle, pinned and checksummed (D224, from stage 4). Until then, and on any other server:

1. Download runicnpc-<version>.tar.gz and SHA256SUMS from this repository's releases, and check the tarball against it (sha256sum -c SHA256SUMS).
2. Copy runicnpc/RunicNPC.cs into oxide/plugins/ or carbon/plugins/. The framework compiles and loads it on the write.

runicnpc/manifest.json, beside it, states the release's version, commit, API version, framework floors, required plugins, and the sha256 of every file it ships.

Checking it

rnpc.status

Answers at the server console and over RCON: the version, the API version, and which of the plugin's hooks have fired. A hook that never fires is the first sign a Rust or framework update has renamed it, because neither framework reports a hook that matches nothing.

For other plugins

Every call is prefixed RunicNpc_ and reached through Call:

[PluginReference] private Plugin RunicNPC;

int api = RunicNPC?.Call<int>("RunicNpc_ApiVersion") ?? 0;

The API is version 2, documented in docs/runicnpc/API.md: spawning and removing NPCs by owner, profiles, placements, routes, the cost warning, and the hooks it raises. The API version moves when a call or a raised hook changes shape, not on every release.

Repository layout

Path	What
plugin/RunicNPC.cs	The plugin. The only file a server gets.
plugin.toml	Its declarations: API version, framework floors, required plugins. The release copies them into the manifest.
scripts/checkPlugin.js	The static checks run on every pull request and again before a release (see its header).
tools/	Developer scaffolding for the test rigs, never shipped: the panel scripts (see tools/rigs.example.json); RunicNpcHarness.cs, the stage 1 measurement plugin; RunicNpcTest.cs, the stage 2 test harness (rnt.run all, then rnt.after after a reload or restart); and fieldlist/ with managed.js, which regenerate the swap's field list (below).

After a Rust update: the swap's field list

Our NPC is Rust's scientist with two components swapped, and the swap copies a fixed list of fields (D232), generated from Rust's unmodified assembly. rnpc.status reports it as swap fields: npc=64/64 brain=32/32 missing=- added=-. On Carbon, where the assembly is unmodified, added names any field Rust has added since the list was made. To regenerate it:

node tools/managed.js carbon <dir>                         # the Carbon rig's RustDedicated_Data/Managed
dotnet run --project tools/fieldlist -- <dir>              # rewrites the block in plugin/RunicNPC.cs

Use the Carbon rig: Oxide's patcher makes Rust's private fields public, so its assembly no longer says which fields Rust itself serialises.

Releases

Work lands on edge and is cut over to main; every releasable push to main tags and publishes a release (.gitea/workflows/release.yml). The version comes from Conventional Commits since the last tag. v1.0.0 is stage 9's release, the one module-rust then requires.

Contributing

See CONTRIBUTING.md — including the AI-disclosure rule — and report security problems privately as SECURITY.md describes.

License

GPL-3.0-or-later — see LICENSE.md.