Hint Specification

这篇文档叙述服务器端提供 hint 的情形, 可作为客户端实现参考.

格式概述

每次客户端从服务器端取得的 hint 是一个 JSON 字典, 格式如下

若你 (当前玩家) 不是此时可响应的玩家, 则你将取得

{
    'code': ret_code.OK,
    'action': X,
    'players': [Y],
}

若你是此时可响应的玩家之一, 则你将取得

{
    'code': ret_code.OK,
    'action': X,
    'players': [Y],
    'abort': A,
    M: D,
}

其中 X, Y, A, M, D 分别表示

• X: 动作分类
• Y: 此时响应的玩家 (整数列表, 每个表项代表一名玩家 ID, 顺序无先后之分)
• A: (仅出现在你是可响应玩家时) 是否可以中止, allow 表示可以中止, disallow 表示不可以中止
• M 与 D: (仅出现在你是可响应玩家时) 可用的方法及详情 (可有多个)

动作分类只会是下面情况之一

• select character 选择角色
• region: 选择区域 (如使用 [过河拆桥] 之后, 选择弃置卡牌的区域时)
• use: 使用卡牌
• discard: 弃置, 展示, 或打出卡牌 (统称为不指定目标的出牌)

若此时其它玩家响应动作, 客户端可以忽略动作分类.

同时, hint 也指导客户端应该在玩家产生正确的行为后, 将该行为编码为特定格式的 JSON 字典传回给服务器端.

该 JSON 字典至少包含下列数据

{ 'token': TOKEN }

其中, TOKEN 为玩家加入游戏时, 服务器为玩家分配的令牌. 玩家应该保存该令牌直到这场游戏结束.

下面的叙述中, 如无特殊说明, 则客户端向服务器发送的 JSON 字典都应额外包含此令牌.

选择角色

当动作分类为选择角色时, 方法及详情会为如下格式

'candidates': [CHARACTER_NAME]

其中, 每个 CHARACTER_NAME 是一个角色名.

在玩家选择角色后, 客户端应当返回如下格式数据

{ 'select': CHARACTER_NAME }

其中, CHARACTER_NAME 为玩家所选的角色名.

选择区域

当动作分类为区域选择时, 方法及详情会为如下格式

'regions': [REGION_ITEM]

其中 REGION_ITEM 为区域名称, 可能的取值包括

• onhand: 手牌区
• weapon: 武器
• armor: 防具
• -1 horse: 进攻马
• +1 horse: 防御马

在玩家选择区域后, 客户端应返回

'region': REGION_ITEM

其中 REGION_ITEM 玩家选择的区域.

不指定目标的出牌

当动作分类为不指定目标的出牌时, 方法及详情会为如下格式

'methods': {
    方法 0: {
        'require': [需求],
        需求参数 0: 需求参数值 0,
        需求参数 1: 需求参数值 1,
        ...
    },
    方法 1: {
        'require': [需求],
        需求参数 0: 需求参数值 0,
        需求参数 1: 需求参数值 1,
        ...
    },
    ...
},

方法为此时可以打出卡牌的方法, 如, 拥有 [龙胆] 技能的角色在响应 [决斗] 需打出 [杀] 时, 方法将有 [杀] 与 [龙胆] 两种方法, 而普通角色此时只有 [杀] 一种方法.

每个方法中都会包含需求, 客户端需要根据需求列表中的值在字典内搜寻需求参数. 如, 下面的方法表示方法名称为 slash, 需求 1 张卡牌, 且这张卡牌的 id 必须为 cards 列表中某一个

'methods': {
    'slash' {
        'require': ['fix card count'],
        'card count': 1,
        'cards': [0, 1, 2, 3]
    }
}

打出卡牌的需求可包含下面这些

固定的卡牌数量

• 需求为 fix card count
• 参数 card count: 数量 (整数)
• 参数 cards: 候选卡牌列表 (整数列表, 表项为牌 id)

限制最少卡牌数量

• 需求为 min card count
• 参数 card count: 数量 (整数)
• 参数 cards: 候选卡牌列表 (整数列表, 表项为牌 id)

以上需求在使用卡牌 hint 中也可能出现.

用户选择方法及卡牌后, 客户端应返回如下字典

{
    'method': 方法,
    'discard': [牌 id],
}

其中方法为方法名称字符串, 牌 id 为卡牌 id 整数列表.

若放弃出牌, 则应返回

{ 'method': 'abort' }

使用卡牌

当动作分类为使用卡牌时, 方法及详情会为如下格式

'card': {
    牌 id 0: {
        'type': 目标类型,
        'target count': 目标数,
        'targets': [候选目标列表],
    },
    牌 id 1: {
        'type': 目标类型,
        'target count': 目标数,
        'targets': [候选目标列表],
    },
    ...
},
'methods': {
    方法 0: {
        'require': [需求],
        需求参数 0: 需求参数值 0,
        需求参数 1: 需求参数值 1,
        ...
    },
    方法 1: {
        'require': [需求],
        需求参数 0: 需求参数值 0,
        需求参数 1: 需求参数值 1,
        ...
    },
    ...
},

其中, card 相对应的字典表示可以按照牌面描述来使用的手牌. 字典中每一项牌 id 表示这张手牌的 id, 目标类型 可以是下面之一

• forbid: 禁止使用 (如 [闪] 牌, 或 [杀] 牌但攻击范围内没有合理的目标), 此时不会有 target count 与 targets
• implicit target: 目标隐含, 无须指定 (如装备), 此时亦不会有 target count 与 targets
• fix target: 固定目标

目标数为整数, 候选目标列表为整数列表, 每个整数表示一名玩家 id.

方法类似打出卡牌中的方法, 其中的需求部分, 除了出牌需求之外, 还可包含下面这些

固定的目标数量

• 需求为 fix target
• 参数 target count: 数量 (整数)
• 参数 targets: 候选目标列表 (整数列表, 表项为玩家 id)

如拥有 [龙胆] 技能的角色在出牌阶段 (尚未使用过 [杀]), 手中有 [杀] (id 为 0) 和 [闪] (id 为 1) 各 1 张, 攻击范围内有玩家 1 名 (id 为 2), 则 hint 方法及详情部分为

'card': {
    0: {
        'type': 'fix target',
        'target count': 1,
        'targets': [2],
    },
    1: { 'type': 'forbid' },
},
'methods': {
    'dragon heart': {
        'require': ['fix card count', 'fix target'],
        'cards': [1],
        'card count': 1,
        'targets': [2],
        'target count': 1,
    },
}

用户选择方法及卡牌后, 客户端应返回如下字典

{
    'action': 方法,
    'use': [牌 id],
    'players': [目标 id],
}

其中方法为方法名称字符串, 如果按照牌面来使用卡牌, 则方法应该是card; 牌 id 为卡牌 id 整数列表; 目标 id 为目标的玩家 id 整数列表.

若放弃出牌, 则应返回

{ 'method': 'abort' }