Sneak Attack! - Barebones Framework

What it is

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

*** Full disclosure! This is a STRONG attempt at sneak attacking - but it is not perfect. If there is anything that is not working well let me know! And I'll happily address it asap! ***

[Also, pictures fuzzy for the moment. Late night. Lemme sleep and fix it in the morning. Sorry m8s]

[Also, your 'Sneak Score' should be as close to 0.0 as possible for the creature to not detect you. 0.2 and above the creature will usually sense you before you can get off your melee sneak attack. You can, if you want, modify the modifiers to make it easier or harder to reach 0.0, if you like.]

---

Sneak Opener is a Vintage Story 1.22+ stealth combat framework. It gives you two connected systems in one mod:

1) Sneak Opener (first-strike damage) — a big bonus on the first qualifying hit while you are sneaking and the creature is not already “in combat” with you.

2) Stealth Signals (detection model) — a live noise + visibility model that drives how easy you are for animals and hostile mobs to sense (animalSeekingRange), so sneaking, gear, weather, light, scent, and movement actually matter before you ever swing.

It also includes sneak movement QoL (walk off ledges while sneaking, jump while sneaking, bows usable while sneaking) and a F9 world HUD so you can see what the server thinks is happening.

What you get at a glance (casual players)

• Sneak up, strike first, hit hard — if the mob hasn’t been fighting you recently, your first sneak hit can multiply damage:
• ×2 ranged (bow / projectile released while sneaking)
• ×3 general melee
• ×5 knife or dagger in main hand (right hand)

Any angle — you do not need a strict backstab cone. Position still matters for your stealth (light, scent, detection), but the opener bonus is not blocked by “wrong side” hits. One opener per fight window — after you damage a creature, it is marked combat engaged for 15 seconds (timer refreshes on further hits). While engaged, you won’t get the opener multiplier again until that window expires without damage. Roleplay + math in chat (on by default) — successful openers can show a short flavor line plus a damage breakdown so you know the bonus actually fired. Press F9 — floating HUD: sneak detection score, noise/visibility breakdown, and whether your current target looks opener READY or BLOCKED. Sneak like a game expects — ledge-walk and jump-while-sneak patches; bows can be drawn and fired while sneaking (server tracks “fired while sneak” for ranged openers).

What it is really solving (why this is a framework, not a single buff)

At a glance this sounds like “sneak = more damage.” In practice the solved problems are deeper:

For opener combat

• deciding opener eligibility on the server at damage time (not client guesses),
• tracking per-creature combat engaged state across hits and a timed reset,
• treating ranged separately (projectile must have been released while sneaking),
• classifying knife/dagger by item code in main hand vs other melee,
• refusing to silently fail in Creative (0-damage hits get a clear chat hint),
• and giving observable feedback (/so debug, F9 preview, flavor + math lines).

For stealth / detection

• building noise and visibility composites from many world and inventory facts,
• publishing them on the player for other systems and modders to read,
• mapping those composites into vanilla’s animalSeekingRange stat so seek AI actually reacts,
• recomputing on a steady server tick (~300 ms) instead of one-off guesses,
• and exposing breakdown attributes for F9 and future extensions.

For interaction routing

• patching sneak movement and bow use without breaking unrelated controls,
• syncing enough state client-side for a trustworthy HUD while keeping damage authoritative server-side.

This is not a cosmetic sneak toggle. It is an interaction-hardened stealth contract: if the server says you’re loud or bright, creatures sense you more; if you’re sneaking on a fresh target, the first hit can pay off; if something blocks the opener, the mod tells you why.

Sneak Opener — rules (explicit)

Opener applies when ALL of these are true on the server:

1. You are the attacker (player damage).
2. You are sneaking at hit time, or (for ranged) the projectile was fired while sneaking.
3. The target is not combat engaged (no player damage on that creature within the last 15 seconds).
4. Your hit deals > 0 damage (use Survival mode for real damage tests; Creative often shows 0 and will explain that in chat).

Damage multipliers (first qualifying hit only):

Attack type	Multiplier
Ranged / projectile (released while sneaking)	×2
Melee (not knife/dagger)	×3
Knife or dagger in main hand	×5

After any damaging hit from a player, that creature becomes combat engaged until 15s pass without taking damage again.

