NPC Spawner — V Rising

Server-side mod for V Rising 1.1.x that brings random encounters to your world: at random moments it spawns a configured group of NPCs around a random online player, and hands out configurable loot when a player kills them.

Everything is configured with plain JSON files — no rebuilding required.

• Never spawns inside player castles, under roofs, or near players who are in combat
• Colour-coded chat messages (spawn announcement, loot, "task completed")
• Admin-only chat commands for live testing
• Works on servers only — clients need nothing installed

⚠️ Server-side mod

Install this on the server only. Players do not need to download or install anything — they just join and play. The mod changes no client files and gives no advantage to players.

📖 Detailed guide (Russian): docs/GUIDE-RU.md — how to install, what is configured where, what every command does, and troubleshooting.

Features

Requirements

Both are installed automatically when using a mod manager.

Installation

1. Install BepInExPack V Rising and Vampire Command Framework.
2. Put NpcSpawner.dll into BepInEx/plugins/.
3. Start the server once. Configuration files are created automatically:

   BepInEx/config/NpcSpawner/
       npcs.json
       loot.json
       NpcSpawner.cfg
   

4. Edit the files and restart the server (or run .npcs reload in game).

Note: BepInEx never overwrites values that already exist in a .cfg file. To apply new defaults after an update, delete NpcSpawner.cfg and restart the server.

How it works

Every IntervalMinSeconds–IntervalMaxSeconds seconds:

1. The mod collects online players who are not in combat (if SkipPlayersInCombat = true).
2. It picks a random player and a random group from npcs.json.
3. For every NPC in that group it picks a random point within RandomAround metres of the player.
4. The point is rejected if it is inside a player castle or under a roof (checked against the game's castle floor tiles). Up to 15 attempts per NPC.
5. If a player has no free space (standing inside their castle), up to 3 other players are tried.
6. When a spawned NPC is killed by a player, that player receives the loot configured in loot.json.
7. When the last NPC of the group is killed, everyone online gets a "task completed" message.

Configuration

npcs.json — what to spawn

A dictionary of groups. Group names are arbitrary.

{
  "night": {
    "RandomAround": 8,
    "Prefabs": {
      "2111003460": 2,
      "-494298686": 2,
      "1980594081": 2
    }
  }
}

Prefab GUIDs can be found on the V Rising Mod Wiki or with the KindredExtract mod.

loot.json — rewards

Keyed by the NPC prefab GUID from Prefabs.

{
  "2111003460": [
    { "ItemId": 429052660, "Amount": 1, "Chance": 0.5 },
    { "ItemId": -77477508, "Amount": 2, "Chance": 1.0 }
  ]
}

Loot is added to the killer's inventory; if the inventory is full the item is dropped nearby.

NpcSpawner.cfg — general settings

[General]

[Spawn]

[Messages] — every message supports Unity rich text colour tags:

Default templates use <color=#RRGGBB>...</color>, for example:

GlobalSpawnMessage = <color=#ff5a5a>Random spawn! Player {0} got group "{1}" — {2} enemies.</color>

Placeholders: {0} player name, {1} group name, {2} enemy count (loot message: {0} amount, {1} item id).

Chat commands (admins only)

Commands work for server administrators only. Other players get a refusal message. Command prefix: .npcs (alias .npcspawner).

Example: .npcs spawn night

spawn / spawnfor follow the same rules as automatic spawning: if the player is in combat, or there is no free space (castle, roof), the command reports why it failed.

Documentation

• Detailed usage guide (Russian) — installation, every config option, every command, how it works, and troubleshooting.
• How to publish and update on GitHub and Thunderstore (Russian)

Building from source

Requires the .NET SDK 6.0 or newer.

dotnet build -c Release

The DLL ends up in bin/Release/NpcSpawner.dll.

• By default the project restores BepInEx and game assemblies from NuGet (nuget.org + nuget.bepinex.dev).
• If a libs/ folder containing BepInEx.Core.dll exists next to the project, those local assemblies are used instead (handy for offline builds).

To build a ready-to-upload Thunderstore package:

powershell -ExecutionPolicy Bypass -File tools/pack.ps1

The package is written to dist/.

Credits

• BepInEx — plugin loader
• Vampire Command Framework by deca — chat commands
• VRising.Unhollowed.Client — game assemblies for compiling

Not affiliated with Stunlock Studios. V Rising is a trademark of Stunlock Studios.

License

MIT — see LICENSE.

Changelog

1.7.1

• Fixed .npcs list (and other long replies) failing: the game chat is limited to 512 bytes, while VCF truncates replies by characters, so long lists of groups — especially with Cyrillic names — blew the limit and threw an error. Long replies are now split into several chat messages and truncated by bytes.
• Every command is now wrapped in a safe handler: instead of a raw error you get a readable message and the full details go to the server log.

1.7.0

• Fixed: NPCs could spawn on upper castle floors — castle blocking now also uses castle hearts ([Spawn] CastleHeartRadius, default 30 m, ignores height) in addition to castle tiles.
• Fixed: commands could fail to find the sender's character.
• Fixed: chat messages could silently fail when a message exceeded the chat limit — messages are now truncated and failures are logged as warnings.
• Added .npcs spawnme <group> — explicit "spawn next to yourself" command (same as .npcs spawn).
• Added .npcs debug — diagnostics: players, who is in combat, how many castles and groups are found.
• Group names and player names now match even with different case, extra spaces, Cyrillic encodings from chat, or a unique prefix.
• Combat buff list is validated against the game's prefab database at startup; unknown buff ids are skipped with a warning, so the "in combat" check can no longer block every spawn.
• docs/GUIDE-RU.md updated for the new settings and commands.

1.6.0

• Added [Spawn] SkipPlayersInCombat — NPCs no longer spawn around players who are in combat.
• Added [Spawn] CombatBuffGuids so the combat buff ids can be adjusted without rebuilding.
• Added a detailed usage guide: docs/GUIDE-RU.md (installation, every setting, every command, troubleshooting).

1.5.0

• NPCs no longer spawn inside player castles or under roofs.
• Added [Spawn] BlockNearCastles and [Spawn] CastleBlockRadius.

1.4.0

• Chat commands are now admin-only (VCF does not enforce adminOnly by itself — the middleware is installed and every command re-checks the admin flag).
• Fixed random spawns never happening and no loot/success messages: the mod tick now runs on ServerBootstrapSystem.OnUpdate and the timer uses real time.
• NPC tracking now works by scanning nearby entities instead of relying on an internal game system.
• Added [Messages] GlobalAnnounce / GlobalSpawnMessage — a message to everyone about a random spawn.

1.3.0

• All chat commands restricted to admins.
• Coloured chat messages; added the "task completed" broadcast.
• Removed SpawnPoints from the config — NPCs always spawn around a random player.

1.2.0

• Chat commands via Vampire Command Framework.
• Configuration file (NpcSpawner.cfg) is now created inside BepInEx/config/NpcSpawner/.

1.1.0

• Removed the Bloody.Core dependency — the mod talks to the game API directly.

1.0.0

• First working version: random NPC groups around a random player with configurable loot.