NpcSpawner

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

| Feature | Description | |---|---| | Random encounters | Picks a random online player and a random NPC group, spawns it around them | | Random timing | Configurable min/max interval between spawns | | Smart spawn points | Re-rolls the position if it lands in a castle or under a roof | | Combat-safe | Skips players who are currently in combat | | Loot on kill | Per-NPC loot tables with item id, amount and drop chance | | Coloured messages | Spawn announcement, personal loot message, global "task completed" message | | Admin commands | .npcs help — list, spawn, random, reload, inspect loot |

---

Requirements

| Component | Link | |---|---| | BepInExPack V Rising (BepInEx 6 IL2CPP) | https://thunderstore.io/c/v-rising/p/BepInEx/BepInExPack_V_Rising/ | | Vampire Command Framework | https://thunderstore.io/c/v-rising/p/deca/VampireCommandFramework/ |

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

1. 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.

1. If a player has no free space (standing inside their castle), up to 3 other players are tried.
2. When a spawned NPC is killed by a player, that player receives the loot configured in loot.json.
3. 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
    }
  }
}

| Field | Meaning | |---|---| | RandomAround | Radius in metres around the chosen player where NPCs appear | | Prefabs | { "npc prefab guid": how many } — up to you how many of each |

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 }
  ]
}

| Field | Meaning | |---|---| | ItemId | Item prefab GUID | | Amount | How many to give | | Chance | Drop chance from 0 to 1 (1 = always) |

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

NpcSpawner.cfg — general settings

[General]

| Key | Default | Meaning | |---|---|---| | Enabled | true | Enable automatic random spawns | | IntervalMinSeconds | 300 | Minimum seconds between spawns | | IntervalMaxSeconds | 600 | Maximum seconds between spawns | | IntervalScalesWithPlayers | false | Divide the interval by the number of online players | | LifetimeSeconds | 0 | How long an NPC lives (0 = until killed) |

[Spawn]

| Key | Default | Meaning | |---|---|---| | BlockNearCastles | true | Never spawn inside castles / under roofs | | CastleBlockRadius | 4 | Radius in metres around castle tiles where spawning is blocked | | CastleHeartRadius | 30 | Radius in metres around castle hearts where spawning is blocked (covers every floor) | | SkipPlayersInCombat | true | Never spawn around a player who is in combat | | CombatBuffGuids | 581443919,697095869 | Comma-separated buff ids that mean "in combat" |

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

| Key | Default | |---|---| | Announce / AnnounceMessage | personal message to the player when a group appears | | GlobalAnnounce / GlobalSpawnMessage | message to everyone about a random spawn | | SuccessAnnounce / SuccessMessage | message to everyone when a group is fully wiped | | NotifyKiller / NotifyMessage | personal message about received loot |

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

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