7. 客户端命令¶

客户端与服务端通过 WebSocket 通讯，当用户操作客户端时，客户端会把相关命令发送到服务端，服务端会把操作的结果返回给客户端。

7.1. 消息格式¶

客户端发送给服务端请求为 JSON 格式的字符串，格式如下：

{
    "cmd": <(str)命令名>,
    "args": <(any)命令参数>(可选),
    "sn": <(int)命令序列号>(可选)
}

cmd: 命令的名字。
args: 命令的参数。不同命令需要不同的参数，可以是数字、字符串、列表、字典等，也可以为空。
sn: 命令的序列号。如果命令带有序列号，服务端在返回对应数据时也会带上这个序列号，通讯层会按照序列号将命令和返回的数据关联起来。如果发送给服务端的命令不带序列号，服务端则不会返回数据给客户端。

如果命令执行后返回以下格式的数据：

{
     "code": <(int)返回码>,
     "data": <(any)返回数据>,
     "msg": <(str)返回信息>
}

code: 返回码为 0 表示命令执行成功，其他值表示执行出现了异常情况。不同返回码的含义可见客户端 webclient/utils/defines.js 文件或服务端 common/utils/exception.py 文件中的定义。
data: 返回的数据，可能是字符串、数字，绝大多数情况下是一个字典。如果命令执行成功，返回的数据会放在 data 字段里，某些命令执行失败后也会将相关数据放在 data 字段中。
msg: 返回的文本信息。命令执行出错时，会将报错信息放在 msg 字段中。

Muddery 服务端支持的全部命令如下：

7.2. 未登录命令¶

不论用户是否登录，都可以使用以下命令。

7.2.1. first_connect¶

客户端初次连接到服务端时获取游戏的基本信息。

命令格式：

{
    "cmd": "first_connect"
}

返回 data：

{
    "game_name": <(str)游戏的名字>,
    "conn_screen": <(str)游戏的欢迎信息>
}

game_name: 游戏展示的名字。
conn_screen: 游戏的欢迎信息，通常显示在游戏的欢迎页面或登录页面上。

7.2.2. create_account¶

创建账号。

命令格式：

{
    "cmd": "create_account",
    "args": {
        "username": <(str)用户名>,
        "password": <(str)密码>,
        "connect": <(bool)是否登录>(可选)
    }
}

username: 新建用户的用户名。
password: 新建用户的密码，如果启用了加密，应该传输加密后的密文。
connect: 账号创建成功后是否立即登录。如果传 true，创建账号后会自动登录，如果传 false，需要用户用新的用户名和密码手动登录。

返回 code=0 表示账号创建成功，如果参数 connect 为 true 则同时登录成功，返回 data：

{
    "name": <(str)用户名>,
    "id": <(int)账号的id>,
    "max_char": <(int)玩家可以创建的最大角色数量>
}

name: 用户设置的用户名，和命令中的 username 一致。
id: 用户账号的 id，是一个数字。
max_char: 玩家可以创建的最大角色数量，用来限制玩家创建角色的数量。最大角色数量为服务端配置文件 server/settings.py 中配置的 MAX_PLAYER_CHARACTERS。

7.2.3. login¶

登录账号。

命令格式：

{
    "cmd": "login",
    "args": {
        "username": <(str)用户名>,
        "password": <(str)密码>,
    }
}

username: 用户的用户名。
password: 用户的密码，如果启用了加密，应该传输加密后的密文。

返回 code=0 表示登录成功，返回 data：

{
    "name": <(str)用户名>,
    "id": <(int)账号的id>,
    "max_char": <(int)玩家可以创建的最大角色数量>
}

name: 用户设置的用户名，和命令中的 username 一致。
id: 用户账号的 id，是一个数字。
max_char: 玩家可以创建的最大角色数量，用来限制玩家创建角色的数量。最大角色数量为服务端配置文件 server/settings.py 中配置的 MAX_PLAYER_CHARACTERS。

7.3. 账号命令¶

用户登录了自己的账号后，可以使用账号命令。

7.3.1. delete_account¶

删除账号。

命令格式：

{
    "cmd": "delete_account",
    "args": {
        "username": <(str)用户名>,
        "password": <(str)密码>,
    }
}

username: 用户的用户名。
password: 用户的密码，如果启用了加密，应该传输加密后的密文。

返回 code=0 表示删除成功。

7.3.2. change_pw¶

修改密码。

命令格式：

{
    "cmd": "change_pw",
    "args": {
        "current": <当前的密码>,
        "new": <新密码>
    }
}

current: 用户当前的密码，如果启用了加密，应该传输加密后的密文。
new: 用户设置的新密码，如果启用了加密，应该传输加密后的密文。

返回 code=0 表示修改密码成功。

7.3.3. char_create¶

创建角色。

命令格式：

{
    "cmd": "char_create",
    "args": {
        "name": <(str)角色名>,
    }
}

name: 新角色的名字。角色名字的长度只能在 1 到 30 个字符之间，不得与其他用户已有的角色名字重复。每个用户能创建的角色数量不能超过最大角色数量，最大角色数量为服务端配置文件 server/settings.py 中配置的 MAX_PLAYER_CHARACTERS。

