by: Jason Kane (aka: Mordok)
Everyone and their grandmother wants to create their own little corner of space. But there isn't (yet) any official documentation on how to do it. So, here goes.
Note that most of the information here is based on guesswork and many trial and error attempts. The game designers are extremely helpful but most of us are more interested in having hem working on the game instead of writing documentation (something we all wholeheartedly support). Most of what's here has been gathered from postings in the stellar frontiers newsgroup (stardock.games.sf) and it's subgroups.
Note: most of this info is at least useful. I have not written anything to explain the #include style file arrangements.
The .dat file is split up into sections, each section describes a particular aspect of the game. there are three basic types of section "bitmap", "data" and "design".
Now I'm going to go through each section of a dat file explaining the format, as well as what each option does.
The game data section includes a series of variable names and corresponding values. these values affect the entire solar system.
|year||This parameter gives you a way of randomizing the positions of the planets. Each value of year will result in a different configuration of the planets in their orbits, unless their initial angles are hard coded. (see planet data section for more info)||3015|
|players||Maximum number of simultaneous players. this includes both humans and computer controlled ships.||64|
|robots||Total # of computer controlled ships (be sure you have at least this many ai names/ships defined in the robots data section)||16|
|max_acc||Maximum acceleration (not maximum velocity)||50|
|light_speed||This is the measure of c in pixels per second||200|
|ship_g||This is the gravitational constant that is applied to gravity between planets and ships. the mass and distance is still factored in, but by making this constant independent from the planets-to-planet gravity we can turn off the planet-planet gravity and keeps the planets positions constant.||50|
|planet_g||This makes the planets more attractive to each other, but does not affect ships. changing this to be nonzero will turn on planet-to-planet gravity, which means that the planets will begin to orbit each other and/or the sun. this tends to not work very well||0|
|debris_count||This is the number of debris/powerup bitmaps that have been defined for each race.||4|
|extra_colonies||By default, the game will not allow more colonies than there are planets. this parameter allows you to expand that capacity. for example, if the solar system has 32 planets defined and extra_colonies is set to 4 then the game will allow up to 36 colonies.||4|
|allow_surrender||In days gone by, you took over a colony with brute force. when allow_surrender is 'yes' colonies will give up when under sustained assult (see defection_rate and loyalty_cycle for more details)||no|
|defection_rate||The %probability / second that a colony with -100 loyalty will defect.||6000|
|offensive_factor||The % factor that an attacking colony will have over a defending one.||200|
|loyalty_cycle||The number of seconds that a 100% loyal colony will wait for help after falling under attack before surrendering.||1800|
|robot_population_total||Determines how many robots are available (shared among all races) based on total population.||8|
|robot_population_rate||This determines at what rate robots are handed out
per percentage point of total population. for the numbers you gave above,
there are 16 robots, 8 of which are distributed to each race based on total
population. One robot is given for every 3% of the total possible system-wide
In addition, a separate pool of robots (in this case 8) is available based on how many planets each race has. to control this there are robot_planet_total and robot_planet_rate, which set how many robots are available and how many planets are necessary for each one.
|robot_planet_total||Determines how many robots are available (shared among all races) based on number of planets.||0|
|robot_planet_rate||Determines at what rate robots are handed out per percentage point of planets controlled.||0|
|powerup_action||There are "swap", "level+##%", "value+##%", "credit+##%" where ## is
a number between 0 and 100.
|laser_defense||Enables/disables autofiring lasers to destroy incoming missles. this is a fairly significant advantage for admirals club members.||off?|
|name||One line name for this scenario. this is what is displayed when players are choosing a server.|
|desc||Multi-line description of this scenario. this is displayed when players first enter this scenario.|
|salvage_right_pct||You can also specify how much credit you get for capturing an enemy held planet -- by dropping a colony, not by bombardment.|
Fortunately for us, all the bitmap sections share the same basic format. I have started with the descriptions given in the .ini comment and expanded them where they may be difficult to understand.
|class||Bitmap class, this can be ship, missile, explosion, planet, moon, asteroid, colony, warp, mainwindow, videowindow, mapwindow, chatwindow, or debris. Generally you'll know what class you should use (ship, missile etc..) so odds are you'll get this one right.|
|name||Bitmap name. used as a default in case object has no name, in other words, if you do everything right this field will be ignored. it's a one-word description of what this is an image of.|
|file||Bitmap filename without the .bmp and without the path. all of the images you add will be in the /bmp/256 directory.|
|nf||Number of frames in bitmap. frame 0 starts at bottom of bmp and frame nf-1 is at the top. as you can see if you open up one of the ships or weapons that come with the game, animated bmp files look like little movie strips. sf uses the bottom-most image first and moves up the strip. take a look at the seqt parameter also.|
|sz||Size of the bitmap. used for collision detection in the game. saturn is a good example of why you would want to specify this parameter at all.|
|tc||Transparent color. 0 = black. use something like 10 to set all pixels darker than rgb 10:10:10 transparent. my results on this have been less than conclusive. my advice is to use 15:15:15 as 'solid' black and 0:0:0 as transparent. that may mean tweaking the color palette for your images, paint shop pro does a pretty good job at this.|
|alpha||Alpha factor. 100 sets all pixels to their full brightness. 50 is 50% brightness. 0 is completely black. the default setup has everything but mines at 100, mines are at 75. why you wouldn't just tweak down the brightness of the 'origional' image i don't know.|
|login||i'm not sure which of these first two serves as the actual name of the ship's captain. i suspect the 'name' field needs to be unique, but the login is the label displayed by sf.|
|rank||rank of is robot (starting at 0)|
|race||robot race (0 - 3 with standard races)|
|st||ship type, this is set in ship designs section under "ship id".|
|ship_name||name of this robot's ship (duhh)|
|nm||number of missions for this robot|
|nk||number of kills for this robot|
|name||name of the race (arcean, terran etc..)|
|id||numeric identifier for the race (0,1,2 ...)|
|home||homeplanet, this is where players of this race 'start'|
|temp||this races prefered temperature, 300 is default for terrans. this presumably effects population growth and habitability.|
|atmp||this races prefered atmospheric pressure, works like temp|
|grav||this races preferred planetary gravity (like temp and atmp)|
|condition||these are the conditions necessary for this race
to be victorious. this is set as a string and all the possible forms it might
take are unknown (i don't recall stardock ever giving us a complete list
of the possibilities). known options are (with # representing a configurable
|rank||cosmetic rank string|
|level||numeric rank identifier, this corresponds with the rank requirements in the ship design section.|
|active score||the number of kills
since your last death you must have to gain the rank. jeff legere
|total score||score required for this rank|
|total kills||# of kills required for this rank|
|duty||? determines ai behavior ?|
If you will notice all major bodies begin with "0." under rad and bodies that would be considered a "moon" of a majorI body do not start with "0." and do immediately follow the information for the major celestial body (mars = major, phobo & demios = mars moons). Sol has a rad of 0 and angle of * (same as a 'null' placeholder?) which i assume is a special case that sets it at the center of the current solar system. (Mordok)
Regarding rad and angle in the planet data section. rad should be the distance from the star, angle is the angle (from 0 to 360) that the planet is placed. take a circle, draw a line from the center out 400 (what ever measurement unit you want) at and angle of 130 from the demarcation line. you get rad of 300 angle 130. simplist method of defining a location in 2d space.
I got this from neil hillis, so you may be able to consider it pretty good info (tm).
Here is the breakdown, some of which you already understand, (for 4504*9*0*24*24*24)
9 is the angular position on the graphic. there are 36 frames / 360 degrees, so each is 10 degrees. a value of nine is equivalent to 90 degrees counterclockwise from north, which is west.
0 is the radial position, in pixels, on the graphic. a value of 0 is a special case for half the width of the bitmap, which is the outer edge.
The first 24 is the default direction (same units as the first parameter) for the beam.
The second 24 is the lower limit of the firing arc in the same units as the first parameter.
The third 24 is the upper limit of the firing arc in the same units as the first parameter.
If you want the beam to fire west, then you should use [mr]4504*9*0*9*9*9, but limiting it to just one angle gives it a pretty narrow arc (10 deg). using [mr]4504*9*0*9*8*10 might be a little better.
0 degrees is due east (right)
90 is straight up
180 is west
270 is down
Lets consider the first contact system. It is multi systemed. here is the contents of the fc_data_planets.sec file:
#echo * loading solar systems for first contact... #include sf_data_planets_sol.sec([r]=0.0,[a]=0) #include sf_data_planets_acentauri.sec([r]=1.2,[a]=250) #include sf_data_planets_eeridani.sec([r]=0.9,[a]=150) #include sf_data_planets_eindi.sec([r]=1.1,[a]=100) #include sf_data_planets_tceti.sec([r]=1.2,[a]=300)
Notice that one system starts out with (0.0,0) for the "coordinates"? this file is setup similar to when you place planets, only you are placing systems. (Plague)
Take the five variables in the module component in the ship's entry in the ships_design file (i think): [mr]4003*a*b*c*d*e,
[mr]4001*9*0*0*-5*5,[mr]4001*-9*0*0*5*-5 will give a [name1] weapon on
each side of your ship, the first one firing from a midpoint of the left
side and the second one firing from a midpoint of the right side.
[mr]4001*9*-10*0*-5*5,[mr]4001*-9*-10*0*5*-5 will give a firing points on each side of the ship, with the first one being on the right and the second one being on the left, at points about the 1/3 the way down the sides.so:
for b 0 refers to the center of the top of the square that is the ship's graphic frame. negative numbers march you down the "spine" of the line that is the vertical "spine" of the frame. positive numbers do some weird thing i don't understand. but see the example.
for "beam" modules (tractor and lasers), there may be a different protocol. so tractor*18*0*18 mean the tractor fire point is at the back and the direction of fire is to the back. and tractor*24*0*24 is left side fire and carry, i find.
for c, d, and e, there are 36 "points", running from 0 to 35 (that's 36 items). 0 and 36 are the same place. unknown
|class||should be "star", "planet", "moon", or "minor" (asteroid).|
|name||the name of the planet.|
|rad||the radius of the orbit in units that depend on what class of planet it is. the stars, planets and asteroids use a unit that used to be such that 1 was the radius of the earth's orbit, but things have been rescaled and the result is that earth is at 0.2 and pluto is at 0.49. moon orbits are more typically around 1.0.|
|angle||the angular position in the orbit in degrees.|
|mass||depends on the class. stars are in units of sol's mass, so sol would be 1.0. planets and asteroids are on the same scale so they should have something in the range 0.05 (asteroid) up to around 17 (jupiter) with earth at 1.0. moons are measured on a luna scale, so luna is 1.0.|
|ap||atmoshperic pressure, which is one of the factors that determines how liveable a planet is. it is 1.0 for earth and everything else scales from that.|
|bi||the bitmap index or name from the planet bitmap section.|
|temp||temperature of the planet's surface in degrees kelvin. earth is around 300 k.|
|hp||hydrographic percentage. it is the percentage of the surface that is covered by a liquid surface and determines how many people can live on the surface (0 if hp is 100%).|
|sg||surface gravity, which is also a factor in the habitability of a planet. the units are based on earth.|
|rr||the race that the planet will revert to after the server resets.|
|ab||accuracy bonus. this is now much of a accuracy bonus a colony will get when it lands on the planet. a 100% accuracy will make full use of the predictive code when aiming shots so the shots will lead a moving target.|
|tf||terrafrom percentage. this also is a factor in how liveable a planet is. even if a planet is not very hospitable, it can be terraformed so that the optimal population is higher. a 100% terraformed planet is limited only by the amount of liveable area (basically surface area * hydro%). a 0 tf% means that the people are exposed to the raw characteristics of the planet (ap, sg, temp). the longer a planet is inhabited the higher the tf% will rise.|
||it says class, but it really means
race. which makes for a rather interesting social statement which may
eventually lead to riots and global condemnation of stellar frontier as a
game which forwards the backwards dogmas of our tangled and violent history.
||even the fungus between my toes doesn't need a description
for this one.
||in every mod i've got handy this
is set to zero, other values will have unknown results. so unless you
want to have just another mod that works instead of a unique statement of
your self-ness and personal independance from the tyrannies of the world
you had better change this to something which better reflects your true self.
||here's one every two-bit hack wants to mess with.
this determines the rank level that a player needs in order to be able to
select this ship design.
||this is a bit of a misnomer because
ships can move more quickly than this in a variety of ways. the obvious
one is qdrive, but we'll ignore that. the other obvious way is with
a boost unit. we'll also ignore that. the third obvious way is
death, which is the fastest way to move from anywhere in the universe to
your homeplanet. but we'll ignore that too. so this 'max speed'
is the fastest speed your ship can reach.
|ship bitmap index
||*||the * means that the game should try to figure it
out. it uses the 'name' field and compares it against the third field
of the ship bitmaps section of the dat. if it can't find a match the
game will automatically dial your mother through your modem and tell her
what a nasty person her little boy/girl turned out to be. so be careful.
||when this ship blows up, what does
it look like?
||which sound from the sound_data will be played when
this ship explodes? there are some really amusing possibilities with
this one. (one of these days i'll make a mod with verbal taunts in
here ala scorched earth)
||this must be unique for every ship-design
in the game. remember that the [r] is going to be replaced by the race
||why have a race id when the 'class' of the ship also
holds the race? heck if i know.
||how much space is available on this
||number of slots available on the ship. note
that the scout has a 12 here, but there are only 11 modules defined.
that's why scouts 'pick up' and install counters, brakes, etc.. anything
that will fit in a slot. what happens when you use a value greater
than 12? well, it sorta works. some parts of the game may have
problems however (notably the refit screen won't scroll to show you the additional
modules so you cannot easily upgrade them, sell them or drop them).
|this is where things get funny.
each module type has a different set of parameters, each of which have different
effects. new server have gotten much smarter. they can take something
like 'power:1' and understand that you mean module id [r]1001. similarly
'tractor' is a named module (in the module data section it has a value under
the name column), so it can be directly referenced here as 'tractor' even
though the actual module type is 'dock' (same deal with cloak). it's
easy to get confused here, take it slow and don't be afraid to experiment.
[race] * 3 50 -200 200 torpedo1 none tube*60*4000*800*[r]001 [r]4001
[race] * 3 50 -500 100 minedrop none tube*15*20000*10*[r]003*6 [r]4003
[race] * 3 50 -500 200 plasma none tube*15*6000*800*[r]004 [r]4004
[race] * 3 50 -1000 200 torpedo2 none tube*100*80000*4*[r]006*6 [r]4006
[race] * 3 50 -500 200 none none tube*15*20000*12*[r]007*6 [r]4007
[race] * 3 50 -200 200 none none tube*20*6000*300*[r]008 [r]4008
[race] * 3 50 -200 200 none none tube*20*6000*300*[r]009 [r]4009
What does this mean? well, I've gotten a lot of questions lately on this very subject so I'm going to dive into some rather painful details. First as you'll note from the [r] and [race] that this is from a .sec file not a .dat file. The [race] will be replaced with the cosmetic race identifier string (ie: drengin, terran, etc..). The [r] will be replaced with the race number. why have both unique strings and unique numbers? Easy. the [r]'s (here and elsewhere) serve to guarantee that module identifiers are unique between races. The far right column is for module identifiers, and the game will have some serious problems if two modules have the same identifier.
So what do all these numbers mean?
|field name||sample value||description|
|class||[race]||string identifier that tells the server which races can buy this item in starbases as well as which colonies will produce this item. this is also used to color this item throughout the game as well as select the proper debris image.|
|name||*||the asterisk indicates that the game should come up with a string describing the module in question. it's the *'s in the module section that can turn shield1 into plasmashield (for instance). in the case of tube modules, this field has no effect (since the description string for tubes is based on the ordinance). but more on that later.|
|vol||3||volumn. every ship has a limited amount of space available.|
|mass||50||mass can be confusing. first note that mass is entirely independant of volumn. next, while each ship type can hold only a particular volumn of modules the amount of mass a ship can lug around is based on your engine. when the game says "your engine cannot handle the upgrade" (whatever, i can't remember the exact message but you know what i mean) that's the games way of telling you that if you added that item your engine would not be strong enough to move the resulting weight of ship.|
|power||-200||the only strange thing here is the negative sign. whatever value is in the 'power' entry is added to the ships power supply. so when you have a -200 power item in your inventory (regardless of whether or not you're using it, this is the power required to maintain the module) your 'top' powerlevel is decreased by 200. that's a little confusing, here's another example. suppose your power plant provides 800 units of power. adding this -200 item reduces the amount of available power to 600. whatever 'excess' power your ship has goes straight into charging up your guns and replenishing your shields so be careful not to overindulge on high-power items.|
|damage||200||there is a two-edged sword in damage. but first an explanation. damage is the number of points of harm that an item can suffer before failing. we've all run into the situation where our boost and engines are knocked out and we're drifting in space. the trick is, the higher the damage number the more hits a component can take before it fails. however, items with high damage numbers (like power units) take a long time to repair without starbase assistance.|
|activate sound||torpedo1||simple enough, when this module is turned on the indicated sound is played.|
|deactiate sound||none||obviously this is the sound used when the module is turned off.|
|function*parms||tube*60*4000*800*[r]001||this is the nastiest part of the module section. the
function*params field determine first what kind of module we're talking about
and second what sorts of parameters are associated with that module. there
are a lot of different module types. it's rather difficult to determine
exactly what each of the parameters do. here they are,
along with what little i know for sure about them: