传奇ZS 插件使用说明

插件目录：plugins/ZsChuanqi

插件标识：ZsChuanqi 作者：kuakeba.cn 版本：1.1.0

适用框架：Zsens Admin（ThinkPHP 6 风格）

一、插件简介

「传奇ZS」是一款经典传奇风格的网页挂机小游戏，支持战士 / 法师 / 道士三职业，包含打怪升级、装备掉落与强化、技能修炼、地图解锁、每日任务、成就、异步竞技场、排行榜、社区金币兑换、世界频道与 AI 随机奇遇等玩法。

1.1.0 版本新增（借鉴经典文字传奇玩法，独立实现）：

• 游戏难度后端可配置：简单 / 普通 / 困难 / 噩梦四档预设，也可切换自定义倍率，统一影响怪物血量、攻防、经验、金币、掉落、首领强度、升级经验、死亡惩罚与复活费用；
• 修真系统：修炼积累修为、四维加点、十大境界突破、修真塔爬塔；
• 灵兽宠物：捕捉、出战、培养、合宠升品、放生，出战后提供属性加成并概率协同出手；
• 法宝系统：领取本命法宝、升级、升段，战斗中概率触发被动伤害，首领与世界BOSS可掉落；
• 世界BOSS：全服共享血量、伤害榜、击杀结算与定时刷新，支持全服播报；
• 活动中心：每日签到（连续签到加成）、活动积分、积分商城与积分流水。

1.0.0 版本已具备：

• 后台完整的战斗 / 经济 / 竞技场 / 世界频道 / AI 配置项，并且全部真实生效；
• 世界频道（玩家实时发言 + 系统全服播报）；
• AI 生成的战斗奇遇文案（无 Key 或失败时自动回退本地随机文案）；
• 游戏公告、页头背景图、休息冷却可配置。

二、安装与卸载

2.1 安装

1. 将 ZsChuanqi 文件夹放入站点根目录的 plugins/ 下；
2. 进入后台 → 插件市场 / 插件管理 → 找到「传奇ZS」→ 点击安装；
3. 安装时会自动完成：

  - 复制静态资源到 public/static/ZsChuanqi（样式 cq.css、上传目录 uploads/）；

  - 执行 install.sql 建表（表名自动加站点前缀，默认 zsens_）；

  - 补齐旧库缺失字段（ensureLegacyColumns）；

  - 写入默认技能、怪物、装备、掉落数据，并初始化世界BOSS「赤月恶魔」；

  - 注册后台菜单「传奇ZS → /admin/cq」及权限规则。

1. 前台入口：/cq，会按登录状态自动跳转到 /cq/home 或 /cq/create。

2.2 卸载

后台插件管理点击卸载，会删除静态资源、后台菜单与全部 cq* 数据表（含 cqshout、cqcultivation、cqpet、cqtreasure、cqworldboss、cqworldbossdamage、cqsignlog、cqpointslog）。

卸载会清空玩家数据，请先备份。

2.3 老版本升级

若之前安装过旧版本，访问任意游戏页面会自动执行 ensureSchema()：

• 检测缺失的数据表（如 cqplayertask、cqshout、cqcultivation、cqpet、cqtreasure、cqworldboss 等）并补建；
• 检测 cqplayer 缺失字段（战力、竞技场、休息时间、活动积分 points、签到 signday/signstreak、世界BOSS冷却 lastboss_time）并补列；
• 补建后自动补齐默认数据（含世界BOSS），无需手动重装。

三、目录结构