返回 code=0 表示创建成功。

7.3.4. char_delete¶

删除角色。

命令格式：

{
    "cmd": "char_delete",
    "args": {
        "id": <(int)玩家角色的id>
    }
}

id: 玩家角色的id。

返回 code=0 表示删除成功。

7.3.5. char_delete_pw¶

验证密码后删除角色。

命令格式：

{
    "cmd": "char_delete_pw",
    "args": {
        "id": <(int)玩家角色的id>,
        "password": <(str)密码>,
    }
}

id: 玩家角色的id。
password: 用户的密码，如果启用了加密，应该传输加密后的密文。

返回 code=0 表示删除成功。

7.3.6. puppet¶

登录角色。

命令格式：

{
    "cmd": "puppet",
    "args": <(int)玩家角色id>,
}

args: 玩家角色的 id。

返回 code=0 表示登录成功，返回 data：

{
    "id": <(int)对象id>,
    "name": <(str)角色名字>,
    "icon": <(str)角色图标>,
    "state": <(dict)角色状态>,
    "location": <(dict)角色所在位置>,
    "look_around": <(dict)角色周围环境>,
    "at_arrive": <(list)到达当前房间的信息>(可选),
    "revealed_maps": <(dict)角色已开启的地图>,
    "channels": <(dict)可用的交流频道>,
    "equipment_pos": <(list)可装备的位置>,
    "min_honour_level": <(int)可以参加荣誉战斗的最低等级>,
    "is_staff": <(bool)是否是管理人员>(可选),
    "last_combat": <(dict)最后未完的战斗>(可选)
}

id

对象的id。请注意，对象id和玩家角色id是不一样的的。玩家角色id是保存在数据库中的，在创建完角色之后就不会改变；对象id是服务器中创建的对象的id，角色登录期间不会变化，但每次登录后都会发生变化。

name

玩家角色显示的名字。

icon

玩家角色的图标信息，如图标的名字、路径，如果没有则为空。

state

玩家角色的状态，格式为：

{
    <状态1的名称>: <状态1的值>,
    <状态2的名称>: <状态2的值>,
    ...
}

location

玩家角色所在位置，格式为：

{
    "area": <(str)所在区域的id>,
    "room": <(str)所在房间的id>
}

格式与 traverse 返回的 location 相同，可参见 traverse 。

look_around

玩家角色所在房间的环境信息，格式为：

{
    "players": [   // 房间中的其他玩家
        {
            "id": <(int)对象id>,
            "name": <(str)显示的名字>,
            "icon": <(str)显示的图标>(可选)
        },
        ...
    ],
    "npcs": [      // 房间中的NPC
        {
            "id": <(int)对象id>,
            "name": <(str)显示的名字>,
            "icon": <(str)显示的图标>(可选)
        },
        ...
    ]
}

格式与 traverse 返回的 look_around 相同，可参见 traverse 。

at_arrive

玩家角色在进入当前房间时可能有一些信息需要显示给用户。格式为：

[
    <(str)信息文本>,
    ...
]

格式与 traverse 返回的 at_arrive 相同，可参见 traverse 。

revealed_maps

玩家角色已开启的地图，格式为：

{
    <(str)地图区域1的key>: true,
    <(str)地图区域2的key>: true,
    ...
}

channels

玩家角色可用的聊天频道，格式为：

{
    <(str)频道1的key>: {
       "type": <(str)频道类型>,
       "name": <(str)频道名称>
    },
    <(str)频道2的key>: {
       "type": <(str)频道类型>,
       "name": <(str)频道名称>
    },
    ...
}

equipment_pos

玩家角色可以穿着装备的位置，格式为：

[
    {
        "key": <(str)位置的key>,
        "name": <(str)位置的名称>,
        "desc": <(str)位置的描述信息>
    },
    ...
]

min_honour_level

玩家角色可以参加荣誉战的最低等级，只有达到这个等级才能参与荣誉战。等级可以在管理平台配置。

is_staff

是否是管理员。管理员账号创建的角色拥有一些特殊的功能。

last_combat

最后未完的战斗。如果玩家角色在战斗中退出，再次登入时如果战斗还没结束，可以继续之前未完成的战斗。如果没有需要继续的战斗话则为空。数据格式为：

{
    "combat_info": {       // 战斗信息
        "desc": <(str)战斗的描述信息>,
        "timeout": <(int)战斗的最长时间(单位:秒)>,
        "characters": [    // 参与战斗的角色
            {
                "id": <(int)对象id>,
                "key": <(str)对象的key>,
                "name": <(str)对象的名称>,
                "desc": <(str)角色的描述信息>,
                "icon": <(str)角色的图标>(可选),
                "team": <(int)对象所属队伍的id>
            }
        ],
        ...
    },
    "combat_commands": [   // 战斗中可用的技能
        {
            "key": <(str)技能的key>,
            "name": <(str)技能的名称>,
            "cd": <(int)技能的CD时间>,
            "icon": <(str)技能的图标>(可选)
        },
        ...
    ],
    "combat_states": {     // 战斗中各个对象的状态信息
        <(int)对象id>: {
            "id": <(int)对象id>,
            <属性1的key>: <属性1的值>,
            <属性2的key>: <属性2的值>,
            ...
        }
    }
}

