Latest version

0.1.11

Last Updated

First Uploaded

Downloads

Likes

Size

193KB

Dependants

0 other mods

CrimsonRaidGuard

Server side only for V Rising 1.1 (Invaders of Oakveil).

CrimsonRaidGuard tracks attackers and defenders after a castle breach and controls how other players can interfere. Server owners can protect offline castles and siege golems, let extra attacking parties join raids on shard holders, and decide whether players can waive protection. With CrimsonAlliance, allied clans can reinforce either side under configurable limits.

Installation

Install BepInExPack V Rising, VAMP, and VampireCommandFramework on the dedicated server.
Extract CrimsonRaidGuard.dll into the server's BepInEx/plugins directory.
Start the server once to generate BepInEx/config/CrimsonRaidGuard.cfg and BepInEx/config/CrimsonRaidGuard/shard_handicaps.json. Stop the server before editing the CFG and restart to apply changes. VAMP can reload the shard JSON while the server is running.

If you're migrating from OfflineRaidGuard, remove its DLL and configure [OfflineGuard] in CrimsonRaidGuard. Offline protection starts disabled.

Config

Start with the generated CFG. The examples below show the defaults and some common combinations. Change keys in their existing sections.

Which settings control a raid?

Decision	Settings and behavior
Should the plugin run?	`[Config] ToggleMod` controls startup. With it off, the plugin skips registering raid commands and installing its gameplay patches.
Should raid rules run?	`[Config] RaidGuard` controls breach tracking and the damage hook. Set it to `true` for third-party damage rules, golem and offline damage protection, shard-based joining, and allied friendly-fire checks.
Can a castle be breached?	The server's normal siege rules still apply. With Offline Guard enabled, qualifying offline castles also get protection against siege golems and supported explosives.
Who can take part after the breach?	The defending owner and the breaching raider determine the initial sides. Eligible clan members and, with CrimsonAlliance, allied players can join on the plot. Shard handicaps can make room for independent attacking parties.
What happens to outsiders?	Raid Guard can block player damage in both directions, apply a burn that blocks healing, and enforce optional low-health kills. The protected player's raid membership and location determine whether a hit counts as interference.

[Config]
ToggleMod = true
RaidGuard = true
LockParticipants = true

A recognized breach starts the raid. It stays tracked while the castle heart is under siege unless the protection is canceled. With LockParticipants = true, leaving the plot or disconnecting keeps your active roster slot. With it off, either action removes you from the active roster, and an empty attacking party frees a party slot. Eligible players can return, subject to available slots.

Third-party interference

[ThirdParty]
BlockThirdPartyDamage = true
BurnThirdParties = false
KillBurned = false
AutoKillIntruders = false
AutoKillInterference = false
ProtectionOffPlot = false

BlockThirdPartyDamage blocks hits between a covered raid participant and an outsider in either direction. Turning it off allows those hits while warnings and penalties can still apply.
ProtectionOffPlot extends coverage to active participants away from the raided plot. With it off, a participant on the raided plot can still be protected from a hit originating outside it. With it on and participant locking enabled, a player who leaves the plot can stay protected until the raid ends.
BurnThirdParties is generated in the CFG but currently has no effect. The interference and golem damage checks can apply burn and anti-heal to attackers, and the raid monitor can apply them to intruders on the plot when all attacking party slots are filled.
KillBurned lets damage through the third-party check when the target already has the raid burn. This allows participants to finish off burned intruders even with damage blocking enabled.
AutoKillIntruders enables the automatic kill check for unauthorized players at 10 HP or below on the raided plot when all attacking party slots are filled. AutoKillInterference enables a separate 10 HP check when an outsider hits a protected participant. The interference check currently reads health from the user entity, so it can miss a low-health character.

Siege golems

[GolemGuard]
GolemGuard = true
GolemEntryProtection = 30
GolemHitAttackProtection = 15
GolemHitBreachedProtection = 30

Golem Guard uses two timers, both in seconds. A castle hit by a golem whose pilot is outside an active raid roster starts or refreshes the attack timer. The targeted castle's defenders can still hit the golem. A castle hit by a pilot on an active raid roster starts or refreshes the breached timer, which uses the raid's third-party check. That check can honor ProtectionOffPlot and KillBurned. Golem Guard blocks qualifying hits independently of BlockThirdPartyDamage.

GolemEntryProtection is generated in the CFG but currently has no effect. The timed protection comes from hitting castle structures.

Offline protection and Safe Logout

[OfflineGuard]
OfflineGuard = false
FactorClanMembers = false
TimeToVerifyOffline = 300
ExpireOfflineGuard = 2880

