MonsterMod

AI monsters for Counter-Strike 2 — spawn creatures that navigate the map, chase players, and fight, driven by a real behaviour brain on CS2's live nav mesh.

---

MonsterMod is a from-scratch ModSharp (CS2 / Source2, C#/.NET 10) platform for PvE monsters — a modern rework, inspired by the classic Half-Life MonsterMod, built on CS2's own navigation mesh with a proper layered AI on top. Monsters get a goal from a Hierarchical-Task-Network brain, a path from an A* search over the live nav graph, local separation steering, CS2-native velocity locomotion, and engine-correct combat — and other plugins add their own species through a clean extension API.

⚠️ Status: early / work-in-progress. The core runtime — HTN brain, A* over the live nav mesh, spawn director, combat, and the extension API — works end-to-end (the bundled MonsterMod.Example module proves the API against real code). Animation driving, the full monster roster, and crowd-scaling are in active development. It is not production-ready — this is shared for feedback and contributions. Much of the groundwork is reverse-engineering; see docs/.

🔧 How it works

The pipeline is deliberately layered and decoupled (docs/STACK.md):

1. Brain — a Fluid-HTN planner picks a goal (Idle / Wander / Chase / Attack / Flee / Follow) each plan tick (~8 Hz, staggered across agents).
2. Nav — a hand-rolled A* over a typed-edge graph built by reading CS2's live nav mesh straight from engine memory (no .nav parsing at runtime — see docs/NAV_RE.md).
3. Steering — boids-style separation keeps a crowd from stacking on one path.
4. Locomotion — CS2's native velocity movement (walk / climb / drop); the body is a chicken entity or a custom prop_dynamic model.
5. Combat — damage always flows through DispatchTraceAttack / TakeDamageInfo (never a raw Health -=), so the engine's pain / death / gib logic runs correctly (docs/PARITY.md).

🚀 Install

Build (see Build) and copy the output into your ModSharp install (<sharp> = your sharp directory):

From	To
.build/modules/MonsterMod.Core/	<sharp>/modules/MonsterMod.Core/
.build/shared/MonsterMod.Shared/	<sharp>/shared/MonsterMod.Shared/
.build/shared/Fluid-HTN/	<sharp>/shared/Fluid-HTN/
.assets/gamedata/monstermod.games.jsonc	<sharp>/gamedata/monstermod.games.jsonc
.assets/configs/monstermod/	<sharp>/configs/monstermod/

Restart the server (or change map) to load. MonsterMod.Example and MonsterMod.ModelTools are dev-only — they are not part of the gameplay bundle.

🧩 Dependencies

MonsterMod.Core is self-contained — it needs only the base ModSharp framework, no other plugins.

Dependency	Required?	Notes
ModSharp framework	Yes	ModSharp.Sharp.Shared, compile-only (the host provides it at runtime).
Fluid-HTN	Bundled	The HTN brain runtime. Ships inside the plugin at shared/Fluid-HTN/ (it must live in its own shared dir — a second copy in another load context causes a TypeLoadException). MIT-licensed.
ValveResourceFormat	Bundled (ModelTools only)	Parses compiled .vmdl_c / animgraph resources for the optional model-inspection tool. MIT-licensed. Not shipped with the gameplay module.

⌨️ Commands

All commands are server-console / RCON only (no client or chat commands, no admin gating — issue them from the console or RCON).

Command	Description
ms_spawn_load	Load the per-map spawn config for the current map and place all configured monsters.
ms_brain_spawn [N] [typeId]	Spawn N brain-driven monsters (default 5).
ms_brain_clear	Remove all brain-driven monsters.
ms_brain_auto [N] [typeId]	Keep N monsters alive around the map (auto spawn/respawn); 0 = off.
ms_brain_hurt [amount]	Damage all live monsters (default 25) — exercises the death / kill events.

Additional low-level ms_* probes exist in the Spike module and MonsterMod.ModelTools — those are reverse-engineering / animation dev tools, not gameplay features.

⚙️ Configuration

There are no ConVars. Monsters are placed from a per-map spawn file and tuned from code.

Per-map spawns — <sharp>/configs/monstermod/spawns/<mapname>.json, auto-loaded on every map start (missing/malformed → a warning, spawns nothing, never throws):

{ "spawns": [ { "type": "zombie", "origin": [x, y, z], "yaw": 90, "count": 3, "respawnDelay": 30 } ] }

A de_dust2.json example ships in .assets/configs/monstermod/spawns/.

Per-species tuning lives on each IMonsterType (default-implemented, override only what you need): BaseHp (100), MeleeDamage (15), AttackRange (80), AttackInterval (1.0s), ModelScale/HpScale/ArmorMultiplier (1), XpReward/GoldReward (0), IsBoss (false), RespawnDelay (0 = none), Hostile (true), Faction (Monster).

Gamedata — monstermod.games.jsonc carries the signatures/offsets MonsterMod uses to read the live nav mesh and animgraph. Re-verify these against the current CS2 build.

🧩 Public API

Other plugins add species/behaviour by consuming IMonsterModShared (resolve in your OnAllModulesLoaded) and its registries — see MonsterMod.Example for a complete, working walkthrough:

var shared = _shared.GetSharpModuleManager()
    .GetOptionalSharpModuleInterface<IMonsterModShared>(IMonsterModShared.Identity)?.Instance;

var types     = shared?.GetService<IMonsterTypeRegistry>();
var combat    = shared?.GetService<IMonsterCombat>();
var factions  = shared?.GetService<IFactionRegistry>();
var abilities = shared?.GetService<IAbilityRegistry>();
var spawner   = shared?.GetService<IMonsterSpawner>();

types.RegisterType(new ZombieType());   // your IMonsterType

A species plugin implements IMonsterType (identity + combat/visual/reward defaults), optionally IDomainContributor (append an HTN behaviour branch) and IMonsterSensor (feed the brain each tick). MonsterMod.Example demonstrates a new species, a chicken-AI species reusing the stock body, a custom sensor + behaviour branch, a registered ability, and a two-faction battle demo.

🗺️ Docs

MonsterMod is built on a lot of Source2 reverse-engineering — the notes live in docs/:

• docs/ROADMAP.md — phase-by-phase status.
• docs/STACK.md — the nav / crowd / brain stack decision record.
• docs/NAV_RE.md — CS2 nav-mesh reverse-engineering spec.
• docs/ORIGINAL_MONSTERMOD.md — capability map of the original HL1 MonsterMod (the behaviour reference).
• docs/PARITY.md — parity checklist vs. the original.
• docs/animation/ — CS2 animgraph (AG2) RE + animation-driving notes.
• docs/chicken/ · docs/CHICKEN_BRAIN_GAPS.md — the CS2 chicken entity as a monster body.

📦 Build

dotnet build -c Release

Non-.Shared projects build to .build/modules/<Project>/, .Shared projects to .build/shared/<Project>/. Requires the .NET 10 SDK.

🙏 Credits

MonsterMod is a clean-room reimplementation — the original code was read only as a behaviour spec, never copied (docs/STACK.md):

• Original MonsterMod — botman, Rick90, and "Giegue" (JulianR0/monstermod-redo, GPL-2.0), the HL1/Metamod monster plugin whose behaviour this project reverse-engineers for parity.
• Fluid-HTN by ptrefall — the HTN planner (MIT).
• ValveResourceFormat — Source2 resource parsing for the model tools (MIT).

📄 License

Released under the MIT License. MonsterMod's own code is original (clean-room); it is not a derivative of the GPL-2.0 original MonsterMod, whose behaviour was used only as a reverse-engineered spec.

---

Made with ❤️ by yappershq

⭐ Star this repo if you find it useful!