7.3.7. puppet_name¶

通过角色名字登录角色。

命令格式：

{
    "cmd": "puppet_name",
    "args": <(str)玩家角色的名字>,
}

args: 玩家角色的名字。

返回 code=0 表示登录成功，返回 data 与 puppet 相同。

7.3.8. unpuppet¶

登出当前登录的玩家角色。

命令格式：

{
    "cmd": "unpuppet",
}

返回 code=0 表示登出角色成功。

7.3.9. char_all¶

查询当前账号下的所有角色。

命令格式：

{
    "cmd": "char_all",
}

返回 code=0 表示查询成功，返回 data：

[
    {
        "id": <(int)玩家角色id>,
        "name": <(str)玩家角色名字>
    }
    ...
]

7.3.10. logout¶

登出当前账号。

命令格式：

{
    "cmd": "logout",
}

返回 code=0 表示登出账号成功。

7.3.11. query_map¶

查询地图信息。

命令格式：

{
    "cmd": "query_map",
}

返回 code=0 表示查询成功，返回 data：

{
    <(str)区域的key>: {
        "key": <(str)区域的key>,
        "name": <(str)区域的名字>,
        "desc": <(str)区域的描述信息>,
        "icon": <(str)区域的图标>(可选),
        "background": <(str)区域的背景图>(可选),
        "rooms": <(dict)区域中的所有房间>
    },
    ...
}

key

区域的唯一标志。

name

区域显示的名称。

desc

区域的描述信息。

icon

区域的图标信息，如图标的名字、路径，如果没有则为空。

background

区域的背景图信息，如背景图的名字、路径，没有则为空。

rooms

区域中的所有房间，格式为：

{
    <(str)房间的key>: {
        "key": <(str)房间的key>,
        "name": <(str)房间的名字>,
        "desc": <(str)房间的描述信息>,
        "icon": <(str)房间的图标>(可选),
        "background": <(str)房间的背景图>(可选),
        "peaceful": <(bool)是否是和平房间>,
        "pos": <(any)房间所在的位置>,
        "objects": <(list)房间中的物体>,
        "exits": <(list)房间的出口>
    },
    ...
}

key

房间的唯一标志。

name

房间显示的名称。

desc

房间的描述信息。

icon

房间的图标信息，如图标的名字、路径，如果没有则为空。

background

房间的背景图信息，如背景图的名字、路径，没有则为空。

peaceful

是否是和平房间，在和平房间内不允许玩家互相战斗。

pos

房间所在的位置信息，默认是房间的二维坐标，也可以定义成其他形式。

objects

房间中的所有物体，物体是固定在房间中不能移动位置的。格式为：

[
    {
        "key": <(str)物体的key>,
        "name": <(str)物体的名字>,
        "desc": <(str)物体的描述信息>,
        "icon": <(str)物体的图标>(可选),
    }
    ...
]

exits

房间中的所有出口，玩家可以通过出口去往另一个房间。格式为：

[
    {
        "key": <(str)出口的key>,
        "name": <(str)出口的名字>,
        "desc": <(str)出口的描述信息>,
        "icon": <(str)出口的图标>(可选),
        "destination": <(str)出口目的地的key>
    }
    ...
]

7.4. 角色命令¶

用户登录角色后，可以使用角色命令。

7.4.1. look_room_obj¶

观察当前房间内的物体。

命令格式：

{
    "cmd": "look_room_obj",
    "args": <(str)物体的key>
}

args: 想要观察的物体的key。

返回 code=0 表示观察成功，返回 data：

{
    "key": <(str)物品的key>,
    "name": <(str)物品的名字>,
    "level": <(int)物品的等级>,
    "desc": <(str)物品的描述信息>,
    "icon": <(str)物品的图标>(可选),
    "cmds": <(list)可对物品使用的命令>
}

key

物品的标志，同类物品据有相同的key。

name

物品的名字。

level

物品的等级，如果为空表示该物品没有等级变化。

desc

物品的描述信息。

icon

物品的图标信息，如图标的名字、路径，如果没有则为空。

cmds

可以对物品使用的命令，前端界面需要把命令展示出来，供用户操作。格式为：

{
    "cmd": <(str)命令的id>,
    "name": <(str)命令显示的名字>,
    "args": <(any)命令的参数>,
    "confirm": <(bool或str)确认信息>
}

cmd: 命令的唯一id。
name: 显示给用户看的命令名字。
args: 向后台发送命令时需要完整地带上 args 中的参数。
confirm: 命令的确认信息。如果为空或为 false，表示命令不需要确认可以直接发送到后端，如果为字符串或为 true，用户选择了该命令后，前端需要弹出确认框让用户确认后才能发送到后端，如果为字符串需要在确认信息中显示字符串的内容，如果为 true 需要显示默认的确认信息。

7.4.2. look_room_char¶

观察当前房间内的角色。

命令格式：

{
    "cmd": "look_room_char",
    "args": <(int)对象id>
}

args:: 想要观察的角色对象的id。

返回 code=0 表示观察成功，返回 data：

