Freeciv Server Guide Version 0.1, 1999/2/10 for Freeciv 1.7.2 + CVS updates through February 10 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 progressed, 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. Unless disabled by the operator, 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. 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 comand 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 OPTION SETTINGS 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, and will have enabled client network connections. Player client programs will connect to the server and wait; you can use the "l" command to show the connected players. Once all settings have been made, and all desired players have connected, you start the game with the "s" command. This will ask each player to select a race, 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 "s" 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 is the real Earth at 160x90 size earth-80x50.sav is the real Earth at 80x50 size europe.sav is 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. -n or --nometa Directs the server not to communicate with the Freeciv Metaserver. You may wish to use this for privacy reasons, or if you are not going to be connected to the Internet at all. -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 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." # comment This is intended for script files. If the first nonblank character on a command line is the "#"-sign, the remainder of the line is ignored. remove playername Removes the named player from the game. The race and al its works are completely erased. save filename Saves the state of the game into the specified file in the working directory. Only allowed once the game is running. meta comment Sets the rest of the line to be the server's description which is sent to the Freeciv metaserver. You may want to use this instead of the default description of "(default)"; for instance "daily restart." h or help Both of these display a list of the available commands. l Lists the players in the game. ai playername Toggles whether the named player is run by an AI. If the command enables an AI, its skill is set to that set by the last easy/normal/hard command. create playername Creates a new player in the game, run by an AI. This is only allowed before you start the game with the "s" command. At that time, if the player name is that of the default leader of some race, and that race was chosen by any human player, the AI will be given that race; otherwise it will get an available race at random. crash This command immediately crashes the server. It makes no backup file. log string Writes to the log file (opened by the command line -f option) the rest of the line. easy easy playername normal normal playername hard hard playername These commands set the skill levels of AI players to the specific state; the names of the levels are relative (see distribution file README.AI for a note on the AI's). If the playername is specified then the skill of that one race is set; otherwise it sets the skill of AI's created in the future. q Quit game. Does not make a backup. c playername Cuts connection to a player. The race continues to exist, and yearly updates will update its status, but it will enter no orders. If timeout is not set, this will effectively block the game until a client reconects or an AI is assigned to play the race. show Shows all current option settings explain Shows a list of the settings. explain setting Provides built-in help for an option setting. set setting value Sets an option setting to the specified value. score Displays the current score. s Starts the game. 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 landmass forests seed ysize mountains swamps generator rivers deserts 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 explorer techpenalty foodbox specials gold diplcost aqueductloss huts techlevel conquercost unhappysize minplayers techs freecost cityfactor maxplayers units railprod razechance aifill buildings railfood civstyle settlers researchspeed railtrade 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 mainyl of interest to scenario developers. The following may be set even after the game has started. diplchance civilwarsize timeout scorelog spacerace endyear saveturns 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. 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/shared/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".