feat(map): 新增英雄图鉴技能分档描述渲染逻辑

1. 为技能图标组件新增所属英雄UUID字段，传递英雄上下文 2. 在英雄列表面板中为技能图标绑定所属英雄ID 3. 新增英雄技能分档渲染逻辑，根据英雄等级展示对应技能解锁状态和描述 4. 补充注释和类型定义，完善代码文档
refactor(hero skill): 重构英雄技能描述生成逻辑
2026-08-27 21:10:39 +08:00 · 2026-08-27 21:06:34 +08:00
6 changed files with 170 additions and 74 deletions
--- a/assets/script/game/common/HeroSkillText.ts
+++ b/assets/script/game/common/HeroSkillText.ts
@@ -24,7 +24,7 @@
 * HeroSkillDesc.ts 暂时保留兼容旧 UI 引用，待迁移完成后移除。
 */
 import {
-    HeroInfo, SkillTriggerType, SkillTriggerName, HSkillInfo, LvSkillEntry, LvTriggerEntry,
+    HeroInfo, SkillTriggerType, SkillTriggerName, HSkillInfo, LvTriggerEntry,
    TriggerGrouped, resolveSkillOverrides, resolveTriggerByLv, resolveFieldByLv, resolveReviveByLv,
    getGroupedTriggerName, getFieldSkillName, getReviveSkillName,
 } from "./config/heroSet";
@@ -145,38 +145,43 @@ function getHeroDisplayLv(heroUuid: number, configLv: number, fac: FacSet): numb
 * 输出一：英雄当前局外等级下，全部技能最大生效档的完整说明（富文本）。
 *
 * 覆盖：普攻/大招（skills，resolve ≤lv 最大档）、5 类触发技能、驻场光环（field）、
- * 复活（revive）。每行 = 「技能名」+ 触发语境 + 模板渲染后的效果文本（数值高亮）。
+ * 复活（revive）。每行 = 「技能名」:（或「技能名」+ 触发语境）+ 模板渲染后的效果文本（数值高亮），
+ * 不展示技能等级档号（当前档由英雄局外等级隐含决定）。
 *
- * @param heroUuid 英雄 uuid（HeroInfo key）
- * @param showName 是否包含「技能名」片段（面板 true，紧凑卡片 false）
- * @returns      多行富文本串，\n 分隔；英雄不存在时返回 ""
+ * Why 普攻默认隐藏：skills 首位为普攻（全英雄共有基础能力），展示场景通常只关心
+ *      特色技能（大招/触发/光环），普攻行信息冗余；需要完整展示时传 showNormal=true。
+ *
+ * @param heroUuid   英雄 uuid（HeroInfo key）
+ * @param showName   是否包含「技能名」片段（面板 true，紧凑卡片 false）
+ * @param showNormal 是否展示普攻（skills 首位技能），默认 false
+ * @returns          多行富文本串，\n 分隔；英雄不存在时返回 ""
 */
