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 0. The plugin loads, answers its API version, and reports on itself. It spawns nothing yet. Stage 1 is a measuring spike; the NPC and its API arrive in stage 2.

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;

Stage 0 has only RunicNpc_ApiVersion(). The full API is planned in PLAN.md §4 and will be documented as docs/runicnpc/API.md in stage 2. 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 (see tools/rigs.example.json).

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.