Optional seek gate: the framework supports gating openers on how “detectable” you are (animalSeekingRange). In the current release this gate is effectively off (always passes) so openers are not silently denied by stealth tuning — but F9 and /so status still show seek values for testing and future tightening.

Stealth Signals — what affects detection (casual + modder-readable)

Every ~300 ms the server recomputes stealth on each player and publishes watched attributes. Lower animalSeekingRange (blended) generally means harder for mobs to sense you.

Noise side (examples)

• Movement: idle / walk / sprint scaling
• Surface underfoot
• Landing impact spikes (jumping down adds temporary noise)
• Backpack fullness (emptier = quieter; stuffed = louder)
• Scent carry: food and organic loot in inventory increases noise; rain/wet can wash scent off
• Armor (metal is loud)
• Sneak reduces noise (and partially eases armor noise for cloth/leather; metal stays punishing)

Visibility side (examples)

• Ambient light at your position
• Rain / weather
• Fog / cloud proxy
• Forest biome density
• Local foliage (grass, shrubs, leaves) and cover (canopy / ceiling)
• Armor visibility (metal shines)
• Held light (torch in hand or on hotbar contributes — carrying light while “sneaking” hurts stealth)
• Sneak reduces visibility (with amplified bonuses in dark/weather/forest tuning)
  
  

Combined

• Noise and visibility feed a geometric blend that drives animalSeekingRange so wolves, drifters, and other seekers respond in-world.

For other modders: attributes like stealthsignals.extNoiseMul and stealthsignals.extVisibilityMul exist so companion mods can scale the final composites without forking the evaluator.

How to use

1. A) Playing stealth combat (Survival)

1. Reduce detection — sneak, avoid torches, mind backpack weight and smelly food, use darkness/weather/forest cover. Watch F9; lower sneak score is better.
2. Pick a fresh target — F9 should show Opener: READY when you’re sneaking on a mob that isn’t engaged.
3. Strike — melee or bow from sneak; knife main hand for maximum opener.
4. Read chat — flavor + damage math confirms the server applied the bonus.
5. Finish the fight — after the first hit, expect normal damage until the 15s engaged window clears on that creature.

1. B) F9 — Stealth telemetry HUD

• Toggle with F9 (in-world overlay, movement-friendly).
• Shows: sneak detection headline, noise section, visibility section, √(noise×vis), opener READY/BLOCKED for crosshair target (or nearest mob within 6 blocks), and stat breakdown footers.
• Preview is client-side; damage multipliers are server-confirmed (HUD may say READY, but Survival damage and chat prove it).

1. C) Chat commands — Sneak Opener (/so)

Requires normal chat privilege (command bar).

Command	What it does
/so or /so status	Your sneak state, seek blended value, combat-engaged info on aimed mob
/so help	Full list
/so debug on|off	Chat explanation on every hit — why opener did or didn’t apply
/so feedback on|off	Flavor + damage math on successful openers (default on)
/so reset	Clears combat engaged on aimed creature (gamemode privilege)
/so dummy [entityCode]	Spawns frozen test mob facing away, no AI (gamemode)
/so dummyclear	Removes nearby test dummies (gamemode)
/so seekbest	Forces very low animalSeekingRange for detection experiments (gamemode)
/so seekset <value>	Forces your blended seek value (gamemode)
/so seekreset	Removes forced seek override (gamemode)

Alias: /monsterhpeffects is not used — the command root is /so.

1. D) Chat commands — Stealth Signals (/sts)

Command	What it does
/sts status	Quick read of published stealth attributes
/sts debug on|off	Reserved / lighter debug channel (F9 always shows breakdown attrs when synced)

Alias: /stealthsignals.

1. E) Recommended test workflow (modders & QA)

1. Confirm modinfo.json version matches the DLL you installed.
2. Use Survival for damage tests.
3. /so dummy → /so debug on → sneak → hit → read chat + F9.
4. /so reset on the dummy between trials for a fresh opener window.
5. Toggle /so feedback off if you only want mechanical logs.
6. For detection tuning, watch F9 while changing light, torch, backpack fill, sprint vs sneak, rain, forest.

Design philosophy

1) Server truth for outcomes
Opener damage and combat-engaged flags are decided on the server at OnEntityReceiveDamage. Clients preview; they do not grant bonuses.

