WorldCreationTutorial

Introduction

Welcome

Welcome to WorldForge!

If you are here now, that must mean that you are interested in the details of bringing a new world to life using the WorldForge framework.

This tutorial series is intended to help you with this goal.

As always, we are available for help via the usual methods listed on http://worldforge.org .

Audience

This tutorial is for prospective WorldForge world creators. As this task is a large and complex issue, there will be external links where appropriate to additional materials.

This tutorial will focus on using the most popular and developed tools in the WorldForge arsenal, cyphesis (the server) and ember (the client).

Prerequisites

Before attempting this tutorial, the following requirements need to be satisfied:

1. Have a working local cyphesis server installed (preferably compiled from source)
2. Have a working local ember client installed (preferably compiled from source)

TODO: insert links to reference for above

Dropping the Hammer

The WorldForge developers and content creators tend to use a utility script call "Hammer" that very much streamlines the process of setting up and isolating a development environment. These tutorials will assume that you have used this method to create a WorldForge Developement Environment(tm) ... or WDE =)

For ease of reference, it will be assumed that ~/wf will be this directory. All WorldForge binaries, libraries and configuration will be self contained within this directory.

Cypheis comes with a default world called mason, and it is a small island, where you are a settler, and you have goals like building and harvesting. This is a fully featured ruleset/world and showcases many things in terms of objects, AI, weather, and so forth. The default cyphesis installation and configuration will result in the rules for this world, and the running world server.

Recently (perhaps not yet merged into the main cyphesis tree yet) a new, and minimal ruleset was created. This ruleset defines only the very bare minimum necessary in order to start cyphesis, and log in. This dataset contains the weather, the ocean, some bland flat terrain, and a rock. That's it, there is zero AI included, nor any of the internal types to support that. This ruleset will be our starting point, and all functionality will be assumed to rest on top of this.

Operational Administrivia

For the rest of the tutorial, please observe the following:

• CYPHESIS_SRC will refer to ~/wf/work/build/worldforge/servers/cyphesis and is the source that is checked out
• WFRUN will refer to ~/wf/work/local and refers to the --prefix destination similar to any autotools source package. This is what you would call the "install directory", and it is where we execute things from.

Most of the WorldForge components are dynamically linked, and so it is required to set the LD_LIBRARY_PATH to include the WorldForge lib path.

E.g.

export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:~wf/work/local/lib"

Building vs Creating

There are two approaches to world creating.

Building, is where you would make modifications in CYPHESIS_SRC (for example to the minimal ruleset), and you would run the hammer build command ( hammer.sh build cyphesis and this would build, and installed into the WFRUN directory ). The main advantage to this is that you will be in a position to commit/submit your changes upstream with ease, and you will not have to worry after that fact about "fitting your changes in". The main disadvantage, is that it requires a little more effort and cycles to go from idea to world. The main directories for this effort will be CYPHESIS_SRC/data/minimal and CYPHESIS_SRC/ruleset/minimal.

Creating, is where you would make modifications directly to the WFRUN directories/files. This method would not require any rebuilding, just making changes and restarting the server. The main advantage of this is of course speed and ease. You don't really have to know or care how cyphesis is built, its dependencies, and so forth, you can focus totally on the world building experience. The downside of this is that at some point when you want to share your world, it will be more difficult and you will need to fit it back into the tree (something that may be difficult if you are not code/build savvy). The main directories for this effort are WFRUN/etc/cyphesis/minimal.d and WFRUN/share/cyphesis/rulesets/minimal.

I personally favour the build methodology, and as such the tutorial will be based on this.

Take a moment to make sure that your cyphesis server is up and running, that the mason ruleset is in effect, and that you can connect and interact with the world via the Ember client.

Minimal Dataset

For the purpose of the tutorial, it will start with the minimal ruleset as the foundation. This is done for simplicity, and to highlight only the topic in question. For many tasks, it is perfectly reasonable to perform the operation on the mason ruleset instead.

Cyphesis should be offline. If this is not the case, stop the server now.

Configure the ruleset

Cyphsis will load it's configuration files in the following order;

1. $HOME/.cyphesis.vconf
2. WFRUN/etc/cyphesis/cyphesis.vconf

As a personal preference, I always keep my cyphesis configurations in my home directory like so:

• $HOME/cyphesis.vconf.default ( a copy of WFRUN/etc/cyphesis/cyphesis.vconf )
• $HOME/cyphesis.vconf.minimal

And then as required, I copy one of my configurations to $HOME/.cyphesis.vconf and restart the cyphesis server. I find this effective for quickly swapping configuration / rulesets easily.

I would not modify the WFRUN/etc/cyphesis/cyphesis.vconf file, as rebuilding will cause this to be overwritten.

Create your cyphesis.vconf.minimal file by making a copy of the default configuration, and make the following edit.

Change these items:

[cyphesis]
# Default ruleset config file and script directory
ruleset="mason"

[client]
# Client specific options
# Script package
package="define_world"
# Script function
function="default" 

Should now read:

[cyphesis]
# Default ruleset config file and script directory
ruleset="minimal"

[client]
# Client specific options
# Script package
package="define_minimal"
# Script function
function="default" 

#Add this new item
[minimal]
ruleset=basic

Load the ruleset

Invoking cyloadrules without arguments purges all existing rules in the database, and loads the files located in WFRUN/etc/cyphesis/RULESET.d where RULESET is defined by the [cyphesis] ruleset=XXX configuration item. In this case, we have configured it to be "minimal", which you can see from the loading message.

