Installing ACM and basic usage
==============================

Contents
--------

	System requirement to execute the binary package under MS Windows
	System requirements to compile under Linux
	System requirements to compile under MS Windows
	Compiling and install from the sources
	Running acm.exe
	Single player, practice mode
	The entities IDs problem solved
	Multiplay on a local network
	Multiplay mode on Internet


System requirement to execute the binary package under MS Windows
-----------------------------------------------------------------

A binary package is also available for MS Windows and comes with the i386 32-bits
executable that runs also under 64-bits systems in compatibility mode. It does
not requires compilation nor installation as it runs just "out of the box" by
double-clicking on the acm.exe executable program.

The dis_realy.exe server is also provided to support multiplayer mode over the
net, as explained below.

Installation of the Tcl/tk interpreter is required to execute the acm.tcl launch
interface, which is handy to start the acm.exe program and tuning the great number
of its options.
The Tcl/tk interpreter is available at www.tcl.tk in binary form by
different providers, for example from Magicsplat at
http://www.magicsplat.com/tcl-installer/index.html
Often these packages provide very advanced libraries and programs along with
the basic Tcl/tk, but for our needs only a basic installation is enough.


System requirements to compile under Linux
------------------------------------------

In order to compile the program from the source you will need:

- A 32-bits or 64-bits Linux system.

- The gcc C compiler and the "make" utility as usual.

- The X Window development libraries and runtime.

- The Tcl/tk interpreter to execute the acm.tcl launch interface (recommended).
  Tcl/tk is typically already installed, or a specific package is available for
  any Linux distribution ready for installation.


System requirements to compile under MS Windows
-----------------------------------------------

In order to compile the program from the source you will need:

- MS Windows 7 or later.

- The MinGW system development kit, in particular the C compiler.

- The Tcl/tk interpreter to execute the acm.tcl launch interface (recommended).
  The Tcl/tk interpreter is available at www.tcl.tk in binary form by
  different providers, for example from Magicsplat at
  http://www.magicsplat.com/tcl-installer/index.html
  Often these packages provide very advanced libraries and programs along with
  the basic Tcl/tk, but for our needs only a basic installation is enough.


Compiling and install from the sources
--------------------------------------

Under Windows, you will have to install MinGW first in order to have a complete
system development kit including the C language compiler, the "make" utility
and other needed tools.

Then, open a terminal window and change the directory up to ACM sources
packages.

There is not a configure script: simply type "make" to build all, and cross the
fingers... :-) This will build all the source tree under the src/ directory,
and usually takes only a few seconds on a recent machine:

	$ make

You may also build part of the system. For example, you may build only the
acm.exe program:

	$ cd src/acm
	$ make

The "installation" procedure ends here. Afterward what you will need to run the
program are only these files:

   src/acm/acm.exe  (the ACM program)
   objects/  (scenery, aircraft models, munitions data, etc.)
   acm.tcl  (acm launch interface)
   src/dis/server/dis_relay.exe  (the relay server for net multiplay)


Running acm.exe
---------------

There are two ways. From the command line, type the command:

	$ src/acm/acm.exe -objects objects/

The acm.exe program has so many options that it is practically unusable from the
command line. For this reason I created the acm.tcl script to provide an handy
lunch interface. You may launch that program explicitly invoking the tk/tcl
"window shell" interpreter:

	$ wish acm.tcl &

Remember to go first in the Configure panel and set the path of the acm.exe
program and the path of the objects/ directory before trying to start the
simulator. The DIS panel allows to chose among the single player mode and the
multiplayer mode as detailed below.


Single player, practice mode
----------------------------
Does not require any network, and allows to learn the basic of the flight
techniques: aircraft control, takeoff, landing and navigation. You may generate
as many opponent drones as you want and fight against them; the "Drone" panel of
the launch panel allows also to set their "aggressiveness", that is how much
close (in percent) to their "G" structural limit they will pull to get behind
you...


The entities IDs problem solved
-------------------------------
Each entity in the DIS protocol (aircraft, missile, detonation, etc.) must have
an identification code, or "DIS entity ID", which must be unique between all the
participants into the simulation. But, how to generate these unique IDs on a
network of independent hosts connected together? This problem has been solved
by the DIS protocol by assigning to each entity a number of sub-IDs: the
exercise ID, the site ID, the application ID and the entity sequential number ID.
In more detail:

- Exercise ID: is a number in the range [0,255] all the participants must agree
  on. acm.exe simply ignores and discards any packet with different exercise ID.

- Site ID: each host must have an unique value in the range [0,65534].
  ACM also allows the special value -1 which triggers site ID automatic
  generation. With site ID automatic generation, ACM-6 generates a random
  number and then enter a validation phase checking for collisions with the
  incoming packets. If a collision is detected, the generation process restarts.

- Application ID: each instance of the acm.exe program on a given host must have
  it own host-specific different number chosen in the range [0,65534].
  ACM also allows the special value -1; in this case the current
  process number is used as application ID.

- Each instance of the acm.exe program will automatically generate an univocal
  further entity sequential number ID in the range [1,65533] for each entity it
  generates.

Then, it is very important to configure the exercise, site and application IDs
as follows:

	- exercise ID: the same number for all the participants in the range
	  [0,255], for example 1.

	- site ID: -1 is the simpler choice.

	- application ID: -1 is the simpler choice.


Multiplay on a local network
----------------------------
You may use the broadcast mode of the ACM program. In the launch interface,
DIS panel, ensure the DIS relay host be the empty string; this triggers the
network broadcast packet routing in the program, allowing all the participants to
talk the DIS protocol using the specified shared UDP port. The default port for
the DIS protocol is 3000, but you may agree on any other port to share with the
other participants. Be aware that the broadcasting routing works only if all the
hosts on the local network really share the same exact sub-net, or they will fail
communicate together.

Example with netmask leaving 8 bits for the local network:
Host1: IP address: 192.168.1.33,  netmask: 255.255.255.0
Host2: IP address: 192.168.1.95,  netmask: 255.255.255.0
Host3: IP address: 192.168.1.147, netmask: 255.255.255.0

Another example with a netmask leaving only 2 bits available:
Host1: IP address: 192.168.1.33, netmask: 255.255.255.252
Host2: IP address: 192.168.1.34, netmask: 255.255.255.252

Also set exercise no. 1 or any other value shared with the other participants.
Leave the site ID and application ID set to -1 to trigger automatic assignment.


Multiplay mode on Internet
--------------------------
There must be a DIS relay server running on one of the machines participating
into the simulation, and that machine must have a public IP address. On that
machine issue this command:

	$ src/dis/server/dis_relay --port 3000

to start the relay server; 3000 is the standard UDP port used by the DIS protocol.
Each player must then set that host and that port in the DIS configuration panel
of acm.tcl.

All the participants must agree on a exercise number ID. Site ID and application
ID should be set both to -1 for automatic assignment.

You may try the --debug command line switch to display all the incoming and
relayed packets, along with the IP addresses of all the participants, new clients
entering the simulation and stale clients leaving.


That's all, enjoy!

Umberto Salsi
Bologna, 2017-07-13