{
    "key": <(str)角色对象的key>,
    "name": <(str)角色对象的名字>,
    "level": <(int)角色对象的等级>,
    "desc": <(str)角色对象的描述信息>,
    "icon": <(str)角色对象的图标>(可选),
    "cmds": <(list)可对角色对象使用的命令>
}

与 look_room_obj 返回的物品信息相同，请参见 look_room_obj 。

7.4.3. traverse¶

穿越出口。

命令格式：

{
    "cmd": "traverse",
    "args": <(str)出口的key>
}

args:: 出口的唯一标志。

返回 code=0 表示已执行操作，返回 data：

{
    "traversed": <(bool)是否穿越成功>,
    "location": <(dict)目的地信息>(如果穿越成功),
    "look_around": <(dict)目的地环境>(如果穿越成功),
    "at_leave": <(list)离开之前房间的信息>(如果穿越成功,可选),
    "at_arrive": <(list)到达当前房间的信息>(如果穿越成功,可选),
    "exit": <(dict)出口的信息>(如果穿越不成功),
    "events": <(list)触发的事件>(可选),
    "quests": <(list)影响的任务>(可选)
}

traversed

是否成功穿越了出口。

location

如果穿越成功会返回目的地的位置。格式为：

{
    "area": <(str)目的地区域的key>,
    "room": <(str)目的地房间的key>
}

look_around

如果穿越成功会返回目的地的环境。格式为：

{
    "players": [   // 房间中的其他玩家
        {
            "id": <(int)对象id>,
            "name": <(str)显示的名字>,
            "icon": <(str)显示的图标>(可选)
        },
        ...
    ],
    "npcs": [      // 房间中的NPC
        {
            "id": <(int)对象id>,
            "name": <(str)显示的名字>,
            "icon": <(str)显示的图标>(可选)
        },
        ...
    ]
}

at_leave

如果穿越成功，在离开之前房间时可能有一些信息需要显示给用户。格式为：

[
    <(str)信息文本>,
    ...
]

at_arrive

如果穿越成功，在进入当前房间时可能有一些信息需要显示给用户。格式为：

[
    <(str)信息文本>,
    ...
]

exit

如果穿越不成功，会返回出口的信息。格式为：

{
    "key": <(str)出口的key>,
    "name": <(str)出口的名字>,
    "desc": <(str)出口的描述信息>,
    "icon": <(str)出口的图标>(可选),
    "destination": <(str)出口目的地的key>
}

与 look_room_obj 返回的物品信息相同，请参见 look_room_obj 。

events

如果玩家的行动触发了事件，会返回相关事件的信息。格式为：

[
    {
        <事件动作的id>: <(any)事件动作的信息>
    }
    ...
]

quests

如果玩家的行动引起任务目标达成，会返回相关的任务信息。格式为：

{
    "accomplished": [   // 达成的任务
        {
            "key": <(str)任务的key>,
            "name": <(str)任务的名字>,
        },
        ...
    ]
}

7.4.4. unlock_exit¶

解锁出口。如果出口已上锁，符合条件的玩家可以解锁出口。

命令格式：

{
    "cmd": "unlock_exit",
    "args": <(str)出口的key>
}

args:: 出口的唯一标志，出口必须和玩家在同一房间内。

返回 code=0 表示已执行操作，返回 data：

{
    "unlocked": <(bool)是否解锁成功>,
    "exit": {      // 解锁后出口的样子
        "key": <(str)出口的key>,
        "name": <(str)出口的名字>,
        "level": <(int)出口的等级>,
        "desc": <(str)出口的描述信息>,
        "icon": <(str)出口的图标>(可选),
        "cmds": <(list)可对出口使用的命令>
    }
}

unlocked: 是否解锁成功
exit: 解锁后出口的样子，格式与 look_room_obj 返回的物品信息相同，请参见 look_room_obj 。

7.4.5. inventory¶

查询背包的信息。

命令格式：

{
    "cmd": "inventory",
}

返回 code=0 表示查询成功，返回 data：

[
    {
        "position": <(int)物品在背包中的位置>,
        "number": <(int)物品的数量>,
        "can_remove": <(bool)是否可以删除该物品>,
        "name": <(str)物品的名字>,
        "level": <(int)物品的等级>,
        "desc": <(str)物品的描述信息>,
        "icon": <(str)物品的图标>(可选)
    }
    ...
]

position: 物品在背包中的位置，位置的数字不一定连续，应该按位置的先后次序显示物品。
number: 物品的数量，可以为0。
can_remove: 当物品数量为0时是否可以删除该物品，如果 can_remove 为 false，即使物品数量为 0 也需要显示该物品。
name: 物品的名字。
level: 物品的等级，如果为空表示该物品没有等级变化。
desc: 物品的描述信息。
icon: 物品的图标信息，如图标的名字、路径，如果没有则为空。

7.4.6. inventory_obj¶

查询背包中物品的信息。

命令格式：

{
    "cmd": "inventory_obj",
    "args": <(int)物品在背包中的位置>
}

args: 物品在背包中的位置，即背包物品的 position。

返回 code=0 表示查询成功，返回 data：

