Echo/Assets/_Project/Docs/PlayerControlLock_Technical_Reference.md

玩家控制锁（PlayerControlLockService）技术说明

目标：当 UI 打开时（设置/暂停/平板等），统一锁定玩家移动/互动并显示鼠标；关闭 UI 时恢复到打开前状态。

一、脚本

• PlayerControlLockService.cs

二、设计要点

• 以“owner 计数/集合”的方式实现可重入：
  • 多个 UI 同时打开时，不会互相覆盖
  • 只有当最后一个 owner 解锁时才真正恢复输入
• 缓存并恢复组件 enabled 状态：
  • 锁定时记录目标组件原始 enabled 值
  • 解锁时按缓存逐个恢复，避免把原本就禁用的组件错误打开

三、锁定时做的事情（当前实现）

• 禁用（若存在）：
  • Player.PlayerController
  • ItemUsageSystem
  • InventoryUI
• 复位输入缓存：
  • 锁定与解锁时会清空 PlayerController 的 Move/Look 缓存，避免 UI 关闭后出现“卡住上一帧输入”的粘滞移动/转向
• 光标：
  • Cursor.lockState = None
  • Cursor.visible = true

四、解锁时做的事情（当前实现）

• 恢复上述组件到锁定前的 enabled 状态
• 光标：
  • Cursor.lockState = Locked
  • Cursor.visible = false

五、调用接口

• PlayerControlLockService.Instance.Lock(object owner)
• PlayerControlLockService.Instance.Unlock(object owner)
• PlayerControlLockService.Instance.IsLocked()

六、项目内接入点

• 暂停菜单打开/关闭：
  • InGamePauseMenuController.cs
• AI 平板打开/关闭：
  • TabletController.cs
• 自动创建（DontDestroyOnLoad）：
  • SettingsBootstrap.cs