S T A R G A T E
                              version 0.15
        http://www.mbnet.fi/%7Eitvirta/stargate.html
        http://phost.de/~vagabond/addons/#stargate

Contents:
 General
 Using the program
 The build process
 Detecting stargates
 Using stargates
 Destroying stargates
 Configuration options
 Bugs, misfeatures and changes
 VPA

General
-------

Stargate is a host side add-on program for the game VGA Planets.
It is written in C and uses the Portable Host Development Kit (PDK) to
access the data structures. This means that it should be easy to port
it to many platforms.

The idea of Stargate is to allow faster movement through the galaxy
(in-game). This is done by building stargates with starbases and ships, and
then travelling from one stargate to another. Stargate uses four extended
commands and some control messages. The extended commands are:
 - Build Stargate
 - Deploy Stargate
 - Use Stargate
 - Destroy Stargate

Stargate was originally written in 1999 by me, Ilkka Virta
(currently itvirta@mbnet.fi). Heiko Schlenker was of great
help with version 0.13 which was created in April 2001.

Using the program
-----------------

On host side:
 In the pcontrol section of your pconfig.src file, replace the line
	Movement                                =  Normal
 with 
	Movement                                =  Exec sgmove.ini
 and replace
	SensorSweep                             =  Normal
 with
	SensorSweep                             =  Exec sgscan.ini

 Then add the files sgmove.ini and sgscan.ini containing the following
 (in sgmove.ini)
  sg015 1 path_to_game_directory path_to_global_files_directory
 (in sgscan.ini)
  sg015 2 path_to_game_directory path_to_global_files_directory

 sg015 is the name of the executable file, so replace if you have
 renamed (or recompiled) the program.

On player side:
 Read the documentation and put up some test games.
 Add the necessary lines to your VPA.MSG if you're using VPA. (see below)
 If you don't you're pretty much in trouble since at least I'm not aware
 of any other program being capable of displaying the gates on map.
 (Stargate does NOT generate any other information in addition
 to the messages.)

The build process
-----------------

Stargates are built at starbases and then placed in ships to be deployed in
deep space. In the game it works like this: 
Turn one:
  Get a ship to a starbase and load it with the necessary materials.
  Set the mission to Build Stargate and wait for the next turn.
  (ATTENTION: Do not set the starbase mission to "Unload Freighters"!)
Turn two:
  Now the ship contains a stargate. There should be a message indicating this.
  Order the ship to fly to some point in deep space. Wait for next turn.
  The ship must be far enough. See config options below.
Turn three:
  Order the ship to Deploy the Stargate. Wait for next turn.
Turn four: 
  Stargate is operational. Note that this is the first turn during which
  the gate can be used. It does NOT work on the same turn it was deployed.

The required amount of minerals equals buildcost1 + buildcost2 
(config opts. below). buildcost1 is the amount of minerals removed during
Build Stargate command. The rest (buildcost2) will stay on the ship
(representing the gate) until the gate is deployed or until they are moved
away in which case the stargate is considered recycled. Capturing or
giving away a ship carrying a stargate does not destroy the gate.


Detecting stargates
-------------------

To use a stargate you must first know two stargates. The one you travel from,
and the one you travel to. You can gain knowledge of a stargate in three
different ways. These are:
 1) You build it.
 2) You scan it.
  a) The sensor sweep mission scans for stargates. The closer you are to
     the stargate, the more probable it is that you will see it.
     You can't sensor sweep stargates on planets (normally stargates
     aren't and shouldn't be allowed to be set at planets.)
  b) If you are on the same position as the stargate is, you will
     automatically scan it regardless of your mission.
 3) Someone tells you about the gate. This has be done in-game by
    a command message. To tell someone about a stargate you should send
    yourself a message that contains a line like the following:

xtern stargate tell P about SG

    Here P is the number of player, and SG is the number of the stargate.
    [ I'm not sure if this has been tested yet. :-/ ]


Using stargates
---------------

To use a stargate you fly to the same position in space the stargate is
and set your mission to Use Stargate with the number of the destination
gate as the argument. You must know the destination gate before this.
Note that since you have to change your mission you will can't be cloaked
while you do this. There is now another argument to the command.
This is the ID number of the ship you want to tow through the gate.
If you tow a ship you pay the needed fuel for both ships but the towed
ship can be your enemy's ship (if it doesn't have any fuel) and it doesn't
need to have the required engines. NOTE: If the towed ship has fuel on board,
it will gain knowledge of the destination gate after the ships have
arrived. Ships without fuel can't detect any gates.

The following applies if interracial travelling is restricted via a
configuration option:
    To use a stargate, the owners of the source and target stargate
    have to offer a ship level alliance to each other. The owner of
    the travelling ship and the owners of the stargates must be allies
    and must have the ship level alliance enabled to each other.


Destroying stargates
--------------------