{
    "key": <(str)物品的key>,
    "name": <(str)物品的名字>,
    "level": <(int)物品的等级>,
    "desc": <(str)物品的描述信息>,
    "icon": <(str)物品的图标>(可选),
    "cmds": <(list)可对物品使用的命令>
}

格式与 look_room_obj 返回的物品信息相同，请参见 look_room_obj 。

7.4.7. use¶

使用背包中的物品。

命令格式：

{
    "cmd": "use",
    "args": {
        position: <(int)物品在背包中的位置>
    }
}

position: 物品在背包中的位置，即背包物品的 position。

返回 code=0 表示使用成功，返回 data：

null
或
{
    "msg": <(str)使用的结果>,
    "state": <(dict)角色状态>
}

null

表示没有任何效果。

msg

用文字描述的使用效果。

state

使用后的角色状态，格式为：

{
    <状态1的名称>: <状态1的值>,
    <状态2的名称>: <状态2的值>,
    ...
}

格式与 puppet 返回的 state 相同，请参见 puppet 。

7.4.8. discard¶

丢弃背包中的物品。

命令格式：

{
    "cmd": "discard",
    "args": {
        position: <(int)物品在背包中的位置>
    }
}

position: 物品在背包中的位置，即背包物品的 position。

返回 code=0 表示丢弃成功。

7.4.9. all_equipments¶

查询已装备的物品。

命令格式：

{
    "cmd": "all_equipments",
}

返回 code=0 表示查询成功，返回 data：

{
    <(str)装备的位置>: {
        "name": <(str)物品的名字>,
        "level": <(int)物品的等级>,
        "desc": <(str)物品的描述信息>,
        "icon": <(str)物品的图标>(可选)
    },
    ...
}

装备的位置: 即 puppet 中返回的 equipment_pos 玩家角色可以穿着装备位置的 key。
name: 物品的名字。
level: 物品的等级，如果为空表示该物品没有等级变化。
desc: 物品的描述信息。
icon: 物品的图标信息，如图标的名字、路径，如果没有则为空。

7.4.10. equipments_obj¶

查询已装备物品的信息。

命令格式：

{
    "cmd": "equipments_obj",
    "args": <(str)装备的位置>
}

args: 即 all_equipments 中返回的装备位置中的一个。

返回 code=0 表示查询成功，返回 data：

{
    "key": <(str)物品的key>,
    "name": <(str)物品的名字>,
    "level": <(int)物品的等级>,
    "desc": <(str)物品的描述信息>,
    "icon": <(str)物品的图标>(可选),
    "cmds": <(list)可对物品使用的命令>
}

格式与 look_room_obj 返回的物品信息相同，请参见 look_room_obj 。

7.4.11. equip¶

装备背包中的物品。

命令格式：

{
    "cmd": "equip",
    "args": {
        position: <(int)物品在背包中的位置>
    }
}

position: 物品在背包中的位置，即背包物品的 position。

返回 code=0 表示装备成功，返回 data：

{
    "state": <(dict)角色状态>
}

state

装备后的角色状态，格式为：

{
    <状态1的名称>: <状态1的值>,
    <状态2的名称>: <状态2的值>,
    ...
}

格式与 puppet 返回的 state 相同，请参见 puppet 。

7.4.12. takeoff¶

卸下已装备的物品。

命令格式：

{
    "cmd": "takeoff",
    "args": {
        position: <(str)装备的位置>
    }
}

position: 即 all_equipments 中返回的装备位置中的一个。

返回 code=0 表示成功卸下，返回 data：

{
    "state": <(dict)角色状态>
}

state

卸下后的角色状态，格式为：

{
    <状态1的名称>: <状态1的值>,
    <状态2的名称>: <状态2的值>,
    ...
}

格式与 puppet 返回的 state 相同，请参见 puppet 。

7.4.13. loot¶

从对象拾取物品。

命令格式：

{
    "cmd": "loot",
    "args": <(str)对象的key>
}

args: 拾取的对象必须和玩家在同一个房间，参数为对象的key。

返回 code=0 表示拾取成功，返回 data：

{
    "objects": [
        {
            "key": <(str)获得物品的key>,
            "name": <(str)获得物品的名字>,
            "icon": <(str)获得物品的图标>(可选),
            "number": <(int)获得物品的数量>,
            "reject": <(str)无法获得物品的原因>
        },
        ...
    ],
    "quests": <(list)影响的任务>(可选)
}

key: 获得物品的key。
name: 获得物品的名字。
icon: 获得物品的图标信息，如图标的名字、路径，如果没有则为空。
number: 获得物品的数量。
reject: 如果无法拾取物品，会返回无法拾取的原因。
quests: 如果玩家拾取物品引起任务目标达成，会返回相关的任务信息。格式与 traverse 返回的 quests 相同，请参见 traverse 。

7.4.14. all_skills¶

查询玩家当前的所有技能。

命令格式：

{
    "cmd": "all_skills"
}

返回 code=0 表示查询成功，返回 data：

[
    {
        "key": <(str)技能的key>,
        "name": <(str)技能的名字>,
        "desc": <(str)技能的描述信息>,
        "icon": <(str)技能的图标>(可选),
        "cmds": <(list)可对技能使用的命令>,
        "passive": <(bool)是否是被动技能>,
        "cd": <(int)技能的CD时间>
    },
    ...
]

