# Zulip配置目录

本目录包含Zulip集成系统的配置文件。

## 文件说明

### map-config.json

地图映射配置文件，定义游戏地图到Zulip Stream/Topic的映射关系。

#### 配置结构

```json
{
  "version": "1.0.0",
  "lastModified": "2025-12-25T00:00:00.000Z",
  "description": "配置描述",
  "maps": [
    {
      "mapId": "地图唯一标识",
      "mapName": "地图显示名称",
      "zulipStream": "对应的Zulip Stream名称",
      "interactionObjects": [
        {
          "objectId": "交互对象唯一标识",
          "objectName": "交互对象显示名称",
          "zulipTopic": "对应的Zulip Topic名称",
          "position": { "x": 100, "y": 150 }
        }
      ]
    }
  ]
}
```

#### 字段说明

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| version | string | 否 | 配置版本号 |
| lastModified | string | 否 | 最后修改时间（ISO 8601格式） |
| description | string | 否 | 配置描述 |
| maps | array | 是 | 地图配置数组 |

##### 地图配置 (MapConfig)

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| mapId | string | 是 | 地图唯一标识，如 "novice_village" |
| mapName | string | 是 | 地图显示名称，如 "新手村" |
| zulipStream | string | 是 | 对应的Zulip Stream名称 |
| interactionObjects | array | 是 | 交互对象配置数组 |

##### 交互对象配置 (InteractionObject)

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| objectId | string | 是 | 交互对象唯一标识 |
| objectName | string | 是 | 交互对象显示名称 |
| zulipTopic | string | 是 | 对应的Zulip Topic名称 |
| position | object | 是 | 对象在地图中的位置 |
| position.x | number | 是 | X坐标 |
| position.y | number | 是 | Y坐标 |

## 配置示例

### 新手村配置

```json
{
  "mapId": "novice_village",
  "mapName": "新手村",
  "zulipStream": "Novice Village",
  "interactionObjects": [
    {
      "objectId": "notice_board",
      "objectName": "公告板",
      "zulipTopic": "Notice Board",
      "position": { "x": 100, "y": 150 }
    },
    {
      "objectId": "village_well",
      "objectName": "村井",
      "zulipTopic": "Village Well",
      "position": { "x": 200, "y": 200 }
    }
  ]
}
```

### 酒馆配置

```json
{
  "mapId": "tavern",
  "mapName": "酒馆",
  "zulipStream": "Tavern",
  "interactionObjects": [
    {
      "objectId": "bar_counter",
      "objectName": "吧台",
      "zulipTopic": "Bar Counter",
      "position": { "x": 150, "y": 100 }
    },
    {
      "objectId": "fireplace",
      "objectName": "壁炉",
      "zulipTopic": "Fireplace Chat",
      "position": { "x": 300, "y": 200 }
    }
  ]
}
```

## 热重载

配置文件支持热重载，修改后无需重启服务即可生效。

### 启用配置监听

在代码中调用：

```typescript
configManagerService.enableConfigWatcher();
```

### 手动重载配置

```typescript
await configManagerService.reloadConfig();
```

## 验证配置

系统启动时会自动验证配置文件的有效性。验证规则包括：

1. mapId必须是非空字符串
2. mapName必须是非空字符串
3. zulipStream必须是非空字符串
4. interactionObjects必须是数组
5. 每个交互对象必须有有效的objectId、objectName、zulipTopic和position
6. position.x和position.y必须是有效数字

## 注意事项

1. **Stream名称**: Zulip Stream名称区分大小写，请确保与Zulip服务器上的Stream名称完全匹配
2. **Topic名称**: Topic名称同样区分大小写
3. **位置坐标**: 位置坐标用于空间过滤，确保与游戏客户端的坐标系统一致
4. **唯一性**: mapId和objectId在各自范围内必须唯一