plugins/ZsChuanqi/
├── plugin.json              插件元信息
├── ZsChuanqiPlugin.php      插件入口（配置、安装、卸载、菜单）
├── install.sql              建表脚本（22 张 cq_* 表）
├── routes.php               前台 / 后台路由
├── controller/              控制器
│   ├── GameBase.php         前台基类（统一渲染与玩家解析）
│   ├── Index.php            入口 / 主页 / 创建角色
│   ├── Battle.php           攻击 / 挂机 / 休息 / 复活 / 地图 / 日志
│   ├── Bag.php              背包 / 装备 / 强化
│   ├── Skill.php            技能学习与升级
│   ├── Quest.php            每日任务
│   ├── Achievement.php      成就
│   ├── Arena.php            竞技场
│   ├── Shop.php             商店
│   ├── Rank.php             排行榜
│   ├── Exchange.php         社区金币兑换
│   ├── Shout.php            世界频道
│   ├── Cultivation.php      修真 / 加点 / 突破 / 修真塔
│   ├── Pet.php              灵兽捕捉 / 出战 / 培养 / 合宠 / 放生
│   ├── Treasure.php         法宝领取 / 升级 / 升段
│   ├── Boss.php             世界BOSS
│   ├── Activity.php         活动签到 / 积分商城
│   └── admin/               后台管理（设置 / 玩家 / 怪物 / 装备）
├── model/                   数据模型
├── service/                 业务服务
│   ├── BattleService.php    战斗核心（难度、倍率、掉落、奇遇、播报）
│   ├── DifficultyService.php 难度预设与倍率换算
│   ├── CultivationService.php 修真境界、加点、修真塔
│   ├── PetService.php       灵兽属性、合宠与协同出手
│   ├── TreasureService.php  法宝属性与被动触发
│   ├── WorldBossService.php 世界BOSS血量、伤害榜与结算
│   ├── ActivityService.php  签到、积分与积分商城
│   ├── ArenaService.php     竞技场（次数与积分配置）
│   ├── EnhanceService.php   装备强化（+8 播报）
│   ├── AiService.php        AI 奇遇文案
│   ├── ShoutService.php     世界频道服务
│   └── ...                  装备、地图、任务、技能等服务
├── view/
│   ├── front/               前台模板（home / world / bag / ...）
│   └── admin/               后台模板
└── static/                  源样式（安装时复制到 public/static/ZsChuanqi）

四、前台页面与入口

五、玩法说明

5.1 战斗

• 点击怪物「攻击」触发一次战斗，最多 30 回合，按攻击 / 防御 / 暴击 / 闪避计算伤害；
• 已学技能每回合有 40% 概率释放，消耗魔法并提升伤害倍率；
• 怪物属性按当前难度倍率换算，列表与战斗结果一致；
• 胜利获得经验与金币，怪物按概率掉落装备；失败按后台「死亡金币/经验惩罚」扣减并生命归零；
• 生命归零后需点击「复活」并消耗配置的金币（默认 50，0 为免费）才能继续战斗；
• 每场战斗后自动恢复 10% 生命与魔法；
• 「休息恢复」可立即回满生命与魔法，冷却时间由后台配置（默认 60 秒）；
• 手动战斗会播放约 1.2 秒的「遭遇战」过渡动画，点击、Esc 或空格可跳过；挂机不播放。

5.2 地图解锁

• 地图按顺序解锁，击败当前地图的首领后可解锁下一张；
• 地图列表：新手村 → 比奇省 → 蜈蚣洞 → 野猪洞 → 毒蛇谷 → 石墓阵；
• 首领首次被击败时会在世界频道发布全服播报。

5.3 装备与强化

• 装备分武器 / 头盔 / 衣服 / 腰带 / 裤子 / 靴子 / 项链 / 戒指 / 手镯 9 个部位；
• 品质：普通、优秀、稀有、史诗、传说；
• 强化上限 +15，只消耗金币，失败不掉级、不损坏；
• 强化到 +8 及以上成功时，会在世界频道发布全服播报；
• 强化到 +N 需要角色等级 ≥ 2N。

5.4 技能

• 每个职业 3 个技能，按等级解锁；
• 可消耗金币学习与升级，技能等级每 +1 提升 10% 伤害倍率。

5.5 每日任务与成就

• 每日任务 5 项（击杀、首领、强化、竞技场、兑换等），完成后可领取金币与经验；
• 成就 11 项，达成后自动解锁并发放金币奖励。

5.6 竞技场（异步 PVP）

• 挑战其他玩家的属性快照，等级相近优先匹配；
• 每日挑战次数、胜利积分、失败扣分均可在后台配置；
• 20 回合未分胜负时按剩余血量比例判定；
• 积分不会低于 0。

5.7 社区金币兑换

• 玩家可用社区金币兑换游戏金币，比例、单次下限、每日上限均可配置；
• 兑换使用数据库事务，保证扣款、到账与日志一致；
• 每日上限按「社区金币消耗量」统计，0 表示不限制。

5.8 世界频道（新增）

• 位于游戏主页底部，每 10 秒自动刷新，也可按回车立即发送；
• 玩家发言受「最大字数」与「冷却时间」限制，冷却内无法重复发送；
• 系统播报：首领首杀、强化 +8 及以上成功；
• 频道关闭后前台不再显示面板，接口也会拒绝发言；
• 消息按时间正序展示，显示「刚刚 / N 分钟前 / 时间」的相对时间。