key、name、desc、icon、cmds: 格式与 look_room_obj 返回的物品信息相同，请参见 look_room_obj 。
passive: 是否是被动技能，被动技能不能手动施放。
cd: 技能的CD时间，单位为秒。

7.4.15. query_skill¶

查询技能信息。

命令格式：

{
    "cmd": "query_skill",
    "args": {
        "key": <(str)技能的key>
    }
}

返回 code=0 表示查询成功，返回 data：

{
    "key": <(str)技能的key>,
    "name": <(str)技能的名字>,
    "desc": <(str)技能的描述信息>,
    "icon": <(str)技能的图标>(可选),
    "cmds": <(list)可对技能使用的命令>,
    "passive": <(bool)是否是被动技能>,
    "cd": <(int)技能的CD时间>
}

格式与 all_skills 返回列表中单个的任务信息相同，请参见 all_skills 。

7.4.16. cast_skill¶

在非战斗状态下施放技能。

命令格式：

{
    "cmd": "cast_skill",
    "args":{
        "skill": <(str)技能的key>,
        "target": <(int)施放对象>(可选)
    }
}

skill: 技能的key
target: 如果对特定对象使用技能，传入施放对象的 id，如果对自己使用技能或者是不需要对象的技能，则不传该参数。

返回 code=0 表示施放成功，返回 data：

{
    "skill_cd": {      // 技能CD信息
        "skill": <(str)技能的key>,
        "cd": <(float)技能的CD>,
        "gcd": <(float)公共CD>
    },
    "result": {        // 技能施放结果
        "skill": <(str)技能的key>,
        "main_type": <(str)技能的主类型>,
        "sub_type": <(str)技能的次类型>,
        "caller": <(int)技能施放者的id>,
        "target": <(int)技能施放目标的id>(可选),
        "states": <(dict)技能施放后相关对象的状态>,
        "cast": <(str)施放技能的文字描述信息>,
        "result": <(str)技能施放结果的文字描述信息>
    }
}

skill

技能的唯一标志。

cd

技能的CD时间，单位为秒。

gcd

公共CD时间，单位为秒。

main_type

技能主类型，如攻击、治疗、控制等。

main_type

技能主类型，如攻击、治疗、控制等，没有则为空。

sub_type

技能次类型，如攻击、治疗、控制等，没有则为空。

caller

技能施放者的角色对象id。

target

技能施放目标的角色对象id，没有则为空。

states

技能施放后相关对象的状态，格式为：

{
    <角色对象id>: {
        <状态1的名称>: <状态1的值>,
        <状态2的名称>: <状态2的值>,
        ...
    },
    ...
}

cast

施放技能的文字描述信息，可以展示给玩家。

result

技能施放结果的文字描述信息，可以展示给玩家。

7.4.17. all_quests¶

查询玩家当前的所有任务。

命令格式：

{
    "cmd": "all_quests"
}

返回 code=0 表示查询成功，返回 data：

[
    {
        "key": <(str)任务的key>,
        "name": <(str)任务的名字>,
        "desc": <(str)任务的描述信息>,
        "cmds": <(list)可对任务使用的命令>,
        "icon": <(str)任务的图标>(可选),
        "objectives": <(list)>任务需要完成的目标>
    },
    ...
]

key、name、desc、icon、cmds

格式与 look_room_obj 返回的物品信息相同，请参见 look_room_obj 。

objectives

任务需要完成的目标，格式为：

[
    {
        "target": <(str)目标达成的方式>,
        "object": <(str)目标对象的名字>,
        "accomplished": <(int)已经达成的数量>,
        "total": <(int)总共需要达成的数量>
    },
    ...
]

7.4.18. query_quest¶

查询任务信息。

命令格式：

{
    "cmd": "query_quest",
    "args": {
        "key": <(str)任务的key>
    }
}

返回 code=0 表示查询成功，返回 data：

{
    "key": <(str)任务的key>,
    "name": <(str)任务的名字>,
    "desc": <(str)任务的描述信息>,
    "cmds": <(list)可对任务使用的命令>,
    "icon": <(str)任务的图标>(可选),
    "objectives": <(list)>任务需要完成的目标>
}

格式与 all_quests 返回列表中单个的任务信息相同，请参见 all_quests 。

7.4.19. give_up_quest¶

放弃任务。

命令格式：

{
    "cmd": "give_up_quest",
    "args": <(str)任务的key>
}

args: 任务的唯一标志。

返回 code=0 表示放弃成功，返回 data：

{
    "key": <(str)任务的key>,
    "name": <(str)任务的名字>
}

key: 任务的唯一标志。
name: 任务显示的名字。

7.4.20. talk¶

和NPC对话。

命令格式：

{
    "cmd": "talk",
    "args": <(int)NPC对象的id>
}

args: 对话NPC对象的id，NPC必须和玩家在同一个房间内。

返回 code=0 表示对话成功，返回 data：

{
    "target": {        // 对话的对象
        "id": <(int)对象id>,
        "name": <(str)显示的名字>,
        "icon": <(str)显示的图标>(可选)
    },
    "dialogues": [     // 对话
        {
            "key": <(str)对话的key>,
            "content": <(str)对话的内容>
        },
        ...
    ]
}

