Ground Control Dedicated Server
Network Protocol Version 1.0.3.3
Readme File
June 2, 2000

[ To read this file, select Edit/Word Wrap from the menu above ]

***********************************************************************
About This Document:

This document contains information about the Ground Control Dedicated Server software.

***********************************************************************

		    	TABLE OF CONTENTS

		  I.	OVERVIEW
		 II.	RELEVANT FILES
		III.	CONFIG FILE SYNTAX
	   IIII.	THE UI AND MENUS
	               




I. OVERVIEW
=======================

The Ground Control Dedicated Server software consists of two programs, the DedicatedServer.exe (hereafter referred to as the DS),
and the DosDSS (hereafter referred to as the DSS).

The DS operates as a central place to start actual game sessions (instances of the DSS). This is achieved by registering its existence with
WON directory servers, thereby letting Ground Control game clients communicate with it and start games. The operator of a DS has control over
many aspects of this process, either via the config file, or via the DS user interface.



II. RELEVANT FILES
============================

Both the DS and the DSS must reside in the data subdirectory of your Ground Control installation directory (default C:\Sierra\GC\data) to
operate properly. All filenames and directory paths hereafter are relative this directory, and will be created by the DS if they do not exist.

If you're running the DS separately from a Ground Control installation the DS and DSS must be placed together with the datafiles that came with
the distribution.

Make sure you change the name of your Dedicated Server (the WONName tag in the dedicatedserver.cfg, see below) so that your DS have a
unique name (the DS will not operate properly if you do not do this).


AUTOSTART (multiplayer/autostart)

Any .cyc (session cycle) files in this directory will be automatically started when the DS executes. This features is designed to allow hands-off
session creation when for example the system is rebooted remotely.


CLIENTCONFIGS (multiplayer/clientconfigs)

When Ground Control clients create game sessions, they effectively send the contents of a .ses session configuration file to the DS. This information
is written to a file in the CLIENTCONFIGS directory for later use during creation of the DSS, and for DS administrator reference.


CUSTOMCONFIGS (multiplayer/customconfigs)

Any custom session configurations edited via the DS UI are stored in this directory.


CYCLES (multiplayer/cycles)

A good place to store any user created game cycles.


MISSIONS (multiplayer/missions)

Here reside all the default multiplayer missions (along with their default session configuration (.ses) files). Both mission names and .ses files
are loaded from this directory.


DEDICATEDSERVER.LOG (multiplayer/dedicatedserver.cfg)

The default log file for the DS. You can change the log filename via the config file.


DEDICATEDSERVER.CFG (multiplayer/dedicatedserver.cfg)

Many aspects of the DS are controlled via the config file. If this file doesn't exist, the DS will automatically generate it with default values.
If however the file exists but is corrupt or contains invalid data, the DS will not execute. To remedy this, edit the file or delete it to generate a
new config file with default values. The config file is resaved each time the DS terminates to ensure proper formatting.



III. CONFIG FILE SYNTAX
============================

The config file is simple text file with tags on one line followed by values on the next. Standard C++ style comments are supported (// at start of
line only, no /* */ comments). Tags are not case sensitive and are explained below.


LogFile

Defaults to multiplayer/dedicatedserver.log.
This file stores all output to the DS log window. Specify <none> for no file logging.


ListenPort

Defaults to 21000.
This is the public TCP/IP port of the DS. All connections are made via this port (both DSSs and Ground Control game clients).


BaseSessionPort

Defaults to 20000.
This is the starting port number used by DSSs. Each DSS will space its ports by 10 (the DSS itself will however only use 3 ports in this interval).


MaxClients
Defaults to 64.
This is the max number of game clients to be server by the machine. This value ONLY applies to standard/sync-start game sessions created by remote
Ground Control clients, and not to drop-in game sessions started via the DS UI or the AUTOSTART directory. Specifying 0 will not allow remote
Ground Control clients to start game sessions at all, but drop-in sessions can still be started by the user via the UI or AUTOSTART directory.


MissionPath
Defaults to 'multiplayer/missions'.
Where the missions are located.


CustomConfigPath
Defaults to 'multiplayer/customconfigs'.
Where the custom session configs (.ses) are located.


ClientConfigPath
Defaults to 'multiplayer/clientconfigs'.
Where the remote Ground Control game client session configs (.ses) are stored upon session creation.


SessionNoConnectionTimeout
Defaults to 20.0 (seconds).
Once a standard/sync-start game session has been created, it will wait this time period before automatically shutting down if no connections are
established by remote game clients.


WONName
Defaults to 'Ground Control Dedicated Server'.
The name of the server as visible to Ground Control users via the World Opponent Network. Make sure you change this to a unique name or 
your DS will not work properly.


WONServers
Defaults to 'groundcontrol.east.won.net:15101,groundcontrol.west.won.net:15101,groundcontrol.central.won.net:15101'.
The ip adress and port of one or several WON directory servers for registration purposes. Any number of servers are allowed. Use ':' to delimit
ip address and port, and ',' to delimit servers.


WONUpdateFrequency
Defaults to 60.0 (seconds).
The frequency with which to update status to WON. The information included is the number of active game sessions on the DS, information about each
DS, etc. Note that this information is automatically update regardless of this frequency value whenever a game sessions is created or terminated.