OfflineGuard protects qualifying castles against siege golem damage and supported explosives. The castle heart must be processing. An owner opt-out bypasses the check. Explosive damage can go through once a raid is already being tracked.
FactorClanMembers checks the owner's clan as well. A connected clan member who has yet to qualify through Safe Logout keeps the castle raidable. This setting checks members of the owner's clan. The owner timer below is the reliable basis for tuning the logout delay because the current clan-member check compares a stored timestamp directly to the configured delay.
TimeToVerifyOffline is the minimum number of seconds since the owner's recorded last connection time. The default is five minutes. Use -1 to skip the owner's delay check when the ordinary timer applies.
ExpireOfflineGuard is the maximum time in minutes since the owner's recorded last connection time. The default is 2,880 minutes (48 hours). Use -1 for protection without a time limit. With finite limits, set expiry later than the start of protection.

Safe Logout is configured under [OptOut]. It changes how Offline Guard decides whether a player counts as offline.

[OptOut]
SafeLogout = false
TimeUntilSafe = 300
AFKCancel = 120

With OfflineGuard = true and SafeLogout = true, enter a coffin and stay connected for TimeUntilSafe seconds. Log out after the confirmation message and within AFKCancel seconds. Leaving the coffin clears that player's status. Logging out before the confirmation can leave the castle vulnerable. Set AFKCancel = 0 to let a player remain in the coffin after qualifying without the AFK timeout.

For owners whose last connection is after the current server boot, the coffin status takes the place of the usual TimeToVerifyOffline check. Owners last connected before that boot use the ordinary offline delay. Expiry still applies in both cases. The coffin status is held in memory. If FactorClanMembers is enabled, an unsafe clan member can still prevent protection after the owner completes the coffin timer. Use .raid safe while standing on a castle plot to check its current eligibility.

Shard handicaps and extra attacking parties

[ShardHandicap]
ShardHandicaps = false
OnPlotJoining = true
OnDamageJoining = true
DefenderPlotRequired = true

With ShardHandicaps = false, the raid has one attacking party slot. With it on, the defending owner's shard count sets the total number of attacking parties, including the first. For a clan castle, the count includes the defending clan's equipped shards, shards in player inventories, and occupied shard pedestals. Counts above five use the five-shard entry.

BepInEx/config/CrimsonRaidGuard/shard_handicaps.json starts with this mapping.

[
  { "ShardsOwned": 0, "AllowedRaidParties": 1 },
  { "ShardsOwned": 1, "AllowedRaidParties": 2 },
  { "ShardsOwned": 2, "AllowedRaidParties": 3 },
  { "ShardsOwned": 3, "AllowedRaidParties": 4 },
  { "ShardsOwned": 4, "AllowedRaidParties": 5 },
  { "ShardsOwned": 5, "AllowedRaidParties": 128 }
]

Keep one entry for every count from 0 to 5 and use a positive integer for each party limit. The five-shard default is a cap of 128 parties. VAMP checks for JSON changes periodically. A raid keeps the cap it received when it started, and new raids use the mapping once VAMP reloads it. If parsing fails, the mod falls back to one party at every shard count.

OnPlotJoining	OnDamageJoining	How an outsider can claim an open slot
`true`	`true`	Step onto the raided plot, hit a qualifying castle structure as a regular player, or hit an active defender who passes the location check.
`true`	`false`	Step onto the raided plot.
`false`	`true`	Hit a qualifying castle structure as a regular player or hit an active defender who passes the location check.
`false`	`false`	These two join routes are disabled. A further recognized breach can still register an attacking party if a slot is open.

DefenderPlotRequired applies to damage against an active defender. With it on, that defender must be on friendly territory. Turn it off to let hitting an active defender away from friendly territory qualify. Castle-structure damage uses its own check. If plot joining is off and a slot is open, the plot monitor does not apply the ordinary trespass penalty. The full-party check triggers that penalty.

These switches still matter with shard handicaps off if roster rotation frees the single attacking party slot.

Player-controlled protection

[OptOut]
ToggleOptOut = false
OptOutPersistance = false
CancelGuard = false

ToggleOptOut enables .raid optout, .raid optin, and .raid optstatus. Opting out removes the current raid from Raid Guard tracking and bypasses future breach tracking and offline protection for that owner until the opt-out expires or is cleared. The record uses the owner's Steam ID, so it can cover multiple castles owned by the same player.
OptOutPersistance is spelled this way in the CFG. Enable it to save updates across restarts. A previously saved file is still read at startup even with saving disabled.
CancelGuard enables .raid cancel separately. It removes the active Raid Guard record for that castle without creating a timed opt-out. The in-game siege can continue.

Opt-out save file

The mod manages BepInEx/config/_WipeData/craidguard_optedout.json. With saving enabled, it creates the file as an empty array if needed and updates it when opt-outs change. A record looks like this.

[
  { "Steamid": 76561198000000000, "Until": "2027-01-01T18:00:00-05:00" }
]

CrimsonAlliance integration

Install CrimsonAlliance to use allied reinforcements and the two allied friendly-fire settings. This section is generated when CrimsonRaidGuard finds the CrimsonAlliance API.

[Alliance]
LimitAssists = false
FriendlyFireRaid = true
FriendlyFireWorld = true
AllianceAssists = 4
LockClanPriority = false

