目录概览


evennia/
  ev.py
  contrib/
  docs/
  game/
  locale/
  src/

Evennia的主目录(evennia)分为五个子目录 —— src/ 、game/ 、contrib/ 、 locale/ 和 doc/ 。前两个最重要:game/ 是你创建自己游戏的地方,src/ 存放的是Evennia服务器代码。通常,你应该只从 src/ 导入资源,而不要在哪里修改它。

所有目录中都包含 .py 结尾的文件,它们都是Python模块,是Python代码的基本单位。在这些目录的顶层都有一个名为 __ init__.py 的空文件,这是Python的要求,为的是能够找到并导入其他目录中的模块。当你运行过Evennia之后,你还会发现有 .pyc 文件生成,这些是 .py 文件预编译出的二进制文件,它们可以加快执行速度。

ev.py 应该重点记住,这是Evennia平面API的所在地,它实际上是一套指向 src/ 中各个重要位置的快捷方式。你在 game/ 中写的代码可以导入 ev,这样你就可以访问Evennia系统中最重要的部分而不需要知道它们存放在什么位置。这些位置会在下面的章节叙述。


docs/ 目录

这基本上是空的,因为最新的文档都放在网络维基中了。

你可以按照 doxygen/README 中的指导创建Evennia的自动文档。它可以利用源代码自身为所有源码和注释创建一个不错的可浏览的网页索引。理论上,你还可以用同样的方式为Evennia的源码创建漂亮的 LaTeX 格式的PDF文档(总共有400多页...)。


locale/ 目录

这包含了翻译Evennia核心服务器的不同语言版本的国际化字符串。更多信息请见国际化


contrib/ (“贡献”)目录

这个目录包含了多种独立的代码段,它们都挺有用的,但我们认为这些代码过于专注于特定类型的游戏,因而不适合作为服务器的常规部分。要使用 contrib/ 中的模块,你必须明确地导入并使用它们。contrib文件夹中还带有世界教程游戏的例子。参见 contrib/README 获取更多信息。


game/ 目录

game/ 目录中包含所有与特定游戏相关的东西。如果想开始一个全新的游戏,你可以替换掉 game 目录并从头开始。这个目录的顶层包含了最重要的 manage.py 和 evennia.py,你需要用它们来启动、运行服务器。
game/
  evennia.py
  manage.py
  
  gamesrc/
    commands/
      examples/
    scripts/
      examples/
    objects/
      examples/
    world/
      examples/
    conf/

game/gamesrc/
game/gamesrc 是你花费大部分时间工作的地方。你梦想游戏中所有的东西都应以附加Python模块的形式放在这里。gamesrc 目录中的文件夹都带有 examples 子文件夹,它们从不同方面定义了名为“Red Button”的示例物体。这个按钮会闪烁,按下它时还会做一些有趣的事。它的设计综合了许多不同系统,展示了Evennia的多种高级功能。

gamesrc/commands/
gamesrc/commands/ 目录中包含了定义命令的模块。在 commands/examples 中可以找到帮你自定义的命令和命令集的模板。把它们复制到上一层的 command 文件夹中,在那里修改它们。

gamesrc/scripts/
gamesrc/scripts/ 中的所有东西都和脚本有关。你可以把 scripts/examples 中的模版复制出来,用来定义你自己的脚本。

gamesrc/objects/
gamesrc/objects/ 中应该放入你所有物体的定义。objects/examples 中有物体的模板以及其基本子类 —— 角色、房间和出口的模板。你在定义自己的游戏实体时可以把这些模版复制出来,以此为基础来做开发。

gamesrc/world/
gamesrc/world/ 中包含你游戏世界中的其余东西。你可以在这里放你自己的经济系统、战斗机制、表情解析或其它你拥有的东西;组织结构可以是任何你喜欢的形式。但要记住,如果你在 world 中建立新文件夹,它们必须包含一个空文件 __init__.py,否则Python不知道如何从它们导入模块。Evennia的批量处理器也默认会在 world 中搜索自己的输入文件,它们可以让你用自己喜欢的文本编辑器脱机构建自己的世界,而不必在线用命令行联机输入。命令批处理器使用的是以 .ev 结尾的文件,而更高级的代码批处理器使用的是带有特殊格式的 .py 文件。

world/examples/ 中有这两种批处理文件,它们会用各自的语法在虚空中创建一个红色按钮对象。

gamesrc/conf/
gamesrc/conf/ 中放的是Evennia引擎可选的扩展模块。它默认是空的,但在 conf/examples/ 中有许多可用的服务器配置文件的模板。每个模板中都有使用说明,你可以把想要的文件复制到 conf/ 目录中,并在那里修改它们。


src/ 目录

