Combat System

Authoritative project content

Combat is balanced gun + melee — [CONFIRMED]. Both are first-class; the player constantly switches based on ammo, range, and threat. All combat is server-authoritative.

Camera & aiming

• Third-person over-shoulder with three aim modes (see 02-Player-Character.md): HipRelaxed (weapon down), ShoulderAim (third-person firearm toggle), ADS (first-person firearm toggle). Melee and empty hands toggle guard aim in either view; see the linked player contract.
• Spread, movement speed penalty, and camera interp all key off replicated aim mode (ULambeerAimComponent).

• [RECOMMENDATION] subtle aim assist for controller in ShoulderAim/ADS only; mouse is raw.

Independent fire heading — later-phase upgrade [CONFIRMED INTENT]

Owner requested 2026-09-20: add a later-phase upgrade so the player can fire in a heading that differs from movement heading. Example: travel south, then raise the weapon and fire north.

Current baseline (not this upgrade): HipRelaxed orients the actor to movement (VelocityDirection). ShoulderAim/ADS orients the actor to look/aim yaw (LookingDirection), then locomotion plays look-relative strafe or backpedal clips. Aimed fire therefore still turns the whole actor toward the look heading. Walking south while looking north currently means facing north and moving backward; it does not keep a south-facing body while firing north. Canonical rotation contract: TECH-PLAYER-LOCOMOTION 10.7.

This upgrade is deferred. It is not P09 presentation work and not P10 firing, damage, or ammo implementation. Do not change the 10.7 rotation contract for this request now. Exact later numbered phase remains [TBD]; do not reuse P00–P31 IDs.

TBD-COMBAT-AIM-001 — independent fire vs movement heading

[TBD] Approve the later-phase contract before implementation:

• Which aim modes it applies to (HipRelaxed, ShoulderAim, ADS, melee/unarmed guard).
• Idle standing versus moving, and whether a last movement heading is kept after stopping.
• Maximum yaw split between movement/body heading and fire/look heading.
• Whether the capsule/actor stays on the movement heading with upper-body/arm aim, or another rotation model.
• Animation and content requirements; replication for remote proxies.
• Exact later phase ID after P09/P10.

Record the approved contract only in this specification and the locomotion guide. Production: PIPE-ROADMAP later-phase scope.

P10 selected slice — [CONFIRMED 2026-09-20]

First playable combat loop:

• Firearm: Item.Weapon.L1810 only. Double Barrel Shotgun and the wider catalog stay P20/P27. Break-action loading is not this slice.
• Melee: Crowbar, FireAxe, Sledgehammer, WoodenMallet. Light strike only. Heavy/block/parry/shove remain recommendations until separately approved.
• Throw: any DA_Item_* that can occupy a hand uses the existing throw contract. Throw does not deal combat damage in this slice.
• Melee attack gate: only a held item whose definition has bMeleeWeapon=true may melee-attack. Held items without that flag can still be thrown.
• Presentation: firearm shots have no Fire animation; they use NotifyWeaponShot plus Procedural Recoil. Melee uses existing sequences under /Game/Lambeer/Characters/Player/Animation/Attack/ (verified: Melee1H Right/Dual Stand/Crouch/Prone, Melee2H Stand/Crouch/Prone). Reload presentation uses verified /Game/Lambeer/Characters/Player/Animation/FirearmReload/A_PistolReload.

Gunplay

Firing model — [CONFIRMED 2026-09-20] for L1810

• L1810 is a projectile (travel time and gravity). Hitscan is not this slice firearm.
• Keep a per-weapon data field so later firearms may be hitscan or projectile without unique classes. Do not treat hitscan as an L1810 fallback.
• Range damage drop still evaluates at impact from muzzle to hit, then hit-zone multipliers, then GAS. Never accept a client-reported damage amount.

TBD-COMBAT-PROJECTILE-001 — L1810 projectile flight numbers

[RESOLVED 2026-09-20] Owner approved the L1810 P10 flight contract. Record these values in this specification and the owning Data Assets. Do not bake a different muzzle velocity as a hidden C++ default.