LimitAssists enables AllianceAssists as a player cap for the defending roster and for each attacking party. Primary clan members count toward it too. For example, a cap of four with three primary clan members already on the roster leaves one place for an ally. Use a positive number.
LockClanPriority gives incoming primary clan members priority when the cap is full, allowing them to displace allies. It also applies when LockParticipants is off. With both locks enabled, leaving the plot keeps a slot occupied, but primary clan priority can still displace an allied player.
FriendlyFireRaid set to false blocks damage between allied clans when either player is on an active raid roster. FriendlyFireWorld set to false blocks it when neither is on a raid roster. With both set to true, the alliance check allows damage. The game and earlier Raid Guard damage checks still apply.

CrimsonLog is also optional. CrimsonRaidGuard sends raid activity to its raids log when available and writes diagnostic messages to the BepInEx log.

Example server setups

Apply the settings for a setup to the existing sections of the CFG. The examples assume ToggleMod = true and RaidGuard = true.

Server policy	Settings to use	What players experience
One attacking party and no rotations	Keep the defaults for `LockParticipants`, `ShardHandicaps`, and `BlockThirdPartyDamage`.	The first party holds its slot for the raid. Outsider damage involving a participant on the plot is blocked.
Protect participants who leave the plot	Set `ProtectionOffPlot = true` and keep `LockParticipants = true` and `BlockThirdPartyDamage = true`.	Participants keep their roster slots and third-party damage protection while fighting or retreating outside the plot.
Let raiders fight off burned intruders	Keep `BlockThirdPartyDamage = true` and set `KillBurned = true`.	Players can hit an intruder who already has the raid burn. An unburned outsider remains covered by the ordinary damage rules.
Offline protection after a grace period	Set `OfflineGuard = true`, keep `SafeLogout = false`, and use `TimeToVerifyOffline = 300` and `ExpireOfflineGuard = 2880`. Enable `FactorClanMembers` if a connected clanmate should keep the castle raidable.	An eligible owner gets protection after five minutes, and the castle becomes raidable again after 48 hours.
Coffin logout required	Set `OfflineGuard = true`, `SafeLogout = true`, `TimeUntilSafe = 300`, and `AFKCancel = 120`.	A player waits five minutes in a coffin, then has two minutes to log out before losing their safe status.
Extra parties join shard raids by engaging	Set `ShardHandicaps = true`, `OnPlotJoining = false`, `OnDamageJoining = true`, and `DefenderPlotRequired = true`.	With the default JSON, a clan with two shards can face three attacking parties total. An outsider can claim an open slot by damaging the castle or an active defender on friendly territory.
Allied reinforcements with rotation	Install CrimsonAlliance. Set `LimitAssists = true`, `AllianceAssists = 4`, `LockClanPriority = true`, and `LockParticipants = false`.	The defending roster and each attacking party have four player slots. Departures free slots, and primary clan members can take priority over allied reinforcements.
Temporary opt-outs that survive restarts	Set `ToggleOptOut = true` and `OptOutPersistance = true`.	An eligible player can run `.raid optout 2h`. The owner's opt-out lasts until the original expiry even if the server restarts during those two hours.

Commands

Run these commands in chat. Quote a character name containing spaces, for example .raid check "Night Watch".

Command	Who can use it	What it does
`.raid members`	Any player	Lists the active members of your raid team.
`.raid check [playerName]`	Server admins	Lists owners of castles with tracked raids, or shows the attackers and defenders for a named participant.
`.raid toggleguard` or `.raid toggle`	Server admins	Flips `[Config] RaidGuard`. Turning it off also turns off the damage hook. Start the server with `RaidGuard = true` for reliable breach tracking, since the breach hook caches its initial value.
`.raid safe`	Any player on a castle plot, with `OfflineGuard = true`	Checks the castle's current offline protection. It can also report a pending coffin timer.
`.raid optout [duration]`	Castle owner, or clan leader if the ownership check allows it, on a friendly plot with `ToggleOptOut = true`	Opts out for the specified duration. Defaults to `1h`.
`.raid optin`	Same access as `.raid optout`	Clears the castle owner's opt-out.
`.raid optstatus`	Any player on a friendly plot, with `ToggleOptOut = true`	Shows the castle owner's opt-out status and expiry.
`.raid cancel`	On a friendly plot with `CancelGuard = true` and an active tracked raid	Ends tracking for that castle. The current ownership check can skip cancellation when it finds a castle owned by the caller. The clan-leader fallback runs only when that lookup finds no castle for the caller.

Opt-out durations take one number followed immediately by one unit, such as 30m, 2h, 1day, or 1week. Accepted units are m/min/mins/minute/minutes, h/hr/hrs/hour/hours, d/day/days, and w/week/weeks. The castle lookup also limits clan-leader opt-in and opt-out access. When it finds a castle owned by the caller, the caller must be standing on that castle.