5.9 战斗奇遇（新增）

• 战斗胜利后按「奇遇触发概率」随机触发；
• 奇遇会额外奖励金币与经验，并展示一段文案；
• 开启 AI 后文案由 AI 实时生成；AI 关闭、未配置 Key、请求失败或超时时，自动使用本地随机文案池（8 条）。

5.10 修真

• 修炼消耗金币获得修为，修为可用于四维加点（攻击 20 / 防御 20 / 生命 10 / 魔法 10 修为 = 1 点）；
• 境界共 10 级：凡人 → 炼气期 → 筑基期 → 金丹期 → 元婴期 → 化神期 → 炼虚期 → 合体期 → 大乘期 → 渡劫期；
• 突破需要满足等级、累计修为与金币条件，突破后每境界额外提供百分比全属性加成（默认 5%/境界）；
• 修真塔每日可挑战固定次数，层数越高守塔者越强，奖励金币、修为与活动积分，每 10 层全服播报；
• 修真、宠物、法宝加成统一并入 EquipmentService::getTotalStats()，战斗、竞技场与页面显示一致。

5.11 灵兽宠物

• 消耗金币捕捉灵兽，品质分普通 / 优秀 / 稀有 / 史诗 / 传说，首只自动出战；
• 出战灵兽按品质与等级提供攻击、防御与生命加成，并有概率在战斗中协同出手；
• 培养消耗金币提升等级（上限 60 级）；合宠需两只灵兽均达到 10 级，副宠品质越高升品概率越高；
• 放生返还部分金币；携带上限、捕捉费用均可在后台配置。

5.12 法宝

• 首批法宝免费领取，类型分攻击 / 防御 / 生命三类；
• 消耗金币升级与升段（最高 6 段），等级与段位共同提升属性；
• 战斗中按触发概率对怪物追加被动伤害；
• 击败地图首领有 20% 概率掉落随机法宝，击杀世界BOSS也有机会获得。

5.13 世界BOSS

• 全服共享同一只 BOSS 的血量，玩家攻击按 2 秒冷却（可配置）；
• 攻击造成伤害并受到反击（反击伤害上限为玩家最大生命的 15%）；
• BOSS 被击杀后按伤害榜前 10 名发放金币、活动积分与元宝，击杀者额外有 25% 概率获得法宝；
• BOSS 死亡后进入冷却，到点自动满血刷新，并同步后台配置的血量 / 攻防；
• 击杀与刷新会通过世界频道全服播报。

5.14 活动中心

• 每日签到获得基础积分（默认 10），连续签到每天额外 +2，最多 +14；
• 修真塔、世界BOSS伤害榜也会发放活动积分；
• 积分商城可兑换游戏金币、元宝与修为，所有变动写入积分流水（cqpointslog）；
• 签到记录按「玩家 + 日期」唯一，避免重复领取。

六、后台设置说明

后台路径：/admin/cq/settings（「传奇ZS → 游戏设置」）。

6.1 基础设置

6.2 社区金币兑换

6.3 战斗与经济（新增）

6.4 竞技场（新增）

6.5 世界频道（新增）

6.6 AI 文案（新增）

6.7 游戏难度（新增）

四档预设的倍率：

6.8 修真与修真塔（新增）

6.9 宠物与法宝（新增）

6.10 世界BOSS（新增）

6.11 活动与签到（新增）

七、AI 接入指南

插件调用的是 OpenAI 兼容的 /chat/completions 接口，只需填写根地址、Key 与模型名。

7.1 OpenAI

接口地址：https://api.openai.com/v1
模型：    gpt-4o-mini（或 gpt-4.1-mini 等）
API Key： sk-xxxxxxxx

7.2 DeepSeek

接口地址：https://api.deepseek.com/v1
模型：    deepseek-chat
API Key： sk-xxxxxxxx

7.3 本地 / 自建兼容服务

接口地址：http://127.0.0.1:8000/v1
模型：    按服务实际模型名填写
API Key： 服务要求时填写

7.4 行为说明

• AI 只负责生成「奇遇文案」，奖励数值始终由本地随机计算，避免通过 AI 影响经济平衡；
• 请求参数：temperature=1.1、max_tokens=160，系统提示限定为一句不超过 60 字的中文；
• 返回文案会去标签、去换行、截断到 120 字，并移除 4 字节字符（兼容 utf8 连接）；
• 任何异常（无 Key、HTTP 非 200、超时、解析失败、未安装 curl）都会自动回退本地文案，不会影响战斗流程；
• 建议超时 5-8 秒；AI 同步调用会略微增加战斗响应时间，必要时可关闭 AI 或降低奇遇概率。

