ev API


Evennia由许多部件组成,其中一些的交互方式非常复杂。举个例子,类型类系统就由 src/ 目录下的4个不同目录构成。这样做是为了提高效率、避免代码重复,但也会造成理解上的混乱,难以弄清部件的连接方式,而且当你想使用某个游戏模块时难以知道它到底继承、使用了哪些属性。

Evennia的ev API(应用编程接口)就是用来解决这个问题的。 ev.py 在evennia的根目录下,因此在你的代码中可以直接用 import ev 来导入它。ev 模块基本实现了访问 src/ 内部组件的快捷方式,其目标就是提供一个简单的“平面”结构(不是深层的嵌套结构)。这不仅是Python的建议,同时还可以让你很容易地弄清楚哪些东西是可用的。


探索ev

如果你想用交互的方式查看evennia,建议你使用高级Python解释器,如ipython。在ipython中你可以轻松查看模块头部和说明信息,它还有自动补全功能。

在 game/ 目录中输入以下内容,可以直接启动针对Evennia配置的shell(如果你正确安装的话,它会使用ipython):
python manage.py shell
这将设置Evennia和Django所需的所有环境变量(参见这里)。在这个python shell中导入ev 模块:
import ev
如果你使用ipython,你可以输入如 ev? 之类的命令查阅API的说明信息,使用如 ev.Object? 之类的命令查阅对象类型类的文档。输入 ev.default_cmds.CmdLook?? 可以看默认look命令的源代码。你也可以先输入 ev. 然后按键,看看ev包含哪些内容。tab键补全功能对搜索代码很有用。


重点

  • Object、Player、Script、Room、Character、Exit —— 它们直接链接到Evennia中最常见的基类。
  • search_* —— 搜索 src.utils.search 中函数的快捷方式,例如search_object()或search_script()
  • create_* —— 创建对象函数的快捷方式。请注意,所有类型类对象必须用这种方法(或用src.utils.create中的父类方法)创建,只有这样才能让类型类正确工作。
  • managers —— 这是一个容器对象,包含连接到已初始化的Evennia的Django管理器的快捷方式。所以managers.objects实际上就相当于ObjectDB.objects,你可以用managers.objects.all()来获取所有数据库对象的列表。managers允许以多种不同方式探索数据库。从ev导入managers,就可以通过managers对象与所需的管理器建立连接。
  • default_cmds —— 这是一个ev容器,集合了所有的默认命令和命令集。从ev导入default_cmds,然后你就可以通过default_cmds对象访问任何默认命令了。
  • utils、logger、gametime、ansi 是各种实用程序。特别是utils包含了文档编码工具中所说的许多有用的函数。
  • syscmdkeys是一个容器,它包含所有用于定义系统命令的关键字。与managers容器类似,导入之后就可以通过syscmdkeys对象使用这些关键字了。


从ev导入时要记住以下下几点

ev 中的属性并不是它自己模块的,它们只是存储在 ev.py 中的快捷方式,因此你不能使用点标记来导入 ev 中嵌套的模块名。按照常规,你导入的层次不能多于一层。因此,你可以这样
import ev print ev.default_cmds.CmdLook
或者导入下面一层
    from ev import default_cmds
    print default_cmds.CmdLook
但你不能导入下面两层
    from ev.default_cmds import CmdLook # 出错!
这样会报导入错误,告诉你模块default_cmds无法找到。这并不奇怪 —— default_cmds 只是 ev.py 模块中的变量名,在 ev.py 之外它并不存在。

只要你记住这一点应该就没什么问题了。如果你真的想完全控制从哪一级导入包,你可以跳过 ev 直接从 src/ 导入。如果要这么做,你可以看看 ev.py 是从哪里导入它的。


(原文:https://github.com/Evennia/evennia/wiki/ev API    翻译:卢铱俊)