Faust, Lord of Investigation

A server-side mod that gives your V Rising server its missing information layer — the authoritative, global view of players, castles, plots, and activity that no game client can see on its own. Out of the box it's a powerful moderation and oversight console for admins; from there, you decide how much of that knowledge to share — as PvP intel (scout a rival's castle, resources, and activity windows — for a price), or as community features on a PvE server (open plots, who's online, server stats, clan rosters). Every capability is controlled per feature — Off, admin-only, or players — with an optional item cost (the Faustian toll), cooldown, or unlock. Pairs with its companion client Raphael, Lord of Wisdom, or works from .faust chat.

🧠 Faust is the server brain; Raphael is the screen

Faust is designed to be run alongside Raphael, Lord of Wisdom. Raphael is the client that turns Faust's data into a usable UI — the Player Positions map, the All-Plots castle table, the Server Stats dashboards, the Clans tab, and the player-activity charts. You can use Faust on its own from chat, but the experience these two are built for is the pair.

Behind that, every feature is independently controlled — who can use it (Off / Admin-only / Players), the price, a cooldown or usage window, a PvP/PvE restriction, a progression unlock, or a proximity requirement. Sensitive intel defaults to admin-only, so a fresh install is locked down; you open up only what you want, on the terms you set. Admins also control what Faust collects in the background, so it never costs server performance.

⚠ Pre-1.0 — for testing

This is a pre-1.0 release, published for testing. The full investigation feature set and the per-feature admin-control surface are implemented and working in-game, but Faust is still being validated and refined — by running it, you're helping test it. Back up your server save before adding any mod, and expect commands, config keys, wire shapes, and behavior to keep evolving before 1.0.

Run it with Raphael, Lord of Wisdom. Faust ships its data to Raphael; that pairing is what's being tested, and it's how you get the UI Faust is built for.

💬 We want your feedback

Faust is all about information — so tell us whether the information is right, useful, and presented well. Is a number wrong or confusing? A chart missing a cut you'd want? An intel view you wish existed? A feature you'd like to grant players differently? That feedback directly shapes 1.0.

• The Shadow Realm Discord — the primary place for bug reports, feedback on the data, and requests for new features / enhancements. Come tell us what you need.
• GitHub issues: https://github.com/KDavidP1987/Faust-Lord-of-Investigation/issues — written-up bugs and ideas welcome too.

Repo: https://github.com/KDavidP1987/Faust-Lord-of-Investigation Status: pre-1.0 · server-side only · investigation feature set complete, in live testing.

What it does

Faust holds the authoritative, global view of the server that a game client can't see (clients only receive what's near the local player). It gathers that view, gates it per feature, optionally charges an item cost for it, and ships it to the BloodCraftHub UI (or answers in chat). Best paired with BloodCraftHub for point-and-click panels, overlays, and graphs — but every query also works from chat.

Investigation queries:

• Castle & plot info — a plot's owner, region, map location (X,Z), size, decay state & time, and the owner's online / last-online.
• Plot availability — open building plots across the whole map, largest first.
• Full castle map — every territory (claimed + open) in one list: owner, region, size, state, decay, online (admin-default).
• Decay watch — claimed castles ranked by who's closest to decaying (with the owner's last-online): spot abandoned plots and cleanup targets (admin-default).
• Player info — online state, last-online, and (tracked by Faust over time) total playtime, session count, logins per week, and peak play hour.
• Online player positions (admin-default, PvP-sensitive) — now with each player's region.
• Player-position heat map (admin-default, opt-in collection) — snapshots positions on a timer (every 30s–5min) and bins them into a grid, so you can see where players spend time — per player or aggregated for the whole server. Built for Raphael to render as a heat map.
• Enemy castle resource totals — sum everything stashed in a castle (admin-default; a natural one to price or restrict to PvP).
• Server stats — a playtime leaderboard and a server-population history, ready for graphs.
• Activity analytics — chart-ready breakdowns of when people play (by hour of day and day of week), daily active players + play-minutes, new arrivals per day, how long sessions last, and a per-player daily trend — server-wide or per player.
• Activity drill-down — the detail behind the charts: a roster of who joined recently (name, when, clan), each player's individual session timeline, an active-days grid across all players, and an average-per-player cut on the hourly chart (admin-default).
• Clan composition — how many players are in clans vs going solo (with the currently-online split), plus a per-clan roster: size, who's online, how many castles they hold, and the leader (admin-default).
• Population health — active-player counts (DAU/WAU/MAU), retention, who's drifting away, the population peak/average, and where everyone is (players + castles per region).

