中文版          English

---

HZP_Flashlight

基于 SwiftlyS2 的 CS2 手电筒插件。
支持人类/僵尸分组光效、自定义特感僵尸光效、按键与命令双入口、以及完整生命周期清理，适合直接用于上线服。

---

特别感谢 :

SwiftlyS2-Toolkit & agents By laoshi : (开源swiftlys2 Skills 和 agents)

SwiftlyS2-mdwiki By LynchMus : (开源swiftlys2 mdwiki)

---

如果你喜欢这个插件,可以用以下方式支持我,感谢!

If you like this plugin, you can support me in the following ways. Thank you!

---

功能概览

• 支持按 F 键直接切换手电筒。
• 同时注册命令 flashlight 与 forceflash（便于 bind 回退方案）。
• 普通玩家命令仅影响自己，不允许直接控制其他玩家。
• 提供独立管理员命令 flash，支持模糊名字匹配后强制控制目标玩家。
• 基于阵营应用不同光照配置：Human / Zombie。
• 支持 SpecialZombies 按僵尸职业名覆盖配置（对接 HanZombiePlague API）。
• 支持防抖时间窗口 ToggleDebounceMs，避免同一动作重复触发。
• 支持可见性策略：仅自己可见、或队友可见（VisibleToTeammates）。
• 支持机器人开关（AllowBots）。

效果说明

• 人类与僵尸可分别配置亮度、距离、颜色、阴影、FOV/锥角、挂点等参数。
• 实体使用 light_barn，lightcookie 为 materials/effects/lightcookies/flashlight.vtex。
• 默认挂点为 axis_of_intent，可在配置中改为其他骨骼挂点。

命令与按键

命令

• flashlight 仅当前发送者切换手电筒（不接收目标参数）。
• swiftly_flashlight_toggle 与 flashlight 相同，推荐用于按键绑定回退或机器人自控输入。
• flash <玩家名|playerId> [on|off|toggle] 管理员命令，支持模糊字符串匹配玩家名，默认动作为 on。 权限来源：AdminCommandPermission（支持用 , 分隔多个权限，命中任意一个即可） 示例：admin.dex 或 admin.dex,admin.other

推荐按键回退

如果你的服环境下 F 原始按键事件不稳定，可使用：

bind f swiftly_flashlight_toggle

生命周期行为（当前代码行为）

• 玩家断开：移除会话状态并销毁手电筒实体。
• 玩家死亡：立刻清除手电筒实体并关闭状态。
• 玩家重生：执行清理逻辑，确保不会遗留旧灯。
• 回合开始/结束：统一清除当前激活手电状态。
• 地图卸载 / 插件卸载：清理全部状态与实体。
• 僵尸感染事件（HanZombiePlague）：被感染玩家会立即关闭手电。

依赖关系

• 必需：SwiftlyS2 运行环境。
• 可选：HanZombiePlague 共享接口（存在时自动接入）。
• 未接入 HanZombiePlague 时：阵营识别将回退到队伍号判断（T/CT）。

配置文件

• 路径：configs/plugins/HZP_Flashlight/HZP_Flashlight.jsonc
• 根节点：HZP_FlashlightCFG

全局配置

字段	类型	说明
Enable	bool	插件总开关
AllowBots	bool	是否允许机器人使用
ToggleDebounceMs	int	切换防抖毫秒
AdminCommandPermission	string	管理员命令权限串，, 分隔多个权限（命中任意一个即通过）
Human	object	人类光照配置
Zombie	object	僵尸光照配置
SpecialZombies	array	特感僵尸覆盖配置

Profile 配置（Human/Zombie）

字段	类型	说明
Enable	bool	该阵营是否启用手电
Brightness	float	亮度
Distance	float	光照距离
AttachmentDistance	float	视角前推距离
FovOrConeAngle	float	光束角/视角参数
Shadows	bool	是否开启阴影
Attachment	string	挂点名称
ColorR/G/B/A	int	光照颜色
VisibleToTeammates	bool	是否给同阵营队友可见

SpecialZombies 项

• Name：需与僵尸职业名匹配（不区分大小写）。
• Enable：该覆盖项开关。
• 其余字段为可选覆盖值（如亮度、距离、颜色、可见性等）。

安装与使用

1. 将插件部署到服务器插件目录。
2. 确认 configs/plugins/HZP_Flashlight/HZP_Flashlight.jsonc 已按需配置。
3. 启动服务器并加载插件。
4. 进服按 F 或执行 flashlight 验证效果。

回归检查建议（上线前）

1. 连续快速按 F，确认防抖生效。
2. 玩家死亡后确认灯光实体被清除。
3. 回合开始/结束后确认无残留灯光。
4. 玩家断开后确认无孤儿实体。
5. 接入 HanZombiePlague 时，感染后确认手电立即关闭。
6. 分别验证 Human、Zombie、SpecialZombies 三类配置效果。