Vampire-Act-Mono/design/gdd/blood-energy-economy.md

Blood Energy Economy

Status: In Design Author: SepComet + Claude Last Updated: 2026-04-27 Implements Pillar: 操作优于数值 (Skill Over Stats), 切换即承诺 (Switch is Commitment)

Overview

Blood Energy Economy 是夜裔的核心资源系统——管理玩家用于切换形态的"血能"资源。血能通过攻击敌人和承受伤害两种方式获取，仅用于支付形态切换的消耗。它不是"攒大招"的能量槽，而是一个强制性的战术节奏控制器：你必须在前线积极战斗来赚取血能，然后在正确的时机消费它来切换形态。没有血能系统，形态切换退化为"CD好了就切"，失去"切换即承诺"的战术重量。

Player Fantasy

此系统是纯基础设施——玩家感知的是它赋能的操作（切形态），而非血能数字本身。不展开独立幻想章节。

Detailed Design

Core Rules

1. Blood Energy Gain

Blood energy is earned through aggressive play:

• Attack Hit: baseAttackGain × enemyTypeMultiplier per hit
• Enemy Kill: baseKillGain × enemyTypeMultiplier per kill
• Taking Damage: baseHurtGain × (damageTaken / maxHealth) — compensation ensures the player is never fully locked out of switching
• Wave Clear: fixedBonus × waveNumber — reward for completing a wave

2. Blood Energy Spending

Blood energy has exactly one use: form switching.

• Switch Cost: baseSwitchCost × (1.0 - skillDiscount)
• Interrupted Switch: Blood energy is consumed on switch request (at Windup start). If the switch is interrupted, the energy is NOT refunded. This is the core punishment for switching at the wrong time.

3. Constraints

Rule	Value
Valid range	[0.0, maxEnergy]
Initial value (game start)	0
On death	Reset to 0
Maximum value	baseMax × (1.0 + upgradeBonus)
Cannot exceed max	Add() clamps to max
Cannot go below 0	Spend() returns false if insufficient

States and Transitions

Blood Energy Economy has no complex states — it is a single float value with three meaningful thresholds:

Threshold	Event	Significance
Current == 0	OnEnergyEmpty	Player is locked out of switching — must attack or take damage
Current >= switchCost	(check via CanSpend())	Switching is possible
Current == Max	OnEnergyFull	Further gains are wasted — signals "you should switch now"

Every value change fires OnEnergyChanged(current, max) for HUD/L1 consumption.

Interactions with Other Systems

System	Direction	Interface
Form Switch SM	Consumes	Calls CanSpend(cost) before switching, Spend(cost) on switch start
HUD (L2)	Reads	Subscribes to OnEnergyChanged for display
Skill Tree	Modifies	Can set GainRate, baseSwitchCost, baseMax, skillDiscount
Death/Respawn	Resets	Calls Reset() on player death

Formulas

Attack Gain

energyGain_attack = baseAttackGain × enemyTypeMultiplier

Variable	Symbol	Type	Range	Description
Base attack gain	baseAttackGain	float	2–8	Energy gained per hit
Enemy type multiplier	enemyTypeMultiplier	float	0.5–2.0	Riskier enemies reward more

Output: 1–16 per hit | Extreme: Swarm enemies low (0.5x), Brute/Stalker high (1.5–2.0x)

Kill Gain

energyGain_kill = baseKillGain × enemyTypeMultiplier

Variable	Symbol	Type	Range	Description
Base kill gain	baseKillGain	float	10–25	Kill reward significantly higher than hit
Enemy type multiplier	enemyTypeMultiplier	float	0.5–2.0	Same as attack formula

Output: 5–50 | Example: Brute kill (2.0x) = 25 × 2.0 = 50 energy

Hurt Gain

energyGain_hurt = baseHurtGain × (damageTaken / maxHealth)

Variable	Symbol	Type	Range	Description
Base hurt gain	baseHurtGain	float	8–20	Compensation to prevent deadlock
Damage ratio	damageTaken / maxHealth	float	0.0–1.0	Bigger hits give more energy

Intent: Ensures pressured players can earn a switch-out resource.

Switch Cost

switchCost = baseSwitchCost × (1.0 - skillDiscount)

Variable	Symbol	Type	Range	Description
Base switch cost	baseSwitchCost	float	25–60	~5-12 attack hits to earn one switch (at default ratio ≈8)
Skill discount	skillDiscount	float	0.0–0.4	Skill Tree cost reduction

Output: 18–50 | Example: baseSwitchCost=40, no discount → cost=40

Wave Clear Bonus

waveClearBonus = min(fixedBonus × waveNumber, 2 × fixedBonus)

Variable	Symbol	Type	Range	Description
Fixed bonus	fixedBonus	float	20–40	Base reward per cleared wave
Wave number	waveNumber	int	1–N	Caps at 2× fixedBonus to prevent late-wave overflow

Output: 20–80 | Cap ensures wave bonuses don't exceed ~80% of maxEnergy in one reward