ConnectionTimeout
Defaults to 20.0 (seconds).
Connections made to the DS are expected to identify themselves with a valid identifier within this time period, otherwise they will be disconnected.
The only valid connections at this time are DSSs or Ground Control game clients.


AutostartCyclePath
Defaults to 'multiplayer/autostart'.
Any .cyc (session cycle) files present in this directory upon DS execution will be automatically started.


AutostartCycleInterval
Defaults to 10.0 (seconds).
DSSs once created must have time to connect back to the DS locally before the next DSS is created to ensure proper port usage. Use of a value smaller
than 2 or 3 seconds is discouraged.


SessionLog
Defaults to 1.
Any nonzero number will enable DSS event logging. DSSs will log to a unique filename based on game name and port in the multiplayer directory.






IIII. THE UI AND MENUS
============================

A) MAIN UI
B) SESSION CONFIGURATIONS
C) STARTING DROP-IN SESSIONS / CYCLES

A) MAIN UI
-----------------

In the main dialog of the DS there is a large window which logs events as they occur, and a smaller window below which lists active network connections
to the DS. Currently there are only two types of legal connections, which will be either a DSS or a Ground Control game client. Ground Control game
clients will however only be connected for a very short period of time, as the DS will disconnect them automatically upon serving any issued requests.

For whatever reason, a connection may be terminated explicitely by the DS operator by selecting a connection in the lower list box and pressing the
Terminate button.


B) SESSION CONFIGURATIONS
-----------------------

A session configuration is a set of options and a mission name, which as a unit form the information needed by the DS to start an actual game session.
Each multiplayer mission created by the Ground Control mission editor GenEd has a .ses file, which is the default session configuration for that mission.

It is possible to create unique session configurations via the Session / Create/Edit Session Custom Session Configuration menu item.


NEW SESSION CONFIGURATION DIALOG

The drop-down box presented will include any custom configurations created by the user. It is possible to create new session configurations by pressing
the New button and typing a name. Edit a configuration by pressing Edit.


CUSTOM SESSION CONFIGURATION DIALOG

This dialog displays all options settings in the session configuration. It is possible to base the custom configuration on an existing mission's
session configuration by choosing that .ses file in the Default Mission Configurations list. The Mission Information secetion displays non-modifiable
information about the mission, but all other options can be freely edited. The options presented here are the same as in the Host LAN Game screen
in Ground Control itself. Please refer to the Ground Control manual for further information about there options.

Press OK to save your changes to the current session config, or Cancel to cancel them.


C) STARTING DROP-IN SESSIONS / CYCLES
------------------------------------------

Ground Control clients can create standard or sync-start game sessions via the network, but not drop-in (persistent) game sessions. This is the sole
right of a DS operator.

To create a drop-in session or cycle of sessions, use the Session / Start Session Cycle (Drop-In) menu item. This dialog displays the settings for a
game cycle.


PORT

The DS will automatically assign a base port for the new DSS the will be created when the cycle is started.


GAME NAME

You must type a game name to be allowed to start a DSS.


PASSWORD

Passwords are optional. Leave this field blank for no password.


MAX CLIENTS

The maximum number of players allowed in the session. This value may be changed automatically by the DS if the Allow Alliances options is unchecked.


TECH LEVEL

The tech level controls the units available to players. The higher the techlevel, the more advanced units are available.


DEFAULT SQUADS

If this options is checked, players are not allowed to make custom squad configurations.


ALLOW ALLIANCES

If this options is checked, multiple players are allowed on the same team. If not, players must be on a unique team.

Due to the fact that missions are scripted with a max team limit rather than a max player limit (dropzones are assigned on a per team basis), unchecking
Allow Alliances option may result in a change in the Max Clients value, depending on the session configurations currently in the cycle.


CYCLE TEAMS

Check this option results in players automaically changing teams (+1, will wrap) every time the DSS cycles to a new session. This is meant to be used
in games when the roles are to be reversed between players.


CONFIGURATION

This list contains all default mission session configurations, and any custom configurations created by the user. Press the Add To Cycle button to
add a selected configuration to the current cycle.


CYCLE

A DSS must have at least one session configuration in it's cycle in order to run. If there is more than one configuration in the cycle, the DSS
will cycle through them in order, and revert to the first again after the last has been played.

Note that the Tech Level will automatically be set to the highest value of all the configurations in the cycle, and if Allow Alliances is unchecked,
the Max Clients value will be set to the lowest Max Player Teams value of all the configurations in the cycle (the Max Player Teams value is
an attribute of the mission itself, and dictates the number of teams that have dropzones in mission. This value can be viewed in the Custom
Session Configuration dialog).

The Remove button will remove a selected configuration from the cycle, and the Clear button will clear the cycle.


START SESSION

This button will start a DSS with the information in the dialog. If this button is dimmed, a vital piece of information is missing (missing game name
or no configurations in the cycle, for example).

Once a game session is started, a DSS will be started, load itself, and then connect back to the DS. This can be seen in the DS log window and
the connection noted in the connection window.

The session may be terminated by selecting the relevant connection and pressing the Terminate button in the main DS interface, or by focusing
the DSS window and pressing Q. Note that if any game clients are connected their game will be terminated and they will be disconnected with a
server shutdown message.


LOAD / SAVE CYCLE

The state of the dialog can be saved as a .cyc file for later use or automatic starting of game sessions upon execution of the DS.


EXIT

Exit the dialog without creating a game session.




