Ground Control Dedicated Server
Network Protocol Version 1.0.3.2
Readme File
June 1, 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.    ISSUES TO AVOID
II.    RELEVANT FILES
IV.    CONFIG FILE SYNTAX
V.     THE UI AND MENUS
	               

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

The unsupported 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).  To find out information about 
this software, please goto http://groundcontrol.won.net.

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. ISSUES TO AVOID
=======================

Our test team found some issues that we'd like to warn you about. If you do the 
following steps, you will run into an error message. To find updates to this 
software, check back at http://groundcontrol.won.net periodically.  

1)  Start ds, click session, start session cycle. Add FZ 8 to the cycle. 

2)  Create a new session or edit an existing one.  Enter letters into the Score 
Limit, Time Limit or Interval.  Click OK.  Click Ok twice to get past the pop-up 
boxes. Click OK again.  Click Ok after the next pop-up box 

3)  Create a new session or edit an existing one.  Enter letters into the Score 
Limit, Time Limit or Interval.  Click OK.  Click Ok twice to get past the pop-up 
boxes. Click on the map drop down box and choose a map.  

4)  Start the DS.  Create a new session.  Edit it and give it a map.  Click OK.  
Start a Session Cycle.  Add the new session to the list.  Give the cycle a name 
and save it.  Exit all the way out of the DS.  Start up the DS.  Start a 
Session Cycle.  Load the cycle you just made.  


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.


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.


WONServers
Defaults to 'groundcontrol.east.won.net:15101,groundcontrol.west.won.net:15101,groundcontrol.central.won.net:15101'.
The ip address 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 explicitly 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 secretion 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 automatically 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.




