Nocturne Forge

Nocturne Forge is an open-source, evidence-first V Rising reverse-engineering and mod-creation toolkit for legitimate local installations, private development games, and modded servers whose owners install the required plugins.

It is not a DRM crack, piracy tool, cheat menu, anti-cheat bypass, or arbitrary memory editor.

Release status

Version 0.1.0-research-preview implements the fully specified discovery and safety foundations from Phases 1–10 of the supplied brief:

• an IL2CPP assembly survey with SHA-256 provenance;
• an admin-only, server-authoritative entity and component inspector;
• a searchable 23,583-entry prefab catalog;
• semantic snapshot comparison that preserves unreadable fields;
• a double-gated typed-field editor with snapshots, append-only audit, conflict-aware undo, and reset;
• bounded entity/component tracing with automatic stop and drop counts;
• an 11-archetype NPC research catalog;
• a strict, versioned NPC definition schema that rejects unknown fields;
• a staged deterministic-donor factory contract with rollback;
• an external JSON identity registry with persistence-key rebinding;
• a separate, buildable Ashbound Warden blueprint using observed donor, ability, faction, aggro, leash, and loot references.

The runtime plugin was load-tested on an isolated dedicated server and exported all 23,583 prefabs, 11 archetype studies, and a decoded Militia Guard donor snapshot. See docs/RUNTIME-VERIFICATION.md.

The downloaded brief is incomplete: D:\Downloads\message.txt ends at line 633, Phase 11, in the middle of * Patrol a. No missing requirements have been invented. The Ashbound Warden is therefore a validated deterministic-donor blueprint, not a claimed finished spawnable NPC mod. Runtime spawn, death, save/restart, custom-name presentation, persistent respawn, and mod-removal cleanup remain explicitly gated experiments.

Technical classification

Forge does not claim to register a new native V Rising prefab. The verified fallback design is a deterministic modified-prefab instance created from a compatible donor. The reusable factory orchestrator is implemented; its game-specific asynchronous spawn adapter is intentionally not armed until the remaining lifecycle experiments are completed on a backed-up disposable save.

Projects

src/
  Nocturne.Forge.Core/            schemas, evidence, diff, factory, identity
  Nocturne.Forge.Plugin/          in-game inspector/editor/tracer/catalog
  Nocturne.Forge.Cli/             offline catalog, diff, validation, research
  Nocturne.Forge.Workbench/       Windows NPC Studio authoring application
tools/
  Nocturne.Forge.AssemblySurvey/  hashed interop metadata discovery
tests/
  Nocturne.Forge.Core.Tests/      deterministic dependency-free tests
examples/
  Nocturne.AshboundWarden/        separate validated example blueprint
  Nocturne.Witch/                 first NPC Studio acceptance project
evidence/                         version-pinned generated observations
docs/                             audit, evidence contract, experiments, status
skills/nocturne-forge/            versioned Codex skill for Forge workflows

Requirements

• V Rising dedicated server v1.1.13.0-r99712-b17
• BepInEx IL2CPP 6.0.0-be.733 / runtime pack 1.733.2
• VampireCommandFramework (load-tested with 0.11.0)
• .NET 8 SDK for the CLI/tools/tests

The plugin fails closed when a deterministic game/IL2CPP input hash or required runtime API differs from the audited build. Generated interop DLL hashes are recorded as observations, not treated as stable identities.

Install the server plugin

Copy these release files to:

<VRisingServer>/BepInEx/plugins/NocturneForge/
  Nocturne.Forge.Core.dll
  Nocturne.Forge.Plugin.dll

Start the server once to create:

BepInEx/config/dev.nocturne.forge.cfg

Inspection is enabled by default. Both mutation settings are false by default:

[Mutation]
DevelopmentMode = false
DedicatedServerMutations = false

[NPC Studio]
LifecycleExperiments = false
ProbeLifetimeSeconds = 60
HeadlessProbeRequestFile =

Keep them false outside a disposable/private development server.

In-game commands

All commands are administrator-only. .nf is an alias for .forge.

.forge status
.forge inspect self|target|nearest
.forge inspect prefab <guid>
.forge inspect entity <index> <version>
.forge inspect component <name>
.forge export <selector>
.forge compare <selector-a> <selector-b>
.forge compare prefab <guid-a> <guid-b>
.forge catalog export
.forge catalog search <text> [limit]
.forge research bundle [donor-prefab-guid]
.forge npc list
.forge npc status
.forge npc probe <project-id>
.forge get <selector> <component> <field>
.forge set <selector> <component> <field> <value>
.forge undo
.forge reset <selector>
.forge trace self|target|nearest [seconds]
.forge trace component <name> [seconds]
.forge trace prefab <guid> [seconds]
.forge trace stop|status|export

The typed editor allowlist is limited to health, level, movement speed, aggro/leash values, and physical/spell power. Structural add/remove and unverified system/event tracing report a blocked result without mutation.

Complete JSON exports are written under:

BepInEx/config/NocturneForge/

CLI