src/ 中是Evennia服务器运行的主要代码。你可以从这里直接导入文件,但通常使用顶层 ev 模块中的快捷方式会更方便。

你永远也不要直接修改这个文件夹中的任何东西,因为里面的内容可能会被我们发布的更新所覆盖。如果你想将其中的代码用作自己工作的基础(比如要添加新的命令),可以把相关代码复制到 game/gamesrc 路径中你自己的模块里。如果你发现有 bug 或功能遗漏,可以给我们发送bug报告,或给我们发邮件。
src/
  settings_defaults.py

  commands/
  comms/
  help/
  objects/
  locks/
  players/
  scripts/
  server/
    portal/
  typeclasses/
  utils/
  web/
src/ 中的大多数文件夹从技术上讲都是“Django应用程序”。它们的特征是包含有文件 models.py,而且通常带有文件 managers.py、admin.py 和子文件夹 migrations。

Django模型是用于将数据保存到数据库的模板。为了提供全面的持久性支持,模型在Evennia中用得很广,它们在相应的 model.py 文件中定义。managers.py 中包含了用来访问数据库中现有对象的类。admin.py 文件配置Django的Web功能,可以自动建立一个漂亮的基于页面的数据库管理界面,这样你就可以通过浏览器添加、编辑、删除对象了。最后,在 migrations 文件夹中有许多数据库架构的更新文件。当数据库架构发生变化时,south 可以用它们做无缝迁移(这样你就不用为此烦心了)。

在 src 的根目录中有一个 settings_defaults.py 文件,这是Evennia的主配置文件。如果你想自定义什么东西,应该把相关配置信息从这个文件复制粘贴到你的 game/settings.py 文件中。

src/commands/
这个目录中是Evennia的命令系统,它定义了基本命令函数、语法解析、命令集处理及默认的命令集。

commands/default/ 中有大量的模块,它们一起构成了Evennia的默认命令集(MUX风格)。如果你想编辑默认命令,可以把相关模块复制粘贴到 game/gamesrc/commands/ 中,并且修改默认命令集指向你修改的模块(参见命令教程)。

src/comms/
src/comms/ 定义了所有与角色无关的通信,特别是频道、消息以及连接频道和外部接收者的基本操作。

src/help/
这里定义Evennia的帮助系统、命令的自动帮助以及以数据库为中心的游戏内帮助文件。

src/objects/
src/objects/ 定义了如何在数据库中存储、查找、处理游戏中的物体

src/locks/
这个目录定义了强大的Evennia锁系统,它用来限制访问对象。默认的锁函数都可以在这里找到。

src/players/
玩家是连接到游戏的与角色无关的个人。这个目录定义了数据库管理以及和玩家有关的方法。

src/scripts/
src/scripts/ 定义了所有与脚本相关的内容 —— 它们是如何被激活、重复执行、存储在内存或数据库中的。主引擎脚本(如用于跟踪游戏时间、运行时间和连接超时的脚本)也在这里定义。

src/server/
这个目录是Evennia的心脏,其中有自身的服务器进程(从 game/evennia.py 启动)。子文件夹 portal/ 中有接入程序以及所有帮用户连接到游戏的会话和协议

src/typeclasses/
src/typeclasses/ 定义了遍布Evennia各处的类型类系统,让程序员可以和普通Python类交互,而不用关心底层数据库实现。这个目录很少需要直接访问,对象、脚本和玩家都应该继承自各自的核心类。另外属性也在这里定义。

src/utils/
src/utils/ 是一个很有用的目录,它包含了供MUD程序员使用的辅助功能。比如 utils/create.py 模块集中了创建各种数据库模型的方法(包括对象、脚本、帮助项等),这样就不必直接使用相应的数据库管理器了。utils/search.py 为了搜索数据库搜索类似函数。这个目录中还有许多以各种方式解析、转换数据的辅助模块。

src/web/
这个目录中的东西和运行Evennia网站及ajax web客户端有关。它可以由用户自己定义,但目前还没有将它挂接到 game/ 目录的简便方法,所以目前推荐的方法是将这个目录拷贝到 game/gamesrc 中,将 settings 文件中的连接设置到正确路径,然后在那里作修改。


其他事项

即便在 game/gamesrc/ 中已经包含了一套目录,你可能会觉得另一种结构更适合你的开发。比如有时候,将某个对象中需要同时用到的命令和脚本作为对象放在同一模块中,要比机械地将它们分割开放在各自的目录中然后分别导入要简便。不要羞于按照自己的需要定义目录结构。但避免代码重复仍然是基本的经验法则,因此如果某个脚本或命令对其它对象也有用,还是应该将它们分开放到各自的模块中导入。别忘了,如果你要添加新的目录,它必须包含一个 __init__.py 文件(它可以是空的),这样Python才能将它作为导入模块的地方。


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