[Freeciv-Dev] 'newer' version of Freeciv Server User's Guide

["Bart Coppens" <coppensbart@xxxxxxxxxxxxxxxxx>]

As I was (again ;) terribly bored today, I decided to play Freeciv again. So after looking again a bit at the server manual so I could set op my game, I typed 's', just as the manual asked, but I got the warning that the command was ambigous. I knew that I got that command last time as well. After a bit of looking in the different files of the manual, I found out it's still made for version 1.8, while I used today's CVS. As I see it, the manual is just terribly outdated and as far as I could see no one cared about it. So I decided to make things a bit more 'modern' (partly because I didn't want to look in the code or wanted to use the help command each time I wanted some help :-)

 

I used the code at stdinhand.c as a base for the 'new' command list, as it seemed the only place where all commands were united. I only changed the 'Commands' section of teh manual and changed some references to the "s"-command (and "l") to their working counterparts. Because it would become too difficult to look which commands were added since the manual was written and which were changed, I completely retyped the section with the commands. I also made the appearance of the arguments somewhat easier to look at with the use of italics. I used the order of stdinhand to make it more comfortable for me to put all the text together.

 

I know that probably all these 'new' commands are in the help of Freeciv, but this makes it easier to use as a reference. I really hope that you find this 'update' as useful as I do :-)

 

Bart Coppens

The Freeciv Server User's Guide

Overview

The Freeciv server is the core of the Freeciv system. It maintains the complete states of all game variables (map, units, cities, research, etc.), updates them based on player client requests, and sends updates to the clients. For multiplayer games it is the central arbiter of the game's progress. For solitaire play, it implements the Artificial Intelligence (AI) races.

Whether for solitaire or multiplayer games, the server operator runs the server in a window. The operator may set game options, including loading entirely new sets of game rules, or load prepackaged scenarios. Players use client programs to connect to the server via the network (even solitaire games, run on one computer, use the network software to connect the client and server programs). Once all players have connected, the server operator starts the game, and players then proceed with play.

In the course of a typical game, server operators will monitor progress, using mechanisms inside the game ("chat") or outside the game (E-mail) to communicate with players. The operator may also play, running a client program in another process. As the game progresses, the operator may use server commands to adjust game options, save the game for later restart, or terminate the game.

The Freeciv Metaserver is a server on the Internet which provides a coordination point for Freeciv multiplayer games. If enabled by the operator by command line option --meta, the server informs the Metaserver of the status and progress of the game. This one-way information flow (server to Metaserver) should, in time, allow players to locate servers and games to play on.

This document reflects the Freeciv server program for the 1.8.0 build. The general concepts involved will also help in using Freeciv 1.7.2 and earlier versions.

Usage

On a Unix system, you will need to start the server in a window (e.g., xterm, virtual console), since commands must be entered during play. Run the server with the command "civserver" followed by your desired command line options (described later). (If you do not have Freeciv installed with "make install", use the "ser" script provided in the distribution.) The server will initialize and prompt for input.

At this point, you will wish to set game options, minor ones (timeout times), medium ones (map size), and major ones (rules for Civilization I or II). For the game options, see Command Line Options and Files and Environment below. If you have a collection of option settings which you use often, you may enter them into a flat ASCII file and read them into the server quickly with the -r option. You should coordinate your option choices with the players to reduce confusion. You may also load entire scenarios with the -f command line option.

While you are entering commands, the server will have announced the game to the Freeciv Metaserver (if you enabled it), and will have enabled client network connections. Player client programs will connect to the server and wait; you can use the "list" command to show the connected players. Once all settings have been made, and all desired players have connected, you start the game with the "start" command. Once the game is started, each player will be asked to select a race. After these selections, the server will assign AI races, generate the map, send all initial data to the clients, and the game is on.

In Civilization I and II, each race's turn proceeds in sequence: first the human player moves, and presses Next Turn; then the Romans move, then the Greeks, and so on through a standard list of AI races, ending with the Barbarians, after which the human player gets control again. In Freeciv multiplayer, all of the players enter orders simultaneously. The server processes all orders from clients in the order in which they are received. Some things, however, only update at the end of a "turn": Cities grow and eat food, research happens, revolutions complete, units heal damage, and the calendar turns to a new year. That end-of-turn update takes place when all human players have indicated Next Turn (but see the Timeout option setting). If a player takes several minutes to finish moves, all players wait until that last one completes before the update takes place. If there are AI races, they make their moves at the start of the turn update.

Once the victory conditions have been met (see README in the distribution), the game ends. But you may suspend the game at any time, and resume it another day if you wish. The "save" command will write out all game state into a file as of the instant of the command (even with players entering orders). Then you may quit the server. When you wish to resume (and have coordinated the restart of the game with the players), run the server again with the -f option to read in the save file. That will reset the internal data to reflect the state in the file, and leave the game paused. Once the player clients reconnect, an "start" command will get the game moving again. In addition, if the server or the system fails, you may be able to fall back to the list automatic save done every few turns (set by option setting saveturns); its files are the same.

Command Line Options

The following options are accepted on the command line of the server. They may not be combined; that is, "civserver -fp savegame.sav 555" will not work, instead you would need to enter "civserver -f savegame.sav -p 555". Most options have a short form (single hyphen and single letter) and a long form (double hyphen and a complete word); their effects are identical.

-f filename or --file filename

Loads a saved game into the server before initialization, instead of starting a new game. This is for reloading saved games, or for loading scenarios. The distribution comes with three such scenarios, typically stored in /usr/local/share/freeciv:

earth-160x90.sav

the real Earth at 160x90 size

earth-80x50.sav

the real Earth at 80x50 size

europe.sav

the real Europe at 200x100 size

-h or --help

Prints out a description of the command line options and exits.

-l filename or --log filename

Defines a log file to be produced during processing. By default, "fatal" and "normal" messages are printed to standard output. With a log file, such messages go to the log instead. Use the -d option to set how much is logged.

-g filename or --gamelog filename

Defines a log file to be produced during processing. This is a game progress log, of game-related events recording the activities of the players.

-m or --meta

Directs the server to communicate with the Freeciv Metaserver.

-p number or --port number

Specifies the TCP port number to which clients will connect; players must know this number to be able to connect if they are not to use the default of 5555 decimal. You may need to use this if 5555 is not available for your use on your system.

-r filename or --read filename

Specifies a file of server commands which the server will automatically read and process, as if you had typed them in at the server's prompt. The distribution has an example that sets options to be similar to Civilization I, which the option -r /usr/local/share/freeciv/civ1.serv would read.

-s name or --server name

Specifies the name to be given to the Freeciv Metaserver as the name of this server. This is distinct from the description line set by the "meta" command; both are displayed in the Metaserver's output.

-d number or --debug number

Sets the amount of debugging information to be logged in the file named by the -l option. The number should be 0 for fatal errors only, 1 for fatal and normal messages, or 2 for fatal, normal, and debugging messages.

-v or --version

Causes the server to display its version number and exit.

Commands

(updated for version 1.12 CVS of 18/02/02)
You may enter commands into the server at any time, either before or during the running of a game. Command names are case-sensitive, as are filename and setting; argument playername generally is not. In all cases where a playername is expected as a command argument, it is the name of the ruler of a race in the same; e.g., you probably want to refer to "caesar" rather than "romans."

start

Starts the game

help (option-name)

Displays more information about the server commands and options, if you add the option-name, it gives help about that option

list

Lists the playsers in the game

quit

quit the game and shut the server down

cut playername

Cut playername's connection to the game

explain option-name

Gives help information to a specific command; synonym for help option-name

show (option-name)

Without argument, it gives a list of all server options and their values, with an argument it returns the value of the option option-name

score

Displays the current score

wall message

Sends message to all connected players

set option-name value

Set the value of the server option option-name to value

metaconnection (? or up or down)

With the argument ?, this command gives the status of the connection with the metaserver; up brings the connection with the server up while down brings it down

metaserver weblocation-of-metaserver

