Creature HP Effects - Barebones Framework

What it is

[[Designed for as a barebones framework for modders to flesh out!]] 

 

Monster HP Effects turns non-player damage into a three-gate injury model tied to max HP. When a creature’s current HP first crosses downward through 75%, 50%, and 25% of a captured baseline max HP, the server can roll a pass/fail “gate” for that threshold. Each successful gate adds a stacking injury tier; a failed gate locks in that threshold as a miss (no stat gain at that band) but does not roll back lower tiers. All of that is server-authoritative: movement debuffs, optional aggressor melee scaling, optional best-effort AI nudges, and tier-3 “badly hurt / dangerous” telegraph (red light, glow, particles, and a short roleplay line for aggressors who complete all three gates). In normal play you do not need to do anything: eligible creatures get a small behavior at load, and injury math runs on real combat damage. For pack makers and server operators, the mod is also a framework: constants and attribute keys are the contract; stat layer names are namespaced; debug chat exists to verify what the server believes about a mob under the reticle. The feature list looks small; the problems it actually has to solve in Vintage Story include:

• Hook order vs. health application — the behavior is registered to run before the health behavior applies damage, so threshold math can use “before/after” HP consistently.

• Persistent, load-safe state — gate results, baselines, aggressor flag, and tier-3 visual flag live in watched attributes so chunk cycles and saves do not silently reset injury progress.

• Additive stat math — walk/sprint/melee use a dedicated stat layer (mhe-effects) so other mods are less likely to fight raw stat replacement.

• Aggressor is not “whatever the JSON says” — a heuristic classifier (path hints, AI/task reflection where possible, behavior names) decides whether a creature is treated as an aggressor for melee scaling and some AI patch paths, with generous defaults for ambiguous modded mobs.

• Tier-3 visuals across clients — a custom server channel broadcasts tier-3 on/off by entity id; joining players get a replay of known tier-3 entities so late joiners are not blind. The client applies particles plus red dynamic light and glow (with restore when tier-3 ends) so rust-colored or flat-shaded models still read “injured” next to furrier creatures.

• AI changes without shipping entity patches for every mob — reflection-based inspection of task graphs attempts to reduce prey-like behavior and bump engagement on wounded aggressors; this is explicitly best-effort and safe-fails rather than pretending every mod AI is identical.
  
  

Monster HP Effects is a server-led combat tone mod for Vintage Story 1.22+: injured creatures slow down (stacking move penalties), dangerous ones can get meaner as they drop (aggressor melee tiers), and maximum injury is readable and synced — not just “numbers in a spreadsheet.”

At a glance

It sounds like “damage thresholds → debuffs.” In practice it is a small state machine per creature glued to real damage events, with networked tier-3 feedback and optional AI steering so “hurt monster” feels like pressure in combat, not only a slower walk animation.

How to use

Default play (no commands) Fight creatures as usual. When HP crosses the three bands downward, gates may pass or fail; tiers stack; tier-3 triggers the strong visual telegraph (and the aggressor-only roleplay line when applicable). Debug / inspection (/mhe, alias monsterhpeffects) Requires a player context and normal chat privilege (see your server’s permission setup). Typical subcommands (exact wording may match your build’s help text):

1. /mhe status — Summarize the entity you are looking at (or similar targeting): baselines, gate bits, aggressor flag, tier-3 visual, etc.

1. /mhe probe — Similar diagnostic path for debugging attachment/state.

1. /mhe tierup — Forces a consistent re-apply path useful when testing tier transitions and aggressor AI patching.

1. /mhe dmg [n] — Apply damage (decimal separator: use dot, e.g. 3.5, for predictable parsing).

1. /mhe heal [n] — Heal by amount (same parsing rules).

1. /mhe reroll 1|2|3 — Development-style control over re-rolling a gate band where supported.
   
   

Use /mhe help for the authoritative list shipped with your version. Quick verify After changing configs or updating the DLL, confirm modinfo version and watch the server log for a warning if the custom network channel failed to bind (tier-3 visual sync would then be unreliable). Troubleshooting

• No tier-3 glow/particles — Confirm the creature actually reached three successful gates (status), confirm network channel is not warning on boot, and confirm you are within client FX distance (particles are distance-limited; glow/light follow tier-3 state more broadly).

• aggressor looks odd — It is a heuristic, not a lore tag; use status to see what the server stored.

• /mhe dmg/heal parse oddly — Use invariant decimal format (12.5 not 12,5 on some locales).

Design philosophy

First: server truth is absolute. Gates, baselines, tiers, and aggressor classification for gameplay consequences are decided on the server. The client renders what it is told (and tier-3 packets fill gaps where pure attribute sync is not enough). Second: composability over stealth. Stat changes go through a named layer and additive deltas where appropriate so “Monster HP Effects” does not silently overwrite unrelated mods’ movement or damage math. Third: honesty about AI. Anything that pokes task lists via reflection is best-effort: helpful when it works, never advertised as universal across every custom AI graph. Fourth: diagnostics are part of the product. Chat commands and structured attributes exist because injury state is invisible without them; operators deserve to see gates(raw), tier3Visual, and baseline max HP without guessing. Fifth: launch-ready visuals are layered. Particles alone fail on some materials; light + glow + particles cover more creature shaders while restoring prior client light/glow when tier-3 ends.

What it is not

• Not a full wound simulation — no bleeding stacks, infection, or limb HP; it is three discrete thresholds plus RNG gate outcomes.

• Not a universal AI rewrite — no guarantee every mod creature becomes smarter; patches are opportunistic.

• Not a player HP system — players are excluded from this behavior’s damage logic.

• Not a claims / protection / anti-grief layer — it does not protect blocks or creative builds; see No Touch Items-style mods for that problem space.

• Not a config-heavy rebalance suite — the “contract” is in constants; extending

License / use
Free to use, copy, modify, and redistribute this mod and derived works for any purpose (including commercial packs), provided you credit the original author (Squidbat) in your readme, ModDB page, or in-repo credits so others can find the upstream author for questions, debugging, or merge requests. Provide link to my profile. Same caveat as above regarding formal licenses if you need one

Github: https://github.com/19HarryHaller27/Creature-HP-Effects---Barebones-Framework/tree/main