Max Energy

maxEnergy = baseMax × (1.0 + upgradeBonus)

Variable	Symbol	Type	Range	Description
Base max	baseMax	float	80–150	Initial energy cap (default 100)
Upgrade bonus	upgradeBonus	float	0.0–0.5	Skill Tree capacity growth

Output: 100–150

Edge Cases

#	Condition	Resolution	Rationale
1	Add() would exceed MaxEnergy	Clamp to Max, fire OnEnergyFull	Overflow waste — incentivizes spending before full
2	Spend() amount exceeds current	Return false, no side effects, no events	Silent failure — UI should prevent this via CanSpend
3	Add() called while dead	Ignore, return immediately	Dead players don't accumulate resources
4	Switch interrupted (Interrupt())	Energy NOT refunded — deducted at Windup start	Core punishment of "Switch is Commitment"
5	skillDiscount pushes cost near 0	Enforce minimum cost of 1.0	Switching always has a cost
6	Simultaneous Gain and Spend in same frame	Process Gains first, then Spends	Kill reward can enable immediate switch
7	Wave bonus causes overflow	Clamp to Max (same as #1)	Incentivize spending before wave end
8	skillTree undo reduces maxEnergy below current	Force current = min(current, newMax)	Cannot hold more than new cap

Dependencies

System	Relationship	Data Flow
Form Switch SM	Downstream consumer	Calls CanSpend() / Spend()
HUD (L2)	Downstream display	Subscribes to OnEnergyChanged
Skill Tree	Upstream modifier	Sets GainRate, baseMax, skillDiscount
Death/Respawn	Upstream reset	Calls Reset()

No upstream dependencies — this is a Foundation layer system.

Tuning Knobs

Parameter	Default	Safe Range	Too Low	Too High
baseAttackGain	5	2–8	Switching too slow, stuck in one form	Switching too frequent, no tactical weight
baseKillGain	20	10–30	Kills not worth prioritizing	Kill-chasing replaces form strategy
baseHurtGain	12	8–20	Being pressured = no comeback	Deliberate self-damage becomes optimal
baseSwitchCost	40	25–60	Switching has almost no threshold	Gap too long, player afraid to switch
baseMax	100	80–150	Energy always capped → waste anxiety	Decision window too large → no urgency
fixedBonus	30	20–40	Wave bonus imperceptible	Between-wave switching too lenient

Key tuning pair: baseSwitchCost / baseAttackGain ≈ 8 — roughly 8 attack hits to earn one switch. This ratio defines the core combat rhythm.

Visual/Audio Requirements

This system has no direct visual output. Its presentation is via:

• HUD (L2): Blood energy bar with fill animation, drain animation on switch, color flash on value change
• VFX Spawner (L1): Brief player glow on OnEnergyFull — visual cue "switch now"
• Audio Player (L1): Warning sound on OnEnergyEmpty — audio cue "cannot switch"

UI Requirements

Element	Position	Content
Blood Energy Bar	HUD bottom/side	Amber Gold gradient, fill ratio current / max
Form Switch Buttons	HUD corner	One per form: grey = insufficient energy, bright = can switch, highlighted = current
Full Energy Indicator	Next to bar	Pulse effect when OnEnergyFull fires

Acceptance Criteria

#	GIVEN	WHEN	THEN
1	Blood energy is 0	Player attacks and hits an enemy	Energy increases by baseAttackGain × enemyTypeMultiplier
2	Blood energy is 50, cost is 40	Player requests a form switch	CanSpend(40) returns true, Spend(40) succeeds, energy = 10
3	Blood energy is 10, cost is 40	Player requests a form switch	CanSpend(40) returns false, Spend(40) returns false, energy stays 10
4	Blood energy is 95, gain is 10	Player gains energy	Energy becomes 100 (clamped), OnEnergyFull fires
5	Energy was 60, 40 deducted on switch	Player is hit during Windup	Switch interrupted, energy stays at 20 (deducted cost not refunded, remainder preserved)
6	Player dies	Reset() called	Energy becomes 0
7	Energy reaches 0	Any cause	OnEnergyEmpty fires
8	skillDiscount=0.4, baseSwitchCost=40	Player switches	Cost = 24, energy decreased by 24
9	Energy changes (any cause)	Per frame or event	OnEnergyChanged(current, max) fires with correct values
10	baseMax changed from 100 to 50, current is 80	Skill tree update	Current clamps to 50
11	skillDiscount set to 1.0, baseSwitchCost = 40	Player requests switch	Cost = max(40 × 0.0, 1.0) = 1.0 (minimum cost enforced)
12	Player is dead, Add(10) called	Energy gain event	Gain ignored, energy unchanged

Open Questions

• Final baseSwitchCost value (recommended 40) needs prototype validation — actual game feel will determine the right "attacks-per-switch" rhythm
• Should there be a "low health → increased energy gain" comeback mechanic? Currently handled by hurt gain; revisit if playtest shows deadlock issues in low-health situations