Every feature is independently controlled by the admin. You decide, per feature, what (if anything) players can see and on what terms. Per feature you can set:

• Who — off, admin-only, or all players.
• A price — an item cost per use (the Faustian toll).
• A time-lock — a flat cooldown, or a usage window per period (e.g. "a 10-minute window, once per day").
• PvP/PvE — usable only on the matching server mode.
• A progression unlock — opens only after a player defeats a configured V Blood or Dracula.
• A place — usable only within range of a configured object (an altar/station/landmark).

Admins can also block or schedule any feature live (a countdown or a daily time window) with no restart.

Screenshots

Every view below is rendered by the companion client Raphael, Lord of Wisdom from Faust's data.

Castle Info — owner, region, map location, size, decay, floors, owning clan & total item count

Open Plots — available building plots, largest first

All Plots — the full server castle map (every territory, claimed + open)

Decay Watch — claimed castles ranked by soonest-to-decay

Castle Resources — total resources stashed in a castle (+ prisoners)

Player Info — online state, last-online, playtime, sessions, frequency, peak hour

Clans — clanned vs independent, with per-clan rosters

Player Positions + Activity Heat Map — live positions and the position-density heat map

Nearby Objects — in-world object labels

Server Stats — new-player roster

Server Stats — new vs returning players

Server Stats — activity by day of week

Server Stats — session timelines

Server Stats — active-days grid

Admin — Faust usage & access oversight

Installation

Faust is a server-side mod — install it on your V Rising dedicated server, not on player clients.

Via Thunderstore Mod Manager / r2modman (recommended)

1. Open the mod manager and select V Rising → your dedicated-server profile.
2. Search for Faust under the Mods tab → Install.
3. Ensure its dependencies are installed in the same profile (they install automatically): BepInExPack_V_Rising and VampireCommandFramework.
4. Launch the server through the mod manager's profile.

Manual install

1. Install BepInExPack V Rising (1.733.2 or compatible) into your dedicated server.
2. Install VampireCommandFramework into BepInEx/plugins/.
3. Drop Faust.dll into BepInEx/plugins/.
4. Start the server once to generate BepInEx/config/kdpen.Faust.cfg, then edit and restart.

⚠ Stop the server before replacing Faust.dll — a running server file-locks the DLL.

Dependencies & compatibility

Companion client — Raphael, Lord of Wisdom: the client-side mod that renders Faust's data into in-game UI — the Player Positions map, the All-Plots castle table, the Server Stats dashboards (population / recency / peak / regions), the Clans tab, and the per-player activity charts. Faust is built to be used with Raphael — it's the screen for Faust's server brain. Technically Raphael isn't a hard dependency (every Faust feature also works from .faust chat), but the intended experience is the pair. Grab Raphael from The Shadow Realm.

Faust is also a sibling to the author's other server-side mods Uriel, Lord of Hosts and Beelzebub, Lord of Gluttony; each is independent.

Commands

All commands are chat commands prefixed with .faust. Type .faust for an overview or .faust help [players|castles|server|admin] for a topic menu. Most queries are intended to be driven by the BloodCraftHub UI, but each works from chat too.

Playtime/frequency stats accrue from the moment Faust is installed (the game only remembers your last login, so Faust logs sessions over time). Each query obeys its per-feature access, item cost, and cooldown (config below); an empty or not-found lookup is never charged.

Configuration

BepInEx/config/kdpen.Faust.cfg — a global block plus one block per feature. Config changes take effect on server restart.

Features (<feature>): playerpositions, castleinfo, playerinfo, plotavailability, allcastles, decaywatch, objectscan, castleresources, stats, clans, heatmap. Every feature defaults to AdminOnly — Faust is an admin tool first; open up whichever ones you want to share, per server.

Collection controls — what Faust gathers in the background

Separate from who can read a feature, you control what Faust passively collects, so it never costs server performance. Almost every query reads live state on demand (zero idle cost); only the session/population history accumulates over time, and you can bound or switch it off:

Faust's data is stored in BepInEx/config/Faust/ — on the server, not in the world save — so it survives a world wipe. That's deliberate: the same players return, so their playtime/stats stay relevant. When you do want to reset it (or it grows too large), use the data commands below.

Live admin controls (no restart)

Admins can override features at runtime — these persist across restarts:

A feature can also require a progression unlock before players may use it — set Unlock = FinalBoss (defeat Dracula) or Unlock = BossKill:<vbloodGuid> per feature in the config.

Feedback & community

Built and tested alongside the The Shadow Realm V Rising community, hand-in-hand with its companion client Raphael, Lord of Wisdom. This is a pre-1.0 testing release, and your feedback — on whether the information is accurate, useful, and well-presented, and on what intel you wish Faust surfaced — directly shapes what 1.0 becomes. Bug reports, ideas, and enhancement requests all welcome.

• The Shadow Realm Discord (primary — bugs, feedback & feature requests): https://discord.gg/usC9QgBrXK
• Raphael (companion client): available from The Shadow Realm (link above)
• GitHub issues / source: https://github.com/KDavidP1987/Faust-Lord-of-Investigation/issues

Acknowledgements

• VampireCommandFramework — by deca — the chat-command framework (hard dependency).
• BepInEx — the loader that makes V Rising modding possible.
• KindredCommands — by odjit — open-source territory/heart/owner and info-command patterns Faust builds on.

License

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) — copyright © 2026 Kristopher Penland. Faust adapts AGPL-licensed server-side techniques from odjit's KindredCommands and is released under the same copyleft license; full source is on GitHub.

Changelog

Condensed, player-facing changelog. Full technical history: GitHub.

Every release below is pre-1.0 and built to run with the companion client Raphael, Lord of Wisdom. Faust is in active testing — feedback and feature requests at the Shadow Realm Discord shape 1.0.

0.16.5 (2026-06-13)

• Fixed: held prisoners now show their blood type and quality. In the castle-resources view, prisoners were listed with no blood type and a blank quality. Faust now reads a captured unit's blood from the right place, so each prisoner shows its actual blood type and quality %.

0.16.4 (2026-06-13)

• New: time-windowed heat maps. The player-position heat map can now be filtered by time — today, this week, this month, or any number of recent days — instead of only the all-time map. Works together with the existing per-player filter, so you can see one player's activity for just this week. The all-time map is unchanged. A new RetentionDays setting (default 30) controls how much per-day history is kept.

0.16.3 (2026-06-13)

• Fixed: more bosses show their real map location, and none show a bogus off-map point. Many bosses on the "down" half of the board are actually alive but parked off-map while no one's nearby. Faust now reads their real lair location from the game's own V Blood objective map marker and reports them with coordinates, and it no longer mistakes the off-map parking spot for a real location (so a boss without a resolvable position shows as "down" instead of sitting at the edge of the map).
• Fixed: a filtered world scan no longer skips matching assets. When you searched the map with a narrow filter (say, NPCs with blood quality 99+), the result cap was being applied while gathering — before your filter ran — so on busy maps the scan filled up on common entities and never reached the rare matches you were looking for. The scan now gathers the whole map first and applies your result limit afterward, so a narrow search finds every match.

0.16.2 (2026-06-13)

• Roaming bosses now show their real location on the map. Bosses that wander were reporting their status but not a usable position — their combat data is parked off-map when no one's nearby. Faust now pulls the location from the game's own map tracking (the same data the blood-altar map uses) and combines it with the boss's status, so roaming bosses appear where they actually are. Static bosses are unchanged.

0.16.1 (2026-06-13)

• Fixed: roaming bosses no longer go missing from the boss board. V Bloods that wander the map (rather than sit in a fixed lair) were showing as "down" with no location — even the boss standing next to you — because their position was being read from a value that goes stale when no player is nearby. The board now reads each boss's live position correctly, so roaming bosses appear on the map where they actually are.
• Improved the admin .faust admin bossdiag tool with much more detail for diagnosing boss-location issues.
• World scan sees more of the map. The result cap rose from 2000 to 10000, and you can now set it to 0 for unlimited so a busy map's scan isn't cut short and miss matching objects. Change it any time with .faust admin setglobal worldscanmaxresults=0 (or edit [Faust.WorldScan] MaxResults).

