Combat Core and Loop

Kill reward flow

When an enemy dies on the server, EnemyController broadcasts RpcNotifyEnemyKilled(enemyLevel, categoryValue, enemyInstanceId) to all clients. Only the local player's client sends the API call โ€” remote clients ignore it to prevent duplicate reports.

Payload sent to POST /api/combat/kill:

{ "characterId": <int>, "enemyLevel": <int>, "enemyCategory": "<string>", "enemyInstanceId": <uint> }

enemyCategory is the lowercase RewardCategory name (e.g. "grunt", "elite"). enemyInstanceId is the Mirror netId of the enemy. The server owns XP calculation from these values.

CombatSessionTracker.PostKill() handles the request when a CombatSessionTracker is available on the local player; EnemyController.DirectPostKill() is the fallback path.

PlayerProgressManager.ApplyKillReward() reads the server response. Updated servers return a canonical progression snapshot in data:

FieldNotes
xpGainedXP earned for this kill.
goldGainedGold earned for this kill.
levelCharacter level after the kill.
experienceTotal experience after the kill.
xpToNextXP required to reach the next level.
goldTotal gold after the kill.
leveledUpTrue when this kill triggered a level-up.

When data.level > 0, ApplyKillReward() immediately writes Level, Xp, XpToNext, and Gold from the snapshot, fires OnDataRefreshed, and fires OnLevelUp if the level increased โ€” without waiting for a subsequent Refresh() GET. Older servers that return only xpGained (top-level or data.xpGained) fall back to the previous Refresh() path.

On every kill reward response, ApplyKillReward() also calls InventoryBagUI.Refresh() to pull an updated inventory snapshot from the server, immediately reflecting any loot the auth server deposited into the character's inventory.

XpBar subscribes to OnXpGained and spawns a floating "+N XP" label per kill that animates upward and fades out over 1.5 seconds. Multiple rapid kills each receive their own label; labels stack vertically (offset by 24 px per concurrent label, capped at 7 stacked offsets).

Per-hit reporting

Each time a player deals damage to an enemy, the server calls EnemyController.ReportAuthenticatedHit(). This requires the attacker to have a reachable PlayerIdentity and NetworkConnectionToClient. The client receives a TargetRpc and POSTs to POST /api/combat/hit:

{ "characterId": <int>, "enemyLevel": <int>, "enemyCategory": "<string>", "enemyInstanceId": <uint>, "damageDealt": <float> }

The nearest-player aggro fallback does not trigger hit reporting โ€” only verified attacker identity does.

PVP combat

PvpCombatRules (static class) governs open-combat player-vs-player in the PVP zone (SceneNames.PvpZone = "PVPZONE").

Zone detection: IsPvpZone(context) returns true when the context object's scene is loaded and named "PVPZONE" (case-insensitive).

Target matching: Abilities authored with targetTag = "Enemy" automatically extend to players when both attacker and target are in the PVP zone scene. PvpCombatRules.MatchesTarget(attacker, hit, targetTag, out Health health) replaces direct tag checks in physics-hit paths so the existing ability system requires no per-ability changes.

Damage blocking: ShouldBlockPlayerDamage(source, target) returns true for player-on-player damage outside the PVP zone, providing a defense-in-depth gate for damage paths that bypass AbilityCaster targeting. Enemy and environmental damage are unaffected.

Deduplication: Dash slam damage uses a HashSet<Health> per swing to prevent the same target from being hit twice by one physics event, even after PVP targeting is considered.

Player damage is blocked everywhere except PVPZONE. A player cannot accidentally deal PVP damage in any other scene.

Character stat progression

CharacterStats is a NetworkBehaviour. The server applies account-owned level and primary stats at spawn via CharacterStats.SetProgressionStats() (called in RodNetworkManager when auth.fromDB is true). Stats sync to all clients via SyncVars and feed into CharacterStats.Recalculate() โ€” affecting damage multiplier, max health, max mana, and move speed. See Heroes & Classes for stat-to-class mappings.

Equipment stat bonuses are applied on top of progression stats as _equipmentStr/Agi/Int/Vit SyncVars. All scaling uses effective values (EffectiveStrength, etc.). See Loot, Inventory and Crafting.

CharacterStats.CombatBalanceVersion is a SyncVar that carries the server's loaded CombatBalance version integer to all clients. The CombatBalance static class reads versioned ability scaling rules from Resources/Combat/ability-scaling-v1.json and exposes them for damage resolution and tooltip display. See Ability Atlas and Synergies for the full rule table and per-ability bonuses.

XP persistence

PlayerProgressManager reads canonical XP totals from GET /character. The API field is experience (with a legacy xp fallback for older development responses). After each kill reward that does not include a full progression snapshot, ApplyKillReward() triggers a Refresh() to obtain the updated totals. A concurrent Refresh() call during an in-flight fetch is queued and fires once the fetch completes.