Per-weapon data (data-driven)

Each firearm is defined by a DataAsset/DataTable row, not a unique class. Fields:

Range damage drop — [CONFIRMED]

Firearm hits lose damage over shot distance. The system is data-driven and server-authoritative. P10 evaluates the authored curve on the server at impact inside UCombatComponent / ALambeerProjectile. Example table values such as 35 damage are not approved tuning.

• Distance is the 3D length from the shot origin (muzzle) to the hit location, in Unreal units (centimeters).
• The same distance rule applies whether the shot is hitscan or projectile: evaluate at impact. Never accept a client-reported damage amount.
• The server scales authored base firearm damage by the falloff curve, then by locational hit-zone multipliers, then applies the result through GAS. ULambeerAbilitySystemLibrary::ApplyDamage already accepts a final amount; cheat/debug callers that pass a raw amount skip this scale.
• Deterministic: the same authored curve and distance produce the same scale. Clients may predict muzzle and impact presentation only.
• Range drop does not apply to melee strikes, improvised swings, or Lambeer.Damage.
• Thrown improvised-object damage stays under the improvised-weapon TBD; this contract does not add throw falloff.
• Scope rail position does not change damage or falloff. Other attachments do not change falloff unless a later decision says so.
• HUD does not display falloff, damage numbers, or hit markers, per FEAT-HUD-UI.
• Item Data Assets store the curve on ULambeerItemDefinition::FirearmCombat (nested struct, not a CRV_ asset). CRV_ remains the curve naming prefix in TECH-FOLDER-STRUCTURE if a later firearm needs a shared curve asset.

Application order:

AppliedDamage = BaseDamage × FalloffScale(DistanceCm) × HitZoneMultiplier

BaseDamage, curve keys, and hit-zone multipliers for L1810 are approved under TBD-COMBAT-RANGE-001 and hit zones. Do not copy example 35 into other firearms.

TBD-COMBAT-RANGE-001 — firearm falloff numeric contract

[RESOLVED 2026-09-20] Owner approved the L1810 P10 prototype contract below. Attachments do not change falloff. 9x19 does not override the firearm curve. Multi-pellet rules are not used on L1810. Example 35 remains unapproved. Other firearms must be authored before they fire; a firearm with no curve refuses the shot.

Record these values in this specification and the owning Data Assets. Do not bake them as hidden C++ constants copied from examples. MCP authored and saved DA_Item_L1810.FirearmCombat on 2026-09-20 (is_dirty false); readback matches this table plus RPM 400, spread 2.5 / 1.2 / 0.35, muzzle 36000 cm/s, and bUseProjectile true.

Acceptance (after numbers exist): two hits with the same firearm at different authored distances apply different GAS amounts according to the curve; a client-reported damage amount is ignored; melee and Lambeer.Damage stay unscaled by shot distance. Owner-reported 2026-09-20: close-versus-far L1810 falloff passed on Dedicated Server + two clients under ROAD-P10-04.

Damage & hit zones

• Locational damage applies after range falloff. [CONFIRMED 2026-09-20] P10: head ×1.75, all other zones ×1.0. Limb splits wait on authored zombie/body physics.
• Zombies have weak points (e.g., head); some boss zombies have armor/weak-point mechanics. See ../03-Enemies/01-Zombie-Design.md.

Owner animation clarification — 2026-09-16: the requested aiming cases use ShoulderAim, not ADS. Firearms fire independently by right/left hand; a firearm/melee mixed pair uses only the right hand for aim and actions while the left retains its held item. All poses are required. Dual one-handed melee uses a dedicated paired animation. P10 occupancy inputs below supersede the open-button note. P09 animation profiles, Layered Blend and recoil design distinguish character recoil from weapon mechanism animation.

Owner movement decision — 2026-09-17, updated 2026-09-23: Active ShoulderAim permits Walk only. Pressing Sprint immediately cancels ShoulderAim or ADS before normal gait selection; releasing Sprint does not restore aim. Carry upper-body poses are shared across gaits. Canonical Sprint cancellation contract and owner acceptance. Animation context and implementation.