2) Observability is part of the product
F9, /so debug, /so status, and optional chat feedback exist because stealth games fail when players can’t tell why something didn’t proc.

3) Composability for mod packs
Stealth Signals publishes stable attribute paths and ext multipliers. Sneak Opener is a focused behavior (!sneakopener:core) you can reason about or fork. Constants files are the contract.

4) Practical movement, not animation theater
Ledge-walk, sneak-jump, and sneak-bow patches exist so stealth playstyles aren’t fighting vanilla control quirks.

5) Honest scope
Flavor text is evocative, but mechanics are explicit multipliers with timestamps and flags — not hidden crit rolls with no paper trail.

Why Harmony (0Harmony.dll) is required

Vanilla does not expose clean hooks for everything this framework does. Harmony patches game methods at runtime so we can:

• Walk off block edges while sneaking (vanilla normally blocks “stepping off” a ledge in sneak).
• Jump while sneaking (restore jump impulse vanilla suppresses).
• Use bows while sneaking (client + server track interact/release so ranged sneak openers know the shot was fired from sneak).

Without 0Harmony.dll, those features may not load or may throw errors at startup; opener damage and Stealth Signals math can still partially run, but the mod is not intended to be used without Harmony in the mod folder.

What it is not

Sneak Opener is not:

• a full thief class / pickpocket / lockpick suite,
• a invisibility or aggro-wipe cheat,
• a territory/claims or anti-grief system,
• a guaranteed one-shot assassin mod (multipliers are strong but still respect armor, HP, and weapon stats),
• a client-only damage hack (all opener math is server-side),
• or a replacement for vanilla AI overhaul mods (it feeds animalSeekingRange; it does not rewrite every mob brain).

It is a barebones stealth combat framework: first-hit sneak damage, a tunable detection model, movement/bow fixes, and first-class diagnostics.

For modders extending the framework

Hook points & contracts

• Player watched attributes under stealthsignals.* (noise/visibility composites, dbg breakdown, pack/scent multipliers, blended seek).
• Creature flags sneakopener.combatEngaged and sneakopener.combatLastDamageMs.
• Projectile flag sneakopener.firedWhileSneak for ranged openers.
• Ext muls: stealthsignals.extNoiseMul, stealthsignals.extVisibilityMul (default 1).
• Entity behavior id: !sneakopener:core (runs early in damage pipeline).

Typical extension patterns

• Tighten SneakAttackMaxAnimalSeekingBlended so only “very stealthy” players get openers.
• Add traits/perks that scale extNoiseMul / extVisibilityMul.
• Read composites in your own AI mod instead of duplicating light/smell logic.
• Fork EntityBehaviorSneakOpener for custom multiplier tables or backstab cones if you want stricter design than “any angle.”

Build

• .NET 10, VintagestoryAPI.dll via VintageStoryPath in Directory.Build.props.
• Output: SneakOpener.dll + modinfo.json.

Known quirks / troubleshooting

• “I sneak hit but nothing happens” → Confirm Survival, target not engaged, you’re actually sneaking (ranged: shot must be released while sneaking). Run /so debug on.
• F9 says READY but damage looks normal → Server may have blocked; read debug chat. Creative often deals 0 — not an opener test environment.
• Torch on hotbar still bright → Held-light logic counts inactive hotbar slots at reduced weight; stow lights for serious stealth.
• Smelly inventory → Food/organic carry increases scent noise unless washed out by rain/wet.
• After first hit, no more ×5 → Working as designed; wait 15s without damaging that creature or /so reset on test dummies.
• Long /so or F9-related logs → Some verbose traces may be easier to read in server-main.log than in-game chat if lines are huge.

 

Flavor

The forest does not announce you. It measures you — breath, footfall, the grease of fear on iron, the honest glare of a torch you swore you would not need.

Sneak Opener is for the player who treats the first strike as a sentence already written in the dark: one opening, one price, one moment where the world forgets your name and remembers your steel.

When the mud knows your weight and the wind carries your supper, wolves lift their heads. When the rain washes your trail and the canopy drinks the moon, you become a rumor. When you finally move, it should feel like the night itself decided to bite.

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/Sneak-Attack---Barebones-Framework/tree/main