WorldCompiler

Description

The worldCompiler script takes an input directory structure (also called the "content") and produces output ("compiled") directory structures (one for the server, and one for the client).

Each of the output directory structures is in packageable form. That is, they can be copied to other locations and run without modification.

At the moment this is in development (the script has not yet been released). But I wanted to start on documentation as I went.

Invoking the Compiler

Once you have your input directory structure set up (see "Input Formats" below), you can invoke the world compiler as such:

% worldCompiler --content-directory=/full/path/to/your/input/directory --output-directory=/full/path/to/output/root

There are many other optional parameters, but the content-directory and output-directory parameters are required.

This will look for the master configuration file ("master.txt" by default) in the content directory, and begin parsing.

Input Formats

Directory Structure

The directory structure of the input is completely arbitrary, and is intended to be so. The compiler can determine what to do based on the master configuration file, and by the extension of all files found in the content tree.

That said, for sanity I recommend a simple directory structure like this:

content
|-- behaviors
|   |-- animals
|   `-- core
|-- bin
|-- classes

Behaviors (python scripts for now) are put in the behavior directory. "core" behaviors are those scripts which are independent of the ruleset used and are required for running at all.

.class files go in the classes directory.

Binaries (cyphesis, cyclient, ember) go in the bin directory.

Note that all paths specified in the content tree are assumed to be relative to the content-directory root.

The Master Configuration File

The master.txt file must have these entries:

• world-name (whatever the name of the world should be--this is visible to players)
• ruleset-name (name of the ruleset--used in output configs but not user-visible)
• terrain-file (local path to the terrain file)
• cyphesis-bin (local path to the cyphesis binary to use)
• cyclient-bin (local path to the cyclient binary to use)
• ember-bin (local path to the ember binary to use)

Binary Files

You will need to supply executable binaries for cyphesis, cyclient, and ember. These can be downloaded from the WorldForge website.

TODO: need to figure out how multiple platforms will work. I think game authors will produce different packages for each platform. In practice, that is as simple as swapping out binaries and re-running the compiler.

The Terrain File

The terrain file has a very simple format: it is a list of i,j,z values. For instance, the file could be:

 #
 # Sample Terrain File
 #
 # As with all config files, lines beginning with a hash '#' are ignored
 #
  0   0  5
  1   1  10
 -1  -1  20

This is transformed into executable Python and copied into the define_world.py file. If you want to generate terrain i,j points using an algorithm, do that in a separate script and copy the output to this local file.

Behavior Files

A behavior is a script. One example is an AI script (usually called a "mind" file). Another example is a script used to control behavior of plants. And a third example is pluggable scripts that don't control in-game behaviors but are necessary for the server to run, such as ruleset_import_hooks.py.

A behavior is assumed to be encapsulated in a single file. At the moment, only python scripts (.py files) are supported, but in the future it is possible that compiled shared object (.so files) will be supported, etc.

Whatever the script or binary, a .behavior file should accompany it so the compiler can figure out how to treat the behavior. The behavior file does three things:

• specifies the ID of the behavior (so other classes etc. can reference it)
• specifies the language of the behavior (only python is supported for now)
• specifies the local path to the behavior (local relative to the content directory, not the behavior file!)

Here is an example behavior file, for the panlingua.py script:

id              mind.panlingua.panlingua
language        python
local-path      behaviors/core/panlingua.py

You can separate the .behavior file from its corresponding script (that is, put them in different directories) but for sanity I like to keep them together.

The content directory is walked recursively, and all .behavior files found are parsed.

Core Behaviors

Somewhere (typically the behavior/core directory) you must specify these files (python script plus accompanying .behavior file) or the server won't work:

• Statistics
• editor
• interlinguish
• panlingua
• ruleset_import_hooks

Class Files

A .class file specifies a class that appears in the output ruleset xml file. Classes are basically objects that are allowed to appear in the game: characters, trees, animals, tools, etc.

Here is an example class file (for the wolf):

#
# class file
#

id              wolf


bounding-box {
       x0      -0.6
       y0      -0.26
       z0      0
       x1      1.3
       y1      0.26
       z1      1
}


mass            20

maxmass         30

mind            mind.animals.WolfMind

parent          character

modeldef        wolf

All .class files found in the content directory tree are parsed. The compiler will complain if a class inherits from another class that has not been defined (but it uses a 2-pass approach so ordering of files/directories is not important).