basegames/zeling_v2

Fork 0

Files

Joywayer f55d2a57c3 chore: initial commit

2026-05-08 11:04:00 +08:00

13 KiB

Raw Permalink Blame History

03 · 玩家系统规范

所属文档集 ← 返回索引
摘要：玩家实体的构成、资源模型、状态机规范与对外行为契约。
关联：04_CombatSystem · 05_MovementSystem · 06_FormSystem

1. 玩家实体构成

玩家实体是多个职责分离的子系统的协调器，自身不含具体业务逻辑：

PlayerEntity（协调器）
├── MovementController    ← 物理移动（速度、跳跃、冲刺）
├── StatContainer         ← 资源数值（HP、灵力、魄元、灵泉、Geo）
├── CombatHandler         ← 攻击判定（HitBox 开关、连击链）
├── FormController        ← 形态管理（天魂/地魂/命魂切换）
├── WeaponSlot            ← 当前武器（形态联动自动切换）
├── SkillExecutor         ← 技能执行（魂技能/魄技能）
├── ParryHandler          ← 弹反逻辑
├── HurtBox               ← 受击判定（路由 DamagePacket）
└── StateMachine          ← 行为状态机（协调上述子系统）

协调器原则：PlayerEntity 只负责：

初始化子系统并维护引用
维护状态机（决定当前行为）
在受击时强制转换到受击状态
在死亡时触发 OnPlayerDied 事件

2. 资源模型

2.1 资源总览

资源	类型	范围	特性	用途
HP	Integer	0 ~ MaxHP	受击减少，存档点/灵泉恢复	生存指标
灵力（SoulPower）	Integer	0 ~ 100	近战命中积累，死亡清零	魂技能燃料
魄元（SpiritPower）	Integer	0 ~ 100	时间自动恢复，死亡恢复至上限	魄技能燃料
灵泉次数（SpringCharges）	Integer	0 ~ MaxCharges	击杀积分驱动，存档点恢复	治疗次数
Geo（灵晶）	Integer	0 ~ ∞	击败敌人获得，死亡遗留遗骸	货币

2.2 灵力积累规则

设计目标：鼓励玩家主动攻击，弹反作为高回报行为

来源	灵力增量
近战命中普通敌人	+10
近战命中 Boss	+5
弹反成功	+33

死亡时归零
无自动恢复

2.3 魄元恢复规则

设计目标：魄元是始终可用的"持续消耗"资源，不依赖风险操作

来源	魄元增量
每秒自动恢复	+`spiritRegenRate`（见配置参数）
死亡复活	恢复至上限
存档点交互	恢复至上限

受伤不影响魄元
使用魄技能后扣除固定量

2.4 灵泉次数规则

设计目标：治疗是"击杀驱动"而非"时间驱动"，鼓励激进战斗风格

来源	变化
击杀普通敌人	+1 积分
击杀精英怪	+3 积分
击杀 Boss	+5 积分
积分达到阈值	+1 次灵泉（积分清零）
使用灵泉（治疗）	-1 次
与存档点交互	恢复至上限
死亡复活	不恢复（死亡惩罚）

设计决策：死亡不恢复灵泉
原因：保留一定死亡惩罚，让玩家珍惜治疗机会，但由于复活在存档点旁，玩家仍可快速通过激活存档点补满

2.5 Geo（货币）规则

来源	变化
击败敌人	掉落固定 + 随机范围
破坏场景容器	少量固定
任务奖励	固定量
死亡	Geo 留在遗骸，不直接丢失
取回遗骸	遗骸的 Geo 归还玩家
再次死亡（未取回遗骸）	遗骸 Geo 永久丢失

3. 玩家状态机

3.1 状态优先级

优先级	状态	说明
100	`DeathState`	死亡，不可被任何状态打断
90	`HurtState`	受击硬直，仅死亡可打断
80	`DashState`	冲刺（含空中冲刺），受伤/死亡可打断
75	`SoulSkillState`	魂技能前摇，冲刺/受伤可打断
72	`SpiritSkillState`	魄技能前摇，冲刺/受伤可打断
70	`ParryState`	弹反等待，受伤可打断
60	`AttackState`	攻击，弹反/受伤可打断
55	`SpringState`	使用灵泉，前摇可被打断
40	`InteractState`	与 NPC/物件交互
35	`WallGrabState`	抓墙悬挂，冲刺/技能可打断
30	`AirState`	空中（含跳跃/下落）
20	`RunState`	地面奔跑
10	`SwimState`	游泳（解锁后）
0	`IdleState`	待机（最低优先级）