[sryan@hyperion-linux local]$ $WFRUN/bin/cyloadrules
Reading rules from minimal
4 classes stored in rule database from terrain.xml.
1 classes stored in rule database from environment.xml.
2 classes stored in rule database from characters.xml.
3 classes stored in rule database from basic.xml.
[sryan@hyperion-linux local]$ 

Start the Server

Now that your world is now playing by new rules, lets start it up.

[sryan@hyperion-linux local]$ $WFRUN/bin/cyphesis
According to my calculations Cyphesis should be installed in /home/sryan/wf/work/local/bin/..
Starting Cyphesis....
2012-08-07T12:55:48 INFO Running

Cyphesis can possibly have many errors during startup, but as long as you see "INFO Running", the server is up and online.

Instantiate Entities

The WFRUN/bin/cyclient utility is used to perform operations on the server. In this case, most commonly to instantiate the ruleset objects.

[sryan@hyperion-linux bin]$ $WFRUN/bin/cyclient
Seen: world(0)
Seen: boundary(1494)
Created: weather(1508)
Created: rock(1509)
Created: path(1510)
Server disconnected
[sryan@hyperion-linux bin]$ 

And if you left the cyphesis running on the console as in Step 3, you would now see:

Starting Cyphesis....
2012-08-07T12:55:48 INFO Running
2012-08-07T13:05:28 NOTICE Sending create response
2012-08-07T13:05:28 NOTICE Sending create response
2012-08-07T13:05:28 NOTICE Sending create response

Observe the World

So now, if you log in to your server, you will see pretty barren terrain, and a rock, and that's about it. One thing to note, is that because there is no graphical item specified for the "rock", it will be represented by a black rectangle with the word "Placeholder" on it. All

Mars Needs WorldForge

Now that you have loaded your minimal ruleset and explored your world, we need to move on to bigger and cooler things. However, we do not want to disturb the minimal dataset, as other World Builders will be interested in starting from the same point.

To that end, we will now create a new ruleset that is exactly the same as the minimal ruleset. In all my creative glory, I have decided to call mine "mars".

This ruleset will exist in the cyphesis source, and will be the accumulation of tutorials as I go through them. You will need to select your own inspiring name, and replace "mars" with "yourcoolworld"

Note: As a reminder, all modifications are explained and made from the CYPHESIS_SRC directory. Source control and those processes are left as an exercise of the reader.

Unless otherwise stated, all changes going forward will require the following steps:

1. Shutdown of server, if running
2. BUILD and INSTALL ( ala hammer.sh build cyphesis )
3. Running SRC/scripts/cyphesis-setup.sh ( note: cyloadrules will fail )
4. Running WFRUN/bin/cydb world purge ( to purge state )
5. Running WFRUN/bin/cyloadrules
6. Running WFRUN/bin/cyclient

Henceforth, this will be known as "BUILD And INSTALL", as all the steps are covered in detail earlier.

A New Ruleset is Born

Create a data ruleset directory (remember, ALL commands are listed as relative to CYPHESIS_SRC!!)

cd data
mkdir mars
cp minimal/*.xml mars

Create data/mars/Makefile.am and make it look like this:

MARS_RULES = basic.xml characters.xml environment.xml terrain.xml

confdir = $(sysconfdir)/cyphesis

rulesetdir = $(sysconfdir)/cyphesis/mars.d
dist_ruleset_DATA = $(MARS_RULES)

confbackupdir = $(datadir)/doc/cyphesis-$(VERSION)/conf
confbackup_DATA = $(MARS_RULES)

check-local:
        @for rule in $(MARS_RULES) ; do \
          echo $(XMLLINT) -noout $(srcdir)/$$rule; \
          $(XMLLINT) -noout $(srcdir)/$$rule; \
        done;

Edit data/Makefile.am and change the SUBDIR line to be:

SUBDIRS = minimal mars

Create the ruleset directory:

mkdir rulesets/mars
cp -r rulesets/minimal/* rulesets/mars
mv rulesets/mars/define_minimal.py rulesets/mars/define_mars.py 

Modify rulesets/Makefile.am RULESETS directive to include mars:

RULESETS = basic/mind mason minimal mars

BUILD AND INSTALL

Tutorial : Adding Entities

adding a new instance of an entity

Ruleset

 note: adding in via define_minimal.py and cyclient

Realtime

 note: via cycmd shell

Tutorial : Adding Entity Types

adding new types, add some type that is inanimate ... rock2 or something reinforce 1 by adding new instance

Tutorial : Changing the Terrain

mercator explanation, plus initial point deformation terrain levels and textures

Tutorial : AI

panlinguish explanation adding mind to a world behaviour, knowledge, goals adding a new entity with simple goals ( maybe a waypoint route and some simple emote logic )

Tutorial : Adding Attributes to an Entity

precursor to statistic practical application thereof

Tutorial : Combat

combat goals default combat logic handling death respawning

Tutorial : Looting

entity looting, an entity (such as a chest, or a corpse) derives from a container object. Object is filled at creation time based on caller. Random mobs will hit a loot table, Players will maybe pass off inventory to a corpse object.

Tutorial : Adding Questing

quest AI ( handling the fishing, detection, response to states and so forth ) definition of a quest/lore type item definition of quest (dialogue, steps, requirements (speech, item, interaction), etc) inventory special case quest can be assigned to mob/npc will require ember update will require core code update

Tutorial : Adding a Vendor

vendor type ember interface artifact buyback (global, attached to char, available at any vendor)

Tutorial : Adding Economy

money attributes trading bank limited supply vendor item

Tutorial : Adding Travel/Transport System

definition of waypoint type

Tutorial : Adding a Model to a new Type

ember tutorial ... intro to mapping, add model to replace placeholder for rock

Tutorial : Adding New Resource

ember tutorial ... model animation texture mapping