mirror of
https://github.com/worldforge/cyphesis
synced 2026-08-13 12:26:04 -04:00
15e81005bd
* README: Regenerate from source. * TODO: Add note describing eventual goals of statistics system.
307 lines
15 KiB
Text
307 lines
15 KiB
Text
Table of Contents
|
|
|
|
Introduction
|
|
|
|
Building from Source
|
|
|
|
Setup
|
|
|
|
Setup as a System Service
|
|
|
|
Running a basic server
|
|
|
|
Usage and configuration
|
|
|
|
Copyright notices
|
|
|
|
Introduction
|
|
|
|
Welcome to cyphesis, at the time of writing the only fully armed and
|
|
operational WorldForge server. Cyphesis is a small scale or personal
|
|
server for WorldForge games, and is currently being used to develop new
|
|
techniques and technologies for the WorldForge project. Code from cyphesis
|
|
will also be used to control NPCs in future servers such as STAGE using AI
|
|
techniques.
|
|
|
|
--------------------------------------------------------------------------
|
|
|
|
Building from Source
|
|
|
|
cyphesis is built using autoconf. Please see the file INSTALL for details.
|
|
It requires Python and PostgreSQL which are included with most Linux
|
|
distributions, and Atlas-C++, varconf, Mercator, wfmath and skstream2
|
|
which are provided by the WorldForge project. GNU readline is required by
|
|
some of the included tools.
|
|
|
|
If built from source the software and data must be installed using "make
|
|
install" before it will be ready. Go to the Section called Setup for
|
|
information on the setup steps required after installation.
|
|
|
|
--------------------------------------------------------------------------
|
|
|
|
Setup
|
|
|
|
The software requires some post-installation configuration before it will
|
|
run correctly. If you plan to run a server using the System V init
|
|
services as provided by the cyphesis rpm then most of this configuration
|
|
is handled for you automatically. If this is the case please see the
|
|
Section called Setup as a System Service for more information.
|
|
|
|
The first step is to setup the database access. The database is required
|
|
to store account and rule information. If full server persistence is
|
|
enabled, the database is also used to store the entire world state. A
|
|
postgresql server must be running on the system where you plan to run
|
|
cyphesis, and the user who will run cyphesis must have access to the
|
|
database. If you do not have root access on the system you will need to
|
|
contact the system administrator to request a database account. By default
|
|
cyphesis assumes that access to a PostgreSQL RDBMS running on the same
|
|
machine from a user account with the same name as the database account
|
|
does not require a password. If this is not the case you can either
|
|
configure the PostgreSQL RDBMS to work this way, or specify a password in
|
|
the config file.
|
|
|
|
Once database access has been granted you must run cyloadrules to load the
|
|
default rulesets into the database. For more information on how
|
|
cyloadrules works, including advanced usage see the Section called
|
|
Usage and configuration.
|
|
|
|
The server is now ready to run. For for more information on how to start
|
|
the server see the Section called Usage and configuration.
|
|
|
|
--------------------------------------------------------------------------
|
|
|
|
Setup as a System Service
|
|
|
|
Running cyphesis as a service is the simplest way to get the server up and
|
|
running. If you are using rpm packages, the cyphesis rpm handles creating
|
|
a user account so that cyphesis does not run as the superuser. In order to
|
|
run the server correctly, the cyphesis service must be started, followed
|
|
by the cyclient service. This can be handled by configuring the system to
|
|
start these services at boot time, or by running the init scripts manually
|
|
as root as follows:
|
|
|
|
# /etc/init.d/cyphesis start
|
|
# /etc/init.d/cyclient start
|
|
|
|
|
|
The postgresql service is required and must be started before cyphesis.
|
|
The first time the cyphesis service is run, the init script will ensure
|
|
that cyphesis has access to the database, and will preload the database
|
|
with the neccessary data automatically.
|
|
|
|
If you are not using the packaged version of cyphesis, but wish to run it
|
|
as a system service, the init scripts are included in the top directory of
|
|
the source package and are called cyphesis.init and cyclient.init. Both of
|
|
these files should be installed in the init script directory on your
|
|
system, usually /etc/rc.d/init.d/. The procedure for enabling system
|
|
services varies from system to system. One command used for controlling
|
|
services is the chkconfig command, found on most Linux systems, and some
|
|
Unix variants. Once installed the scripts can be activated as follows:
|
|
|
|
# chkconfig --add cyphesis
|
|
# chkconfig --add cyclient
|
|
|
|
|
|
The services are then enabled as follows:
|
|
|
|
# chkconfig cyphesis on
|
|
# chkconfig cyclient on
|
|
|
|
|
|
For further details please see the chkconfig documentation. By default the
|
|
cyphesis init scripts attempt to run the server and client as a user
|
|
called cyphesis. An account with this username will need to be created
|
|
before the service will work. The file called cyphesis.sysconfig can
|
|
optionally be installed as /etc/sysconfig/cyphesis and edited to control
|
|
the username used to run the cyphesis server and client processes.
|
|
|
|
When cyphesis has been run as a system service, any error message or other
|
|
information are sent to the syslog. On most Linux systems this means that
|
|
you can see these message by looking at /var/log/messages. Please see the
|
|
syslog documentation for information about how to control these log
|
|
messages.
|
|
|
|
--------------------------------------------------------------------------
|
|
|
|
Running a basic server
|
|
|
|
Before you run the server for the first time, run the cyloadrules to
|
|
prepare the database tables. The command should print out some message
|
|
indicating the number of rules loaded. You will not need to run this
|
|
command again unless you upgrade to a newer version of the rules or of
|
|
cyphesis.
|
|
|
|
Start the server with the cyphesis command. It will output some startup
|
|
messages and then run in the foreground. If you want to run the server in
|
|
the background, start the server with the option --cyphesis:daemon=true .
|
|
|
|
Each time the server is run it needs to be populated with game data before
|
|
it does anything useful. If you are running the server using the System V
|
|
init service then this is handled for you by the cyclient service. If you
|
|
are running the server manually you will need to run cyclient yourself. In
|
|
a separate terminal run the cyclient command, which will populate the
|
|
server, outputting messages as it does this. Once it has completed
|
|
cyclient will exit, and the server will be ready. The server will
|
|
automatically register its presence with the metaserver so you will not
|
|
need to advertise it.
|
|
|
|
If you everything has worked so far, and you are not planning to do any
|
|
server or world development at this time then you do not need to read any
|
|
of the rest of these instructions.
|
|
|
|
--------------------------------------------------------------------------
|
|
|
|
Usage and configuration
|
|
|
|
The main server binary is called cyphesis. Its command line arguments and
|
|
configuration are managed by varconf, which means options can be set in
|
|
configuration files and on the command line. The main configuration file
|
|
is called cyphesis.vconf, and server settings are stored in the [cyphesis]
|
|
section. The file can be found in the cyphesis source directory, and is
|
|
installed into the sysconf directory, which is by default /etc. Settings
|
|
in this configuration file can be overridden in on the command line, and
|
|
once overridden they will be stored permanently in .cyphesis.vconf in the
|
|
users home directory. In order to drop back to the default settings,
|
|
remove this file. Settings can be incrementally overridden in
|
|
~/.cyphesis.vconf non-interactively by passing them as command line
|
|
options to cyconf. cyconf will store any settings it is given in
|
|
~/.cyphesis.vconf and then exited. If you are planning to have multiple
|
|
servers run on the same system at the same or different times, the easiest
|
|
way to handle the differences in configuration would be to use the
|
|
~/.cyphesis.vconf file, and avoid modifying the master configuration file.
|
|
|
|
As an example, the ruleset to be used is set in cyphesis.vconf as follows:
|
|
|
|
[cyphesis]
|
|
ruleset="mason"
|
|
|
|
This setting can be overridden by invoking cyphesis with the following
|
|
option:
|
|
|
|
--cyphesis:ruleset=werewolf
|
|
|
|
For more details of varconf usage see the Varconf documentation. For full
|
|
details on configuraton options for cyphesis, see the cyphesis(1) man
|
|
page.
|
|
|
|
The ruleset specified indicates the entity types available, the set of
|
|
scripts that will be used for these entities, and the initialisation
|
|
script used to populate the server.
|
|
|
|
The server is populated using the client program, cyclient. cyclient
|
|
should be run once the server has been started, and it will display a
|
|
report of the world it is setting up, and then exit.
|
|
|
|
The default ruleset for this version is Mason, but an additional
|
|
development ruleset is provided for Werewolf, but will probably only be
|
|
useful as a reference. To switch to the Werewolf ruleset, follow the
|
|
instructions above.
|
|
|
|
Before you start the server for the first time, you will need to load some
|
|
data into the server's database tables. You will first have to load
|
|
ruleset data into the database. If this is the first time you have run
|
|
cyphesis, you will need to set it up so cyphesis has access. In order to
|
|
use databases, cyphesis needs to know the name of an account it can use,
|
|
and the name of a database where it can create its tables. By default it
|
|
uses the current user name to connect to PostgreSQL, and the name cyphesis
|
|
for the database. It has been assumed that PostgreSQL has been set up as
|
|
it is on most systems to accept a local connection from a user with the
|
|
same name as the database account name without a password. If you want to
|
|
go through the setup of the database manually, or for some reason
|
|
cyphesis-setup does not work, you will need to create a database account
|
|
with the right name, and a database belonging to that account called
|
|
cyphesis, or whatever name you choose to call it. For information on how
|
|
to do this, please see the PostgreSQL documentation provided with the
|
|
version you have installed.
|
|
|
|
Once cyphesis has access to the database, run cypasswd with no arguments
|
|
to set the admin password to something unique.
|
|
|
|
A ruleset will need to be loaded into the database before you can do
|
|
anything useful with the server. Each ruleset optionally depends on
|
|
another ruleset, so in addition to the ruleset you are using you will need
|
|
to load the rulesets on which it depends. A ruleset is distributed with
|
|
cyphesis as an atlas xml file. The default is mason.xml, which depends on
|
|
acorn.xml, which in turn depends on basic.xml. These three rulesets can be
|
|
loaded into the database using the cyloadrules command with no arguments
|
|
as follows:
|
|
|
|
$ cyloadrules
|
|
Reading rules from mason
|
|
49 classes stored in rule database.
|
|
Reading rules from basic
|
|
29 classes stored in rule database.
|
|
$
|
|
|
|
This automatically loads the rulesets in order into the database, first
|
|
ensuring that the rules table is empty.
|
|
|
|
cyloadrules can also be used to load individual rulesets into the database
|
|
as follows:
|
|
|
|
$ cyloadrules mason.xml
|
|
49 classes stored in rule database.
|
|
$ cyloadrules basic.xml
|
|
29 classes stored in rule database.
|
|
$
|
|
|
|
You will only need to do this if you are developing new rulesets, or
|
|
customising existing ones.
|
|
|
|
The database store is persistent. If new a ruleset is provided, it will be
|
|
necessary to clear the database tables before loading them with new data.
|
|
|
|
Once cyphesis is running, it will need to be populated with a map. In
|
|
order to set up a game, you need to run a client to set up the map. The
|
|
client will use a script included in the current ruleset to define what
|
|
the world should contain. This script is kept together with the entity and
|
|
AI scripts required for the ruleset in a directory under the rulesets
|
|
directory. For example, the Mason script is found in
|
|
rulesets/mason/define_world.py. In order to populate the world, simply run
|
|
cyclient once the server is running. You will need to do this each time
|
|
cyphesis is started.
|
|
|
|
--------------------------------------------------------------------------
|
|
|
|
Copyright notices
|
|
|
|
The server code in C++ is distributed under the GNU General Public
|
|
License. See the file COPYING for details. The script files included with
|
|
this distribution are also distributed under the GNU General Public
|
|
License. Note that this copyright does not cover user scripts that use
|
|
server services but do not use code from the scripts provided. Using such
|
|
scripts is considered ordinary use of the server, and does not fall under
|
|
the heading of derived work.
|
|
|
|
Under the terms of the GNU General Public License version 2, you are
|
|
entitled to modify the software, and are required to make the source code
|
|
to those changes available if you redistribute the modified version.
|
|
Specifically, you are not required to make the source code available if
|
|
the modified version is not redistributed. As the author of the
|
|
cyphesis-C++ core, I believe in your freedom to do what you want with the
|
|
software, and I do not believe I have any right to force you to publish
|
|
any changes if you do not wish to redistribute the modified program. There
|
|
has been some discussion within the Free Software movement about this
|
|
issue, which some see as a hole in the GPL, and it is possible that a
|
|
future version of the GNU General Public License will forbid using a
|
|
modified version of a GPL licensed program to run a service unless the
|
|
changes to the source code are made available. The licensing of many
|
|
programs permit redistribution under the terms of the GNU General Public
|
|
License version 2 or at the licensee's option, a later version, so it is
|
|
possible that a version of those programs may be released that is under
|
|
the terms of a license which requires the source code changes to be
|
|
published for a modified version being used to run an on-line service. As
|
|
the current author and owner of the source code to this program, I have
|
|
never intended that this restriction be placed on the software, and do not
|
|
support its enforcement. I have therefor chosen to restrict redistribution
|
|
of this program to the license provided with the source, which at the time
|
|
of writing is the GPL version 2. If a new version of the GPL is released,
|
|
I will consider on its merits whether or not to make this code available
|
|
under that license. The scripts provided with this software should be
|
|
considered a separate work, as they were not written by me. Nothing in
|
|
this paragraph should be considered to be a legal statement of any kind.
|
|
It is simply a clarification of my opinion on some of the terms of the GNU
|
|
General Public License. If anything in the above paragraph is unclear,
|
|
please feel free to contact me to discuss it.
|
|
|
|
Al Riddoch <alriddoch@zepler.org> 2nd April 2002
|