0.16.0 (2026-06-12)

Configure Faust in-game, plus two new things to investigate:

• Change any setting from chat — no restart. Admins can now set every per-feature gate (access, item cost, cooldown, daily/hourly use limits, PvP availability, unlock, proximity) and every global option live with .faust admin set … / setglobal … (and get … to read, resetcfg … to restore defaults). Changes apply instantly and are saved to the config file.
• Boss status board. .faust api bosses / boss <name> — see which V Bloods are up right now, where they are (coords + region), their health, level, and whether they've been defeated. (Admin-default; open it to players if you like.) Now covers the whole map, including outer-region bosses (the on-map range is tunable via [Faust.Bosses] MapLimit).
• Kill leaderboards. .faust api kills (top killers) and .faust api bosskills (how many times each boss has fallen) over today, this week, or all-time — for fun server leaderboards and achievements. Opt-out via [Faust.Collection] KillTracking.
• In-game prefab lookup. .faust admin prefab <id or name> finds prefab IDs and names right in chat — by ID, or by a partial name — so you don't have to leave the game to set up whitelists, item costs, etc.
• World-asset map. .faust api worldscan — a filterable map of NPC units (with blood type + quality) and resource nodes (ores, trees, plants), so a client can build a "find items on the map" tool and filter by type, blood type, or blood quality. Admins curate what shows with a whitelist (.faust admin worldscan list|add|remove|clear|seed). The whole-map scan is cached + rate-limited (configurable) to protect performance.
• Fixes: .faust admin data status no longer errors on busy servers; retired the unused objectscan feature.
• Verified in-game: the per-feature admin controls/limiters — access level, item cost, cooldown, usage limits, proximity, PvP availability, and unlock gates — are working (further testing recommended before production).

0.15.0 (2026-06-11)

Tester-feedback batch — the detail tables beneath the activity charts (who, and when):

• New-players roster. .faust api newplayers roster lists who joined recently, when, and their clan — the names behind the new-vs-returning chart.
• Average-per-player hours. The hour-of-day chart now also reports how many distinct players were on in each hour, so a client can show average minutes per player as well as the total.
• Session timeline. .faust api sessions timeline <all|player> returns each player's individual online sessions (start/end) for a per-player activity timeline.
• Active-days grid. .faust api stats activegrid shows, for every player, which days they played in the window — the all-players version of the per-player daily trend.
• Roster extras. The new-players roster now also shows each player's total playtime and how many castles they own.
• Region "fill %". The by-region view now reports each region's total buildable plots, so a client can show how full each region is (claimed ÷ buildable), not just a raw castle count.
• Regions over time. New .faust api stats regiondaily tracks castles/plots/players per region per day, so building popularity can be charted as a trend. (Faust starts collecting this from install — it has no back-history of the castle map — and samples once a day.)
• NEW: player-position heat map. .faust api heatmap [all|player] returns a density grid of where players spend time — per player or server-wide — ready for Raphael to draw as a heat map. Turn it on with [Faust.Heatmap] Enabled=true (off by default); it snapshots positions every 30s–5min (your choice), bins them into a grid, and you can reset it any time with .faust admin data wipe heatmap.
• Castle/plot map coordinates. Castle and plot listings now include each plot's map location (X,Z) — so the castle/decay/all-plots tables can show where a plot is, not just its owner.
• Sharper heat maps. The heat map now reports the full map bounds, so it draws at true map scale even when only a little data has been collected.
• Fixed: clan members with spaces. Looking up a clan whose name has a space (e.g. "Blood Lords") no longer fails with "server didn't respond" — multi-word clan names now resolve.
• The §9/§10/§11 stats additions are under the existing stats gate (admin-default); the heat map has its own heatmap gate. All additive — older clients simply don't query them.

0.14.0 (2026-06-11)

Tester-feedback batch — more castle detail, prisoners, clan rosters, and admin oversight:

• More Castle Info. castleinfo now also shows the castle's floors (storeys), the owning clan, and a grand-total item count (the single number — not a per-item raid list).
• Prisoners in Castle Resources. resources now reports how many prisoners a castle holds, with each prisoner's name and blood type/quality.
• Clan rosters. New .faust api clanmembers <clan> lists a clan's members (who's online, who leads).
• New-vs-returning activity. The daily activity series now splits each day into new vs returning players for a clearer growth picture.
• Faust oversight for admins. New .faust api access (who can use each feature) and .faust api usage (how often each feature is used and what it costs players) — pure server-side accounting, surfaced in .faust admin data status and resettable via .faust admin data wipe usage.

0.13.0 (2026-06-10)

• All features now default to admin-only. Faust is an admin tool first — admins choose what (if anything) to grant players. castleinfo, plots, objectscan and stats now start admin-only like everything else. (Existing configs are untouched; change any feature in the .cfg.)
• New: anti-spam rate limit. [Faust] RateLimitSeconds (default off) — minimum seconds between a player's queries, so nobody can hammer a query and stress the server. Admins exempt by default.
• New: lock data resets to senior admins. [Faust.Data] ResetSteamIds — only the listed admins can run .faust admin data clear/wipe. Empty = any admin (as before). For tiered admin teams.
• New: .faust api stats players — a full player-activity roster (active-today/this-week, last-seen, sessions, playtime, days-idle) behind the population dashboards.

0.12.0 (2026-06-10)