Owner aim eligibility decision — 2026-09-17: Item-family tools cannot enter ShoulderAim or ADS. The right-held item determines eligibility; with no right item, use the left. Empty hands retain unarmed aim. Right Firearm/Melee with left Item is allowed, with the left retaining Carry. Switching to a disallowed item cancels aim. Crowbar/FireAxe/WoodenMallet now have bMeleeWeapon=true; Sledgehammer was already true. P10 light-strike integration uses UCombatComponent and existing Attack sequences.

L1810 ADS presentation: owner-authored SightReference and standing supported ADS pose feed opt-in camera-relative weapon alignment. Neutral ADS is solved in view space; trial sway and visual recoil offset the weapon around the grip; hands follow that result. Camera stays character-based. Scope, tuning and acceptance; other stance/topology content remains separate.

Recoil & feedback

Owner confirmed — 2026-09-17, spring/camera channels — 2026-09-19: all character recoil uses Procedural Recoil; no recoil Animation Sequence or profile Recoil field is required. The shot event remains NotifyWeaponShot plus multicast. Weapon kick is now critically damped springs from the aiming guide. Camera recoil is a separate visual spring on the local camera, not Control Rotation or P10 damage. Owner visual/network acceptance is pending. Canonical animation contract.

• Deterministic recoil pattern + small random bloom; recoil recovers when not firing.
• Strong world impact feedback: impact VFX/decals, world blood splatter, audio. Feedback quality is a pillar (readable combat). No UI hit, headshot or kill markers are shown, per the confirmed HUD contract. Persistent stains on gear/bodies and the local HUD blood overlay are specified in Blood Visual. Blood also contributes to periodic infection risk; exact probability tuning remains in the survival specification.

Combat occupancy inputs — [CONFIRMED 2026-09-20]

KBM. Occupancy is classified from the held stacks after the existing right-then-left family rule. Mixed firearm (right) + anything in left uses the firearm rows, not the melee rows. Existing IA_Throw (middle mouse) and throw-cancel on either mouse button during windup stay. IA_CheckChamber / IA_CheckMagazine stay Shift+R / Alt+R.

• [CONFIRMED 2026-09-20] A valid firearm fire press from HipRelaxed is allowed: the same press enters the current-view aimed firearm mode and then fires. Owner wording is “enter ADS and fire immediately.” Canonical mode names stay: third-person aimed firearm is ShoulderAim; first-person aimed firearm is ADS. This does not force a first-person camera swap.
• [CONFIRMED 2026-09-20] A valid melee attack press from HipRelaxed enters melee ready and attacks on the same press. RMB-only still enters ready without attacking.
• Empty hands are not a melee weapon. Unarmed Attack clips exist as content; they are not a P10 combat action unless a held bMeleeWeapon item is present.
• Left-only one-handed melee (right empty) uses the one-handed melee row on the occupied hand.

Reload and L1810 bolt — [CONFIRMED 2026-09-20]

• L1810 is a closed-bolt semi-auto. A successful shot consumes the chambered round, then immediately chambers the next round from the installed magazine when one remains. Empty magazine: empty chamber, no shot. Dry-fire does not consume durability. [CONFIRMED 2026-09-20] P10 has no rack action: an empty chamber with magazine ammo feeds one round and fires on the same LMB.
• Removing a magazine can still leave one chambered round.
• Separate charge / rack / slide-lock controls are deferred. They are not required to fire this slice.
• R starts the confirmed 3-second field magazine install while a firearm is held. Dual one-handed firearms install the right firearm first, then the left. Drag-install remains valid. When several compatible magazines exist, the server uses inventory order: first mag with remaining ammo, else the first compatible mag. If a magazine is already installed, R ejects it into inventory and installs the selected replacement in the same 3-second action. Magazine install/remove may continue while moving; chamber/magazine inspection (Shift+R / Alt+R) still cancels on movement.
• Reload presentation: /Game/Lambeer/Characters/Player/Animation/FirearmReload/A_PistolReload.

