The VGA planets I/O Library V3 (VPL3) is distributed both as a part of the RLSystems VGA planets Software Development Kit for DJGPP, and seporately. This file should be included in both distributions as of July 2000.
This file documents all methods, variables, etc. in the library - even the ones you shouldn't use! - so be careful when using the library, and try to stick to the recommended routines as much as possible: using the methods not recommended for use can result in future copies of your program to behave differently, as those methods may be subject to change without prior notice - or any notice for that matter.
I've tried not to skip anything, and describe each and every method, but there are a lot of them, and I am only human. Should I have missed a method somewhere, please notify me at once, so I can document it.
As you will know as you read this, VGA planets is a multi-player Play-By-E-Mail (PBEM) game, with two distinct parts: the host-side software and the player-side software. The host has been designed to accept extentions to it's own functions, using so-called add-ons (different from plugins because the code is not executed by the host itself). In theory, anyone who knows the setup of the data the host maintains can write an add-on to manipulate that data. Examples of such add-ons - examples I wrote using this library - are Gators, the Starbase Enhancer, the Trampoline Device, etc. The biggest drawback to writing add-ons is, however, that you need to know how the host operates in order to be able to write your add-ons and have them interact with the game.
I have spent quite a few days/weeks/months figuring out how the game works internally, and I think I have a pretty good grasp of it by now. This knowledge has helped my win games, but has also enabled me to write add-ons, and put the code common to all those add-ons together in a reusable component - this library.
After some time, I decided to make this library available to the general public: this is the third version of the library, and only very few people have the first two versions, which were written in other languages, and it is now at a stage at which I think more people can actually benefit from it. So here it is: a library which allows you nigh complete access to the databases the host maintains, and some databases my own add-ons maintain.
Use this library with DJGPP, the free GNU C/C++ compiler by DJ Delorie et al. (Look for the ZIP Picker on his site and download the files you need..).
The entire library was written in C and consists of two parts: one "raw"
access part, accessed through <vgap.h>; and an easier part, with a
lot of dispatchers and background software (most of the library consists
of software for this part) accessed through <vpl3.h>.
If you know for sure you're not going to use that, but will only be using
the "raw" part, use the "raw" version of this library, <libVGAPRaw.a>.
It has been compiled with only what you need for that part of the library.
(You'll still need the Swing library, though, because it is needed for the
error identification (e.g. if certain files are missing)).
This documentation is written for the full version. The part of the
documentation handling the <vgap.h> file is all you'll need for the
raw version.
The other library, <libVGAPExtentions.a>, contains dispatchers for
RLSystems add-ons I/O. It is not finished yet, but when it is, it will be
documented here.
To get started with the library as quickly as possible, just remember these simple steps when writing your program:
#define LSW1_All #include <swing.h> #include <vpl3.h>
bool rc = true; /* ... */ if (rc) rc = initSwing(); if (rc) rc = initVPL3(USE_ALL, gamePath, basePath, &numships, 0);
if (rc) {
return(0);
} else done(errCode);
To install the package, all you need to do is unzip it on your DJGPP directory.. C'est tout!
The two main header files for this library are <vpl3.h> and
<vgap.h>.
<vpl3.h> contains the (prototypes of) the VGA
Planets I/O dispatchers. You do not need any more than this to access
anything you might want to access in the host data. Most of the hard work
is done for you, and the data is presented to you in well-documented data
structures, which are filled in by the dispatchers, as you read the data
from several files. These dispatchers require some memory, but are not
all that memory-hogging in that they can run on most machines, and you can
force them to use temp files in stead of keeping the data in memory (at
the expense of speed).
<vgap.h> contains the (prototypes of) the raw I/O stuff.
All you need to access can be accessed with this, but it does substantially
less for you. Nice if you want to do the hard-core programming yourself,
so you know exactly what is being done, but (to my opinion) less elegant.
There are several other header files for the library, most of which you will not need to use. Still, as this documentation is supposed to be complete, they are listed here:
<vpl3/battle.h>
The Battle module of the library contains a port of Tim's VCR program, adapted so it can also do battle with Gators, warped ships, and potentially other objects as well. Should you have an object of your own with which you would like to have ships, planets, warped ships or Gators do battle, just tell me the specs and I will add it to the engine.
The doBattle() method is not guaranteed to keep the same interface (i.e.: objects may be added to the parameters later).
<vpl3/compilers.h>
The Compilers module is internal to the library, and should not be used by any other software. (It is documented in more detail below).
<vpl3/enh2Structures.h>
The Enhancer V2 Structures module contains all the structures used by the RLSystems Starbase Enhancer, and the filters to the data as it is saved on disk.
<vpl3/enhancerOptions.h>
The Enhancer V2 Options module contains the core of the RLSystems Starbase Enhancer - you can't actually recreate the add-on with this module, because the actual functional dispatchers are not included, but you can access al the information.
<vpl3/filters.h>
The Filters module is internal to the library and should not be used by other software. It is fully documented below.
<vpl3/gators.h>
The Gators header is only part of the library because some defines in the header are used by other modules. The actual module is not included in the library.
The macros and defines are documented below.
<vpl3/globalVGAPInfo.h>
The Global VGAP Info module contains information used by just about every add-on written, but not necesarrily by the library itself. It is included in the library as an aid, but not required for any part of the library.
<vpl3/gtr3FileDispatchers.h>
The Gators V3 File Dispatchers module takes care of all file I/O for RLSystems Gators V3, and is used by many other add-ons, which use Gators.
<vpl3/gtr3Structures.h>
The Gators V3 Structures module contains all the structures used by RLSystems Gators, and the filters for memory to disk and vice versa conversion.
<vpl3/gtr3UFODispatchers.h>
The Gators V3 UFO Dispatchers module contains the methods used by Gators to put Gators, MiniGates and warped ships in the UFO database.
<vpl3/messages.h>
The Messages module contains all pre-defined messages sent by Gators, The Starbase Enhancer, The Trampoline Device, Spy, The Freelan People's add-on, etc. It also contains everything you need to access the subspace messages in the game, but the getMessage() method has not been fully tested yet.
<vpl3/rlssbenh.h>
The RLSystems Starbase Enhancer header file serves roughly the same purpose as the Gators header does: the actual module is not part of the library.
<vpl3/spy.h>
The Spy header file serves roughly the same purpose as the Gators header does: the actual module is not part of the library.
<vpl3/spyStructures.h>
The Spy Structures module contains all structures used by Spy, and the associated filters. THIS ADD-ON IS UNDER CONSTRUCTION! The structures WILL NOT remain the same, and the modules may even be removed from the library altogether..
More modules will be added to the library - e.g. the Freelan modules have not been added yet..
These are the most important functions in the vpl3-part of the library: the initialize the library, open the required files, set up the required memory buffers, and allow you access to all you need.
#include <vpl3.h> bool initVPL3(int mode, char *gamePath, char *basePath, short *numberOfShips, byte player);
Initializes the library in mode MODE, which is a combination of:
Prevents the library from putting all the accessed game data in memory - has it use temporary files in stead. This makes your program slower, but less memory-hogging.
Tells the library to allow access to ship data. This means you will be able to use readShip() and writeShip() from your program.
Tells the library to allow access to planet data. This means you will be able to use readPlanet() and writePlanet() from your program.
Tells the library to allow access to the starbase data. This means you will be able to use readStarbase() and writeStarbase() from your program.
Tells the library to allow access to the race data. This means you will be able to use readRace() and writeRace() from your program.
Tells the library to allow access to the host/game configuration data. This means you will be able to use readConfig() and writeConfig() from your program.
Tells the library to allow access to the minefield data. This means you will be able to use readMinefield() and writeMinefield() from your program.
Tells the library to allow access to the ion storm data. This means you will be able to use readIonstorm() and writeIonstorm() from your program.
Tells the library to allow access to the UFO data. This means you will be able to use readUFO() and writeUFO() from your program.
Tells the library to validate and repair all data before it is written to the databases, and before it is presented to your program. Currently, this doesn't do anything because the validation filters haven't been implemented in this release of the library yet (they exist, but are not part of the library yet).
Tells the library your program is not a host-side add-on, but a player-side utility.
combines the USE_* options.
GAMEPATH should be the complete path to the game data, including
the final slash; BASEPATH should be the complete path to the host - or to
the directory where the host data files are kept (the HULLSPEC.DAT,
ENGSPEC.DAT, TORPSPEC.DAT and BEAMSPEC.DAT files), including the final
slash. NUMBEROFSHIPS should point to a variable where you expect the
maximal number of ships to be returned, or NULL if you're not going to use
it. If you use the <globalVGAPInfo.h> header, you can use
&numberOfShips, which is a variable in the Global VGA Planets Info
module. PLAYER should be the ID of the player, if your program is a
player-side utility, or 0 if it's either a host-side utility, or should
read all player data. For host-side utilities & add-ons, this is ignored.
Player-side utilities are not supported yet.
if (rv) rv = initVPL3(NO_BUFFERING | USE_ALL, "y:/honor/process/", "z:/planets.32/", 0);
true if successful, false if not. If it fails, errCode will be set accordingly, and done() will have Swing display the proper error message.
#include <vpl3.h> bool readConfig(configType *cfg);
Reads the entire host/game configuration and presents the data in a comprehesive structure containing the hconfig settings, which race can build which ships, and the the hull, engine, beam weapon and torpedo specifications. In short: everything you might want to know about the host/game configuration. Races names etc. are available from readRace(), planet names etc. are available in readPlanet().
true if successful, false if not.
#include <vpl3.h> bool readShip(shipRecordType *p, short record);
Reads all relevant information about ship ID# RECORD into P. This includes the owner, name, ID#, fCode, cargo, strength, speed, engine specs, probable location next turn, mission, etc.
true if successful, false if not.
#include <vpl3.h> bool readPlanet(planetRecordType *p, short record);
Reads all relevant information about planet ID# RECORD into P. This includes the ID, name (which is not read-only!!), owner, friendly code, core contents, mined minerals, mineral density, structures, climate, population, etc.
true if successful, false if not.
#include <vpl3.h> bool readStarbase(starbaseRecordType *p, short record);
Reads all relevant information about starbase ID# RECORD into P. This includes the ID, name, owner, friendly code, and what it's doing.
true if successful, false if not.
#include <vpl3.h> bool readRace(raceRecordType *r, short record);
Reads all relevant information about race ID# RECORD into R. This includes the ID, name (which is not read-only!!), race type (for SwitchRace hosts: SRace allows any race to act as any other races if the host chooses so..), alliances, points, etc.
true if successful, false if not.
#include <vpl3.h> bool readMinefield(minefieldRecordType *m, short record);
Reads all relevant information about minefield ID# RECORD into M. This includes the ID, owner, size, etc.
true if successful, false if not.
#include <vpl3.h> bool readIonstorm(ionstormRecordType *m, short record);
Reads all relevant information about ion storm ID# RECORD into M. This includes the ID, size, strength, etc.
true if successful, false if not.
#include <vpl3.h> bool readUFO(UFORecordType *m, short record);
Reads all relevant information about UFO ID# RECORD into M. This includes the ID, owner, etc.
true if successful, false if not.
#include <vpl3.h> bool readHost(hostRecordType *hostRecord);
Reads the information about the host
true if successful, false if not.
#include <vpl3.h> bool readPlayer(playerRecordType *playerRecord, short record); // see comment R3
Reads the information about a player. Can only be used at the player-side.
true if successful, false if not.
#include <vpl3.h> bool readIncomingMessage(messageRecordType *messageRecord, short record);
Reads an incoming message - player-side only.
true if successful, false if not.
#include <vpl3.h> bool readOutgoingMessage(messageRecordType *messageRecord, short record);
Reads an outgoing message - player-side only.
true if successful, false if not.
#include <vpl3.h> bool writeConfig(configType *cfg);
Stores the configuration data in CFG for later use.
true if successful, false if not.
#include <vpl3.h> bool writeShip(shipRecordType *p, short record);
Stores the ship record in P for later use. Assumes RECORD is a correct indication for the ship ID number.
true if successful, false if not.
#include <vpl3.h> bool writePlanet(planetRecordType *p, short record);
Stores the planet record in P for later use. Assumes RECORD is a correct indication for the planet ID number.
true if successful, false if not.
#include <vpl3.h> bool writeStarbase(starbaseRecordType *p, short record);
Stores the starbase record in P for later use. Assumes RECORD is a correct indication for the planet/starbase ID number.
true if successful, false if not
#include <vpl3.h> bool writeRace(raceRecordType *r, short record);
Stores the race record in R for later use. Assumes RECORD is a correct indication for the race ID number.
true if successful, false if not
#include <vpl3.h> bool writeMinefield(minefieldRecordType *m, short record);
Stores the mine field record in M for later use. Assumes RECORD is a correct indication for the mine field ID number.
true if successful, false if not
#include <vpl3.h> bool writeIonstorm(ionstormRecordType *m, short record);
Stores the ion storm record in M for later use. Assumes RECORD is a correct indication for the ion storm ID number.
true if successful, false if not
#include <vpl3.h> bool writeUFO(UFORecordType *m, short record);
Stores the UFO record in M for later use. Assumes RECORD is a correct indication for the UFO ID number.
true if successful, false if not.
#include <vpl3.h> bool writeIncomingMessage(messageRecordType *messageRecord, short record);
Writes an incoming message
true if successful, false if not.
#include <vpl3.h> bool writeOutgoingMessage(messageRecordType *messageRecord, short record);
Writes an outgoing message
true if successful, false if not.
The following functions are used by the dispatchers and by certain add-ons. For "normal" VGA Planets software, you will not need these functions - ever.
Access to the standard host files through non-dispatched functions requires extensive knowledge of the setup of the game. Make sure you have such knowledge, or leave it to the dispatchers!
The following is a list of openers, closers, readers and writers. These are all available in <vgap.h> and provide "raw" access to the host data. If you have studied the setup of the <vpl3.h> dispatchers and structures, you will find that the endogenous host structures contain considerably less data. You will have to gather all the data you need for yourself, and will thus often have to do a lot of programming, while it has already been done for you..
#include <vgap.h> bool openGen(char *genPath);
Opens the file pointed to by GENPATH and assumes it's (the equivalent of) GEN.HST - the file with the general game info.
true if successful, false if not
#include <vgap.h> bool openHConfig(char *hConfigPath);
Opens the file pointed to by HCONFIGPATH and assumes it's (the equivalent of) HCONFIG.HST - the file with the host configuration info.
true if successful, false if not
#include <vgap.h> bool openPlanetXYDB(char *planetXYPath);
Opens the file pointed to by PLANETXYPATH and assumes it's (the equivalent of) XYPLAN.HST - the file with the starmap.
true if successful, false if not
#include <vgap.h> bool openPlanetNameDB(char *planetNMPath);
Opens the file pointed to by PLANETNM and assumes it's (the equivalent of) PLANET.NM - the file with the planet names.
true if successful, false if not
#include <vgap.h> bool openRaceNameDB(char *raceNamePath);
Opens the file pointed to by RACENAMEPATH and assumes it's (the equivalent of) RACE.NM - the file with the race names.
true if successful, false if not
#include <vgap.h> bool openGreyDB(char *greyPath);
Opens the file pointed to by GREYPATH and assumes it's (the equivalent of) GREY.HST - the file with the ion storms etc.
true if successful, false if not
#include <vgap.h> bool openTorpDB(char *torpPath);
Opens the file pointed to by TORPPATH and assumes it's (the equivalent of) TORPSPEC.DAT - the file with the torpedo specifications.
true if successful, false if not
#include <vgap.h> bool openBeamDB(char *beamPath);
Opens the file pointed to by BEAMPATH and assumes it's (the equivalent of) BEAMSPEC.DAT - the file with the beam weapon specifications.
true if successful, false if not
#include <vgap.h> bool openEngineDB(char *enginePath);
Opens the file pointed to by ENGINEPATH and assumes it's (the equivalent of) ENGSPEC.DAT - the file with the engine specifications.
true if successful, false if not
#include <vgap.h> bool openBaseDB(char *basePath);
Opens the file pointed to by BASEPATH and assumes it's (the equivalent of) BDATA.HST - the file with the starbase info.
true if successful, false if not
#include <vgap.h> bool openHullDB(char *hullPath);
Opens the file pointed to by HULLPATH and assumes it's (the equivalent of) HULLSPEC.DAT - the file with the hull specifications.
true if successful, false if not
#include <vgap.h> bool openMineDB(char *minePath);
Opens the file pointed to by MINEPATH and assumes it's (the equivalent of) MINES.HST - the file with the general game info.
true if successful, false if not
#include <vgap.h> bool openPlanetDB(char *planetPath);
Opens the file pointed to by PLANETPATH and assumes it's (the equivalent of) PDATA.HST - the file with the planet info.
true if successful, false if not
#include <vgap.h> bool openShipDB(char *shipPath);
Opens the file pointed to by SHIPPATH and assumes it's (the equivalent of) SHIP.HST - the file with the ship info.
true if successful, false if not
#include <vgap.h> bool openShipXYDB(char *shipXYPath);
Opens the file pointed to by SHIPXYPATH and assumes it's (the equivalent of) SHIPXY.HST - the file with the ship coordinat info.
true if successful, false if not
#include <vgap.h> bool openUFODB(char *UFOPath);
Opens the file pointed to by UFOPATH and assumes it's (the equivalent of) UFO.HST - the file with the UFO info.
true if successful, false if not
#include <vgap.h> bool openCloakDB(char *cloakPath);
Opens the file pointed to by CLOAKPATH and assumes it's (the equivalent of) CLOAKC.HST - the file with the ship shield status and cloak status info.
true if successful, false if not
#include <vgap.h> bool closeGen(void);
Closes the file opened by openGen()
true if successful, false if not
#include <vgap.h> bool closeHConfig(void);
Closes the file opened by openHConfig()
true if successful, false if not
#include <vgap.h> bool closePlanetXYDB(void);
Closes the file opened by openPlanetXYDB()
true if successful, false if not
#include <vgap.h> bool closePlanetNameDB(void);
Closes the file opened by openPlanetNameDB()
true if successful, false if not
#include <vgap.h> bool closeRaceNameDB(void);
Closes the file opened by openRaceNameDB()
true if successful, false if not
#include <vgap.h> bool closeGreyDB(void);
Closes the file opened by openGreyDB()
true if successful, false if not
#include <vgap.h> bool closeTorpDB(void);
Closes the file opened by openTorpDB()
true if successful, false if not
#include <vgap.h> bool closeBeamDB(void);
Closes the file opened by openBeamDB()
true if successful, false if not
#include <vgap.h> bool closeEngineDB(void);
Closes the file opened by openEngineDB()
true if successful, false if not
#include <vgap.h> bool closeBaseDB(void);
Closes the file opened by openBaseDB()
true if successful, false if not
#include <vgap.h> bool closeHullDB(void);
Closes the file opened by openHullDB()
true if successful, false if not
#include <vgap.h> bool closeMineDB(void);
Closes the file opened by openMineDB()
true if successful, false if not
#include <vgap.h> bool closePlanetDB(void);
Closes the file opened by openPlanetDB()
true if successful, false if not
#include <vgap.h> bool closeShipDB(void);
Closes the file opened by openShipDB()
true if successful, false if not
#include <vgap.h> bool closeShipXYDB(void);
Closes the file opened by openShipXYDB()
true if successful, false if not
#include <vgap.h> bool closeUFODB(void);
Closes the file opened by openUFODB()
true if successful, false if not
#include <vgap.h> bool closeCloakDB(void);
Closes the file opened by openCloakDB()
true if successful, false if not
#include <vgap.h> bool readActive(bool *isActive, short record);
Reads whether or not race RECORD is active. Sets ISACTIVE accordingly (true if the race is still alive, false if not).
true if successful, false if not
#include <vgap.h> bool readAllianceStatus(allianceType *alliances);
Reads the alliances in the game.
true if successful, false if not
#include <vgap.h> bool readKillPoints(short *PBP, short record);
Reads the priority build points (aka killpoints) of race RECORD into PBP.
true if successful, false if not
#include <vgap.h> bool readCrewExperience(short *experience, short record);
Reads the crew experience of ship number RECORD.
true if successful, false if not
#include <vgap.h> bool readIonStorm(ionType *ionRec, short record);
Reads the information about ion storm number RECORD
true if successful, false if not
#include <vgap.h> bool readTorpRecord(torpSpecType *torpRec, short record);
Reads the torpedo specifications for torpedo (tube) RECORD
true if successful, false if not
#include <vgap.h> bool readBeamRecord(beamSpecType *beamRec, short record);
Reads the beam weapon specifications for beam weapon RECORD
true if successful, false if not
#include <vgap.h> bool readEngineRecord(engineSpecType *engineRec, short record);
Reads the engine specifications for engine type RECORD
true if successful, false if not
#include <vgap.h> bool readBaseRecord(baseType *baseRec, short record);
Reads the starbase at planet ID# RECORD
true if successful, false if not
#include <vgap.h> bool readHullRecord(hullSpecType *hullRec, short record);
Reads the hull specifications of hull type number RECORD
true if successful, false if not
#include <vgap.h> bool readMineRecord(mineType *mineRec, short record);
Reads the info about mine field number RECORD
true if successful, false if not
#include <vgap.h> bool readPlanetRecord(planetType *planetRec, short record);
Reads the info about planet number RECORD
true if successful, false if not
#include <vgap.h> bool readShipRecord(shipType *shipRec, short record);
Reads the info about ship number RECORD
true if successful, false if not
#include <vgap.h> bool readShipXYRecord(shipXYType *shipXYRec, short record);
Reads the coordinats and mass of ship number RECORD
true if successful, false if not
#include <vgap.h> bool readUFORecord(UFOType *UFORec, short record);
Reads the info about UFO number RECORD
true if successful, false if not
#include <vgap.h> bool readHConfig(hConfigType *hConfigRec);
Reads the host configuration
true if successful, false if not
#include <vgap.h> bool readPlanetXYRecord(planetXYType *planetXYRec, short record);
Reads the location of planet number RECORD
true if successful, false if not
#include <vgap.h> bool readPlanetNameRecord(char *planetNMRec, short record);
Reads the name of planet number RECORD
true if successful, false if not
#include <vgap.h> bool readRaceNames(raceNameType *raceNames);
Reads the names of all races in all allowable forms
true if successful, false if not
#include <vgap.h> bool readShipShieldStatus(shipShieldStatusType *S, short record);
Reads the shield and cloak status of theip ID# RECORD
true if successful, false if not
#include <vgap.h> bool writeActive(bool *isActive, short record);
Sets whether or not race RECORD is active.
true if successful, false if not
#include <vgap.h> bool writeAllianceStatus(allianceType *alliances);
Writes the alliances
true if successful, false if not
#include <vgap.h> bool writeKillPoints(short *PBP, short record);
Writes the priority build points for race RECORD
true if successful, false if not
#include <vgap.h> bool writeCrewExperience(short *experience, short record);
Writes the crew experience for ship number RECORD
true if successful, false if not
#include <vgap.h> bool writeIonStorm(ionType *ionRec, short record);
Writes the information of ion storm RECORD
true if successful, false if not
#include <vgap.h> bool writeTorpRecord(torpSpecType *torpRec, short record);
Writes the torpedo specifications of torpedo type RECORD
true if successful, false if not
#include <vgap.h> bool writeBeamRecord(beamSpecType *beamRec, short record);
Writes the beam weapon specifications for beam weapon type RECORD
true if successful, false if not
#include <vgap.h> bool writeEngineRecord(engineSpecType *engineRec, short record);
Writes the engine specifications for engine type RECORD
true if successful, false if not
#include <vgap.h> bool writeBaseRecord(baseType *baseRec, short record);
Writes the information of the starbase as planet number RECORD
true if successful, false if not
#include <vgap.h> bool writeHullRecord(hullSpecType *hullRec, short record);
Writes the hull specifications of hu
true if successful, false if not
#include <vgap.h> bool writeMineRecord(mineType *mineRec, short record);
Writes mine field RECORD
true if successful, false if not
#include <vgap.h> bool writePlanetRecord(planetType *planetRec, short record);
Writes info of planet RECORD
true if successful, false if not
#include <vgap.h> bool writeShipRecord(shipType *shipRec, short record);
Writes info of ship RECORD
true if successful, false if not
#include <vgap.h> bool writeShipXYRecord(shipXYType *shipXYRec, short record);
Writes coordinats and mass of ship RECORD
true if successful, false if not
#include <vgap.h> bool writeUFORecord(UFOType *UFORec, short record);
Writes info of UFO RECORD
true if successful, false if not
#include <vgap.h> bool writeHConfig(hConfigType *hConfigRec);
Writes the host configuration
true if successful, false if not
#include <vgap.h> bool writePlanetXYRecord(planetXYType *planetXYRec, short record);
Writes the coordinats of planet RECORD
true if successful, false if not
#include <vgap.h> bool writePlanetNameRecord(char *planetNMRec, short record);
Writes the name of planet RECORD
true if successful, false if not
#include <vgap.h> bool writeRaceNames(raceNameType *raceNames);
Writes the names of all races
true if successful, false if not
#include <vgap.h> bool writeShipShieldStatus(shipShieldStatusType *S, short record);
Writes the shield and cloak status of ship RECORD
true if successful, false if not
RLSystems Gators V3 keeps a number of files, linking parts of the Echo Cluster together, as well as different games. The third version of Gators is also compatible with some earlier versions of Gators - as of version 2.0.8 F. This library provides access into all those files, and lets you know whether they exist or not. It also lets you convert V2 Gators to V3 Gators, but not the other way around.
#include <vpl3/gtr3FileDispatchers.h> bool existGTR2GatorDB(void);
Checks whether or not the GATOR.HST file exists in the game path. It does not check inside the file to see whether or not it is actually a V2 Gators database.
true if the file exists, false if not. Will normally return false.
#include <vpl3/gtr3FileDispatchers.h> bool existGTR2GatorConfig(void);
Checks whether or not the V2 Gators configuration file exists. This does not look inside the file to see what the actual version number is.
true if the file exists, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool existGTR3GatorDB(void);
Checks whether or not the GATORS.HST file exists in the game directory. This file always exists if Gators is being used, and is thus a good indication for whether or not Gators is being used.
true if the file exists, false if not. This will usually return true if Gators is being used, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool existGTR3GatorConfig(void);
Checks whether or not the Gators configuration file exists in the game path. It does not look inside the file for which version of Gators is being used.
true if the file exists, false if not.
#include <vpl3/gtr3FileDispatchers.h> short readGTRVersion(void);
Gets the version number of the file setup of the Gators files from the configuration file.
a representation of the version of Gators being used. The upper byte is the main version number (0x02 or 0x03); the lower byte is the version of the file setup (usually 0x08, 0x00 or 0x11).
This version number only changes when the setup of the Gators files changes and is then changed to the version number of the version implementing the new setup. The last change up til now (July 13th 2000) was with version 3.1.1 of Gators, at which time the setup was adjusted to allow for a lot of new options.
Gators V3 is compatible with data files from version 2.0.8 and later.
#include <vpl3/gtr3FileDispatchers.h> bool openGTR2GatorDB(void);
Opens the V2 Gators database - should only be used if you know that it exists, and that the version is V2. normally, you just shouldn't use it.
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool openGTR2Config(void);
Opens the V2 configuration file. Normally, you won't have to use this function.
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool closeGTR2GatorDB(void);
Closes the file opened by openGTR2GatorDB()
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool closeGTR2Config(void);
Closes the file opened by openGTR2Config()
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool readGTR2GatorRecord(GTR2_GatorType *gator, short record);
Reads V2 Gator record RECORD
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool readGTR2Config(GTR2_ConfigType *config);
Reads the configuration of Gators V2
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool writeGTR2GatorRecord(GTR2_GatorType *gator, short record);
Writes V2 Gator record RECORD
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool writeGTR2Config(GTR2_ConfigType *config);
Writes the Gators V2 configuration
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool GTR2Gtr2GTR3Gtr(gatorType *gtr3, GTR2_GatorType *gtr2);
Converts a V2 Gator GTR2 to a V3 Gator GTR3
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool GTR2Cfg2GTR3Cfg(gatorConfigType *cfg3, GTR2_ConfigType *cfg2);
Converts V2 Gator configuration to V3 Gator configuration
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool renameGTR2ConfigFile(void);
Prior to conversion, V2 files may have to be renamed to their original V2 counterparts, as V2 files sometimes had names now associated with V3 of Gators. This method renames the Gators configuration.
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool renameGTR2GatorDB(void);
Prior to conversion, V2 files may have to be renamed to their original V2 counterparts, as V2 files sometimes had names now associated with V3 of Gators. This method renames the Gators database.
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool initGatorDB(void);
Initializes the Gators database and destroys all existing Gators.
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool initGatorConfig(void);
Initializes the Gators configuration to the defaults.
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool initShipUFODB(void);
initializes the database with the warped ships
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool initLinkShipDB(void);
Initializes the database with the ships between universes. This database is used when a ship is warped into a parallel universe - another game - to store the ships that haven't arrived yet.
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool openGatorDB(void);
Opens the Gators database
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool openGatorConfig(void);
Opens the Gators configuration file
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool openShipUFODB(void);
Opens the database with the warped ships
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool openLinkShipDB(void);
opens the database with the ships between universes
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool closeGatorDB(void);
Closes the file opened by openGatorDB()
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool closeGatorConfig(void);
Closes the Gators configuration file opened by openGatorConfig()
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool closeShipUFODB(void);
Closes the database with the warped ships opened by openShipUFODB()
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool closeLinkShipDB(void);
Closes the database with the ships between universes opened by openLinkShipDB()
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool getGatorRecord(gatorType *gator, short record);
Reads a Gator record directly from the database. You won't normally have to use this function, but should use readGatorRecord() in stead.
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool readGatorRecord(gatorType *gator, short record);
Reads Gator record RECORD into GATOR.
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool readGatorConfig(gatorConfigType *config);
Reads the configuration of Gators
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool readShipUFORecord(shipUFOType *shipUFO, short record);
Reads warped ship RECORD into SHIPUFO.
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool readLinkShipRecord(linkShipType *linkShip, short record);
Reads info about a ship between universes, number RECORD into LINKSHIP
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool putGatorRecord(gatorType *gator, short record);
Writes a gator record directly to the database. Normally, you should use writeGatorRecord() in stead of this function.
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool writeGatorRecord(gatorType *gator, short record);
Writes Gator record RECORD
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool writeGatorConfig(gatorConfigType *config);
Writes the configuration of the Gators add-on
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool writeShipUFORecord(shipUFOType *shipUFO, short record);
Writes warped ship number RECORD.
true if successful, false if not.
#include <vpl3/gtr3FileDispatchers.h> bool writeLinkShipRecord(linkShipType *linkShip, short record);
Writes ship between universes number RECORD
true if successful, false if not.
The Starbase Enhancer uses a relatively novel way to store some of it's information, designed to enable almost any amount of objects to be stored.
The components being towed by ships are stored in an unindexed array, of which the order is subject to change and irrelevant. The array is stored in a file as a whole, and loaded into memory as such. It's end is marked by an impossible record, and access to it's data is managed by "surrounding" software designed to keep track of the array by itself. Thus, the components have no unique ID code, nor is there any other way to distinguish them from any other component save by the tags they carry. The ID of the component is stored in the database, but is completely arbitrary and may change between runs of the add-on.
This method of storing towed components ensures that the component database is never larger than it needs to be, and it is always possible to create another towed component. Theoratically, there could be 2.147.483.648 components in tow without any problems at all - save perhaps a lack of hard disk space on the host computer, as each component does take 32 bytes of storage space and most computers don't have 64 GB of free disk space.
This method is applied to both the components and the starbases being towed. Enhanced starbases are stored in an indexed array, with the index being the planet ID# of the planet the base is orbiting.
#include <vpl3/enhancerOptions.h> bool openEnhancedBaseDB(void);
Opens the database with the enhanced starbases
true if succesful, false if not
#include <vpl3/enhancerOptions.h> bool closeEnhancedBaseDB(void);
Closes the database with the enhanced starbases
true if succesful, false if not
#include <vpl3/enhancerOptions.h> bool readEnhancedBaseRecord(enhancedBaseRecordType *ESB, short record);
Reads the information about enhanced starbase ESB around planet RECORD.
true if succesful, false if not
#include <vpl3/enhancerOptions.h> bool writeEnhancedBaseRecord(enhancedBaseRecordType *ESB, short record);
Writes the information about enhanced starbase ESB around planet RECORD
true if succesful, false if not
#include <vpl3/enhancerOptions.h> bool getComponentTable(void);
Reads the table of towed components into memory, so it can be accessed.
true if succesful, false if not
#include <vpl3/enhancerOptions.h> bool getTowedBaseTable(void);
Reads the table of towed starbases so it can be accessed.
true if succesful, false if not
#include <vpl3/enhancerOptions.h> bool putComponentTable(void);
Writes the table of towed components to file, when done with the components.
true if succesful, false if not
#include <vpl3/enhancerOptions.h> bool putTowedBaseTable(void);
Writes the table of towed starbases to file.
true if succesful, false if not
#include <vpl3/enhancerOptions.h> int countComponents(void);
Counts the number of components being towed. This number is needed if you want to know when to stop asking for more components.
the number of components being towed, or -1 if an error occured.
#include <vpl3/enhancerOptions.h> int newComponent(void);
Creates a new, empty towed component.
the number of the new component, or -1 if an error occured
#include <vpl3/enhancerOptions.h> bool loadEngines(shipRecordType *ship, starbaseRecordType *starbase, byte techLevel);
Loads all engines of type TECHLEVEL from the STARBASE onto the SHIP
true if succesful, false if not
#include <vpl3/enhancerOptions.h> bool loadBeamWeapons(shipRecordType *ship, starbaseRecordType *starbase, byte techLevel);
Loads all beam weapons of type TECHLEVEL from the STARBASE onto the SHIP
true if succesful, false if not
#include <vpl3/enhancerOptions.h> bool loadTorpedoes(shipRecordType *ship, starbaseRecordType *starbase, byte techLevel);Return value
Loads all torpedo tubes of type TECHLEVEL from the STARBASE onto the SHIP
true if succesful, false if not
#include <vpl3/enhancerOptions.h> bool loadHulls(shipRecordType *ship, starbaseRecordType *starbase, byte techLevel);
Loads all hulls of type TECHLEVEL (actually the index of the hull type being loaded in the list of hulls the starbase can build) from the STARBASE onto the SHIP
true if succesful, false if not
#include <vpl3/enhancerOptions.h> int countTowedBases(void);
Counts all starbases being towed.
the number of starbases being towed
#include <vpl3/enhancerOptions.h> int newTowedBase(void);
Creates a new starbase being towed
the index number of the new starbase
#include <vpl3/enhancerOptions.h> bool hookStationaryStarbase(shipRecordType *ship, starbaseRecordType *starbase);
Hooks the STARBASE onto the SHIP, which will then tow it.
true if succesful, false if not
#include <vpl3/enhancerOptions.h> bool makeUFOTowedBase(towedBaseRecordType *T);
Makes a UFO record for the starbase T being towed.
true if succesful, false if not
#include <vpl3/enhancerOptions.h> bool unmakeUFOTowedBase(towedBaseRecordType *T);
Removes the starbase T from the UFO database
true if succesful, false if not
#include <vpl3/enhancerOptions.h> bool makeUFOComponent(componentRecordType *T);
Creates a UFO record for a towed component T
true if succesful, false if not
#include <vpl3/enhancerOptions.h> bool unmakeUFOComponent(componentRecordType *T);
Removed towed component T from the UFO database
true if succesful, false if not
Because of the differences between the various compilers used to make VGA Planets software, it is necessary to filter all data used by this library from the structures used to store them in memory to the way they are stored on disk. The only data that does not need to be filtered - and isn't filtered - is the temporary data which is only used during the run of the program itself. Part of the filters employed by this library may seem slightly redundant, but I have found that in order to have the code always behave the same, I should not depend on the compiler it is compiled on to sort out how my data is aligned, so I don't.
The list below is a list of all filters and compilers used by the library. The difference between a filter and a compiler is simple: a filter converts one data type to another, and lets all useable data go through. A compiler compiles the required information from the available sources and returns the end result. A decompiler does the exact opposite of a compiler, and stores the compiled information it is given in the sources of the original information.
#include <vpl3/compilers.h> bool compileConfig(configType *config);
Compiles the configuration information in configType CONFIG.
true if successful, false if not
#include <vpl3/compilers.h> bool decompileConfig(configType *config);
Decompiles the configuration information in configType CONFIG and stores the data on disk.
true if successful, false if not
#include <vpl3/compilers.h> bool compileMinefieldRecord(minefieldRecordType *minefieldRecord, short record);
Compiles the mine field information for mine field RECORD
true if successful, false if not
#include <vpl3/compilers.h> bool decompileMinefieldRecord(minefieldRecordType *minefieldRecord);
Decompiles the mine field information in MINEFIELDRECORD. Assumes Read-Only fields were only read.
true if successful, false if not
#include <vpl3/compilers.h> bool compileRaceRecord(raceRecordType *raceRecord, short record);
Compiles the race information for race RECORD
true if successful, false if not
#include <vpl3/compilers.h> bool decompileRaceRecord(raceRecordType *raceRecord);
Decompiles the information in RACERECORD. Assumes the Read-Only information was only read.
true if successful, false if not
#include <vpl3/compilers.h> bool compileShipRecord(shipRecordType *shipRecord, short record);
Compiles the ship information for ship RECORD
true if successful, false if not
#include <vpl3/compilers.h> bool decompileShipRecord(shipRecordType *shipRecord);
Decompiles the ship information in SHIPRECORD
true if successful, false if not
#include <vpl3/compilers.h> bool compilePlanetRecord(planetRecordType *planetRecord, short record);
Compiles the planet information for planet RECORD
true if successful, false if not
#include <vpl3/compilers.h> bool decompilePlanetRecord(planetRecordType *planetRecord);
Decompiles the planet information in PLANETRECORD.
true if successful, false if not
#include <vpl3/filters.h> bool planetXY2buffer(void *buffer, planetXYType *planetXY);
Converts planetXYType to the way it is stored on disk.
true if successful, false if not
#include <vpl3/filters.h> bool buffer2planetXY(planetXYType *planetXY, void *buffer);
Converts the data in BUFFER to planetXYType
true if successful, false if not
#include <vpl3/filters.h> bool planet2buffer(void *buffer, planetType *planet);
Converts planetType to the way it is stored on disk
true if successful, false if not
#include <vpl3/filters.h> bool buffer2planet(planetType *planet, void *buffer);
Converts the data in BUFFER to planetType
true if successful, false if not
#include <vpl3/filters.h> bool buffer2ship(shipType *ship, void *buffer);
Converts shipType to the way it is stored on disk
true if successful, false if not
#include <vpl3/filters.h> bool ship2buffer(void *buffer, shipType *ship);
Converts the data in BUFFER to shipType
true if successful, false if not
#include <vpl3/filters.h> bool shipXY2buffer(void *buffer, shipXYType *shipXY);
Converts the shipXYType to the way it is stored on disk
true if successful, false if not
#include <vpl3/filters.h> bool buffer2shipXY(shipXYType *shipXY, void *buffer);
Converts the data in the buffer to shipXYType
true if successful, false if not
#include <vpl3/filters.h> bool base2buffer(void *buffer, baseType *base);
Converts the data in baseType to the way it is stored on disk
true if successful, false if not
#include <vpl3/filters.h> bool buffer2base(baseType *base, void *buffer);
Converts the data in BUFFER to baseType
true if successful, false if not
#include <vpl3/filters.h> bool raceName2buffer(void *buffer, raceNameType *raceNames);
Converts the raceNameType info to the way it is stored on disk.
true if successful, false if not
#include <vpl3/filters.h> bool buffer2raceName(raceNameType *raceNames, void *buffer);
Converts the buffer data to raceNameType
true if successful, false if not
#include <vpl3/filters.h> bool hullSpec2buffer(void *buffer, hullSpecType *hullSpec);
Converts the hullSpecType to the way it is stored on disk
true if successful, false if not
#include <vpl3/filters.h> bool buffer2hullSpec(hullSpecType *hullSpec, void *buffer);
Converts the BUFFER data to hullSpecType
true if successful, false if not
#include <vpl3/filters.h> bool engineSpec2buffer(void *buffer, engineSpecType *engineSpec);
Converts the engineSpecType data to the way it is stored on disk
true if successful, false if not
#include <vpl3/filters.h> bool buffer2engineSpec(engineSpecType *engineSpec, void *buffer);
Converts the BUFFER data to engineSpecType
true if successful, false if not
#include <vpl3/filters.h> bool beamSpec2buffer(void *buffer, beamSpecType *beamSpec);
Converts the beamSpecType data to the way it is stored on disk
true if successful, false if not
#include <vpl3/filters.h> bool buffer2beamSpec(beamSpecType *beamSpec, void *buffer);
Converts the BUFFER data to beamSpecType
true if successful, false if not
#include <vpl3/filters.h> bool torpSpec2buffer(void *buffer, torpSpecType *torpSpec);
Converts the torpSpecType data to the way it is stored on disk
true if successful, false if not
#include <vpl3/filters.h> bool buffer2torpSpec(torpSpecType *torpSpec, void *buffer);
Converts the BUFFER data to torpSpecType
true if successful, false if not
#include <vpl3/filters.h> bool hConfig2buffer(void *buffer, hConfigType *hConfig);
Converts the hConfigType data to the way it is stored on disk
true if successful, false if not
#include <vpl3/filters.h> bool buffer2hConfig(hConfigType *hConfig, void *buffer);
Converts the BUFFER data to hConfigType
true if successful, false if not
#include <vpl3/filters.h> bool VCR2buffer(void *buffer, VCRType *VCR);
Converts the VCRType data to the way it is stored on disk
true if successful, false if not
#include <vpl3/filters.h> bool buffer2VCR(VCRType *VCR, void *buffer);
Converts the BUFFER data to VCRType
true if successful, false if not
#include <vpl3/filters.h> bool mine2buffer(void *buffer, mineType *mine);
Converts the mineType data to the way it is stored on disk
true if successful, false if not
#include <vpl3/filters.h> bool buffer2mine(mineType *mine, void *buffer);
Converts the BUFFER data to mineType
true if successful, false if not
#include <vpl3/filters.h> bool UFO2buffer(void *buffer, UFOType *UFO);
Converts the UFOType data to the way it is stored on disk
true if successful, false if not
#include <vpl3/filters.h> bool buffer2UFO(UFOType *UFO, void *buffer);
Converts the BUFFER data to UFOType
true if successful, false if not
#include <vpl3/filters.h> bool ion2buffer(void *buffer, ionType *ion);
Converts the ionType data to the way it is stored on disk
true if successful, false if not
#include <vpl3/filters.h> bool buffer2ion(ionType *ion, void *buffer);
Converts the BUFFER data to ionType
true if successful, false if not
#include <vpl3/filters.h> bool alliance2buffer(void *buffer, allianceType *alliance);
Converts the allianceType data to the way it is stored on disk
true if successful, false if not
#include <vpl3/filters.h> bool buffer2alliance(allianceType *alliance, void *buffer);
Converts the BUFFER data to allianceType
true if successful, false if not
#include <vpl3/filters.h> bool UFORecord2UFO(UFOType *UFO, UFORecordType *UFORecord);
Converts the UFOType data to UFORecordType data
true if successful, false if not
#include <vpl3/filters.h> bool UFO2UFORecord(UFORecordType *UFORecord, UFOType *UFO);
Converts the UFOType data to UFORecordType data
true if successful, false if not
#include <vpl3/filters.h> bool ion2ionstormRecord(ionstormRecordType *ionstormRecord, ionType *ion);
Converts the ionType data to ionRecordType data
true if successful, false if not
#include <vpl3/filters.h> bool ionstormRecord2ion(ionType *ion, ionstormRecordType *ionstormRecord);
Converts the ionRecordType data to ionType data
true if successful, false if not
#include <vpl3/filters.h> bool base2starbaseRecord(starbaseRecordType *starbaseRecord, baseType *base);
Converts the starbaseRecordType data to baseType data
true if successful, false if not
#include <vpl3/filters.h> bool starbaseRecord2base(baseType *base, starbaseRecordType *starbaseRecord);
Converts the baseType data to starbaseRecordType data
true if successful, false if not
#include <vpl3/enh2Structures.h> bool buf2Cmp(componentRecordType *C, char *B);
Converts the buffer B to componentRecordType
true if successful, false if not
#include <vpl3/enh2Structures.h> bool cmp2Buf(char *B, componentRecordType *C);
Converts the componentRecordType data to the way it is stored on disk
true if successful, false if not
#include <vpl3/enh2Structures.h> bool buf2Tsb(towedBaseRecordType *T, char *B);
Converts the buffer B to towedBaseRecordType data
true if successful, false if not
#include <vpl3/enh2Structures.h> bool tsb2Buf(char *B, towedBaseRecordType *T);
Converts the towedBaseRecordType data to the way it is stored on disk
true if successful, false if not
#include <vpl3/enh2Structures.h> bool buf2Esb(enhancedBaseRecordType *E, char *B);
Converts the buffer B to enhancedBaseRecordType data
true if successful, false if not
#include <vpl3/enh2Structures.h> bool esb2Buf(char *B, enhancedBaseRecordType *E);
Converts the enhancedBaseRecordType data to the way it is stored on disk
true if successful, false if not
#include <vpl3/gtr3Structures.h> bool GTR2_gtr2Buf(char *buffer, GTR2_GatorType *gator);
Converts a V2 Gator (GTR2_GatorType) to the way it is stored on disk
true if successful, false if not
#include <vpl3/gtr3Structures.h> bool GTR2_buf2Gtr(GTR2_GatorType *gator, char *buffer);
Converts the BUFFER data to GTR2_Gatortype
true if successful, false if not
#include <vpl3/gtr3Structures.h> bool GTR2_cfg2Buf(char *buffer, GTR2_ConfigType* config);
Converts the V2 Gators Configuration (GTR2_ConfigType) to the way it is stored on disk
true if successful, false if not
#include <vpl3/gtr3Structures.h> bool GTR2_buf2Cfg(GTR2_ConfigType* config, char *buffer);
Converts the BUFFER data to GTR2_ConfigType
true if successful, false if not
#include <vpl3/gtr3Structures.h> bool gtr2Buf(char *buffer, gatorType *gator);
Converts gatortype information to the way it is stored on disk
true if successful, false if not
#include <vpl3/gtr3Structures.h> bool buf2Gtr(gatorType *gator, char *buffer);
Converts the BUFFER data to gatorType
true if successful, false if not
#include <vpl3/gtr3Structures.h> bool cfg2Buf(char *buffer, gatorConfigType *config);
Converts gatorConfigType to the way it is stored on disk
true if successful, false if not
#include <vpl3/gtr3Structures.h> bool buf2Cfg(gatorConfigType *config, char *buffer);
Converts data in BUFFER to gatorConfigType
true if successful, false if not
#include <vpl3/gtr3Structures.h> bool spu2Buf(char *buffer, shipUFOType *shipUFO);
Converts shipUFOType to the way it is stored on disk
true if successful, false if not
#include <vpl3/gtr3Structures.h> bool buf2Spu(shipUFOType *shipUFO, char *buffer);
Converts BUFFER data to shipUFOType
true if successful, false if not
#include <vpl3/gtr3Structures.h> bool lnk2Buf(char *buffer, linkShipType *linkShip);
Converts linkShipType to the way it is stored on disk
true if successful, false if not
#include <vpl3/gtr3Structures.h> bool buf2Lnk(linkShipType *linkShip, char *buffer);
Converts BUFFER data to linkShipType
true if successful, false if not
#include <vpl3/gtr3Structures.h> valid validateGatorRecord(gatorType *gator, short record);
Checks validty of GATOR number RECORD
v_error if an erro occured, v_true if the record was valid, v_yellow if it was fixed, v_red if it could not be fixed and was cleared in stead. In case of v_yellow and v_red, it should be saved as it was returned.
#include <vpl3/gtr3Structures.h> bool explodeGator(gatorType *gator);
Destroys GATOR
true if successful, false if not
#include <vpl3/gtr3Structures.h> bool explodeShip(shipRecordType *ship);
Destroys SHIP
true if successful, false if not
#include <vpl3/gtr3Structures.h> bool explodeShipUFO(shipUFOType *shipUFO);
Destroys warped ship SHIPUFO
true if successful, false if not
The Battle Engine is designed to emulate Tim's VCR code as closely as possible, when having warped ships and/or Gators do battle with eachother, or with planets or ships. It can also emulate ships fighting eachother, in which case it should produce the same results as Tim's own VCR. It does not use Tim's VCR setup, so it doesn't produce VCR??.DAT - type records and can not be used to create Visual Combat Recordings from the host data: it simply calculates the battle between two opposing objects.
#include <vpl3/battle.h> bool doBattle(shipRecordType *ship1, shipRecordType *ship2, planetRecordType *planet, starbaseRecordType *starbase, gatorType *gator, shipUFOType *shipUFO);
Calculates the battle between two opposing objects - the rest of the parameters should be set to NULL.
shipRecordType ship; gatorType gator; bool rv = true; if (rv) rv = readGatorRecord(&gator, 2); if (rv) rv = readShip(&ship, 32); if (rv) rv = doBattle(&ship, (shipRecordType*)NULL, (planetRecordType*)NULL, (starbaseRecordType*)NULL, &gator, (shipUFOType*)NULL); if (rv) rv = writeGatorRecord(&gator, 2); if (rv) rv = writeShip(&ship, 32);
true if successful, false if not.
The message engine of this library is designed for use by RLSystems add-ons only, but will be made available to other applications at a later date. As is, you will not be able to use them, because parts of the actual module are not available. Should you use them any message you send will have the content "You should not have received this message".
You can use the putMessage() method, which is used by the engine to store the messages in the host data files. The getMessage() method has not been tested yet, and should not be used.
#include <vpl3/messages.h> void setMessage(short messageType, messageDataType *message, shipRecordType *ship, planetRecordType *planet, starbaseRecordType *starbase, raceRecordType *race, gatorType *gator);
Sets the message parameters for message MESSAGETYPE, based on the other passed info. Do not use.
none
#include <vpl3/messages.h> bool getMessagePointer(messagePointerType *ptr, short record);
Gets the message information about message RECORD. not tested
true if successful, false if not
#include <vpl3/messages.h> bool putMessage(short cc, char xzstr[], short ID, char gG[]);
Sends a subspace message to race CC, content XZSTR, sender ID, pre-string GG.
if (rv) rv = putMessage(1, "<< TEST MESSAGE >>\rThis is a test message\r", 0, "-m0");
true if successful, false if not
#include <vpl3/messages.h> bool issueMessage(messageDataType *message);
Sends a message with message parameters stored in MESSAGE, set up by setMessage. Do not use
true if successful, false if not
There are a number of methods in this library which are definatly not intended for use outside of this library. However, I said I'd document everything, and that includes the internal methods.
None of these methods should be used outside this library!
bool vpl3_openFiles(void);
Opens the files with the requested information.
true if successful, false if not
bool vpl3_closeFiles(void);
Closes the opened files
true if successful, false if not
void downVPL3(void);
Shuts down the library
true if successful, false if not
bool vpl3_getConfig(void);
Gets the configuration directly from the files, compiles it and stores it in the buffer for readConfig() and writeConfig()
true if successful, false if not
bool vpl3_getShips(void);
Gets the ships directly from the files, compiles it and stores it in the buffer for readShip() and writeShip()
true if successful, false if not
bool vpl3_getPlanets(void);
Gets the planets directly from the files, compiles it and stores it in the buffer for readPlanet() and writePlanet()
true if successful, false if not
bool vpl3_getStarbases(void);
Gets the starbases directly from the files, compiles it and stores it in the buffer for readStarbase() and writeStarbase()
true if successful, false if not
bool vpl3_getRaces(void);
Gets the Races directly from the files, compiles it and stores it in the buffer for readRace() and writeRace()
true if successful, false if not
bool vpl3_getMinefield(void);
Gets the mine fields directly from the files, compiles it and stores it in the buffer for readMinefield() and writeMinefield()
true if successful, false if not
bool vpl3_getIonstorms(void);
Gets the ion storms directly from the files, compiles it and stores it in the buffer for readIonstorm() and writeIonstorm()
true if successful, false if not
bool vpl3_getUFOs(void);
Gets the UFOs directly from the files, compiles it and stores it in the buffer for readUFO() and writeUFO()
true if successful, false if not
bool vpl3_getHost(void);
Gets the host info directly from the files, compiles it and stores it in the buffer for readHost() and writeHost()
true if successful, false if not
bool vpl3_putConfig(void);
Puts the configuration directly into the files
true if successful, false if not
bool vpl3_putShips(void);
Puts the ships directly into the files
true if successful, false if not
bool vpl3_putPlanets(void);
Puts the planets directly into the files
true if successful, false if not
bool vpl3_putStarbases(void);
Puts the starbases directly into the files
true if successful, false if not
bool vpl3_putRaces(void);
Puts the races directly into the files
true if successful, false if not
bool vpl3_putMinefield(void);
Puts the mine fields directly into the files
true if successful, false if not
bool vpl3_putIonstorms(void);
Puts the ion storms directly into the files
true if successful, false if not
bool vpl3_putUFOs(void);
Puts the UFOs directly into the files
true if successful, false if not