wtclaude
f8084955e8
All checks were successful
PR Checks / plugin-checks (pull_request) Successful in -1m38s
RunicNPC now spawns its own NPC: Rust's scientist with its ScientistNPC and ScientistBrain swapped for ours, copying a fixed field list generated from Rust's unmodified assembly (D232, tools/fieldlist). Profiles live in data/RunicNPC/profiles.json in the approved shape (D238); placements persist with each/group respawn (D236) and wait for a missing profile or route (D237); roamers wander, follow Rust's monument paths, or walk a route (D233, D234), with our own chase where Rust's needs an AI zone; sentries hold their spot; NPCs walk home and sleep past 160 m of any player (D235). Spawns wait for the navmesh and are spread over frames; caps are off by default and the cost warning is shown instead (D227). The whole PLAN.md section 4 API and its hooks are in, documented in docs/runicnpc/API.md. tools/RunicNpcTest.cs is the stage 2 harness; every group passed on both rigs, and after a plugin reload and a server restart. checkPlugin no longer counts an override (RunicNpcPlayer.OnDied) as a hook. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY
100 lines
4.7 KiB
Markdown
100 lines
4.7 KiB
Markdown
# RunicNPC
|
|
|
|
Runic Gateway's own NPC plugin for [Rust](https://rust.facepunch.com/), 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](https://gitea.whitlocktech.com/RunicGateway) server the
|
|
website authors its NPC profiles and events use its NPCs. The plan of record, stage by stage, is
|
|
[`docs/runicnpc/PLAN.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/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](https://umod.org/plugins/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](https://gitea.whitlocktech.com/RunicGateway/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](https://gitea.whitlocktech.com/RunicGateway/runicnpc-rust/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`:
|
|
|
|
```csharp
|
|
[PluginReference] private Plugin RunicNPC;
|
|
|
|
int api = RunicNPC?.Call<int>("RunicNpc_ApiVersion") ?? 0;
|
|
```
|
|
|
|
The API is version 2, documented in
|
|
[`docs/runicnpc/API.md`](https://gitea.whitlocktech.com/RunicGateway/docs/src/branch/main/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:
|
|
|
|
```bash
|
|
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](CONTRIBUTING.md) — including the AI-disclosure rule — and report security
|
|
problems privately as [SECURITY.md](SECURITY.md) describes.
|
|
|
|
## License
|
|
|
|
GPL-3.0-or-later — see [LICENSE.md](LICENSE.md).
|