This file documents the RLSystems VGA Planets I/O Library V3 and contains a complete documentation of this library. This file should always accompany and be accompanied by the rest of the package of which the VGA Planets I/O library is a part, as distributed by Dlanor Blytkerchan and/or RLSystems. It may be re-distributed free of charge by anyone who cares to do so, as long as the package remains in tact. Copyright (c) 2000 Dlanor Blytkerchan 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. Introduction ************ 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 (http://www.delorie.com), 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 `'; and an easier part, with a lot of dispatchers and background software (most of the library consists of software for this part) accessed through `'. 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, `'. 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 `' file is all you'll need for the raw version. The other library, `', contains dispatchers for RLSystems add-ons I/O. It is not finished yet, but when it is, it will be documented here. Quick Start *********** To get started with the library as quickly as possible, just remember these simple steps when writing your program: * #include #define LSW1_All #include #include * Initialize Use initSwing() and initVPL3() like this: bool rc = true; /* ... */ if (rc) rc = initSwing(); if (rc) rc = initVPL3(USE_ALL, gamePath, basePath, &numships, 0); * Read, Write, etc. Use the proper reads and writers, e.g. readRace() for races, writeShip() for ships; etc. * let the libraries take care of shutting down.. 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! Header Files ************ The two main header files for this library are `' and `'. `' 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). `' 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: * `' 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). * `' The Compilers module is internal to the library, and should not be used by any other software. (It is documented in more detail below). * `' 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. * `' 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. * `' The Filters module is internal to the library and should not be used by other software. It is fully documented below. * `' 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. * `' 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. * `' 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. * `' The Gators V3 Structures module contains all the structures used by RLSystems Gators, and the filters for memory to disk and vice versa conversion. * `' The Gators V3 UFO Dispatchers module contains the methods used by Gators to put Gators, MiniGates and warped ships in the UFO database. * `' 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. * `' 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. * `' The Spy header file serves roughly the same purpose as the Gators header does: the actual module is not part of the library. * `' 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.. VPL3 Dispatchers ================ 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. initVPL3() ========== Syntax ------ #include bool initVPL3(int mode, char *gamePath, char *basePath, short *numberOfShips, byte player); Description ----------- Initializes the library in mode MODE, which is a combination of: * NO_BUFFERING 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. * USE_SHIPS Tells the library to allow access to ship data. This means you will be able to use readShip() and writeShip() from your program. * USE_PLANETS Tells the library to allow access to planet data. This means you will be able to use readPlanet() and writePlanet() from your program. * USE_STARBASES Tells the library to allow access to the starbase data. This means you will be able to use readStarbase() and writeStarbase() from your program. * USE_RACES Tells the library to allow access to the race data. This means you will be able to use readRace() and writeRace() from your program. * USE_CONFIG 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. * USE_MINEFIELDS Tells the library to allow access to the minefield data. This means you will be able to use readMinefield() and writeMinefield() from your program. * USE_IONSTORMS 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. * USE_UFOS Tells the library to allow access to the UFO data. This means you will be able to use readUFO() and writeUFO() from your program. * DO_VALIDATE 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). * PLAYER_DATA Tells the library your program is _not_ a host-side add-on, but a player-side utility. * USE_ALL 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 `' 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. Example ------- if (rv) rv = initVPL3(NO_BUFFERING | USE_ALL, "y:/honor/process/", "z:/planets.32/", 0); Return value ------------ true if successful, false if not. If it fails, errCode will be set accordingly, and done() will have Swing display the proper error message. readConfig() ============ Syntax ------ #include bool readConfig(configType *cfg); Description ----------- 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(). Return value ------------ true if successful, false if not. readShip() ========== Syntax ------ #include bool readShip(shipRecordType *p, short record); Description ----------- 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. Return value ------------ true if successful, false if not. readPlanet() ============ Syntax ------ #include bool readPlanet(planetRecordType *p, short record); Description ----------- 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. Return value ------------ true if successful, false if not. readStarbase() ============== Syntax ------ #include bool readStarbase(starbaseRecordType *p, short record); Description ----------- Reads all relevant information about starbase ID# RECORD into P. This includes the ID, name, owner, friendly code, and what it's doing. Return value ------------ true if successful, false if not. readRace() ========== Syntax ------ #include bool readRace(raceRecordType *r, short record); Description ----------- 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. Return value ------------ true if successful, false if not. readMinefield() =============== Syntax ------ #include bool readMinefield(minefieldRecordType *m, short record); Description ----------- Reads all relevant information about minefield ID# RECORD into M. This includes the ID, owner, size, etc. Return value ------------ true if successful, false if not. readIonstorm() ============== Syntax ------ #include bool readIonstorm(ionstormRecordType *m, short record); Description ----------- Reads all relevant information about ion storm ID# RECORD into M. This includes the ID, size, strength, etc. Return value ------------ true if successful, false if not. readUFO() ========= Syntax ------ #include bool readUFO(UFORecordType *m, short record); Description ----------- Reads all relevant information about UFO ID# RECORD into M. This includes the ID, owner, etc. Return value ------------ true if successful, false if not. readHost() ========== Syntax ------ #include bool readHost(hostRecordType *hostRecord); Description ----------- Reads the information about the host Return value ------------ true if successful, false if not. readPlayer() ============ Syntax ------ #include bool readPlayer(playerRecordType *playerRecord, short record); // see comment R3 Description ----------- Reads the information about a player. Can only be used at the player-side. Return value ------------ true if successful, false if not. readIncomingMessage() ===================== Syntax ------ #include bool readIncomingMessage(messageRecordType *messageRecord, short record); Description ----------- Reads an incoming message - player-side only. Return value ------------ true if successful, false if not. readOutgoingMessage() ===================== Syntax ------ #include bool readOutgoingMessage(messageRecordType *messageRecord, short record); Description ----------- Reads an outgoing message - player-side only. Return value ------------ true if successful, false if not. writeConfig() ============= Syntax ------ #include bool writeConfig(configType *cfg); Description ----------- Stores the configuration data in CFG for later use. Return value ------------ true if successful, false if not. writeShip() =========== Syntax ------ #include bool writeShip(shipRecordType *p, short record); Description ----------- Stores the ship record in P for later use. Assumes RECORD is a correct indication for the ship ID number. Return value ------------ true if successful, false if not. writePlanet() ============= Syntax ------ #include bool writePlanet(planetRecordType *p, short record); Description ----------- Stores the planet record in P for later use. Assumes RECORD is a correct indication for the planet ID number. Return value ------------ true if successful, false if not. writeStarbase() =============== Syntax ------ #include bool writeStarbase(starbaseRecordType *p, short record); Description ----------- Stores the starbase record in P for later use. Assumes RECORD is a correct indication for the planet/starbase ID number. Return value ------------ true if successful, false if not writeRace() =========== Syntax ------ #include bool writeRace(raceRecordType *r, short record); Description ----------- Stores the race record in R for later use. Assumes RECORD is a correct indication for the race ID number. Return value ------------ true if successful, false if not writeMinefield() ================ Syntax ------ #include bool writeMinefield(minefieldRecordType *m, short record); Description ----------- Stores the mine field record in M for later use. Assumes RECORD is a correct indication for the mine field ID number. Return value ------------ true if successful, false if not writeIonstorm() =============== Syntax ------ #include bool writeIonstorm(ionstormRecordType *m, short record); Description ----------- Stores the ion storm record in M for later use. Assumes RECORD is a correct indication for the ion storm ID number. Return value ------------ true if successful, false if not writeUFO() ========== Syntax ------ #include bool writeUFO(UFORecordType *m, short record); Description ----------- Stores the UFO record in M for later use. Assumes RECORD is a correct indication for the UFO ID number. Return value ------------ true if successful, false if not. writeIncomingMessage() ====================== Syntax ------ #include bool writeIncomingMessage(messageRecordType *messageRecord, short record); Description ----------- Writes an incoming message Return value ------------ true if successful, false if not. writeUFO() ========== Syntax ------ #include bool writeOutgoingMessage(messageRecordType *messageRecord, short record); Description ----------- Writes an outgoing message Return value ------------ true if successful, false if not. Non-dispatched functions ************************ 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 standard host files ============================= _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 and provide "raw" access to the host data. If you have studied the setup of the 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.. openGen() ========= Syntax ------ #include bool openGen(char *genPath); Description ----------- Opens the file pointed to by GENPATH and assumes it's (the equivalent of) GEN.HST - the file with the general game info. Return value ------------ true if successful, false if not openHConfig() ============= Syntax ------ #include bool openHConfig(char *hConfigPath); Description ----------- Opens the file pointed to by HCONFIGPATH and assumes it's (the equivalent of) HCONFIG.HST - the file with the host configuration info. Return value ------------ true if successful, false if not openPlanetXYDB() ================ Syntax ------ #include bool openPlanetXYDB(char *planetXYPath); Description ----------- Opens the file pointed to by PLANETXYPATH and assumes it's (the equivalent of) XYPLAN.HST - the file with the starmap. Return value ------------ true if successful, false if not openPlanetNameDB() ================== Syntax ------ #include bool openPlanetNameDB(char *planetNMPath); Description ----------- Opens the file pointed to by PLANETNM and assumes it's (the equivalent of) PLANET.NM - the file with the planet names. Return value ------------ true if successful, false if not openRaceNameDB() ================ Syntax ------ #include bool openRaceNameDB(char *raceNamePath); Description ----------- Opens the file pointed to by RACENAMEPATH and assumes it's (the equivalent of) RACE.NM - the file with the race names. Return value ------------ true if successful, false if not openGreyDB() ============ Syntax ------ #include bool openGreyDB(char *greyPath); Description ----------- Opens the file pointed to by GREYPATH and assumes it's (the equivalent of) GREY.HST - the file with the ion storms etc. Return value ------------ true if successful, false if not openTorpDB() ============ Syntax ------ #include bool openTorpDB(char *torpPath); Description ----------- Opens the file pointed to by TORPPATH and assumes it's (the equivalent of) TORPSPEC.DAT - the file with the torpedo specifications. Return value ------------ true if successful, false if not openBeamDB() ============ Syntax ------ #include bool openBeamDB(char *beamPath); Description ----------- Opens the file pointed to by BEAMPATH and assumes it's (the equivalent of) BEAMSPEC.DAT - the file with the beam weapon specifications. Return value ------------ true if successful, false if not openEngineDB() ============== Syntax ------ #include bool openEngineDB(char *enginePath); Description ----------- Opens the file pointed to by ENGINEPATH and assumes it's (the equivalent of) ENGSPEC.DAT - the file with the engine specifications. Return value ------------ true if successful, false if not openBaseDB() ============ Syntax ------ #include bool openBaseDB(char *basePath); Description ----------- Opens the file pointed to by BASEPATH and assumes it's (the equivalent of) BDATA.HST - the file with the starbase info. Return value ------------ true if successful, false if not openHullDB() ============ Syntax ------ #include bool openHullDB(char *hullPath); Description ----------- Opens the file pointed to by HULLPATH and assumes it's (the equivalent of) HULLSPEC.DAT - the file with the hull specifications. Return value ------------ true if successful, false if not openMineDB() ============ Syntax ------ #include bool openMineDB(char *minePath); Description ----------- Opens the file pointed to by MINEPATH and assumes it's (the equivalent of) MINES.HST - the file with the general game info. Return value ------------ true if successful, false if not openPlanetDB() ============== Syntax ------ #include bool openPlanetDB(char *planetPath); Description ----------- Opens the file pointed to by PLANETPATH and assumes it's (the equivalent of) PDATA.HST - the file with the planet info. Return value ------------ true if successful, false if not openShipDB() ============ Syntax ------ #include bool openShipDB(char *shipPath); Description ----------- Opens the file pointed to by SHIPPATH and assumes it's (the equivalent of) SHIP.HST - the file with the ship info. Return value ------------ true if successful, false if not openShipXYDB() ============== Syntax ------ #include bool openShipXYDB(char *shipXYPath); Description ----------- Opens the file pointed to by SHIPXYPATH and assumes it's (the equivalent of) SHIPXY.HST - the file with the ship coordinat info. Return value ------------ true if successful, false if not openUFODB() =========== Syntax ------ #include bool openUFODB(char *UFOPath); Description ----------- Opens the file pointed to by UFOPATH and assumes it's (the equivalent of) UFO.HST - the file with the UFO info. Return value ------------ true if successful, false if not openCloakDB() ============= Syntax ------ #include bool openCloakDB(char *cloakPath); Description ----------- 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. Return value ------------ true if successful, false if not closeGen() ========== Syntax ------ #include bool closeGen(void); Description ----------- Closes the file opened by openGen() Return value ------------ true if successful, false if not closeHConfig() ============== Syntax ------ #include bool closeHConfig(void); Description ----------- Closes the file opened by openHConfig() Return value ------------ true if successful, false if not closePlanetXYDB() ================= Syntax ------ #include bool closePlanetXYDB(void); Description ----------- Closes the file opened by openPlanetXYDB() Return value ------------ true if successful, false if not closePlanetNameDB() =================== Syntax ------ #include bool closePlanetNameDB(void); Description ----------- Closes the file opened by openPlanetNameDB() Return value ------------ true if successful, false if not closeRaceNameDB() ================= Syntax ------ #include bool closeRaceNameDB(void); Description ----------- Closes the file opened by openRaceNameDB() Return value ------------ true if successful, false if not closeGreyDB() ============= Syntax ------ #include bool closeGreyDB(void); Description ----------- Closes the file opened by openGreyDB() Return value ------------ true if successful, false if not closeTorpDB() ============= Syntax ------ #include bool closeTorpDB(void); Description ----------- Closes the file opened by openTorpDB() Return value ------------ true if successful, false if not closeBeamDB() ============= Syntax ------ #include bool closeBeamDB(void); Description ----------- Closes the file opened by openBeamDB() Return value ------------ true if successful, false if not closeEngineDB() =============== Syntax ------ #include bool closeEngineDB(void); Description ----------- Closes the file opened by openEngineDB() Return value ------------ true if successful, false if not closeBaseDB() ============= Syntax ------ #include bool closeBaseDB(void); Description ----------- Closes the file opened by openBaseDB() Return value ------------ true if successful, false if not closeHullDB() ============= Syntax ------ #include bool closeHullDB(void); Description ----------- Closes the file opened by openHullDB() Return value ------------ true if successful, false if not closeMineDB() ============= Syntax ------ #include bool closeMineDB(void); Description ----------- Closes the file opened by openMineDB() Return value ------------ true if successful, false if not closePlanetDB() =============== Syntax ------ #include bool closePlanetDB(void); Description ----------- Closes the file opened by openPlanetDB() Return value ------------ true if successful, false if not closeShipDB() ============= Syntax ------ #include bool closeShipDB(void); Description ----------- Closes the file opened by openShipDB() Return value ------------ true if successful, false if not closeShipXYDB() =============== Syntax ------ #include bool closeShipXYDB(void); Description ----------- Closes the file opened by openShipXYDB() Return value ------------ true if successful, false if not closeUFODB() ============ Syntax ------ #include bool closeUFODB(void); Description ----------- Closes the file opened by openUFODB() Return value ------------ true if successful, false if not closeCloakDB() ============== Syntax ------ #include bool closeCloakDB(void); Description ----------- Closes the file opened by openCloakDB() Return value ------------ true if successful, false if not readActive() ============ Syntax ------ #include bool readActive(bool *isActive, short record); Description ----------- Reads whether or not race RECORD is active. Sets ISACTIVE accordingly (true if the race is still alive, false if not). Return value ------------ true if successful, false if not readAllianceStatus() ==================== Syntax ------ #include bool readAllianceStatus(allianceType *alliances); Description ----------- Reads the alliances in the game. Return value ------------ true if successful, false if not readKillPoints() ================ Syntax ------ #include bool readKillPoints(short *PBP, short record); Description ----------- Reads the priority build points (aka killpoints) of race RECORD into PBP. Return value ------------ true if successful, false if not readCrewExperience() ==================== Syntax ------ #include bool readCrewExperience(short *experience, short record); Description ----------- Reads the crew experience of ship number RECORD. Return value ------------ true if successful, false if not readIonStorm() ============== Syntax ------ #include bool readIonStorm(ionType *ionRec, short record); Description ----------- Reads the information about ion storm number RECORD Return value ------------ true if successful, false if not readTorpRecord() ================ Syntax ------ #include bool readTorpRecord(torpSpecType *torpRec, short record); Description ----------- Reads the torpedo specifications for torpedo (tube) RECORD Return value ------------ true if successful, false if not readBeamRecord() ================ Syntax ------ #include bool readBeamRecord(beamSpecType *beamRec, short record); Description ----------- Reads the beam weapon specifications for beam weapon RECORD Return value ------------ true if successful, false if not readEngineRecord() ================== Syntax ------ #include bool readEngineRecord(engineSpecType *engineRec, short record); Description ----------- Reads the engine specifications for engine type RECORD Return value ------------ true if successful, false if not readBaseRecord() ================ Syntax ------ #include bool readBaseRecord(baseType *baseRec, short record); Description ----------- Reads the starbase at planet ID# RECORD Return value ------------ true if successful, false if not readHullRecord() ================ Syntax ------ #include bool readHullRecord(hullSpecType *hullRec, short record); Description ----------- Reads the hull specifications of hull type number RECORD Return value ------------ true if successful, false if not readMineRecord() ================ Syntax ------ #include bool readMineRecord(mineType *mineRec, short record); Description ----------- Reads the info about mine field number RECORD Return value ------------ true if successful, false if not readPlanetRecord() ================== Syntax ------ #include bool readPlanetRecord(planetType *planetRec, short record); Description ----------- Reads the info about planet number RECORD Return value ------------ true if successful, false if not readShipRecord() ================ Syntax ------ #include bool readShipRecord(shipType *shipRec, short record); Description ----------- Reads the info about ship number RECORD Return value ------------ true if successful, false if not readShipXYRecord() ================== Syntax ------ #include bool readShipXYRecord(shipXYType *shipXYRec, short record); Description ----------- Reads the coordinats and mass of ship number RECORD Return value ------------ true if successful, false if not readUFORecord() =============== Syntax ------ #include bool readUFORecord(UFOType *UFORec, short record); Description ----------- Reads the info about UFO number RECORD Return value ------------ true if successful, false if not readHConfig() ============= Syntax ------ #include bool readHConfig(hConfigType *hConfigRec); Description ----------- Reads the host configuration Return value ------------ true if successful, false if not readPlanetXYRecord() ==================== Syntax ------ #include bool readPlanetXYRecord(planetXYType *planetXYRec, short record); Description ----------- Reads the location of planet number RECORD Return value ------------ true if successful, false if not readPlanetNameRecord() ====================== Syntax ------ #include bool readPlanetNameRecord(char *planetNMRec, short record); Description ----------- Reads the name of planet number RECORD Return value ------------ true if successful, false if not readRaceNames() =============== Syntax ------ #include bool readRaceNames(raceNameType *raceNames); Description ----------- Reads the names of all races in all allowable forms Return value ------------ true if successful, false if not readShipShieldStatus() ====================== Syntax ------ #include bool readShipShieldStatus(shipShieldStatusType *S, short record); Description ----------- Reads the shield and cloak status of theip ID# RECORD Return value ------------ true if successful, false if not writeActive() ============= Syntax ------ #include bool writeActive(bool *isActive, short record); Description ----------- Sets whether or not race RECORD is active. Return value ------------ true if successful, false if not writeAllianceStatus() ===================== Syntax ------ #include bool writeAllianceStatus(allianceType *alliances); Description ----------- Writes the alliances Return value ------------ true if successful, false if not writeKillPoints() ================= Syntax ------ #include bool writeKillPoints(short *PBP, short record); Description ----------- Writes the priority build points for race RECORD Return value ------------ true if successful, false if not writeCrewExperience() ===================== Syntax ------ #include bool writeCrewExperience(short *experience, short record); Description ----------- Writes the crew experience for ship number RECORD Return value ------------ true if successful, false if not writeIonStorm() =============== Syntax ------ #include bool writeIonStorm(ionType *ionRec, short record); Description ----------- Writes the information of ion storm RECORD Return value ------------ true if successful, false if not writeTorpRecord() ================= Syntax ------ #include bool writeTorpRecord(torpSpecType *torpRec, short record); Description ----------- Writes the torpedo specifications of torpedo type RECORD Return value ------------ true if successful, false if not writeBeamRecord() ================= Syntax ------ #include bool writeBeamRecord(beamSpecType *beamRec, short record); Description ----------- Writes the beam weapon specifications for beam weapon type RECORD Return value ------------ true if successful, false if not writeEngineRecord() =================== Syntax ------ #include bool writeEngineRecord(engineSpecType *engineRec, short record); Description ----------- Writes the engine specifications for engine type RECORD Return value ------------ true if successful, false if not writeBaseRecord() ================= Syntax ------ #include bool writeBaseRecord(baseType *baseRec, short record); Description ----------- Writes the information of the starbase as planet number RECORD Return value ------------ true if successful, false if not writeHullRecord() ================= Syntax ------ #include bool writeHullRecord(hullSpecType *hullRec, short record); Description ----------- Writes the hull specifications of hu Return value ------------ true if successful, false if not writeMineRecord() ================= Syntax ------ #include bool writeMineRecord(mineType *mineRec, short record); Description ----------- Writes mine field RECORD Return value ------------ true if successful, false if not writePlanetRecord() =================== Syntax ------ #include bool writePlanetRecord(planetType *planetRec, short record); Description ----------- Writes info of planet RECORD Return value ------------ true if successful, false if not writeShipRecord() ================= Syntax ------ #include bool writeShipRecord(shipType *shipRec, short record); Description ----------- Writes info of ship RECORD Return value ------------ true if successful, false if not writeShipXYRecord() =================== Syntax ------ #include bool writeShipXYRecord(shipXYType *shipXYRec, short record); Description ----------- Writes coordinats and mass of ship RECORD Return value ------------ true if successful, false if not writeUFORecord() ================ Syntax ------ #include bool writeUFORecord(UFOType *UFORec, short record); Description ----------- Writes info of UFO RECORD Return value ------------ true if successful, false if not writeHConfig() ============== Syntax ------ #include bool writeHConfig(hConfigType *hConfigRec); Description ----------- Writes the host configuration Return value ------------ true if successful, false if not writePlanetXYRecord() ===================== Syntax ------ #include bool writePlanetXYRecord(planetXYType *planetXYRec, short record); Description ----------- Writes the coordinats of planet RECORD Return value ------------ true if successful, false if not writePlanetNameRecord() ======================= Syntax ------ #include bool writePlanetNameRecord(char *planetNMRec, short record); Description ----------- Writes the name of planet RECORD Return value ------------ true if successful, false if not writeRaceNames() ================ Syntax ------ #include bool writeRaceNames(raceNameType *raceNames); Description ----------- Writes the names of all races Return value ------------ true if successful, false if not writeShipShieldStatus() ======================= Syntax ------ #include bool writeShipShieldStatus(shipShieldStatusType *S, short record); Description ----------- Writes the shield and cloak status of ship RECORD Return value ------------ true if successful, false if not Access to Gators files ********************** 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. existGTR2GatorDB() ****************** Syntax ====== #include bool existGTR2GatorDB(void); Description =========== 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. Return value ============ true if the file exists, false if not. Will normally return false. existGTR2GatorConfig() ********************** Syntax ====== #include bool existGTR2GatorConfig(void); Description =========== 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. Return value ============ true if the file exists, false if not. existGTR3GatorDB() ****************** Syntax ====== #include bool existGTR3GatorDB(void); Description =========== 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. Return value ============ true if the file exists, false if not. This will usually return true if Gators is being used, false if not. existGTR3GatorConfig() ********************** Syntax ====== #include bool existGTR3GatorConfig(void); Description =========== 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. Return value ============ true if the file exists, false if not. readGTRVersion() **************** Syntax ====== #include short readGTRVersion(void); Description =========== Gets the version number of the file setup of the Gators files from the configuration file. Return value ============ 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. openGTR2GatorDB() ***************** Syntax ====== #include bool openGTR2GatorDB(void); Description =========== 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. Return value ============ true if successful, false if not. openGTR2Config() **************** Syntax ====== #include bool openGTR2Config(void); Description =========== Opens the V2 configuration file. Normally, you won't have to use this function. Return value ============ true if successful, false if not. closeGTR2GatorDB() ****************** Syntax ====== #include bool closeGTR2GatorDB(void); Description =========== Closes the file opened by openGTR2GatorDB() Return value ============ true if successful, false if not. closeGTR2Config() ***************** Syntax ====== #include bool closeGTR2Config(void); Description =========== Closes the file opened by openGTR2Config() Return value ============ true if successful, false if not. readGTR2GatorRecord() ********************* Syntax ====== #include bool readGTR2GatorRecord(GTR2_GatorType *gator, short record); Description =========== Reads V2 Gator record RECORD Return value ============ true if successful, false if not. readGTR2Config() **************** Syntax ====== #include bool readGTR2Config(GTR2_ConfigType *config); Description =========== Reads the configuration of Gators V2 Return value ============ true if successful, false if not. writeGTR2GatorRecord() ********************** Syntax ====== #include bool writeGTR2GatorRecord(GTR2_GatorType *gator, short record); Description =========== Writes V2 Gator record RECORD Return value ============ true if successful, false if not. writeGTR2Config() ***************** Syntax ====== #include bool writeGTR2Config(GTR2_ConfigType *config); Description =========== Writes the Gators V2 configuration Return value ============ true if successful, false if not. GTR2Gtr2GTR3Gtr() ***************** Syntax ====== #include bool GTR2Gtr2GTR3Gtr(gatorType *gtr3, GTR2_GatorType *gtr2); Description =========== Converts a V2 Gator GTR2 to a V3 Gator GTR3 Return value ============ true if successful, false if not. GTR2Cfg2GTR3Cfg() ***************** Syntax ====== #include bool GTR2Cfg2GTR3Cfg(gatorConfigType *cfg3, GTR2_ConfigType *cfg2); Description =========== Converts V2 Gator configuration to V3 Gator configuration Return value ============ true if successful, false if not. renameGTR2ConfigFile() ********************** Syntax ====== #include bool renameGTR2ConfigFile(void); Description =========== 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. Return value ============ true if successful, false if not. renameGTR2GatorDB() ******************* Syntax ====== #include bool renameGTR2GatorDB(void); Description =========== 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. Return value ============ true if successful, false if not. initGatorDB() ************* Syntax ====== #include bool initGatorDB(void); Description =========== Initializes the Gators database and destroys all existing Gators. Return value ============ true if successful, false if not. initGatorConfig() ***************** Syntax ====== #include bool initGatorConfig(void); Description =========== Initializes the Gators configuration to the defaults. Return value ============ true if successful, false if not. initShipUFODB() *************** Syntax ====== #include bool initShipUFODB(void); Description =========== initializes the database with the warped ships Return value ============ true if successful, false if not. initLinkShipDB() **************** Syntax ====== #include bool initLinkShipDB(void); Description =========== 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. Return value ============ true if successful, false if not. openGatorDB() ************* Syntax ====== #include bool openGatorDB(void); Description =========== Opens the Gators database Return value ============ true if successful, false if not. openGatorConfig() ***************** Syntax ====== #include bool openGatorConfig(void); Description =========== Opens the Gators configuration file Return value ============ true if successful, false if not. openShipUFODB() *************** Syntax ====== #include bool openShipUFODB(void); Description =========== Opens the database with the warped ships Return value ============ true if successful, false if not. openLinkShipDB() **************** Syntax ====== #include bool openLinkShipDB(void); Description =========== opens the database with the ships between universes Return value ============ true if successful, false if not. closeGatorDB() ************** Syntax ====== #include bool closeGatorDB(void); Description =========== Closes the file opened by openGatorDB() Return value ============ true if successful, false if not. closeGatorConfig() ****************** Syntax ====== #include bool closeGatorConfig(void); Description =========== Closes the Gators configuration file opened by openGatorConfig() Return value ============ true if successful, false if not. closeShipUFODB() **************** Syntax ====== #include bool closeShipUFODB(void); Description =========== Closes the database with the warped ships opened by openShipUFODB() Return value ============ true if successful, false if not. closeLinkShipDB() ***************** Syntax ====== #include bool closeLinkShipDB(void); Description =========== Closes the database with the ships between universes opened by openLinkShipDB() Return value ============ true if successful, false if not. getGatorRecord() **************** Syntax ====== #include bool getGatorRecord(gatorType *gator, short record); Description =========== Reads a Gator record directly from the database. You won't normally have to use this function, but should use readGatorRecord() in stead. Return value ============ true if successful, false if not. readGatorRecord() ***************** Syntax ====== #include bool readGatorRecord(gatorType *gator, short record); Description =========== Reads Gator record RECORD into GATOR. Return value ============ true if successful, false if not. readGatorConfig() ***************** Syntax ====== #include bool readGatorConfig(gatorConfigType *config); Description =========== Reads the configuration of Gators Return value ============ true if successful, false if not. readShipUFORecord() ******************* Syntax ====== #include bool readShipUFORecord(shipUFOType *shipUFO, short record); Description =========== Reads warped ship RECORD into SHIPUFO. Return value ============ true if successful, false if not. readLinkShipRecord() ******************** Syntax ====== #include bool readLinkShipRecord(linkShipType *linkShip, short record); Description =========== Reads info about a ship between universes, number RECORD into LINKSHIP Return value ============ true if successful, false if not. putGatorRecord() **************** Syntax ====== #include bool putGatorRecord(gatorType *gator, short record); Description =========== Writes a gator record directly to the database. Normally, you should use writeGatorRecord() in stead of this function. Return value ============ true if successful, false if not. writeGatorRecord() ****************** Syntax ====== #include bool writeGatorRecord(gatorType *gator, short record); Description =========== Writes Gator record RECORD Return value ============ true if successful, false if not. writeGatorConfig() ****************** Syntax ====== #include bool writeGatorConfig(gatorConfigType *config); Description =========== Writes the configuration of the Gators add-on Return value ============ true if successful, false if not. writeShipUFORecord() ******************** Syntax ====== #include bool writeShipUFORecord(shipUFOType *shipUFO, short record); Description =========== Writes warped ship number RECORD. Return value ============ true if successful, false if not. writeLinkShipRecord(), ********************** Syntax ====== #include bool writeLinkShipRecord(linkShipType *linkShip, short record); Description =========== Writes ship between universes number RECORD Return value ============ true if successful, false if not. Access to Starbase Enhancer files ********************************* 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. openEnhancedBaseDB() ******************** Syntax ====== #include bool openEnhancedBaseDB(void); Description =========== Opens the database with the enhanced starbases Return value ============ true if succesful, false if not closeEnhancedBaseDB() ********************* Syntax ====== #include bool closeEnhancedBaseDB(void); Description =========== Closes the database with the enhanced starbases Return value ============ true if succesful, false if not readEnhancedBaseRecord() ************************ Syntax ====== #include bool readEnhancedBaseRecord(enhancedBaseRecordType *ESB, short record); Description =========== Reads the information about enhanced starbase ESB around planet RECORD. Return value ============ true if succesful, false if not writeEnhancedBaseRecord() ************************* Syntax ====== #include bool writeEnhancedBaseRecord(enhancedBaseRecordType *ESB, short record); Description =========== Writes the information about enhanced starbase ESB around planet RECORD Return value ============ true if succesful, false if not getComponentTable() ******************* Syntax ====== #include bool getComponentTable(void); Description =========== Reads the table of towed components into memory, so it can be accessed. Return value ============ true if succesful, false if not getTowedBaseTable() ******************* Syntax ====== #include bool getTowedBaseTable(void); Description =========== Reads the table of towed starbases so it can be accessed. Return value ============ true if succesful, false if not putComponentTable() ******************* Syntax ====== #include bool putComponentTable(void); Description =========== Writes the table of towed components to file, when done with the components. Return value ============ true if succesful, false if not putTowedBaseTable() ******************* Syntax ====== #include bool putTowedBaseTable(void); Description =========== Writes the table of towed starbases to file. Return value ============ true if succesful, false if not countComponents() ***************** Syntax ====== #include int countComponents(void); Description =========== Counts the number of components being towed. This number is needed if you want to know when to stop asking for more components. Return value ============ the number of components being towed, or -1 if an error occured. newComponent() ************** Syntax ====== #include int newComponent(void); Description =========== Creates a new, empty towed component. Return value ============ the number of the new component, or -1 if an error occured loadEngines() ************* Syntax ====== #include bool loadEngines(shipRecordType *ship, starbaseRecordType *starbase, byte techLevel); Description =========== Loads all engines of type TECHLEVEL from the STARBASE onto the SHIP Return value ============ true if succesful, false if not loadBeamWeapons() ***************** Syntax ====== #include bool loadBeamWeapons(shipRecordType *ship, starbaseRecordType *starbase, byte techLevel); Description =========== Loads all beam weapons of type TECHLEVEL from the STARBASE onto the SHIP Return value ============ true if succesful, false if not loadTorpedoes() *************** Syntax ====== #include bool loadTorpedoes(shipRecordType *ship, starbaseRecordType *starbase, byte techLevel); Return value ============ Description =========== Loads all torpedo tubes of type TECHLEVEL from the STARBASE onto the SHIP true if succesful, false if not loadHulls() *********** Syntax ====== #include bool loadHulls(shipRecordType *ship, starbaseRecordType *starbase, byte techLevel); Description =========== 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 Return value ============ true if succesful, false if not countTowedBases() ***************** Syntax ====== #include int countTowedBases(void); Description =========== Counts all starbases being towed. Return value ============ the number of starbases being towed newTowedBase() ************** Syntax ====== #include int newTowedBase(void); Description =========== Creates a new starbase being towed Return value ============ the index number of the new starbase hookStationaryStarbase() ************************ Syntax ====== #include bool hookStationaryStarbase(shipRecordType *ship, starbaseRecordType *starbase); Description =========== Hooks the STARBASE onto the SHIP, which will then tow it. Return value ============ true if succesful, false if not makeUFOTowedBase() ****************** Syntax ====== #include bool makeUFOTowedBase(towedBaseRecordType *T); Description =========== Makes a UFO record for the starbase T being towed. Return value ============ true if succesful, false if not unmakeUFOTowedBase() ******************** Syntax ====== #include bool unmakeUFOTowedBase(towedBaseRecordType *T); Description =========== Removes the starbase T from the UFO database Return value ============ true if succesful, false if not makeUFOComponent() ****************** Syntax ====== #include bool makeUFOComponent(componentRecordType *T); Description =========== Creates a UFO record for a towed component T Return value ============ true if succesful, false if not unmakeUFOComponent() ******************** Syntax ====== #include bool unmakeUFOComponent(componentRecordType *T); Description =========== Removed towed component T from the UFO database Return value ============ true if succesful, false if not Data filters and compilers ************************** 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. compileConfig() *************** Syntax ====== #include bool compileConfig(configType *config); Description =========== Compiles the configuration information in configType CONFIG. Return value ============ true if successful, false if not decompileConfig() ***************** Syntax ====== #include bool decompileConfig(configType *config); Description =========== Decompiles the configuration information in configType CONFIG and stores the data on disk. Return value ============ true if successful, false if not compileMinefieldRecord() ************************ Syntax ====== #include bool compileMinefieldRecord(minefieldRecordType *minefieldRecord, short record); Description =========== Compiles the mine field information for mine field RECORD Return value ============ true if successful, false if not decompileMinefieldRecord() ************************** Syntax ====== #include bool decompileMinefieldRecord(minefieldRecordType *minefieldRecord); Description =========== Decompiles the mine field information in MINEFIELDRECORD. Assumes Read-Only fields were only read. Return value ============ true if successful, false if not compileRaceRecord() ******************* Syntax ====== #include bool compileRaceRecord(raceRecordType *raceRecord, short record); Description =========== Compiles the race information for race RECORD Return value ============ true if successful, false if not decompileRaceRecord() ********************* Syntax ====== #include bool decompileRaceRecord(raceRecordType *raceRecord); Description =========== Decompiles the information in RACERECORD. Assumes the Read-Only information was only read. Return value ============ true if successful, false if not compileShipRecord() ******************* Syntax ====== #include bool compileShipRecord(shipRecordType *shipRecord, short record); Description =========== Compiles the ship information for ship RECORD Return value ============ true if successful, false if not decompileShipRecord() ********************* Syntax ====== #include bool decompileShipRecord(shipRecordType *shipRecord); Description =========== Decompiles the ship information in SHIPRECORD Return value ============ true if successful, false if not compilePlanetRecord() ********************* Syntax ====== #include bool compilePlanetRecord(planetRecordType *planetRecord, short record); Description =========== Compiles the planet information for planet RECORD Return value ============ true if successful, false if not decompilePlanetRecord() *********************** Syntax ====== #include bool decompilePlanetRecord(planetRecordType *planetRecord); Description =========== Decompiles the planet information in PLANETRECORD. Return value ============ true if successful, false if not planetXY2buffer() ***************** Syntax ====== #include bool planetXY2buffer(void *buffer, planetXYType *planetXY); Description =========== Converts planetXYType to the way it is stored on disk. Return value ============ true if successful, false if not buffer2planetXY() ***************** Syntax ====== #include bool buffer2planetXY(planetXYType *planetXY, void *buffer); Description =========== Converts the data in BUFFER to planetXYType Return value ============ true if successful, false if not planet2buffer() *************** Syntax ====== #include bool planet2buffer(void *buffer, planetType *planet); Description =========== Converts planetType to the way it is stored on disk Return value ============ true if successful, false if not buffer2planet() *************** Syntax ====== #include bool buffer2planet(planetType *planet, void *buffer); Description =========== Converts the data in BUFFER to planetType Return value ============ true if successful, false if not buffer2ship() ************* Syntax ====== #include bool buffer2ship(shipType *ship, void *buffer); Description =========== Converts shipType to the way it is stored on disk Return value ============ true if successful, false if not ship2buffer() ************* Syntax ====== #include bool ship2buffer(void *buffer, shipType *ship); Description =========== Converts the data in BUFFER to shipType Return value ============ true if successful, false if not shipXY2buffer() *************** Syntax ====== #include bool shipXY2buffer(void *buffer, shipXYType *shipXY); Description =========== Converts the shipXYType to the way it is stored on disk Return value ============ true if successful, false if not buffer2shipXY() *************** Syntax ====== #include bool buffer2shipXY(shipXYType *shipXY, void *buffer); Description =========== Converts the data in the buffer to shipXYType Return value ============ true if successful, false if not base2buffer() ************* Syntax ====== #include bool base2buffer(void *buffer, baseType *base); Description =========== Converts the data in baseType to the way it is stored on disk Return value ============ true if successful, false if not buffer2base() ************* Syntax ====== #include bool buffer2base(baseType *base, void *buffer); Description =========== Converts the data in BUFFER to baseType Return value ============ true if successful, false if not raceName2buffer() ***************** Syntax ====== #include bool raceName2buffer(void *buffer, raceNameType *raceNames); Description =========== Converts the raceNameType info to the way it is stored on disk. Return value ============ true if successful, false if not buffer2raceName() ***************** Syntax ====== #include bool buffer2raceName(raceNameType *raceNames, void *buffer); Description =========== Converts the buffer data to raceNameType Return value ============ true if successful, false if not hullSpec2buffer() ***************** Syntax ====== #include bool hullSpec2buffer(void *buffer, hullSpecType *hullSpec); Description =========== Converts the hullSpecType to the way it is stored on disk Return value ============ true if successful, false if not buffer2hullSpec() ***************** Syntax ====== #include bool buffer2hullSpec(hullSpecType *hullSpec, void *buffer); Description =========== Converts the BUFFER data to hullSpecType Return value ============ true if successful, false if not engineSpec2buffer() ******************* Syntax ====== #include bool engineSpec2buffer(void *buffer, engineSpecType *engineSpec); Description =========== Converts the engineSpecType data to the way it is stored on disk Return value ============ true if successful, false if not buffer2engineSpec() ******************* Syntax ====== #include bool buffer2engineSpec(engineSpecType *engineSpec, void *buffer); Description =========== Converts the BUFFER data to engineSpecType Return value ============ true if successful, false if not beamSpec2buffer() ***************** Syntax ====== #include bool beamSpec2buffer(void *buffer, beamSpecType *beamSpec); Description =========== Converts the beamSpecType data to the way it is stored on disk Return value ============ true if successful, false if not buffer2beamSpec() ***************** Syntax ====== #include bool buffer2beamSpec(beamSpecType *beamSpec, void *buffer); Description =========== Converts the BUFFER data to beamSpecType Return value ============ true if successful, false if not torpSpec2buffer() ***************** Syntax ====== #include bool torpSpec2buffer(void *buffer, torpSpecType *torpSpec); Description =========== Converts the torpSpecType data to the way it is stored on disk Return value ============ true if successful, false if not buffer2torpSpec() ***************** Syntax ====== #include bool buffer2torpSpec(torpSpecType *torpSpec, void *buffer); Description =========== Converts the BUFFER data to torpSpecType Return value ============ true if successful, false if not hConfig2buffer() **************** Syntax ====== #include bool hConfig2buffer(void *buffer, hConfigType *hConfig); Description =========== Converts the hConfigType data to the way it is stored on disk Return value ============ true if successful, false if not buffer2hConfig() **************** Syntax ====== #include bool buffer2hConfig(hConfigType *hConfig, void *buffer); Description =========== Converts the BUFFER data to hConfigType Return value ============ true if successful, false if not VCR2buffer() ************ Syntax ====== #include bool VCR2buffer(void *buffer, VCRType *VCR); Description =========== Converts the VCRType data to the way it is stored on disk Return value ============ true if successful, false if not buffer2VCR() ************ Syntax ====== #include bool buffer2VCR(VCRType *VCR, void *buffer); Description =========== Converts the BUFFER data to VCRType Return value ============ true if successful, false if not mine2buffer() ************* Syntax ====== #include bool mine2buffer(void *buffer, mineType *mine); Description =========== Converts the mineType data to the way it is stored on disk Return value ============ true if successful, false if not buffer2mine() ************* Syntax ====== #include bool buffer2mine(mineType *mine, void *buffer); Description =========== Converts the BUFFER data to mineType Return value ============ true if successful, false if not UFO2buffer() ************ Syntax ====== #include bool UFO2buffer(void *buffer, UFOType *UFO); Description =========== Converts the UFOType data to the way it is stored on disk Return value ============ true if successful, false if not buffer2UFO() ************ Syntax ====== #include bool buffer2UFO(UFOType *UFO, void *buffer); Description =========== Converts the BUFFER data to UFOType Return value ============ true if successful, false if not ion2buffer() ************ Syntax ====== #include bool ion2buffer(void *buffer, ionType *ion); Description =========== Converts the ionType data to the way it is stored on disk Return value ============ true if successful, false if not buffer2ion() ************ Syntax ====== #include bool buffer2ion(ionType *ion, void *buffer); Description =========== Converts the BUFFER data to ionType Return value ============ true if successful, false if not alliance2buffer() ***************** Syntax ====== #include bool alliance2buffer(void *buffer, allianceType *alliance); Description =========== Converts the allianceType data to the way it is stored on disk Return value ============ true if successful, false if not buffer2alliance() ***************** Syntax ====== #include bool buffer2alliance(allianceType *alliance, void *buffer); Description =========== Converts the BUFFER data to allianceType Return value ============ true if successful, false if not UFORecord2UFO() *************** Syntax ====== #include bool UFORecord2UFO(UFOType *UFO, UFORecordType *UFORecord); Description =========== Converts the UFOType data to UFORecordType data Return value ============ true if successful, false if not UFO2UFORecord() *************** Syntax ====== #include bool UFO2UFORecord(UFORecordType *UFORecord, UFOType *UFO); Description =========== Converts the UFOType data to UFORecordType data Return value ============ true if successful, false if not ion2ionstormRecord() ******************** Syntax ====== #include bool ion2ionstormRecord(ionstormRecordType *ionstormRecord, ionType *ion); Description =========== Converts the ionType data to ionRecordType data Return value ============ true if successful, false if not ionstormRecord2ion() ******************** Syntax ====== #include bool ionstormRecord2ion(ionType *ion, ionstormRecordType *ionstormRecord); Description =========== Converts the ionRecordType data to ionType data Return value ============ true if successful, false if not base2starbaseRecord() ********************* Syntax ====== #include bool base2starbaseRecord(starbaseRecordType *starbaseRecord, baseType *base); Description =========== Converts the starbaseRecordType data to baseType data Return value ============ true if successful, false if not starbaseRecord2base() ********************* Syntax ====== #include bool starbaseRecord2base(baseType *base, starbaseRecordType *starbaseRecord); Description =========== Converts the baseType data to starbaseRecordType data Return value ============ true if successful, false if not buf2Cmp() ********* Syntax ====== #include bool buf2Cmp(componentRecordType *C, char *B); Description =========== Converts the buffer B to componentRecordType Return value ============ true if successful, false if not cmp2Buf() ********* Syntax ====== #include bool cmp2Buf(char *B, componentRecordType *C); Description =========== Converts the componentRecordType data to the way it is stored on disk Return value ============ true if successful, false if not buf2Tsb() ********* Syntax ====== #include bool buf2Tsb(towedBaseRecordType *T, char *B); Description =========== Converts the buffer B to towedBaseRecordType data Return value ============ true if successful, false if not tsb2Buf() ********* Syntax ====== #include bool tsb2Buf(char *B, towedBaseRecordType *T); Description =========== Converts the towedBaseRecordType data to the way it is stored on disk Return value ============ true if successful, false if not buf2Esb() ********* Syntax ====== #include bool buf2Esb(enhancedBaseRecordType *E, char *B); Description =========== Converts the buffer B to enhancedBaseRecordType data Return value ============ true if successful, false if not esb2Buf() ********* Syntax ====== #include bool esb2Buf(char *B, enhancedBaseRecordType *E); Description =========== Converts the enhancedBaseRecordType data to the way it is stored on disk Return value ============ true if successful, false if not GTR2_gtr2Buf() ************** Syntax ====== #include bool GTR2_gtr2Buf(char *buffer, GTR2_GatorType *gator); Description =========== Converts a V2 Gator (GTR2_GatorType) to the way it is stored on disk Return value ============ true if successful, false if not GTR2_buf2Gtr() ************** Syntax ====== #include bool GTR2_buf2Gtr(GTR2_GatorType *gator, char *buffer); Description =========== Converts the BUFFER data to GTR2_Gatortype Return value ============ true if successful, false if not GTR2_cfg2Buf() ************** Syntax ====== #include bool GTR2_cfg2Buf(char *buffer, GTR2_ConfigType* config); Description =========== Converts the V2 Gators Configuration (GTR2_ConfigType) to the way it is stored on disk Return value ============ true if successful, false if not GTR2_buf2Cfg() ************** Syntax ====== #include bool GTR2_buf2Cfg(GTR2_ConfigType* config, char *buffer); Description =========== Converts the BUFFER data to GTR2_ConfigType Return value ============ true if successful, false if not gtr2Buf() ********* Syntax ====== #include bool gtr2Buf(char *buffer, gatorType *gator); Description =========== Converts gatortype information to the way it is stored on disk Return value ============ true if successful, false if not buf2Gtr() ********* Syntax ====== #include bool buf2Gtr(gatorType *gator, char *buffer); Description =========== Converts the BUFFER data to gatorType Return value ============ true if successful, false if not cfg2Buf() ********* Syntax ====== #include bool cfg2Buf(char *buffer, gatorConfigType *config); Description =========== Converts gatorConfigType to the way it is stored on disk Return value ============ true if successful, false if not buf2Cfg() ********* Syntax ====== #include bool buf2Cfg(gatorConfigType *config, char *buffer); Description =========== Converts data in BUFFER to gatorConfigType Return value ============ true if successful, false if not spu2Buf() ********* Syntax ====== #include bool spu2Buf(char *buffer, shipUFOType *shipUFO); Description =========== Converts shipUFOType to the way it is stored on disk Return value ============ true if successful, false if not buf2Spu() ********* Syntax ====== #include bool buf2Spu(shipUFOType *shipUFO, char *buffer); Description =========== Converts BUFFER data to shipUFOType Return value ============ true if successful, false if not lnk2Buf() ********* Syntax ====== #include bool lnk2Buf(char *buffer, linkShipType *linkShip); Description =========== Converts linkShipType to the way it is stored on disk Return value ============ true if successful, false if not buf2Lnk() ********* Syntax ====== #include bool buf2Lnk(linkShipType *linkShip, char *buffer); Description =========== Converts BUFFER data to linkShipType Return value ============ true if successful, false if not validateGatorRecord() ********************* Syntax ====== #include valid validateGatorRecord(gatorType *gator, short record); Description =========== Checks validty of GATOR number RECORD Return value ============ 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. explodeGator() ************** Syntax ====== #include bool explodeGator(gatorType *gator); Description =========== Destroys GATOR Return value ============ true if successful, false if not explodeShip() ************* Syntax ====== #include bool explodeShip(shipRecordType *ship); Description =========== Destroys SHIP Return value ============ true if successful, false if not explodeShipUFO() **************** Syntax ====== #include bool explodeShipUFO(shipUFOType *shipUFO); Description =========== Destroys warped ship SHIPUFO Return value ============ true if successful, false if not The Battle Engine ***************** 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. doBattle() ********** Syntax ====== #include bool doBattle(shipRecordType *ship1, shipRecordType *ship2, planetRecordType *planet, starbaseRecordType *starbase, gatorType *gator, shipUFOType *shipUFO); Description =========== Calculates the battle between two opposing objects - the rest of the parameters should be set to NULL. Example ======= 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); Return value ============ 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. setMessage() ************ Syntax ====== #include void setMessage(short messageType, messageDataType *message, shipRecordType *ship, planetRecordType *planet, starbaseRecordType *starbase, raceRecordType *race, gatorType *gator); Description =========== Sets the message parameters for message MESSAGETYPE, based on the other passed info. _Do not use_. Return value ============ none getMessagePointer() ******************* Syntax ====== #include bool getMessagePointer(messagePointerType *ptr, short record); Description =========== Gets the message information about message RECORD. _not tested_ Return value ============ true if successful, false if not putMessage() ************ Syntax ====== #include bool putMessage(short cc, char xzstr[], short ID, char gG[]); Description =========== Sends a subspace message to race CC, content XZSTR, sender ID, pre-string GG. Example ======= if (rv) rv = putMessage(1, "<< TEST MESSAGE >>\rThis is a test message\r", 0, "-m0"); Return value ============ true if successful, false if not issueMessage() ************** Syntax ====== #include bool issueMessage(messageDataType *message); Description =========== Sends a message with message parameters stored in MESSAGE, set up by setMessage. _Do not use_ Return value ============ true if successful, false if not Internal methods **************** 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!* vpl3_openFiles() **************** Syntax ====== bool vpl3_openFiles(void); Description =========== Opens the files with the requested information. Return value ============ true if successful, false if not vpl3_closeFiles() ***************** Syntax ====== bool vpl3_closeFiles(void); Description =========== Closes the opened files Return value ============ true if successful, false if not downVPL3() ********** Syntax ====== void downVPL3(void); Description =========== Shuts down the library Return value ============ true if successful, false if not vpl3_getConfig() **************** Syntax ====== bool vpl3_getConfig(void); Description =========== Gets the configuration directly from the files, compiles it and stores it in the buffer for readConfig() and writeConfig() Return value ============ true if successful, false if not vpl3_getShips() *************** Syntax ====== bool vpl3_getShips(void); Description =========== Gets the ships directly from the files, compiles it and stores it in the buffer for readShip() and writeShip() Return value ============ true if successful, false if not vpl3_getPlanets() ***************** Syntax ====== bool vpl3_getPlanets(void); Description =========== Gets the planets directly from the files, compiles it and stores it in the buffer for readPlanet() and writePlanet() Return value ============ true if successful, false if not vpl3_getStarbases() ******************* Syntax ====== bool vpl3_getStarbases(void); Description =========== Gets the starbases directly from the files, compiles it and stores it in the buffer for readStarbase() and writeStarbase() Return value ============ true if successful, false if not vpl3_getRaces() *************** Syntax ====== bool vpl3_getRaces(void); Description =========== Gets the Races directly from the files, compiles it and stores it in the buffer for readRace() and writeRace() Return value ============ true if successful, false if not vpl3_getMinefield() ******************* Syntax ====== bool vpl3_getMinefield(void); Description =========== Gets the mine fields directly from the files, compiles it and stores it in the buffer for readMinefield() and writeMinefield() Return value ============ true if successful, false if not vpl3_getIonstorms() ******************* Syntax ====== bool vpl3_getIonstorms(void); Description =========== Gets the ion storms directly from the files, compiles it and stores it in the buffer for readIonstorm() and writeIonstorm() Return value ============ true if successful, false if not vpl3_getUFOs() ************** Syntax ====== bool vpl3_getUFOs(void); Description =========== Gets the UFOs directly from the files, compiles it and stores it in the buffer for readUFO() and writeUFO() Return value ============ true if successful, false if not vpl3_getHost() ************** Syntax ====== bool vpl3_getHost(void); Description =========== Gets the host info directly from the files, compiles it and stores it in the buffer for readHost() and writeHost() Return value ============ true if successful, false if not vpl3_putConfig() **************** Syntax ====== bool vpl3_putConfig(void); Description =========== Puts the configuration directly into the files Return value ============ true if successful, false if not vpl3_putShips() *************** Syntax ====== bool vpl3_putShips(void); Description =========== Puts the ships directly into the files Return value ============ true if successful, false if not vpl3_putPlanets() ***************** Syntax ====== bool vpl3_putPlanets(void); Description =========== Puts the planets directly into the files Return value ============ true if successful, false if not vpl3_putStarbases() ******************* Syntax ====== bool vpl3_putStarbases(void); Description =========== Puts the starbases directly into the files Return value ============ true if successful, false if not vpl3_putRaces() *************** Syntax ====== bool vpl3_putRaces(void); Description =========== Puts the races directly into the files Return value ============ true if successful, false if not vpl3_putMinefield() ******************* Syntax ====== bool vpl3_putMinefield(void); Description =========== Puts the mine fields directly into the files Return value ============ true if successful, false if not vpl3_putIonstorms() ******************* Syntax ====== bool vpl3_putIonstorms(void); Description =========== Puts the ion storms directly into the files Return value ============ true if successful, false if not vpl3_putUFOs() ************** Syntax ====== bool vpl3_putUFOs(void); Description =========== Puts the UFOs directly into the files Return value ============ true if successful, false if not