- 1 Introduction
- 1.1 Welcome
- 1.2 Audience
- 1.3 Prerequisites
- 1.4 Dropping the Hammer
- 1.5 Operational Administrivia
- 1.6 Building vs Creating
- 1.7 Minimal Dataset
- 1.8 Mars Needs WorldForge
- 2 Tutorial : Adding Entities
- 3 Tutorial : Adding Entity Types
- 4 Tutorial : Changing the Terrain
- 5 Tutorial : Adding A Task
- 6 Tutorial : AI
- 7 Tutorial : Adding Attributes to an Entity
- 8 Tutorial : Adding Statistics
- 9 Tutorial : Combat
- 10 Tutorial : Looting
- 11 Tutorial : Adding Questing
- 12 Tutorial : Adding a Vendor
- 13 Tutorial : Adding Economy
- 14 Tutorial : Adding Auction House
- 15 Tutorial : Adding Mail/Communication System
- 16 Tutorial : Adding Travel/Transport System
- 17 Tutorial : Adding a Model to a new Type
- 18 Tutorial : Adding New Resource
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 .
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).
Before attempting this tutorial, the following requirements need to be satisfied:
- Have a working local cyphesis server installed (preferably compiled from source)
- 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.
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.
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.
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;
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 )
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.
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:
- Shutdown of server, if running
- BUILD and INSTALL ( ala hammer.sh build cyphesis )
- Running SRC/scripts/cyphesis-setup.sh ( note: cyloadrules will fail )
- Running WFRUN/bin/cydb world purge ( to purge state )
- Running WFRUN/bin/cyloadrules
- 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
note: adding in via define_minimal.py and cyclient
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 : Adding A Task
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 : Adding Statistics
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 Auction House
Tutorial : Adding Mail/Communication System
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