Melee

• Light attack, heavy attack, block/parry [RECOMMENDATION], shove/kick to create space. [CONFIRMED 2026-09-20] P10 implements light strike only.
• Stamina-gated: attacks cost stamina. Blocks remain a recommendation.
• Melee matters because ammo is scarce (full-loot economy) — it's the reliable fallback, not a last resort.
• Melee weapons are also data-driven (damage, speed, stamina cost, durability).
• Successful melee hits that deal damage to living targets stain the striking item (or fists/gloves/shoes) and the victim. See 10-Blood-Visual.md. Material look remains P12.

TBD-COMBAT-MELEE-001 — first melee slice numeric contract

[RESOLVED 2026-09-20] Shared pipeline, per-item numbers. Hit detect is a server sphere sweep along look (GetBaseAimRotation), radius 18 cm. Cancel on death, hand swap, throw, or insufficient stamina. Moving during the swing is allowed. Connecting hits that damage living targets set item BloodAmount. Values may not be copied as hidden C++ examples.

MCP authored and saved the four Tools MeleeCombat rows plus bMeleeWeapon=true on 2026-09-20 (is_dirty false). Readback matches this table. Production classes and sequence: PIPE-ROADMAP held tools slice.

Owner PIE diagnosis — 2026-09-20: reported FireAxe LMB animation absence was traced from live logs: occupancy classified the right hand as authored melee, LMB reached ServerMelee Right, then the server refused the action because stamina was 2.0 while the FireAxe cost is 14.0. This is the confirmed insufficient-stamina cancellation above, not a broken input binding or missing montage route; a refused attack must not multicast or play the strike. Owner retest 2026-09-20 passed the strike plus upper-body slot while moving at stamina ≥14. Clear denied-action feedback remains a presentation follow-up, not permission to bypass the stamina gate.

Dual-wield one-handed weapons — [CONFIRMED]

• Any combat weapon authored as one-handed can be equipped in either the left hand or right hand. This includes knives, hammers, pistols, and future one-handed weapon types.
• The player can hold two eligible weapon instances at the same time, including two copies of one weapon or a mixed pairing such as pistol + knife. Each instance keeps its own ammunition, chamber, attachments, durability, BloodAmount, and WetAmount state.
• Weapons authored as two-handed are not eligible for a dual-wield pair. The handedness classification is data-driven rather than inferred from the weapon category.
• Per-hand input, dual-firearm fire, dual-melee paired attack, and dual-reload order are [CONFIRMED 2026-09-20] in occupancy inputs. Block/parry remains a recommendation, not P10 work.

Held throw and melee eligibility — [CONFIRMED 2026-09-20]

• Any item that can occupy a hand may be thrown with the existing throw contract. This is P10 work. It is not a damaging thrown attack.
• Melee attack requires bMeleeWeapon=true on that item’s DA_Item_*. A held flashlight, wood stack, or L1810 cannot melee-attack.
• Unmarked environment meshes still cannot enter a hand. A scene prop becomes throwable/melee-eligible only after it is a Data Asset that can be held, with melee still gated by bMeleeWeapon.
• The earlier chair/microwave combat-usable catalog, throw-impact damage, breakage, and “enter normal inventory” questions remain open for a later prop pass. They are not this P10 slice.

Dual-wield & held-item combat acceptance

• The server accepts any pair of weapon instances whose definitions are one-handed, including mixed firearm/melee pairs, and rejects a two-handed item in a dual-wield pair.
• Other clients see the correct item in each hand and receive authoritative attack, ammunition, durability, drop, and damage results.
• LMB/RMB occupancy in the input table is what dedicated-server clients run. Dual 1H firearms: LMB left shot, RMB right shot. Dual 1H melee: LMB plays the paired attack, not two independent left/right swings.
• Throw remains the existing windup contract for any held item. Melee attack is refused unless bMeleeWeapon is true. Unmarked environment props cannot enter a hand.
• Switching, dropping, or throwing cannot duplicate the held weapon; every held-state transition is server-authoritative.
• Durability 0: the item may stay in inventory, hands, holster, or be thrown; fire, melee attack, and tool-role actions are refused.