Mission Destroy Stargate causes a ship to destroy all stargates it
happens to fly to. Destroying a gate happens before movement and
before using the gates. There is a configuration option for the minimum
beam level required for this.



Configuration options
---------------------

Configuration options are set in a file called stargate.cfg
The allow_* and deny_* set who and what ships are able to do something
about stargates. *_player_* options set player limitations and *_ship_*
options set ship limitations. A value of 0 means to allow/deny all.
The options
allow_ship_build_stargate=0
deny_ship_build_stargate=13
would allow all ships except number 13 to build stargates. This is of course
still limited by the size of the cargo bays.

alliance_support controls whether players will automatically gain knowledge
about stargates known to their (ship level) allies.

tell_support controls whether the tell command message is allowed.

tow_support controls whether towing ships through stargates is allowed.

max_scandistance is the maximum distance for detecting a gate with
sensors. All gates closer to max_seedistance are automatically detected.
(only if scanning)

lost_in_hyperspace is an interesting option. It controls what happens to
ships that are trying to use a stargate on the same turn the destination
gate is destroyed. If lost_in_hyperspace = 0, nothing happens and ships
will stay in place. If lost_in_hyperspace = 1, then the ships will be
destroyed. This only applies to stargates destroyed on the same turn,
not to ones destroyed earlier or ones that never existed because the
player trying to use gates would in these cases know that they don't exist
or that he can't use them.

min_distance_from_planet controls how close to planets the stargates can
be placed. Setting this to zero allows setting stargates ON planets and
this is not recommended because it is supposed to have severe implications
on game strategy.

restrict_interracial_travelling controls whether interracial travelling
is restricted to allies.

The rest are hopefully pretty self-explanating.

- - - - - - - - - - - - example
#            n   t   d   m   c   s   $
buildcost1=  50, 50, 50, 50,  0, 50,2000
buildcost2= 150,250,250,250,  0,250,   0
min_distance_from_planet=45
min_hull_tech_to_build=7

min_engine_tech_to_use=5
min_travel_distance=100
max_travel_distance=5000
use_fuel_burn=50
lost_in_hyperspace=1

allow_player_use_stargate=0
allow_hull_use_stargate=0
allow_player_deploy_stargate=0
allow_hull_deploy_stargate=0
allow_player_destroy_stargate=0
allow_hull_destroy_stargate=0
allow_player_build_stargate=0
allow_hull_build_stargate=0
verbosity=0
build_stargate_mission=90
deploy_stargate_mission=91
use_stargate_mission=92
destroy_stargate_mission=93

alliance_support=1
tell_support=1
tow_support=1

restrict_interracial_travelling=1

min_beam_tech_to_destroy=5
max_scandistance=200
max_seedistance=0
- - - - - - - - - - - -


Bugs, misfeatures and changes
-----------------------------

I try to immediately fix all the bugs I find, so I won't keep a list of
known bugs. Not even a list of fixed bugs, so use the newest version.

Misfeatures are another thing.
Here are some known ones:
 * If you are using Timhost, you may notice that travelling between gates
 happens actually _AFTER_ regular movement and combat, even though it's
 supposed to happen before. I believe the reason to be some kind of an
 incompatibility between the Development Kit and Timhost.
 * Alliances and telling about gates don't work in Timhost
 * The program doesn't support > 500 ships (this is completely a (P)DK issue.)

These are probably enough reasons to not use the program with TimHost.


Things added...
... in version 0.13 gamma
 + Added a configuration option to control whether it's allowed to use a
   gate if you're not allied with owner of the gate.
 + Fuelless ships can't detect gates now.


VPA
---

Add the following to the end of your VPA.MSG file to make VPA show
the gates on your map.

======== cut here ========

; *** Stargates
; --- We built a stargate
Message Common
Check 4,[We have built a stargate]
Keep
End
; --- We are carrying a stargate
Message Marker
Check 1,[Known Stargate]
Check 3,[Our ship]
x [(],[(]
y [(],[,,]
keep circle 3
end 

; --- We know a stargate somewhere
Message Marker
Check 1,[Known Stargate]
Check 3,[Stargate]
x [(],[(]
y [(],[,,]
keep square 3
end

; --- We blew up a stargate
Message Marker
Check 1,[Stargate Message]
Check 4,[We have destroyed stargate]
x [(],[(]
y [(],[,,]
keep cross 13
end

; --- Someone else blew up a stargate
Message Marker
Check 1,[Stargate Message]
Check 3,[Stargate explosion detected]
x [(],[(]
y [(],[,,]
keep cross 13
end

; --- We lost a ship in hyperspace
Message Marker
Check 1,[Stargate Message]
Check 4,[has not been seen after it]
Check 5,[entered a stargate at]
x [(],[(]
y [(],[,,]
keep flag 12
end

; --- stargate detected
Message Marker
Check 1,[Stargate Message]
Check 4,[We have detected a stargate!]
x [(],[(]
y [(],[,,]
keep square 3
end

======== cut here ========