abevol/add-map-marker

添加地图标记技能

本技能指导如何在 KingdomMod.OverlayMap 项目中添加新的地图标记。

核心架构

游戏组件 → Notifier → Resolver → MapMarkerType → Mapper → MapMarker
            ↓            ↓                        ↓
通知游戏组件创建/销毁  识别组件类型              创建标记并配置样式

• Resolver: 识别游戏组件，返回对应的 MapMarkerType
• Mapper: 根据标记类型和组件状态，调用 TryAddMapMarker 创建标记
• MarkerStyle: 配置标记的颜色、符号等样式
• Strings: 配置标记的显示名称（多语言）

标记类型选择

| 类型 | 结构 | 适用场景 | 示例 | |------|------|----------|------| | MarkerConfig | Color + Sign | 单一状态标记 | Beach, Portal, Shop | | MarkerConfigStated | Color + Sign + 状态子配置 | 多状态标记（锁定/建造/损坏等） | Wall, Lighthouse, Mine | | MarkerConfigColor | Color only | 仅颜色（用于线条/文字） | StatsInfo, ExtraInfo |

通知方式选择

• 这个需要用户根据游戏的运行信息和游戏对象的转储信息进行判断，因此主要听取用户提供的信息。
• 通知方式包括:
  1. 组件自身事件: 按照组件生命周期的触发顺序，如 Awake, OnEnable, Start, OnDisable, OnDestroy 等。对于具体组件，这些方法并不一定都存在，需要通过技能 game-type-browser 查看组件类型的具体实现才能确定。根据经验，优先使用 Start 和 OnDisable 事件来作为地图图标创建和销毁的触发事件，因为它们处于组件生命周期的中间位置，能够确保在组件初始化完成后和组件销毁前触发。此外，在同一个位置的对象发生连续更替时，OnDisable 事件会在 OnDestroy 事件之前触发，因此可以利用 OnDisable 事件来删除旧的地图图标，确保在新的地图图标创建前旧的地图图标已被正确删除。此外，由于组件自身的 Notifier 只服务于该组件的映射，根据“相关性聚合”原则放在同一个 Mapper 文件内，而不需要像其它的通用通知器那样写到单独的 Notifier 文件。
  2. 父类组件通知器: 利用父类组件的事件通知，比如 PayableBush, PayableUpgrade 继承自 PayableNotifier，因此可以利用 PayableNotifier 的事件通知。
  3. 兄弟组件通知器: 利用同一游戏对象上的其他兄弟组件的事件通知，比如 PayableBlockerNotifier, PayableNotifier, PlayerCargoNotifier, ScaffoldingNotifier, WorkableBuildingNotifier 等。

通用添加流程

所有标记类型都遵循以下核心流程：

1. 在 MarkerStyle.cs 中添加配置字段和绑定
2. 在 Strings.cs 中添加显示名称
3. 在 Mapper 中实现标记逻辑
4. 更新风格配置文件 MarkerStyle.cfg
5. 更新语言配置文件 Language.en-US.cfg（en-US、ru-RU、zh-CN 多语言支持）

关键文件位置

| 文件 | 用途 | |------|------| | OverlayMap/Config/MarkerStyle.cs | 标记样式配置 | | OverlayMap/Config/Strings.cs | 本地化字符串 | | OverlayMap/Gui/TopMap/MapMarkerType.cs | 标记类型枚举 | | OverlayMap/Gui/TopMap/Mappers/*.cs | 标记映射器 | | OverlayMap/Gui/TopMap/Resolvers/*.cs | 组件解析器 | | OverlayMap/Gui/TopMap/TopMapView.cs | TryAddMapMarker 方法 | | OverlayMap/ConfigPrefabs/MarkerStyle.cfg | 风格配置文件 | | OverlayMap/ConfigPrefabs/Language.en-US.cfg | 英文本地化配置文件 | | OverlayMap/Gui/TopMap/MapperInitializer.cs | 注册组件解析器和标记映射器 |

TryAddMapMarker 方法签名

public MapMarker TryAddMapMarker(
    Component target,
    ConfigEntryWrapper<string> color,       // 颜色 (RGBA: "1,1,1,1")
    ConfigEntryWrapper<string> sign,        // 符号 (如 "♜")
    ConfigEntryWrapper<string> title,       // 标题/名称
    CountUpdaterFn countUpdater = null,     // 动态数量更新器
    ColorUpdaterFn colorUpdater = null,     // 动态颜色更新器
    VisibleUpdaterFn visibleUpdater = null, // 可见性更新器
    MarkerRow row = MarkerRow.Settled)      // 行位置

回调函数签名：

Func<Component, int> CountUpdaterFn;      // 返回显示数量
Func<Component, ConfigEntryWrapper<string>> ColorUpdaterFn;  // 返回颜色配置
Func<Component, bool> VisibleUpdaterFn;   // 返回是否可见

IComponentMapper 接口

public interface IComponentMapper
{
    MapMarkerType? MarkerType => null;  // 处理的标记类型
    
    // 旧方法（逐步废弃）
    void Map(Component component) { }
    
    // 新方法（推荐）
    void Map(Component component, NotifierType notifierType, ResolverType resolverType) 
        => Map(component);
}

颜色格式

RGBA 格式，值范围 0-1：

| 颜色 | 值 | 含义 | |------|------|------| | 绿色 | 0,1,0,1 | 正常/已解锁/安全 | | 红色 | 1,0,0,1 | 损坏/危险/未付款/敌人 | | 蓝色 | 0,0,1,1 | 建造中/进行中 | | 灰色 | 0.5,0.5,0.5,1 | 锁定/不可用 | | 紫色 | 0.62,0,1,1 | 传送门/魔法 | | 白色 | 1,1,1,1 | 默认/中立 |

参考文档

• 简单标记 (MarkerConfig)
• 带状态标记 (MarkerConfigStated)
• 纯颜色标记 (MarkerConfigColor)
• 完整示例

常见问题

Q: 标记不显示？

检查清单：

1. Resolver 是否正确返回 MapMarkerType
2. Mapper 是否已在 MapperInitializer 中注册
3. 配置文件是否包含该标记的配置

Q: 复用现有标记类型还是创建新类型？

• 复用：如果新对象与现有对象行为相同，只是样式不同（如不同类型的商店）
• 新建：如果需要独立的状态管理或与其他标记完全区分