id: 对话NPC对象的id。
name: 对话NPC对象的名字。
icon: 对话NPC对象的图标信息，如图标的名字、路径，如果没有则为空。
key: 对话的唯一标志。
content: 对话的文本内容。

7.4.21. finish_dialogue¶

完成当前的对话。

命令格式：

{
    "cmd": "finish_dialogue",
    "args": {
        "dialogue": <(str)对话的key>,
        "npc": <(int)NPC对象的id>,
    }
}

dialogue: 当前正在进行的对话的key。
npc: 当前正在对话的NPC对象的id。

返回 code=0 表示成功，返回 data：

{
    "dialogue": <(dict)后续对话>,
    "events": <(list)触发的事件>(可选),
    "quests": <(list)影响的任务>(可选)
}

dialogue: 如果结束当前对话后还有后续对话，返回后续的对话内容。格式与 talk 返回的信息相同，请参见 talk 。
events: 如果玩家的对话触发了事件，会返回相关事件的信息。格式与 traverse 返回的 events 相同，请参见 traverse 。
quests: 如果玩家的对话引起任务目标达成，会返回相关的任务信息。格式与 traverse 返回的 quests 相同，请参见 traverse 。

7.4.22. say¶

对目标说话。

命令格式：

{
    "cmd": "say",
    "args": {
        "type": <(str)目标类型>,
        "target": <(any)目标的id>,
        "msg": <(str)说话的内容>
    }
}

type

目标的类型。

target

目标的id。

msg

说话的内容，为一串文本。

支持的目标有以下几种：

type	target
PRIVATE	(int)玩家角色id	向指定的玩家私聊
LOCAL	(str)房间的key	在当前房间内说话
CHANNEL	(str)频道的key	在指定频道内说话

返回 code=0 表示成功。

7.4.23. shopping¶

打开商店。

命令格式：

{
    "cmd": "shopping",
    "args": {
        "npc": <(int)NPC对象的id>,
        "shop": <(str)商店的key>,
    }
}

npc: NPC对象的id，NPC必须和玩家在同一房间内。
shop: 商店的key，必须是NPC拥有的商店。

返回 code=0 表示执行成功，返回 data：

{
    "key": <(str)商店的key>,
    "name": <(str)商店的名字>,
    "level": <(int)商店的等级>(可选),
    "desc": <(str)商店的描述信息>,
    "icon": <(str)商店的图标>(可选),
    "cmds": <(list)可对物品使用的命令>,
    "npc": <(int)商店所属NPC对象的id>,
    "goods": <(list)商品列表>
}

key、name、level、desc、icon、cmds

格式与 look_room_obj 返回的物品信息相同，请参见 look_room_obj 。

npc

商店所属NPC对象的id。

goods

商店中售卖的商品列表，格式为：

[
    {
        "index": <(int)商品的序号>,
        "obj": <(str)商品的key>,
        "level": <(int)商品的等级>,
        "name": <(str)商品的名字>,
        "desc": <(str)商品的描述信息>,
        "number": <(int)商品的数量>,
        "price": <(int)商品的价格>,
        "unit": <(str)商品的计价单位>,
        "icon": <(str)商品的图标>(可选),
    },
    ...
]

index

商品的序号。

obj

商品的唯一标志。

level

商品的等级。

name

商品的名字。

desc

商品的描述信息。

number

购买一次可以得到的商品数量。

price

商品的价格。商品是用其他物品计价的，商品的价格即扣除其他物品的数量，购买一个单位的商品就会扣除相应数量的其他物品。

unit

商品的计价单位。商品是用其他物品计价的，商品的计价单位即其他物品，购买一个单位的商品就会扣除相应数量的其他物品。

icon

商品的图标信息，如图标的名字、路径，如果没有则为空。

7.4.24. buy¶

从商店购买商品。

命令格式：

{
    "cmd": "buy",
    "args": {
        "npc": <(int)NPC对象的id>,
        "shop": <(str)商店的key>,
        "goods": <(int)商品的序号>,
    }
}

npc: NPC对象的id，NPC必须和玩家在同一房间内。
shop: 商店的key，必须是NPC拥有的商店。
goods: 商品的序号，即 shopping 命令返回的商品序号。

返回 code=0 表示购买成功，返回 data：

{
    "use": <(list)使用的物品>,
    "get": <(list)收到的物品>
}

use

购买商品所使用的物品列表，格式为：

[
    {
        "object": <(str)使用物品的key>,
        "number": <(int)使用物品的数量>
    },
    ...
]

get

购买的到的商品列表，格式与 loot 返回的数据相同，请参见 loot 。

7.4.25. get_revealed_maps¶

查询玩家已开启的地图。

命令格式：

{
    "cmd": "get_revealed_maps"
}

返回 code=0 表示查询成功，返回 data：

{
    <(str)地图区域1的key>: true,
    <(str)地图区域2的key>: true,
    ...
}

格式与 puppet 返回的 revealed_maps 相同，可参见 puppet 。

7.5. 战斗命令¶

和战斗相关的命令。

7.5.1. attack¶

攻击某个角色。

命令格式：