forge prefab search <catalog.json> [text] [--match <contains|exact|token>] [--component <name>] [--category <category>] [--capability <name>]
forge prefab show <catalog.json> <guid>
forge prefab similar <catalog.json> <guid> [--limit <count>]
forge compare snapshot <first.json> <second.json> [--output <diff.json>]
forge definition validate <definition.json>
forge definition checksum <definition.json>
forge project validate <project.json> [--evidence <bundle.zip>]
forge project checksum <project.json>
forge project generate <project.json> <output-directory> --evidence <bundle.zip>
forge project package <project.json> <output.zip> --evidence <bundle.zip> --source <generated-source-directory> --generated-dll <dll> --forge-plugin <dll> --forge-core <dll> [--lifecycle-evidence <directory>]
forge lifecycle verify <project.json> <evidence-directory>
forge lifecycle headless-request <project.json> <output.json> <request-id> <x> <y> <z> --ack-disposable-server --ack-save-backup
forge package verify <package.zip>
forge evidence create <evidence-directory> <bundle.zip> --game-version <version> [--steam-build <id>]
forge evidence verify <bundle.zip>
forge evidence findings <bundle.zip> [--output <findings.md>]
forge research build <catalog.json> <research.json> [--candidates <count>]

NPC Studio Workbench

The Windows Workbench turns a verified Research Agent bundle into a strict, evidence-pinned .npcstudio.json project. It verifies every bundle entry before showing donors, limits results to coherent donor candidates, keeps unsupported appearance/AI/faction/ability/loot replacements inherited, and creates all seven lifecycle checks as notRun.

Run it from the SDK:

dotnet run --project .\src\Nocturne.Forge.Workbench\Nocturne.Forge.Workbench.csproj -c Release

Or publish a portable Windows build that does not require a separately installed .NET Desktop Runtime:

dotnet publish .\src\Nocturne.Forge.Workbench\Nocturne.Forge.Workbench.csproj -c Release -r win-x64 --self-contained true -o .\artifacts\NocturneForge-Workbench-win-x64

Paste a bundle path or use Browse, choose an evidence-backed donor, describe the NPC, and save to an optional explicit .npcstudio.json output path. Enter a new or empty mod-source directory to generate the deterministic BepInEx project directly in the Workbench. The generated plugin compiles and registers the strict definition with Forge; it is not a runtime-tested NPC until the isolated-server lifecycle matrix passes.

After building the generated DLL, create a deterministic install ZIP with forge project package. The archive contains the generated source, three managed DLLs, evidence receipt, lifecycle report, hashes, and install/remove instructions. Use --lifecycle-evidence whenever any lifecycle check has a completed status. A package with incomplete checks is deliberately marked releaseEligible=false but can be installed on a disposable server to run the remaining experiments.

Completed checks must reference strict schema-v1 lifecycle receipts rather than arbitrary files. Each receipt is bound to the exact project checksum, evidence bundle, game/build, check kind/status, UTC session, and one or more hashed captured artifacts. Run forge lifecycle verify before packaging. See docs/LIFECYCLE-EVIDENCE.md for the schema, workflow, and review boundary.

Build and verify

Run:

powershell -NoProfile -ExecutionPolicy Bypass -File .\build.ps1

Or invoke the projects directly:

dotnet run --project .\tests\Nocturne.Forge.Core.Tests\Nocturne.Forge.Core.Tests.csproj -c Release
dotnet run --project .\examples\Nocturne.AshboundWarden\tests\Nocturne.AshboundWarden.Tests.csproj -c Release
dotnet build .\src\Nocturne.Forge.Plugin\Nocturne.Forge.Plugin.csproj -c Release

Safety model

• Read-only inspection is the default.
• Runtime mutation requires two independent configuration gates.
• Generated-NPC donor probes require a third independent lifecycle gate and are limited to one donor with Forge-owned cleanup after 10-300 seconds.
• A server-owner headless probe additionally requires a short-lived strict request, exact project checksum, two explicit safety acknowledgements, and a persistent create-once claim written before spawn.
• Mutations accept semantic typed fields, never raw addresses.
• Before/after snapshots and append-only JSONL audits are mandatory.
• Undo refuses to overwrite a field that changed again.
• Traces are scoped, bounded, sampled, and auto-stopped.
• Unknown definition fields and zero game references are rejected.
• Factory compatibility checks pin game/build/assembly identity.
• Failed NPC construction must destroy the partial entity.
• External identity persistence does not assume custom ECS serialization.

Start with docs/VERIFIED-FINDINGS.md, docs/NPC-STUDIO-ROADMAP.md, docs/generated/EVIDENCE-FINDINGS-v1.1.13.0.md, docs/AUDIT.md, docs/IMPLEMENTATION-STATUS.md, docs/EVIDENCE.md, and docs/HEADLESS-DONOR-PROBE.md.

Codex skill

The versioned skill package is under skills/nocturne-forge. Install that directory as nocturne-forge in the local Codex skills folder, then invoke it as $nocturne-forge. The skill keeps research, NPC authoring, runtime experiments, documentation, and releases aligned with Forge's evidence and safety contracts.

License

MIT. See LICENSE.