帮助系统


在线帮助系统是Evennia的一个重要组成部分。玩家和工作人员都可以通过它了解游戏命令的使用方式及其它信息。帮助系统有许多不同方面,从在游戏中编辑帮助条目的通常方式,到使用自动帮助系统在开发代码时同步生成帮助条目。


查看帮助数据库

主要的命令是 help:
 help [搜索内容]
这会显示帮助条目的列表,按分类排序。你可以看到两部分内容,命令帮助条目和其他帮助项目(在初始状态下你只能看到第一个)。你可以用 help 命令获取某个条目的详细信息,你也可以只给出部分匹配的内容来检索。如果你给出了类别名,那你只看到该类别中的主题。


命令自动帮助系统

帮助系统的一个重要功能就是在游戏中指导使用命令。Evennia为你的所有命令(不管新旧)都提供了会自动更新的帮助系统,它被称为自动帮助系统。自动帮助系统只会显示出你和你的角色当前可用的命令,这就是说管理员使用 help 命令可以看到的帮助主题要比普通玩家多得多。

自动帮助系统会使用命令定义中的文档字符串(__doc__),并将它格式化,生成便于阅读的帮助条目。这给更新帮助信息提供了非常便捷的途径:只要写好命令的文档字符串,然后调用 @reload 就能更新帮助文件了。你不需要手动创建、维护数据库中命令的帮助条目,只要保持更新文档字符串,帮助信息就会自动为你更新好。

例子(来自于定义命令的模块):
    class CmdMyCmd(Command):
        """
        mycmd - 我自己的命令

        用法:
        mycmd[/开关] <参数>

        开关:
        test - 测试命令
        run - 做其他事

        这是我自己的命令,当你给它提供参数,它会为你做事情。
        """
        ...
        help_category = "Building"
        ...
在命令类定义顶端的文本是类的文档字符串,可以给需要帮助的用户提供信息。你应该尽量使用统一的格式。所有默认命令都使用上述的结构。如果可以,你还应该设定类属性 help_category,这可以让帮助条目分组以便于查找(如果你不提供 help_category,则会默认设为“General”)。


其他帮助条目(存储在数据库中的条目)

并非所有的帮助条目都和命令有关。你可能需要有帮助条目说明你的游戏是怎么玩的,包括游戏规则、世界的描述以及其他没有包含在自动帮助系统中的信息。这样的条目需要由工作人员手动添加到数据库中,只要你创建了它,它就会出现在“其他帮助”标题下。因为不是由Evennia从代码中自动生成的,这些条目作为 HelpEntry 存储在数据库中。

一个帮助条目由四部分组成:
  • 主题 —— 这是帮助条目的名称。当玩家搜索帮助时,搜索的就是这个。主题可以包含空格,与搜索内容部分匹配的主题也能被搜索出来。
  • 帮助类别 —— 比如 Administration、Building、Comms 及 General 等等。这可以对主题进行分类,帮助引擎可以用它来提供更好的浏览。
  • 文本 —— 帮助的文本信息,可以是任意长度。
  • 锁 —— 锁的定义。这可以用来限制对该帮助条目的访问,可能因为这是工作人员的专用信息或其他原因所以要作限制。help 命令会检查锁类型 view 和 edit。锁字符串的例子:view:perm(Builders)。

在代码中你可以用 src.utils.create.create_help_entry() 创建新的帮助条目:
    from src.utils import create 
    entry = create.create_help_entry("emote", 
                                     "Emoting is important because ...", 
                                     category="Roleplaying", locks="view:all()")
在游戏中,拥有正确权限的人可以使用 @sethelp 命令添加、修改帮助条目。
> @sethelp/add emote = emote 命令是...
使用 @sethelp 可以创建、删除或追加文本到现有条目。默认情况下,新加条目的帮助类别是 General。给 @sethelp 命令添加参数可更改帮助类别:
> @sethelp/add emote, Roleplaying = 表情很重要,因为...
如果 Roleplaying 类别不存在则会创建它,并会出现在帮助索引中。

最后,你还可以给帮助条目添加锁,在类别后面再加上锁定义就可以了:
> @sethelp/add emote, Roleplaying, view:all() = 表情很重要,因为...


(原文:https://github.com/evennia/evennia/wiki/Help-System    翻译:卢铱俊)