-export function buildHeroSkillDesc(heroUuid: number, showName: boolean = true): string {
+export function buildHeroSkillDesc(heroUuid: number, showName: boolean = true, showNormal: boolean = false): string {
    const hero = HeroInfo[heroUuid];
    if (!hero) return "";
    const lv = getHeroDisplayLv(heroUuid, hero.lv, hero.fac);
    const lines: string[] = [];
-    const nameSeg = (n: string) => (showName && n ? `${skillNameRich(n)} ` : "");
+    const nameSeg = (n: string) => (showName && n ? skillNameRich(n) : "");

    // ---- 普攻/大招（skills）：resolve 当前等级生效档，渲染该档模板 ----
-    for (const key in hero.skills) {
-        const hSkill = hero.skills[key];
+    const skillKeys = Object.keys(hero.skills);
+    for (let i = 0; i < skillKeys.length; i++) {
+        // 首位技能 = 普攻，默认跳过（基础能力不占描述篇幅）
+        if (i === 0 && !showNormal) continue;
+        const hSkill = hero.skills[skillKeys[i]];
        if (!hSkill) continue;
        const base = SkillSet[hSkill.uuid];
        if (!base) continue;
        const skill = mergeSkillParams(base, resolveSkillOverrides(hSkill, lv));
-        // 生效档（≤lv 最大档）：取其 s_lv 与 desc；未配置 desc 的档位继承上一档模板
-        let entry: LvSkillEntry | undefined;
+        // 生效档（≤lv 最大档）模板：未配置 desc 的档位继承基础/上一档模板
        let inheritDesc = hSkill.desc;
        for (const e of hSkill.lv_entries ?? []) {
-            if (e.lv <= lv) {
-                if (!entry || e.lv > entry.lv) entry = e;
-                if (e.desc) inheritDesc = e.desc;
-            }
+            if (e.lv <= lv && e.desc) inheritDesc = e.desc;
        }
-        const sLv = entry?.s_lv ?? hSkill.lv;
        const text = inheritDesc ? renderDesc(inheritDesc, skill) : fallbackDesc(skill);
-        lines.push(`${nameSeg(hSkill.name ?? base.name)}Lv.${valueRich(sLv)}: ${text}`);
+        // 行首格式「技能名」:（不展示技能等级，等级由英雄局外等级隐含表达）
+        const head = nameSeg(hSkill.name ?? base.name);
+        lines.push(head ? `${head}: ${text}` : text);
    }

    // ---- 5 类标准触发技能：resolve 当前等级生效档 ----
@@ -339,33 +344,39 @@ function collectSkillTiers(hSkill: HSkillInfo): ISkillTierInfo[] {
    return tiers;
 }

+/** 单个技能等级档位的展示行（结构化，供弹窗逐档渲染激活状态与描述） */
+export interface HeroSkillTierLine {
+    /** 技能等级（slv） */
+    sLv: number;
+    /** 该档解锁/激活所需英雄等级 */
+    heroLv: number;
+    /** 行文本：slv1=完整效果；slv2+=相对上一级提升（数值漂移/新增效果），富文本 */
+    text: string;
+}
+
 /**
- * 输出二：指定技能的各阶段说明（富文本）。
+ * 输出二（结构化）：指定技能各等级档位说明，按技能等级升序。
 *
- * 输出结构（按技能等级升序，通用支持任意档数）：
- *   - slv1：完整能力 + 数值 +（英雄X级激活）
- *   - slv2+：相对上一级的提升（数值漂移/新增效果/计时 buff 增减）+（英雄Y级解锁）
+ * slv1 给完整能力 + 数值；slv2+ 给相对上一级的提升。每档附带解锁英雄等级，
+ * 调用方可自行对比英雄当前等级（smc.getHeroOuterLv）判定激活状态。
 *
- * 技能定位顺序：hero.skills[skillUuid]（普攻/大招）→ 5 类触发技能组 → 未找到返回 ""。
+ * 技能定位顺序：hero.skills[skillUuid]（普攻/大招）→ 5 类触发技能组 → 未找到返回 []。
 * Why: 同一底座技能可能被多个英雄以不同 overrides 引用，必须以英雄语境取档。
 *
 * @param heroUuid  英雄 uuid（HeroInfo key）
 * @param skillUuid 技能 uuid（skills key 或触发组 s_uuid）
- * @param showName  是否包含「技能名」片段
- * @returns         多行富文本串，\n 分隔；技能不属于该英雄时返回 ""
+ * @returns         档位行数组；技能不属于该英雄时返回 []
 */
-export function buildHeroSkillTierDesc(heroUuid: number, skillUuid: number, showName: boolean = true): string {
+export function buildHeroSkillTierLines(heroUuid: number, skillUuid: number): HeroSkillTierLine[] {
    const hero = HeroInfo[heroUuid];
-    if (!hero) return "";
+    if (!hero) return [];

-    let name = "";
    let tiers: ISkillTierInfo[] = [];
    let triggerLabel = "";

    const hSkill = hero.skills?.[skillUuid];
    if (hSkill) {
        // 普攻/大招路径
-        name = hSkill.name ?? SkillSet[skillUuid]?.name ?? "";
        tiers = collectSkillTiers(hSkill);
    } else {
        // 触发技能路径：在 5 类触发组中定位 s_uuid
@@ -374,9 +385,8 @@ export function buildHeroSkillTierDesc(heroUuid: number, skillUuid: number, show
            const entries = grouped?.[skillUuid];
            if (!grouped || !entries?.length) continue;
            const base = SkillSet[skillUuid];
-            if (!base) return "";
+            if (!base) return [];
            const sorted = [...entries].sort((a, b) => (a.s_lv ?? 0) - (b.s_lv ?? 0));
-            name = getGroupedTriggerName(grouped, skillUuid);
            let inherit: string | undefined;
            tiers = sorted.map((e: LvTriggerEntry, i: number) => {
                if (e.desc) inherit = e.desc;
@@ -394,22 +404,57 @@ export function buildHeroSkillTierDesc(heroUuid: number, skillUuid: number, show
            break;
        }
    }
-    if (tiers.length === 0) return "";
+    if (tiers.length === 0) return [];

-    const nameSeg = showName && name ? `${skillNameRich(name)} ` : "";
-    const lines: string[] = [];
+    const lines: HeroSkillTierLine[] = [];
    for (let i = 0; i < tiers.length; i++) {
        const t = tiers[i];
-        const head = `${nameSeg}Lv.${valueRich(t.sLv)}（英雄${valueRich(t.heroLv)}级${i === 0 ? "激活" : "解锁"}）`;
        if (i === 0) {
-            // 技能 1 级：完整能力 + 数值（含激活英雄等级）
+            // 技能 1 级：完整能力 + 数值
            const text = t.desc ? renderDesc(t.desc, t.skill) : fallbackDesc(t.skill);
-            lines.push(`${head}: ${triggerLabel ? `${triggerLabel}, ` : ""}${text}`);
+            lines.push({ sLv: t.sLv, heroLv: t.heroLv, text: triggerLabel ? `${triggerLabel}, ${text}` : text });
        } else {
-            // 技能 2 级起：相对上一级的提升 + 解锁英雄等级
+            // 技能 2 级起：相对上一级的提升
            const diff = buildTierDiff(tiers[i - 1], t);
-            lines.push(`${head}: ${diff.length > 0 ? diff.join("，") : "无变化"}`);
+            lines.push({ sLv: t.sLv, heroLv: t.heroLv, text: diff.length > 0 ? diff.join("，") : "无变化" });
        }
    }
-    return lines.join("\n");
+    return lines;
+}
+
+/**
+ * 输出二：指定技能的各阶段说明（富文本整段）。
+ *
+ * 输出结构（按技能等级升序，通用支持任意档数）：
+ *   - slv1：完整能力 + 数值 +（英雄X级激活）
+ *   - slv2+：相对上一级的提升（数值漂移/新增效果/计时 buff 增减）+（英雄Y级解锁）
+ *
+ * @param heroUuid  英雄 uuid（HeroInfo key）
+ * @param skillUuid 技能 uuid（skills key 或触发组 s_uuid）
+ * @param showName  是否包含「技能名」片段
+ * @returns         多行富文本串，\n 分隔；技能不属于该英雄时返回 ""
+ */
+export function buildHeroSkillTierDesc(heroUuid: number, skillUuid: number, showName: boolean = true): string {
+    const hero = HeroInfo[heroUuid];
+    if (!hero) return "";
+    const tiers = buildHeroSkillTierLines(heroUuid, skillUuid);
+    if (tiers.length === 0) return "";
+    // 技能名：大招取 HSkillInfo.name，触发技能取组名，缺省回退底座名
+    const hSkill = hero.skills?.[skillUuid];
+    const name = hSkill
+        ? (hSkill.name ?? SkillSet[skillUuid]?.name ?? "")
+        : resolveTriggerSkillName(hero, skillUuid);
+    const nameSeg = showName && name ? `${skillNameRich(name)} ` : "";
+    return tiers
+        .map((t, i) => `${nameSeg}Lv.${valueRich(t.sLv)}（英雄${valueRich(t.heroLv)}级${i === 0 ? "激活" : "解锁"}）: ${t.text}`)
+        .join("\n");
+}
+
+/** 在英雄触发组中解析技能对外展示名（非触发技能返回底座名） */
+function resolveTriggerSkillName(hero: typeof HeroInfo[number], skillUuid: number): string {
+    for (const type of TRIGGER_KEYS) {
+        const grouped = hero[type] as TriggerGrouped | undefined;
+        if (grouped?.[skillUuid]?.length) return getGroupedTriggerName(grouped, skillUuid);
+    }
+    return SkillSet[skillUuid]?.name ?? "";
 }
--- a/assets/script/game/common/HeroSkillText.ts.meta
+++ b/assets/script/game/common/HeroSkillText.ts.meta
@@ -0,0 +1,9 @@
+{
+  "ver": "4.0.24",
+  "importer": "typescript",
+  "imported": true,
+  "uuid": "481c93ea-b5e9-4f75-8676-c5ec48708c0b",
+  "files": [],
+  "subMetas": {},
+  "userData": {}
+}
--- a/assets/script/game/map/CHeroComp.ts
+++ b/assets/script/game/map/CHeroComp.ts
@@ -20,7 +20,7 @@ import { _decorator, Node, Sprite, Label, RichText, NodeEventType, Vec3, Tween,
 import { ecs } from "../../../../extensions/oops-plugin-framework/assets/libs/ecs/ECS";
 import { CCComp } from "../../../../extensions/oops-plugin-framework/assets/module/common/CCComp";
 import { HeroInfo, HeroCardConfig } from "../common/config/heroSet";
-import { buildSkillDescMoreRich, ISkillDescSource } from "../common/config/HeroSkillDesc";
+import { buildHeroSkillDesc } from "../common/HeroSkillText";
 import { oops } from "db://oops-framework/core/Oops";
 import { GameEvent } from "../common/config/GameEvent";
 import { outlineRich } from "../common/RichOutline";
@@ -270,11 +270,11 @@ export class CHeroComp extends CCComp {
        // 背景：按 card_lv 激活对应颜色子节点（1→green 2→blue 3→purple 4→red 5→yellow）
        this.updateBgNode();

-        // 描述富文本：展示英雄当前局外等级的能力（buildSkillDescMoreRich）
-        // 与英雄信息弹窗同一套文案规则，杜绝手写文案与数值漂移
+        // 描述富文本：展示英雄当前局外等级的能力（buildHeroSkillDesc 文本一）
+        // 行首「技能名」: + 效果文本；heroInfo 内联 desc 模板驱动，数值实时取合并后配置
        // outlineRich 为整段富文本包裹描边，提升深色面板可读性
        if (this.info_rich) {
-            const desc = hero ? buildSkillDescMoreRich(this.buildHeroDescSource(hero), false) : (this.cardData.info || "");
+            const desc = hero ? buildHeroSkillDesc(this.cardData.uuid) : (this.cardData.info || "");
            this.info_rich.string = outlineRich(desc);
            this.info_rich.node.active = !!desc;
        }
@@ -451,30 +451,6 @@ export class CHeroComp extends CCComp {
        return model.hero_uuid ?? null;
    }

-    /**
-     * 构造英雄当前能力描述数据源（ISkillDescSource）。
-     * lv 取英雄局外等级（与 level_label 同口径），由各 resolver 取当前等级生效档，
-     * 展示英雄当前实际能力信息。
-     * @param hero HeroInfo 静态配置项
-     * @returns    描述数据源
-     */
-    private buildHeroDescSource(hero: typeof HeroInfo[number]): ISkillDescSource {
-        return {
-            lv: Math.max(1, smc.getHeroOuterLv(hero.uuid)),
-            skills: hero.skills,
-            call: hero.call,
-            dead: hero.dead,
-            fstart: hero.fstart,
-            atking: hero.atking,
-            atked: hero.atked,
-            field: hero.field,
-            revive: hero.revive,
-            grow_type: hero.grow_type,
-            ap: hero.ap,
-            hp: hero.hp,
-        };
-    }
-
    /**
     * 为英雄图标加载 idle 动画剪辑，提取首帧 SpriteFrame 静止展示，零运行时开销。
     * @param node   图标节点
--- a/assets/script/game/map/HerosListComp.ts
+++ b/assets/script/game/map/HerosListComp.ts
@@ -513,6 +513,7 @@ export class HerosListComp extends CCComp {
            this.skills_node.children[i].destroy()
        }

+        // huuid 已在 onCardSelect 赋值，addSkillIcon 用它携带英雄语境
        const lv = Math.max(1, smc.getHeroOuterLv(hero.uuid))

        // ---- 大招：skills[1] 及以后（英雄出场即激活，与能量条同语义，恒不锁定） ----
@@ -547,7 +548,8 @@ export class HerosListComp extends CCComp {
        const node = instantiate(this.skill_icon_prefab)
        node.name = `skill_${s_uuid}`
        const comp = node.getComponent(SSkillBoxComp) || node.addComponent(SSkillBoxComp)
-        comp.initHeroSkill(s_uuid, s_lv, locked, isField)
+        // 携带所属英雄，点击弹窗按英雄技能分档描述渲染
+        comp.initHeroSkill(s_uuid, s_lv, locked, isField, this.huuid)
        this.skills_node.addChild(node)
    }

--- a/assets/script/game/map/SSkillBoxComp.ts
+++ b/assets/script/game/map/SSkillBoxComp.ts
@@ -42,6 +42,8 @@ export class SSkillBoxComp extends CCComp {

    /** 技能 UUID */
    private s_uuid: number = 0;
+    /** 所属英雄 UUID（英雄图鉴模式，>0 时点击弹窗走英雄技能分档描述） */
+    private hero_uuid: number = 0;
    /** 卡牌等级 */
    private card_lv: number = 1;
    /** 卡牌自定义图标ID（优先级最高，未定义则按 trigger_type 自动取） */
@@ -77,6 +79,8 @@ export class SSkillBoxComp extends CCComp {
            skill_name: this.resolveSkillName(),
            field: this.field,
            trigger_type: this.trigger_type,
+            // 英雄图鉴模式：携带所属英雄，弹窗按英雄技能分档描述渲染
+            hero_uuid: this.hero_uuid || undefined,
        });
    }

@@ -120,13 +124,15 @@ export class SSkillBoxComp extends CCComp {
    /**
     * 初始化英雄技能图标（英雄图鉴面板专用）：
     *   图标按 s_uuid 直接取 SkillSet / FieldSkillSet 配置，不走 EquipPoolList。
-     * @param s_uuid  技能 UUID（大招/触发技能指向 SkillSet，光环词条指向 FieldSkillSet）
-     * @param s_lv    当前英雄等级下生效的技能等级（显示在等级标签）
-     * @param locked  当前等级未激活时显示锁定遮罩
-     * @param isField true 时图标取 FieldSkillSet（驻场光环词条）
+     * @param s_uuid    技能 UUID（大招/触发技能指向 SkillSet，光环词条指向 FieldSkillSet）
+     * @param s_lv      当前英雄等级下生效的技能等级（显示在等级标签）
+     * @param locked    当前等级未激活时显示锁定遮罩
+     * @param isField   true 时图标取 FieldSkillSet（驻场光环词条）
+     * @param heroUuid  所属英雄 UUID（点击弹窗按英雄技能分档描述渲染）
     */
-    initHeroSkill(s_uuid: number, s_lv: number, locked: boolean, isField: boolean = false) {
+    initHeroSkill(s_uuid: number, s_lv: number, locked: boolean, isField: boolean = false, heroUuid: number = 0) {
        this.s_uuid = s_uuid;
+        this.hero_uuid = heroUuid;
        this.card_lv = s_lv;
        this.hero_icon_source = isField ? "field" : "skill";
        this.updateUI();
--- a/assets/script/game/map/SinfoComp.ts
+++ b/assets/script/game/map/SinfoComp.ts
@@ -17,13 +17,15 @@
 *       skill_name: "战后恢复", // 名称（可选）
 *       field: [...],     // 驻场词条（装备卡）
 *       trigger_type: 3,  // 触发类型
+ *       hero_uuid: 5001,  // 所属英雄（英雄图鉴模式：按英雄技能分档描述渲染）
 *   });
 *
 * 依赖：
 *   - oops.gui（UI 生命周期）—— open / removeByNode
 *   - SkillSet / FieldSkillSet（技能/光环静态配置）
 *   - SkillCardList / EquipPoolList（卡牌静态配置）
- *   - HeroSkillDesc（buildCardDescRich 富文本描述生成）
+ *   - HeroSkillDesc（buildCardDescRich 富文本描述生成，卡牌模式）
+ *   - HeroSkillText（buildHeroSkillTierLines 技能分档描述，英雄技能模式）
 */
 import { _decorator, Node, Label, RichText, NodeEventType, Sprite, Color, input, Input, EventTouch, UITransform, Vec3 } from "cc";
 import { ecs } from "../../../../extensions/oops-plugin-framework/assets/libs/ecs/ECS";
@@ -35,6 +37,7 @@ import { SkillCardList } from "../common/config/SCardSet";
 import { EquipPoolList } from "../common/config/EquipSet";
 import { FieldEntry } from "../common/config/heroSet";
 import { buildCardDescRich } from "../common/config/HeroSkillDesc";
+import { buildHeroSkillTierLines, HeroSkillTierLine } from "../common/HeroSkillText";
 import { smc } from "../common/SingletonModuleComp";

 const { ccclass, property } = _decorator;
@@ -53,6 +56,8 @@ export interface SInfoParams {
    field?: FieldEntry[];
    /** 触发类型 */
    trigger_type?: CardTriggerType;
+    /** 所属英雄 UUID（英雄图鉴模式：按英雄技能分档描述渲染，优先级高于卡牌逻辑） */
+    hero_uuid?: number;
 }

 /** 等级提升信息（用于 2 级 / 3 级面板） */
@@ -188,11 +193,64 @@ export class SinfoComp extends CCComp {

    // ======================== 渲染逻辑 ========================

+    /**
+     * 英雄技能模式渲染（文本二：单个技能各阶段说明）。
+     *   - main_info：技能 slv1 完整描述
+     *   - lv2_desc：slv2 相对 slv1 的提升；lv3_desc：slv3 及以后档（合并展示）
+     *   - lv2/lv3_status：按英雄局外等级（smc.getHeroOuterLv）对比档位解锁等级判定激活
+     * @returns true 已渲染（拦截通用卡牌逻辑）；false 技能无分档数据（光环/复活词条），回退通用逻辑
+     */
+    private renderHeroSkill(p: SInfoParams): boolean {
+        const tiers = buildHeroSkillTierLines(p.hero_uuid!, p.uuid);
+        if (tiers.length === 0) return false;
+
+        // 图标 / 名称 / 当前技能等级与通用逻辑一致（card_lv 传的就是当前生效 s_lv）
+        this.renderIcon(p);
+        this.setLabel(this.name_label, this.resolveName(p));
+        this.setLabel(this.lv_label, `Lv.${p.card_lv}`);
+
+        // 技能 1 级：完整能力描述
+        if (this.main_info && this.main_info.isValid) {
+            this.main_info.string = tiers[0].text || "暂无描述";
+        }
+
+        // 英雄当前局外等级：激活判定基准
+        const heroLv = Math.max(1, smc.getHeroOuterLv(p.hero_uuid!));
+
+        // 技能 2 级 / 3 级（3 级以后档位合并进 3 级栏，多行展示）
+        const lv2 = tiers.find(t => t.sLv === 2);
+        const lv3Plus = tiers.filter(t => t.sLv >= 3);
+        this.renderLvPanelFromTier(lv2, heroLv, this.lv2_status, this.lv2_desc);
+        const lv3Merged = lv3Plus.length
+            ? { sLv: lv3Plus[0].sLv, heroLv: lv3Plus[0].heroLv, text: lv3Plus.map(t => t.text).join("\n") }
+            : undefined;
+        this.renderLvPanelFromTier(lv3Merged, heroLv, this.lv3_status, this.lv3_desc);
+        return true;
+    }
+
+    /** 按档位渲染单等级面板：激活状态按英雄等级对比档位解锁等级 */
+    private renderLvPanelFromTier(tier: HeroSkillTierLine | undefined, heroLv: number, statusLabel: Label | null, descRich: RichText | null) {
+        if (statusLabel && statusLabel.isValid) {
+            const unlocked = !!tier && heroLv >= tier.heroLv;
+            statusLabel.string = unlocked ? "已激活" : (tier ? `${tier.heroLv}级解锁` : "");
+            // 已激活显示绿色，未激活显示灰色
+            statusLabel.color = unlocked
+                ? new Color(0, 255, 10, 255)
+                : new Color(150, 150, 150, 255);
+        }
+        if (descRich && descRich.isValid) {
+            descRich.string = tier?.text ?? "";
+        }
+    }
+
    /** 主渲染入口 */
    private render() {
        if (!this.params) return;
        const p = this.params;

+        // ---- 英雄技能模式：按英雄语境渲染分档描述（文本二） ----
+        if (p.hero_uuid && this.renderHeroSkill(p)) return;
+
        // ---- 图标 ----
        this.renderIcon(p);