安全提示：Key 仅保存在后台配置中，前台接口不会输出；请勿将后台账号交由不可信人员使用。

八、数据库表

所有表名带站点前缀（默认 zsens_）。

cqplayer 在 1.1.0 新增字段：points（活动积分）、signday（最近签到日期）、signstreak（连续签到天数）、lastboss_time（世界BOSS攻击冷却）。

九、接口清单

9.1 前台

9.2 后台

十、常见问题

10.1 页面出现 Vdefault} 乱码

ThinkPHP 模板的 switch 默认分支必须写成自闭合 {default/}，写成 {default}...{/default} 会把 {/default} 当文本输出。

10.2 任务 / 竞技场页面 500（BIGINT UNSIGNED out of range）

MySQL 对无符号字段直接做减法会产生负数溢出。涉及 level 等无符号字段的差值排序必须显式转换：

ABS(CAST(level AS SIGNED) - 3)

10.3 分组查询报 1055（onlyfullgroup_by）

GROUP BY 后 ORDER BY 非聚合字段会报错。改用聚合字段排序，例如：

->field('zone, MIN(level) AS min_level')
->group('zone')
->orderRaw('min_level ASC')

10.4 战斗日志时间显示 1970-01-01

模型开启自动时间戳后，读取会把 create_time 转成日期字符串，模板中 (int) 强转只剩年份。模型需设置：

protected $dateFormat = false;

10.5 怪物图标为空 / 写入 emoji 报 1366

本站数据库连接为 utf8（3 字节），无法写入 4 字节 emoji。插件改为在 PHP 中维护图标映射（Monster::DEFAULT_ICONS），不把 emoji 存库；世界频道与 AI 文案也会自动移除 4 字节字符。

10.6 安装了旧版本，缺少新表

访问任意游戏页面会自动补建；也可在后台重新执行一次「安装」以幂等补齐（安装脚本使用 CREATE TABLE IF NOT EXISTS）。

10.7 世界频道无法发言

依次检查：后台「世界频道 → 启用世界频道」是否开启；是否处于冷却时间；内容是否为空或超出最大字数。

10.8 AI 文案没有生效

依次检查：是否开启「启用 AI 文案」；是否填写 API Key；接口地址是否只填到 /v1；模型名是否正确；服务器是否启用 curl 扩展且可访问外网。即使 AI 失败，也会自动使用本地文案，不影响游戏。

10.9 调整难度后怪物属性没变化

• 选择「简单 / 普通 / 困难 / 噩梦」时，下方 8 项自定义倍率不生效；只有「难度预设 = 自定义」时才读取它们；
• 「升级经验倍率」不受预设影响，始终生效；
• 修改后刷新页面即可，无需重启服务。

10.10 世界BOSS血量与自己配置的不一致

• 后台修改 BOSS 血量 / 攻防后，仅在 BOSS 满血（刷新后）时同步，避免战斗中途血量错乱；
• 被击杀后按「刷新间隔」进入冷却，到点自动满血并采用最新配置。

10.11 复活按钮不出现

仅当角色 hp = 0 时显示复活入口；若生命仍有剩余则无需复活。复活会按配置扣除金币，金币不足时无法复活。

十一、二次开发提示

• 新增怪物 / 装备 / 技能可直接在后台管理页维护；
• 掉落关系表 cqmonsterdrop 按权重随机，权重越大越容易掉；
• 新增系统播报可调用 ShoutService::system('内容', $player)；
• 新增配置项需同时修改 ZsChuanqiPlugin::defaultConfig() 与 configSchema()，否则保存时会被过滤；
• 调整难度倍率请改 DifficultyService::PRESETS，所有战斗与列表展示会自动跟随；
• 新玩法属性加成统一在 EquipmentService::getTotalStats() 汇总，避免战斗 / 竞技场 / 页面数值不一致；
• 修改样式请改 plugins/ZsChuanqi/static/cq.css，后台保存设置不会覆盖，但需重新复制到 public/static/ZsChuanqi（或重装插件）。

如需扩展新玩法，建议先在 service/ 中实现业务逻辑，再由控制器与模板做薄封装，保持与现有代码一致的分层方式。