• New: more activity charts. Day-of-week playtime (stats weekdays, server-wide or per player) and a per-player daily trend (stats pdaily <player>) join the existing hour/daily/session charts.
• New: clan composition (.faust api clans). See at a glance how many players are in clans vs going solo (with the currently-online split), plus a per-clan roster — size, who's online, how many castles the clan holds, and the leader. Defaults to admin-only.
• New: server-health metrics. stats population (active players DAU/WAU/MAU + retention), stats recency (who's active vs drifting away), stats peak (population peak/average), and stats regions (players + castles per map region). Plus a per-player days-idle in pinfo.
• Experimental: .faust admin showpositions — put online players on the native in-game map, using the game's own map-icon attach system. Off by default and still being validated — when you enable it on a test server, double-check that the markers are visible only to admins before relying on it.

0.11.0 (2026-06-10)

• New: admin data controls. Faust's history (playtime/sessions, population, unlock progress) lives on the server and survives a world wipe — on purpose, since the same players come back and their stats stay relevant. You now control it directly:
  • .faust admin data status — see how much Faust has stored (counts, age, disk size).
  • .faust admin data clear <days> — drop activity older than N days on demand.
  • .faust admin data wipe <activity|unlocks|usage|all> confirm — reset a store. On a fresh world, unlocks resets boss-kill-gated features; activity resets playtime/charts. The confirm word is required so it can't fire by accident.
• New config DataNamespace — leave empty (default) for one shared dataset, or set a name per world to keep each world's data separate.
• Clearer guidance on SessionRetentionDays (auto-trim old data on big/long-running servers).

0.10.0 (2026-06-10)

• New: activity charts for admins — four new .faust api stats views that turn Faust's session history into graphs: hours (when is the server busy, by hour of day), daily (daily active players + play-minutes), newplayers (new arrivals per day), and sessions (how long people play per sit-down). Each works server-wide or for one player, and renders as a chart in compatible client UIs. Gated by the same stats permission you already control.
• Fixed: player-map regions for everyone, not just players on a plot. The online-player map now shows each player's map region (Farbane Woods, Dunley Farmlands, …) based on where they actually are, instead of only showing a region for players standing on a castle plot. Players out exploring no longer show a blank region.
• Fixed: consistent "no region" for out-of-bounds plots. Castle/plot lists used to show a raw None/Unknown for territories outside the normal map (e.g. the admin island); they now show the same "—" placeholder the rest of the UI uses.
• Improved: full server-population history. The population/concurrency graph is no longer capped to the most recent ~200 data points — it now serves the whole stored history (paged).

0.9.0 (2026-06-10)

• New: .faust api decay — claimed castles ranked by soonest-to-decay, with each owner's last-online. Spot abandoned plots and cleanup targets at a glance. Defaults to admin-only.
• New: collection controls ([Faust.Collection]) — you now control what Faust gathers in the background, not just who can read it. Switch off session/population history, cap how much is kept, or prune old data — so Faust never costs server performance. Almost every query already reads live data on demand (no background cost); these knobs bound the one part that accumulates over time.
• Both READMEs now spell out the philosophy: Faust is an administrative tool and global server view; admins decide, per feature, what (if anything) players can see — a strategic tool to grant in PvP, a community-building tool to share in PvE.

0.8.0 (2026-06-10)

• New: .faust api castles — the full server castle map: every territory, claimed and open, with owner, region, size, state, decay and online status, in one paged list. Defaults to admin-only. Powers BloodCraftHub's "All Plots" tab.
• Player positions now include region — the online-player map data now says which region each player is in (handy when they're far across the map).

0.7.0 (2026-06-09)

• New: tie a feature to a place. Admins can require players to be near a specific object to use a feature — set RequireNearPrefab (the object's id) + RequireNearDistance (metres) per feature. Put an altar/station in a castle (or pick a world landmark) and the ability only works when standing near it, instead of anywhere in the world.

0.6.0 (2026-06-09)

• New: .faust api resources <here|nearest|tindex> — see the total resources stashed in a castle (sums every chest and station). Defaults to admin-only and is a perfect candidate to charge an item for, or restrict to PvP servers, via the per-feature settings. Powerful raid intel for the BloodCraftHub UI.

0.5.0 (2026-06-09)

• New: lock a feature behind beating a boss. A feature can require defeating a specific V Blood (BossKill:<id>) or Dracula (FinalBoss, i.e. finishing the game) before a player can use it — set per feature with Unlock in the config. Admins can also hand-unlock for anyone: .faust admin grant <player> <feature> / revoke / unlocks <player>.
• Admins and a player querying themselves always bypass the lock.

0.4.0 (2026-06-09)

• Admins now have fine-grained control over every Faust feature:
  • Item cost is now actually charged from the player's inventory per use (e.g. 100 of an item to run a query) — and never charged if the query finds nothing.
  • Time-locks: a flat cooldown ("then locked 30 min"), or a window-per-period ("a free 10-minute window, once per day"). Limits persist across restarts.
  • PvP/PvE gating: a feature can be set usable only on PvP or only on PvE servers.
  • Live admin controls (no restart): .faust admin block <feature|all> [minutes] (with an optional countdown), unblock, schedule <feature|all> <HH:MM-HH:MM> (a daily time window), and status.
• Configure it all per feature in kdpen.Faust.cfg (Availability, WindowSeconds, PeriodSeconds, MaxUsesPerPeriod, plus the existing cost/cooldown/access).

0.3.0 (2026-06-09)

• Player stats are now real. Faust now logs connect/disconnect over time, so .faust api pinfo reports actual first-seen, session count, total playtime, logins/week, and peak hour (the game itself only remembers your last login). Data accrues from the moment Faust is installed.
• New: .faust api stats <playtime|concurrency> — a playtime leaderboard and a server population history (for BloodCraftHub graphs).
• Sessions persist to BepInEx/config/Faust/sessions.json.

0.2.0 (2026-06-09)

• First investigation queries are live (for BloodCraftHub + testing):
  • .faust api castleinfo <here|nearest|tindex> — a plot's owner, region, size, decay state & time, and the owner's online/last-online.
  • .faust api plots [page] — open building plots across the map, largest first.
  • .faust api pinfo <name|steamId> — a player's online state & last-online (you can always look yourself up; looking up others is admin-gated by default). Playtime/frequency stats are coming once Faust starts tracking sessions over time.
  • .faust api positions [page] — where online players are (admin-default).
• Each query obeys its per-feature access/cost/cooldown, and an empty or not-found lookup is never charged.
• This is an early data release — built for first in-game testing; please report anything odd.

0.1.0 (2026-06-09)

• Initial scaffold — the mod loads server-side and registers its chat commands. No investigation queries are live yet; this release is the foundation: the per-feature permission/cost gate and the BloodCraftHub handshake that everything else will hang off.
• .faust overview command and .faust help [players|castles|server|admin] menu.
• .faust api version reports each planned feature's access (Off / Admin / Players) and its price, so the BloodCraftHub UI can show what's available and what it costs. .faust api ping is a connection test.
• Every feature is configured independently in BepInEx/config/kdpen.Faust.cfg — sensitive intel defaults to admin-only; nothing costs an item until an admin sets a price.