Building your own World

... with cyphesis

Creating your own world with its own game rules in cyphesis is a huge and daunting task. By far the best way to begin work is to take the existing demo world, and start adapting it to your requirements. Once you have enough experience and knowledge, you can take a copy of the edited world, give it a new name, and continue adapting and changing it until it is entirely your own creation.

Modifying an existing world

Recent versions of Cyphesis include the demo ruleset called mason which is set in a world called Moraf. All the data and code specific to this ruleset are stored the rulesets directory of the cyphesis source code, in a subdirectory called mason, and in the data directory in a file called mason.xml. In the data directory, data/mason.xml defines a number of templates, or classes for objects that will be used to create the world, and make it run. In the rulesets directory, rulesets/mason/define_world.py defines how to bootstrap the world into its initial state on server startup. The simplest change you can make to Moraf is to add some new entities to the world.

Open up rulesets/mason/define_world.py using a text editor, and take a look at it. It is written in Python, which is a commodity scripting language. Python is simple to understand for most people who have programmed before, but you may wish to look at some of the documentation or tutorials on the Python web site if you find something you don't understand. Search down through the file until you find some code that looks like this:

def default(mapeditor):
#   general things

    m=editor(mapeditor)

The code in this file is invoked by the cyclient program when it is run, and it populates the world with entities. If no module or function is specified, cyclient calls the function called default in the module called define_world. Alternatives can be specified by giving the function name in the command line as follows. For example, to populate the world with a function call populate_my_world in the define_world.py file, cyclient would be run as follows:

$ cyclient populate_my_world

or

$ cyclient define_world.populate_my_world

Create a new function to test some changes to the world. Do this by copying the first few lines given above, and paste them lower down the file, after the end of the default function. You can find the end of the function by looking for the next line that begines with def. Change the name of your new function to something suitable. It should now look something like this:

def populate_my_world(mapeditor):
#   general things

    m=editor(mapeditor)

For the rest of this section we will describe code that can be added to this function to create custom changes to the world. Install this file by running "make install" or by copying rulesets/mason/define_world.py into the location where this original version of this file was installed on your system. Make sure your server is running and test your new version as follows:

$ cyclient define_world.populate_my_world

The command should complete without giving any message, as your function currently does not do anything. It may give an error that looks something like this:

2007-05-25 18:33:01 SCRIPT_ERROR AttributeError: 'module' object has no attribute 'populate_my_world'

This means that you did not correctly install your modified define_world.py file, or you did not spell your new function name correctly, either in the file, or when you asked cyclient to run it from the command line. Check the spelling of the function name, and check that the file has been copied correctly to the place where cyphesis is installed.

Your new function currently has the minimum necessary to start to make changes to the world. Each time you add to the function, you will need to install the file, and run cyclient as described above to try it out. In order to ensure you are testing your world changes in a clean space, it may be a good idea to restart the server each time you want to try it. Normally when you restart the server, you would run cyclient to populate it with the full demo world. It will be easier to test your world changes if you don't have a populated server, so don't run cyclient as normal, and wait instead until you are ready to use it to run your function.

The simplest thing to try adding first is an oak tree. All entities are created by calling the m.make function, giving at minimum the name, type and position of the entity to be created. The name is free text, and will be what the user sees when they view or click on the object, so you should make it something obvious or helpful. The type must be "oak" as this defines what we are creating. The position is specified by the pos argument to m.make. It is given in cyphesis world coordinates, where the first or X axis points east, the Y axis points north, and the Z axis points vertically up. When you create or move any entity that normally stands on the ground, the server will automatically adjust its height, so it is not important what you specify for the Z axis. Currently when you create a new character it enters the world within a few metres of the origin, so you should place your test oak tree within this area, so you can log in and see the results of your modification. Once you have added the code to create a new oak tree, your function will look like this:

def populate_my_world(mapeditor):
#   general things

    m=editor(mapeditor)

    m.make('oak', name='My oak tree', pos=(3, 3, 0))

Install it and run cyclient to try it out. cyclient will print out one line indicating that it has create an oak tree.

$ cyclient define_world.populate_my_world
Created: oak(834)
$

Connect to your server using sear or ember, and you should be able to see a lone oak tree in a completely empty world, without even any terrain.