Shield system (Health.cs)

Health manages the active shield state. _shieldRemaining is a [SyncVar], so shield state is visible on all clients.

Applying a shield:

Health.TryApplyShield(float amount, float duration = 0) โ€” server-only. Applies the shield if amount > 0 and amount >= _shieldRemaining (does not apply if the existing shield is larger). Returns false and does nothing when either condition fails.

Health.ApplyShield(float amount, float duration = 0) โ€” calls TryApplyShield and discards the return value.

Health.GrowShield(float amount) โ€” adds to the current shield up to the 80-point cap, but only when a shield is already active. Has no effect when _shieldRemaining == 0.

Timed shields:

When duration > 0, the shield expires server-side when Time.time >= _shieldExpiry. A duration of 0 keeps the shield active until the absorb pool is depleted.

Floating number feedback:

All shield applications and growths emit a floating number using FloatingDamageText.DamageType.Shield. The broadcast goes through RpcShowShieldNumber on networked objects.

Absorb:

Incoming damage drains _shieldRemaining before reaching health. When the absorb pool is fully depleted, _shieldExpiry is cleared.

Public read access:

  • HasShield โ€” true when _shieldRemaining > 0.
  • ShieldRemaining โ€” current absorb pool.

Fall damage (Health.cs / PlayerFallDamage.cs)

Added 2026-09-18. Health.OnStartServer() attaches a PlayerFallDamage component to each spawned player. It is server-only (NetworkServer.active gate) and samples the player's position every FixedUpdate, using a downward raycast against the player's active physics scene (IsOnWalkableGround()) to detect landings โ€” the client never requests or reports fall damage itself.

Damage formula: on landing after at least 0.15 s airborne, PlayerFallDamage.CalculateDamage(fallDistance, maxHealth) = clamp01((fallDistance - 12) * 0.012) * maxHealth. The first 12 m of any fall are free; a 22 m fall costs 12% of max health. The result goes through the normal Health.TakeDamage() path, so shields, damage reduction, and downed-state rules above still apply.

False-positive safeguards: tracking resets via ResetTracking() on a large single-tick position jump (teleport detection), on respawn (Health.OnStartServer) and on every zone-transition teleport (ZoneManager calls it after each cross-zone move), while zoneTransitionProtected or downed, while touching a Water-tagged trigger, and while server-authorized GM flight (RodPlayerAuth.gmActive && gmFlyEnabled) is active.

Status: code-complete; Unity compilation and host/dedicated-server play testing (ordinary jumps, 12/22/40 m drops, water, slopes, moving platforms, zone portals, GM flight, latency) are still pending as of this writing. See _CONTEXT/FALL_DAMAGE.md in the repo for the full acceptance checklist. Because player movement itself remains client-authoritative, this is server-observed damage, not a complete anti-cheat guarantee โ€” full protection would need server-authoritative movement validation.

Projectile delivery

PlayerProjectile (Mirror NetworkBehaviour) is a server-authoritative skill-shot projectile fired by AbilityCaster.LaunchAbilityProjectile when an AbilityDef has launchProjectile = true.

Lifecycle:

  • Spawned on the server via NetworkServer.Spawn (or Instantiate in offline mode, detected by checking !NetworkClient.active && !NetworkServer.active).
  • Travels in its local forward direction at speed m/s every Update.
  • Expires after lifetime seconds (Invoke(SelfDestruct)) or when the distance from spawn origin exceeds maxRange.

Damage: On collision with an Enemy tag (or Player in the PVP zone via PvpCombatRules.MatchesTarget), the projectile resolves damage via CharacterStats.ApplyCriticalStrike(_damage, out wasCritical) on the source's CharacterStats component. Health.TakeDamage(finalDamage, source, wasCritical) is then called. If the hit reduced the target's health and the projectile carries a criticalCombustionBonus > 0, AbilityCaster.AwardCombustionFromDamage(criticalCombustionBonus, wasCritical) is called on the source โ€” the bonus doubles on a critical hit. Collisions with the owning player's root transform are ignored.

Non-trigger colliders (geometry) also trigger Impact(), stopping the projectile.

Impact VFX: When impactVFX is assigned on the prefab, an instance is spawned at the impact position; all child ParticleSystem components play automatically and the effect is destroyed after impactVFXLifetime seconds. On the server, RpcHitEffect replicates the VFX position to clients; the NetworkIdentity is kept alive for one frame via DestroyAfterRpcFlush so the RPC arrives before the destroy message.

Projectile prefabs are created with BCE โ–ถ Spell Forge โ–ถ Projectile Builder. See Ability Atlas and Synergies for AbilityDef projectile fields.


Related: Enemies, Waves & Bosses ยท Heroes & Classes ยท Loot, Inventory & Crafting ยท Zones, Scenes and Multi-Zone