Ammo, magazines & durability

• Ammo is a crafted/looted item with weight; ammo scarcity drives the gun↔melee balance.
• Magazines are items that hold ammo (Tarkov-like). The player loads ammo into a mag, then installs the mag. Magazines do not stack; partial fills persist; mixed compatible ammo types in one mag are allowed when those ItemIds are on the magazine’s DA_Item_* CompatibleItemIds list. The firearm has a chambered round separate from the mag, plus check / charge / bolt-release handling. Full rules: FEAT-WEAPON-CUSTOMIZATION.
• Durability on firearms and tools is [CONFIRMED]. Use reduces durability. There is no dirt system. Repair uses a gun repair kit and/or salvaged family parts (e.g. AR → AR parts). See FEAT-WEAPON-CUSTOMIZATION. Blood stains: FEAT-BLOOD-VISUAL. [CONFIRMED 2026-09-20] Durability 0 keeps the item in inventory, hands, or holster and still allows throw; fire, melee attack, and tool-role actions are refused. [CONFIRMED 2026-09-20] On an otherwise valid fire attempt, jam chance percent is 100 - DurabilityPercent / 2; canonical record TBD-F2319BE6.

Networking notes

• Server is authoritative for damage, ammo, hit validation, projectile simulation, and range-falloff evaluation from shot origin to hit.
• Client-side prediction for responsiveness (firing feedback) with server reconciliation.
• [RISK] lag compensation / hit registration for ~40–60 players is non-trivial; budget time for it. See ../04-Multiplayer/01-Network-Architecture.md.
• Anti-cheat sensitive: never trust client-reported hits/damage. Easy Anti-Cheat (EAC) is the confirmed anti-cheat solution, supplementing server authority.

Grip authoring: see FEAT-INVENTORY grip contract and per-item hand pose. The owner approved shared hand_r/hand_l sockets, per-item transforms, KeepWorld scale, no left-hand mirroring and AnimBP Two Bone IK on 2026-09-16, then per-item finger Pose Assets on 2026-09-17. Runtime/AnimBP integration for placement/IK landed under ROAD-P09-03; native pose fields and ABP hand blends landed under ROAD-P09-05. Authored offsets, Pose Assets and owner PIE remain ROAD-P09-04. Grip references are separate from melee damage geometry and do not establish an accepted combat pose or hit-detection system.

Implementation guidance

• UCombatComponent on the character orchestrates firing/melee; weapon behavior is driven by item Data Assets plus held stacks (chamber, mag, durability). There is no separate melee GameplayAbility in this slice. Tools that are Static Meshes reuse UHeldItemComponent rather than a per-item weapon actor. Sequence: held tools slice.
• Range damage drop is evaluated on the server from FirearmCombat plus shot distance via LambeerFirearmRules, then the scaled amount is passed into GAS. Do not bake example damage numbers into C++.
• L1810 projectile flight is approved under TBD-COMBAT-PROJECTILE-001: 36000 cm/s, world gravity, no tracer in this slice. Runtime fire/melee pipelines live in UCombatComponent and ALambeerProjectile. Owner PIE for this slice closed under ROAD-P10-04.
• Back weapon slots 1–2 (inventory UI) are holstered firearm/melee locations. Drawing and assigning eligible items to the left/right hand follows the dual-wield occupancy table.
• Held throw is the existing item throw, not a second damaging projectile. Scene-prop combat pickup stays a later catalog.
• [RECOMMENDATION] model damage, health, stamina, and buffs through GAS (GameplayEffects for damage and status), which cleanly supports the boss permanent-buff system. See 07-Crafting-and-Progression.md and ../05-Technical/01-Tech-Stack-and-Engine.md.