3.2 状态转换规则

任意状态
  ══受击(HP>0)══►  HurtState      [强制，忽略优先级]
  ══受击(HP=0)══►  DeathState     [强制，不可被打断]

IdleState
  ──移动输入──────────►  RunState
  ──跳跃输入──────────►  AirState
  ──攻击输入──────────►  AttackState
  ──弹反输入──────────►  ParryState
  ──冲刺输入──────────►  DashState
  ──魂技能+灵力充足───►  SoulSkillState
  ──魄技能+魄元充足───►  SpiritSkillState
  ──使用灵泉+次数≥1──►  SpringState
  ──交互输入+目标存在─►  InteractState

RunState
  ──无移动输入─────────►  IdleState
  ──跳跃输入───────────►  AirState
  ──攻击输入───────────►  AttackState（保持RunState，上半身叠加）
  ──弹反/冲刺/技能─────►  对应状态

AirState（统一处理 跳跃/双跳/下落）
  ──落地───────────────►  IdleState 或 RunState
  ──跳跃输入+双跳可用──►  AirState内重置（双跳，不切状态）
  ──贴墙+朝墙方向输入──►  WallGrabState
  ──攻击/弹反/冲刺─────►  对应状态

WallGrabState
  ──跳跃输入───────────►  AirState（蹬墙跳）
  ──反向输入或落地─────►  AirState / IdleState
  ──冲刺/技能──────────►  对应状态

AttackState（上半身叠加，下半身保持原状态）
  ~~动画结束~~──────────►  恢复原状态（Idle/Run/Air）
  ──连击窗口内攻击输入─►  AttackState（切换连击段）
  ──弹反输入───────────►  ParryState

ParryState
  ──弹反成功───────────►  ParrySuccessState（反击窗口）
    ──攻击输入（窗口内）─►  AttackState（ParryCounter）
    ~~反击窗口超时~~─────►  IdleState/RunState
  ~~弹反超时~~──────────►  IdleState/RunState

DashState
  ~~冲刺时长结束~~────── ►  AirState 或 IdleState/RunState

SpringState
  ~~前摇完成~~──────────►  后摇 → IdleState
  ──被打断─────────────►  IdleState（灵泉次数已扣，不返还）

HurtState
  ~~硬直时长结束~~──────►  IdleState

DeathState
  （等待游戏管理器触发复活流程）

3.3 攻击连击链

连击段	触发方式	攻击方向	伤害倍率	备注
`Attack1`	第一次攻击输入	水平	×1.0	各形态动画不同
`Attack2`	连击窗口内再攻击	水平	×1.0
`Attack3`	连击窗口内再攻击	水平	×2.0	重击，连击链结尾
`AirAttack`	空中攻击	水平	×1.0
`UpAttack`	移动方向向上时攻击	向上	×1.0	角色轻微下移（反作用力）
`DownAttack`	空中+移动方向向下时攻击	向下	×1.0	命中时产生弹起（Pogo）
`ParryCounter`	弹反成功后攻击	水平	×3.0	不可被弹反，忽略无敌帧

设计决策：第三击伤害 ×2，弹反反击 ×3
原因：鼓励打满连击，奖励弹反技巧。高倍率使玩家有显著的策略目标。

4. 行为契约

4.1 玩家实体对外接口

Interface IPlayerEntity {
    // 只读属性
    [readonly] position        : Vector2
    [readonly] facingDirection : Integer    // +1 右 / -1 左
    [readonly] currentState    : StateID
    [readonly] isInvincible    : Boolean

    // 强制状态切换（外部系统使用，如受击）
    forceState(stateId: StateID, context: Optional<StateContext>) → void

    // 查询
    hasAbility(abilityId: ID) → Boolean

    // 事件
    [event] onDied         : Event<void>
    [event] onHit          : Event<HitPayload>
    [event] onStateChanged : Event<StateChangedPayload>
}

4.2 StatContainer 对外接口