sets the location of the metaserver on the WWW to weblocation-of-metaserver (must include http://!)

aitoggle playername

Toggle the status of the AI of playername

create playername

Create an AI with the name playername (the race is detirmined by the race playername can be ruler of according to the nationset)

easy (playername)

Sets the AI to 'easy' at player playername, when no playername is given, all AI-players are set to easy

normal (playername)

Sets the AI to 'normal' at player playername, when no playername is given, all AI-players are set to easy

hard (playername)

Sets the AI to 'hard' at player playername, when no playername is given, all AI-players are set to easy

cmdlevel (arguments)

Sets the commandlevel of (a) target player(s). With these levels you can set the degree of the options a player can set. All of the commands/options require a certain level to execute them. See the sourcecode for more info.

firstlevel

Shows the level a player will get when he connects to the game

endgame

Ends the game immediately

remove playername

Completely remove playername from the game, including cities, units, etc.

save (filename)

Saves the current game to filename. If no filename has been specified, the file is saved in the format >auto-save prefix<>year<m.sav[.gz]. You can reload it by starting the server with --file filename

read filename

Load the server-settings from filename

write filename

Write the current server-settings to filename

rulesout rules-type filename

Writes the ruleset of the type rules-type to filename. Currently, the only available rules-type is "techs" (means advances/technologies; this file can be used to create a graph with the "techtree" program)

crash

Crashes the server. This can be useful to create dumps.

Option Settings

These are the options that may be set with the "set" command, shown with the "show" command, and explained with the "explain" command. Many, but not all, are automatically sent to client programs; some are private to the server. Most options have for their values simple integers.

The detailed descriptions of the options are best found via the server's own "explain" command. Repeating those descriptions here would only require maintaining them in two places.

The following options may only be set if the map has not been generated. They are used in the map generation process, establish the general habitability of the map: xsize, ysize, generator, landmass, mountains, rivers, forests, swamps, deserts, seed, grass.

The first three are of interest to most users. The xsize and ysize options define the size of the map, which should be based on the number of players and the planned length of the game. The default map size of 80x50 is big enough for a fairly quick two player game, but will be a frustratingly fast game for more than three people. More than three should try 80x80; for five or more you should consider 100x100.

The "generator" option alters the map generation process. The default generator can produce tiny islands from which it is impossible to make a viable nation. Map generator 2, on 80x50 maps, makes seven islands of equal size; generator 3 will also create some small islands.

The following options may be set if the map has not been generated, or if the map is already generated but is a scenario's predefined map and the game has not actually started. They also relate to map and game creation, on a different level: randseed, specials, huts, minplayers, maxplayers, aifill, settlers, explorer, gold, techlevel, techs, units, buildings, researchspeed, techpenalty, diplcost, conquercost, freecost, railprod, railfood, railtrade, foodbox, aqueductloss, unhappyisze, cityfactor, razechance, civstyle.

The options minplayers, maxplayers, and aifill will be useful to most players. The options techs, units, and buildings are for selecting variant rulesets. The rest are mainly of interest to scenario developers.

The following may be set even after the game has started: diplchance, spacerace, civilwarsize, endyear, timeout, saveturns, scorelog, gamelog.

A note about the timeout option is necessary. Recall the description above of the end-of-turn updates that take place when all players have entered Next Turn. If there are just a few players, in close communication, leaving it in this mode is reasonable. If there are more than just a few, or if there will likely be breaks where one leaves for a minute or so and you don't want to wait, you can set the timeout to some interval such as 60 seconds. In that case, 60 seconds after one update, the next will take place even if a player has not entered Next Turn. Later in the game this can be annoying, and larger timeouts will be necessary. In general, the more players you have, the longer a timeout you will need, but be aware that going above 300 seconds will bother players.

You may wish to make adjustments in various settings (gold, techlevel, researchspeed, etc.) to make the game easier; if you are inexperienced, and playing with inexperienced people, probably no one will object. But this is not a good way to learn how to play; starting with uncommon advantages makes it more difficult for you to learn how to copy with the common settings. For the most part, the game settings are there for those who wish to make an entire "scenario", an alternative world with its own environment and consistency, such as a Fall of Rome scenario, or a Medieval Europe scenario.

Files and Environment

The Freeciv server accepts these environment variables:

FREECIV_CAPS

A string containing a list of "capabilities" provided by the server. The compiled-in default should be correct for most purposes, but if you are familiar with the capability facility in the source you may use it to enforce some constraints between clients and server.

FREECIV_DATADIR

A string containing the name of the directory in which the Freeciv data files are stored. If not specified, the default /usr/local/share/freeciv is used.

The Freeciv server requires the following files in the Freeciv data directory, which is /usr/local/share/freeciv by default:

        default/buildings.ruleset
        default/techs.ruleset
        default/units.ruleset

These are the default rule sets used for the game. Alternate sets of rules can be installed with the option settings "techs", "units", and "buildings", each of which provides a name to replace the directory name "default".