{
    "cmd": "attack",
    "args": <(int)角色对象的id>
}

args:: 角色对象的id。

返回 code=0 表示攻击成功，返回 data：

{
    "from": <(str)攻击发起者的名字>,
    "target": <(str)被攻击者的名字>,
    "combat_info": {       // 战斗的基本信息
        {
            "desc": <(str)战斗的描述信息>,
            "timeout": <(int)战斗的最长时间>,
            "characters": <(list)参与战斗的所有角色>
        }
    },
    "combat_commands": <(list)该角色可在战斗中使用的技能>,
    "combat_states": <(dict)战斗相关所有角色的状态>
}

from

发起攻击的角色的名字。

target

被攻击的角色的名字。

desc

战斗的描述信息。

timeout

战斗的最长时间，单位为秒。如果设定了最长时间，到时间结束还未分出胜负，战斗会强制结束并判为平局。如果没有时间或时间为0，表示没有最长战斗时间的限制。

characters

参与战斗的所有角色，格式为：

[
    {
        "id": <(int)对象id>,
        "key": <(str)对象的key>,
        "name": <(str)对象的名称>,
        "desc": <(str)角色的描述信息>,
        "icon": <(str)角色的图标>(可选),
        "team": <(int)对象所属队伍的id>
    },
    ...
]

id: 角色对象的id。
key: 物品的标志，同类物品据有相同的key。
name: 物品的名字。
level: 物品的等级，如果为空表示该物品没有等级变化。
desc: 物品的描述信息。
icon: 物品的图标信息，如图标的名字、路径，如果没有则为空。
team: 角色对象所属的队伍编号，队伍编号相同的角色属于同一支队伍。

combat_commands

玩家角色在战斗中可以使用的技能信息。格式为：

[
    {
        "key": <(str)技能的key>,
        "name": <(str)技能的名称>,
        "cd": <(int)技能的CD时间>,
        "icon": <(str)技能的图标>(可选)
    },
    ...
]

combat_states

战斗中所有相关角色的状态信息。格式为：

{
    <(int)对象id>: {
        "id": <(int)对象id>,
        <属性1的key>: <属性1的值>,
        <属性2的key>: <属性2的值>,
        ...
    }
}

7.5.2. cast_combat_skill¶

在战斗状态下施放技能。

命令格式：

{
    "cmd": "cast_combat_skill",
    "args": {
        "skill": <(str)技能的key>,
        "target": <(int)施放对象>(可选)
    }
}

skill: 技能的key
target: 如果对特定对象使用技能，传入施放对象的 id，如果对自己使用技能或者是不需要对象的技能，则不传该参数。

返回 code=0 表示施放成功。考虑到战斗的平衡性及网络延迟，技能的施放结果通过专门的 combat_skill_cast 消息发送给所有的战斗相关方。该命令只在 data 中返回技能CD的信息：

{
    "skill_cd": {      // 技能CD信息
        "skill": <(str)技能的key>,
        "cd": <(float)技能的CD>,
        "gcd": <(float)公共CD>
    }
}

skill: 技能的唯一标志。
cd: 技能的CD时间，单位为秒。
gcd: 公共CD时间，单位为秒。

7.5.3. leave_combat¶

当玩家角色处于战斗状态时，脱离战斗状态。

命令格式：

{
    "cmd": "leave_combat"
}

返回 code=0 表示脱离成功，返回 data：

{
    "state": <(dict)角色状态>
}

state

脱离战斗后的角色状态，格式为：

{
    <状态1的名称>: <状态1的值>,
    <状态2的名称>: <状态2的值>,
    ...
}

格式与 puppet 返回的 state 相同，请参见 puppet 。

7.5.4. query_rankings¶

查询荣誉战斗排名，默认会返回排名最高的玩家以及和自己排名相近的玩家的情况。可以在游戏编辑器中设置返回玩家的数量。

命令格式：

{
    "cmd": "query_rankings"
}

返回 code=0 表示查询成功，返回 data：

[
    {
        "name": <(str)玩家角色的名字>,
        "id": <(int)玩家角色的id>,
        "ranking": <(int)玩家角色的排名>,
        "honour": <(int)玩家角色的荣誉值>
    },
    ...
]

name: 玩家角色显示的名字。
id: 玩家角色的id
ranking: 玩家角色的排名。
honour: 玩家角色的荣誉值。

7.5.5. queue_up_combat¶

排队参加荣誉战斗，匹配对手。

命令格式：

{
    "cmd": "queue_up_combat"
}

返回 code=0 表示加入排队。

7.5.6. quit_combat_queue¶

取消参加荣誉战斗的排队，当玩家角色已进入排队并且没有匹配到对手时可以取消排队。

命令格式：

{
    "cmd": "quit_combat_queue"
}

返回 code=0 表示取消成功。

7.5.7. confirm_combat¶

荣誉战斗匹配到对手后，确认加入战斗。

命令格式：

{
    "cmd": "confirm_combat"
}

返回 code=0 表示确认成功。

7.5.8. reject_combat¶

荣誉战斗匹配到对手后，拒绝加入战斗。

命令格式：

{
    "cmd": "reject_combat"
}

返回 code=0 表示拒绝成功。