Interface IStatContainer {
    [readonly] currentHP           : Integer
    [readonly] maxHP               : Integer
    [readonly] currentSoulPower    : Integer
    [readonly] currentSpiritPower  : Integer
    [readonly] currentSpringCharges: Integer
    [readonly] maxSpringCharges    : Integer
    [readonly] currentGeo          : Integer
    [readonly] isAlive             : Boolean

    takeDamage(amount: Integer)           → void
    heal(amount: Integer)                 → void
    addSoulPower(amount: Integer)         → void
    consumeSoulPower(amount: Integer)     → Result<Boolean>
    consumeSpiritPower(amount: Integer)   → Result<Boolean>
    addKillCredit(creditType: KillType)   → void    // 驱动灵泉积分
    useSpring()                           → Result<Boolean>
    restoreSpringCharges()                → void
    addGeo(amount: Integer)               → void
    spendGeo(amount: Integer)             → Result<Boolean>
    beginInvincibility(duration: Duration)→ void

    [event] onHPChanged            : Event<{current, max}>
    [event] onSoulPowerChanged     : Event<{current, max}>
    [event] onSpiritPowerChanged   : Event<{current, max}>
    [event] onSpringChargesChanged : Event<{current, max}>
    [event] onGeoChanged           : Event<{current, delta}>
    [event] onDied                 : Event<void>
}

5. 能力解锁体系

5.1 能力定义

能力 ID	默认状态	影响的状态/行为	解锁位置
`DoubleJump`	锁定	AirState 允许第二次跳跃	探索奖励
`WallGrab`	已解锁	AirState → WallGrabState 允许	初始能力
`AerialDash`	锁定	AirState → DashState 允许（消耗充能）	探索奖励
`Parry`	已解锁	ParryState 可进入	初始能力
`Swim`	锁定	液体区域不死亡，SwimState 可进入	主线解锁
`PlungeAttack`	锁定	空中向下冲刺触发下冲	探索奖励

5.2 解锁流程

玩家触碰解锁物件（AbilityUnlockItem）
  → 世界系统发出 OnCollectiblePickedUp（type=Ability, abilityId）
  → 进程系统处理：将 abilityId 加入已解锁集合
  → 进程系统发出 OnAbilityUnlocked（abilityId）
  → 玩家系统接收：更新运行时能力标记
  → UI 系统显示能力获得动画
  → 存档系统：在下次存档时持久化

6. 玩家配置参数

以下参数在配置数据中定义，运行时只读：

参数	类型	推荐值	说明
`maxHP`	Integer	5	初始最大生命值
`maxSoulPower`	Integer	100	灵力上限
`maxSpiritPower`	Integer	100	魄元上限
`spiritRegenRate`	Number	8.0/s	魄元每秒自动回复量
`maxSpringCharges`	Integer	3	初始最大灵泉次数
`springKillThreshold`	Integer	5	增加 1 次灵泉所需积分
`iFrameAfterHit`	Duration	1.2s	受击后无敌时长
`comboWindowDuration`	Duration	0.5s	连击窗口时长
`comboResetDelay`	Duration	0.3s	第三击后连击重置延迟
`parryCounterDuration`	Duration	0.6s	弹反后反击窗口时长

7. 发出的事件

事件	触发时机	载荷
`OnPlayerDied`	HP 归零	`void`
`OnHPChanged`	HP 任意变化	`{current, max}`
`OnSoulPowerChanged`	灵力变化	`{current, max}`
`OnSpiritPowerChanged`	魄元变化	`{current, max}`
`OnSpringChargesChanged`	灵泉次数变化	`{current, max}`
`OnGeoChanged`	Geo 增减	`{current, delta}`
`OnFormChanged`	形态切换	`{newFormId}`
`OnParrySuccess`	弹反成功	`{counterWindowDuration}`
`OnHitConfirmed`	攻击命中有效目标	`HitPayload`
`OnAbilityUnlocked`	新能力获得	`{abilityId}`

13 KiB Raw Permalink Blame History Unescape Escape

03 · 玩家系统规范

目录

1. 玩家实体构成

2. 资源模型

2.1 资源总览

2.2 灵力积累规则

2.3 魄元恢复规则

2.4 灵泉次数规则

2.5 Geo（货币）规则

3. 玩家状态机

3.1 状态优先级

3.2 状态转换规则

3.3 攻击连击链

4. 行为契约

4.1 玩家实体对外接口

4.2 StatContainer 对外接口

5. 能力解锁体系

5.1 能力定义

5.2 解锁流程

6. 玩家配置参数

7. 发出的事件

13 KiB

Raw Permalink Blame History