V4Face2.dll
From PlanetsWiki
Contents |
[edit] Overview
This DLL gives you access to the ship (.spk) and race (.rce) files so that you can pull out their statistics and even their graphics.
For C++ programmers, there is a (non-official) example of how to interact with V4Face2.dll in order to extract race information from the various race and ship packs.
The VidiVici and ScriptZ0r source code include a PlanetsLib that is set up to allow reusable code in Visual Studio projects to interface with this DLL.
[edit] Race Data
To be able to retrieve race data from the RCE files, you will have to set up access to the DLL's subroutines then some variables to hold the results, then call the subroutine.
Here is an example in Visual Basic 6:
Type RaceFacetype
version As Long
racenum As Long
FarmLow As Long ' low farm climate
FarmHigh As Long ' high farm climate
FavClimate As Long ' climate this race likes the best
PlanetStruct As Long ' structs that this race can build (bitfield)
'// Bit 1 Training Center
'// Bit 2 Factory
'// Bit 3 Farm
'// Bit 4 Smelter
'// Bit 5 Mineral Mine
'// Bit 6 City
'// Bit 7 Pod Launch Pad
'// Bit 8 Military Space Port
'// Bit 9 Raid Shelter
'// Bit 10 Public Space Port
'// Bit 11 Med Lab
'// Bit 12 Engine Plant
'// Bit 13 Fighter Plant
'// Bit 14 Ship Repair Shop
'// Bit 15 Weapons Factory
'// Bit 16 Ordnance Plant
'// Bit 17 Government Center
'// Bit 18 Terra Former
'// Bit 19 Scanner
'// Bit 20 Anti-Aircraft Gun
'// Bit 21 Laser Cannon
'// Bit 22 Air Attack Base
'// Bit 23 Base Shield
'// Bit 24 Assault Plant
'// Bit 25 Ion Cannon
'// Bit 26 Undercity
ModMoney As Long
ModMine As Long
ModHappy As Long
contraLikes(1 To 12) As Long
combatCrew As Long
combatColonist As Long
combatTroop As Long
combatGuard As Long
pilotcrew As Long
pilotTroop As Long
pilotGuard As Long
deltacolcrew As Long
deltacrewtroop As Long
deltatroophg As Long
growthrate As Long
forcedark As Long
forcegood As Long
pcfactor As Long
spifactor As Long
psifactor As Long
leadership As Long
lifeform As Long
' bit 0
' bit 1 Humanoid (ugly bags of mostly water)
' bit 2 Humanoid / Animal
' bit 3 Cyborg
' bit 4 Machine
' bit 5 Silicon based
' bit 6 Lizard / Humanoid
' bit 7 Transdimensional Energy Being
' bit 8 Lovecraftian
' bit 9 Living fire
' bit 10 Sentiel Plant
' bit 11 Consuming Darkness
' bit 12 Being of Light
' bit 13 Avian / Humanoid
' bit 14 Insectoid / Humanoid
PR As Long
law As Long ' How lawful the race is
resortE As Long ' flag of what a resort does for race
cantinaE As Long ' flag of what a cantina does for the race
shipB(1 To 40) As Long ' the ship hulls that can be built
PodSpeed As Long ' How fast a cargo pod can travel under boost
flag1 As Long 'Unused
flag2 As Long
flag3 As Long
flag4 As Long
flag5 As Long
flag6 As Long
flag7 As Long
flag8 As Long
flag9 As Long
flag10 As Long
nm1 As String * 44 ' Long Name
nm2 As String * 20 ' Short name
nm3 As String * 32 ' Leader name
nmgov As String * 32 ' Governent Type
End Type
'Fighter
Type FighterFaceType
FighterSlot As Long '1 2 or 3
FighterRace As Long 'the racenum (race number) that built this
beam As Long
missile As Long
oddsbeam As Long
oddsmissile As Long
maxEleOrd As Long
maxfuel As Long
MaxRange As Long
Armor As Long
SoftSpot As Long
fuelburn As Long
EvasiveMod As Long
AttackMod As Long
speed As Long
cost As Long
gen As Long 'recharge rate
batt As Long 'max energy
rangemissile As Long
rangebeam As Long
aMech As Long
aTroop As Long
aCity As Long
aAir As Long
dAir As Long
dTroop As Long
dMech As Long
flag1 As Long 'Unused
flag2 As Long
flag3 As Long
nm As String * 32
End Type
'Mech Unit
Type MechFaceType
mechslot As Long '1 2 or 3
mechrace As Long 'the racenum (race number) that built this
aAir As Long
aTroop As Long
aCity As Long
aMech As Long
dAir As Long
dTroop As Long
dMech As Long
cloak As Long
speed As Long
cost As Long
special As Long
' bit 1 Spy
' bit 2 Mine
' bit 3 Farm
' bit 4 Covert Anti-Life
' bit 5 PSI Ops
' bit 6 Salvage Harvister
' bit 7 River Boat Royale
' bit 8 Cyborg Assimilator
flag1 As Long 'Unused
flag2 As Long
flag3 As Long
nm As String * 32
End Type
Declare Sub GETRACETEMPBMP Lib "v4face2.dll" (sRaceFile As String, sTempPath As String)
Declare Sub LOADRACEDATA Lib "v4face2.dll" (sRaceFile As String, tRace As RaceFacetype, mech1 As MechFaceType, mech2 As MechFaceType, mech3 As MechFaceType, fighter1 As FighterFaceType, fighter2 As FighterFaceType, fighter3 As FighterFaceType)
Public filepath As String
Public race As RaceFacetype
Public mech1 As MechFaceType
Public mech2 As MechFaceType
Public mech3 As MechFaceType
Public fighter1 As FighterFaceType
Public fighter2 As FighterFaceType
Public fighter3 As FighterFaceType
Private X As Long
Dim racefile As String
X = 101 ' Change the race number to the one that you want
racefile = "race" & X & ".rce"
filepath = "races\" & racefile
LOADRACEDATA filepath, race, mech1, mech2, mech3, fighter1, fighter2, fighter3
GETRACETEMPBMP filepath, ".\"
When the LOADRACEDATA is complete, the race structure will contain all of the data for race 101 (Federation) from the type RaceFaceType, mech1 will contain all of the data for race 101 from the type MechFaceType, etc. With this information you can have your program make decisions, calculations, and output as necessary. The GETRACETEMPBMP creates a few temp files that are the BMP graphics, MIDI music file, and a text info file for race 101.
[edit] Hull Data
To be able to retrieve hull/ship data from the SPK files, you will have to set up access to the DLL's subroutines then some variables to hold the results, then call the subroutine.
Here is an example in Visual Basic 6:
Type HullFaceType
hullname As String * 40 ' The name of the hull type
HClass As Long ' The hull type number
Bays As Long ' Max number of bays (0-20)
BaySize As Long ' The max mass that can dock in the bay
Hugeweapon As Long ' Bit flag Types HUGE weapons this ship can have (bit0-bit4)
' Bit 0 Laser Cannon
' Bit 1 Nemesis
' Bit 2 World Crusher
' Bit 3 Anti-Matter Maul
' Bit 4 Proto-Matter Cannon
LargeLimit As Long ' The max weapon size that will fit in a large slot
mass As Long ' Mass of hull
PointDefense As Long ' Number of anti-fighter gun ports (0-10)
LargeWeapons As Long ' Number of large anti-ship weapons (0-20)
SmallWeapons As Long ' Number of small anti-ship weapons (0-30)
Fueltank As Long ' Amount of fuel ship can carry
MaxSpeed As Long ' Max cruising speed (0 - 400)
MaxHypSpeed As Long ' Max speed using a hyperdrive (0-5000)
Engines As Long ' Number of engines required
gen As Long ' Generator slots (0-5)
PodBays As Long ' Number of Pod bays (0-20)
CrewSize As Long ' Standard Number of crew members
GuestSize As Long ' Number of guest personal (Troops, Colonists, High Guard, Crew)
Stealth As Long ' Stealth rating of ship 100 = Norm ; 0 = invisible
ScanRange As Long ' Range that this ship can scan
ArmorLimit As Long ' The limit on the amount of armor reinforcement
ShieldLimit As Long ' The highest shield power this ship can have
EvasiveMod As Long ' The ability to dodge enemy fire
AttackMod As Long ' The ability to bring weapons to bare
TechLevel As Long ' Tech level required to build
eleD As Long
eleT As Long
eleM As Long
SoftSpot As Long ' Size of "exhaust port hole"
ModFuelBurn As Long ' Modifier to the rate that fuel is used
PowerLimit As Long ' The size of the main weapons capacitor
Sflag1 As Long ' Add-on hull goody - see "CSV: Ship - Device List 1" below
Sflag2 As Long ' Add-on hull goody - see "CSV: Ship - Device List 2" below
SFlag3 As Long ' Add-on hull goody - see "CSV: Ship - Device List 3" below
maxcargo As Long ' Max cargo ship can have
maxord As Long ' Max ordance that ship can carry
maxfix As Long
newhullsize As Long ' = size of new hull ship can build
TractorBeam As Long ' size of ship that can be towed
cost As Long ' Cost to build
modparts As Long ' Damage Mod for ship 100 = normal
modsys As Long
modeng As Long
modlife As Long
modhyp As Long
cloakfuel As Long ' Fuel needed to cloak
U1 As Long ' Unused
U2 As Long
U3 As Long
U4 As Long
U5 As Long
U6 As Long
U7 As Long
U8 As Long
End Type
Declare Sub LOADHULLKEYS Lib "v4face2.dll" (sPath As String, vFirstLong As Long, sKey As String)
Declare Sub FROMFILELOADHULLKEYS Lib "v4face2.dll" (sShipFile As String, vFirstLong As Long, sKey As String)
Declare Sub LOADHULL Lib "v4face2.dll" (sPath As String, vHullID As Long, tHULL As HullFaceType, sKey As String)
Declare Sub GETSHIPTEMPBMP Lib "v4face2.dll" (sPath As String, sTempPath As String, vHullID As Long, sKey As String)
Public g_vList(1 To 2000) As Long
Public g_sKey As String
Public hull As HullFaceType
Public filepath As String
Private X As Long
X = 44 ' Hull number (44 = Victorious Class Battleship)
filepath = "ships\"
g_vList(1) = X ' Assign the first position with the desired hull number
LOADHULLKEYS filepath, g_vList(1), g_sKey ' The rest of the g_vList now contains a 1 if that value is a valid hull number
If g_vList(X) Then ' Hull is in the returned list
LOADHULL filepath, X, hull, g_sKey
GETSHIPTEMPBMP filepath, ".\", X, g_sKey
End If
The LOADHULLKEYS will provide you with a list of valid hulls and the key to be able to query the hull data with LOADHULL. FROMFILELOADHULLKEYS (not demonstrated in this code sample) is a way of doing the same thing as LOADHULLKEYS, but using the exact SPK file name. When LOADHULL is complete, hull will be populated with the HullFaceType data. GETSHIPTEMPBMP will create temp BMP files and an ICO file in the local path.
[edit] Bitfields
Some of the data that you get from the ship and race files as well as the exported CSV files from the Planets client contains condensed on/off data named bitfields. Any building structure that you can only have one of will be in a bitfield as well as whether or not a ship device is on or off.
Bitfield example using the Ship Devices by N/A from the newsgroup: Consider bit 0 to be the rightmost bit and bit 31 to be the leftmost bit. Like such:
00000000000000000000000000000001 (binary) ^ Bit 31 ^ Bit 0
