Strat Wars - Scenario Editing

This will help you go through a scenario file step-by-step. Any scenario file you have downloaded is already heavily commented and can probably be used right away without reading this document. This document is provided to clear up issues that might be unclear and to provide a better understanding of how a scenario file works. It is highly recommended that you edit a duplicated copy of an existing scenario file or copy and paste (or download) the template at the bottom of this page to create your own scenarios. Note that scenario files have the .scn extension. Any reference to text in the scenario file will be shown as sample code for the remainder of this document. It would be helpful to open a scenario file with a text editor to follow along.

First, we'll briefly go over what a scenario file does. A scenario file tells the Strat Wars screensaver what ships to make into "squadrons", what ships other ships will attack and what other objects will be included in the screensaver, such as asteroids, space stations, planets and ships that should have a fixed number regardless of how many ships is set in the screensaver's preferences.

The file starts by defining how many groups of ships there will be. These ships will be affected by the number of ships option in the screensaver preferences. You may have one group or more, although the screensaver resets after one side has beaten the other and it will take longer to reset if there isn't at least two groups. Each group is defined with the quantity of ships, relationship to other groups (friendly or not), starting positions and other things we'll get to below. Having 3 or more groups is entirely possible and there is nothing that says you may only have two sides in the conflict.

Underneath the main ship definition is where extensions go. Extensions define all other things that do not rely on the number of ships slider in the screensaver preferences. These things can be asteroids and other randomly placed objects, a fixed number ship (you don't want more than one Slave I flying around), nebulae and other far-off objects, and objects that need lighting from the sun such as a planet or space station.

That's all there is to a scenario file! It's really quite easy once you understand it's structure. Again, the scenario files included with Strat Wars are heavily commented and it is best to modify copies of existing scenarios to make sure every thing is right. Any line that begins with // is a comment and is not considered part of the definition. Let's jump on in!

The first line you will see is the scenario file header. This must start with AStratWarsScenarioFile 2 followed by the number of extensions and additional ships. For example, a scenario file without any extensions would be AStratWarsScenarioFile 2 0. A scenario file with a group of asteroids, a planet, a space station, two frigates and a unique ship would be AStratWarsScenarioFile 2 5 4 . It is important to note here that "additional ships" means any object file with an extension .shp. The asteroids, space station, frigates and the unique ship all uses models stored in a .shp file. The two frigates count as one ship file. However, if you use include another extension that uses a .shp file already included (like another extension of frigates), you still count that .shp file and any other .shp files of the same type that occur in different extensions.

Underneath this line is the number of ship types you will be defining. The number must be 1 or greater. A number of 1 (or only one "side" to the groups like X-wings and Y-wings only) will result in a simple space patrol, without conflict. This number has nothing to do with how many factions there are. For example, a scenario with X-wings and Y-wings ganging up on Tie-Fighters would have it's number set to 3, even though there are only two factions here. Assigning who attacks who comes a little further down. Note that for the remainder of the main group definition you will be defining each attribute for all of the groups at the same time, with each number being seperated by a space.

Since the screensaver determines how many ships there are by the setting in the preferences, we need to tell it what percentage should be group A, group B, group C, etc. The sum of these numbers must add up to one. The leading 0 is optional, but suggested for clarity and ease of reading. If this line reads 0.50 0.20 0.30, then group A will make up half of the ships, group B 20% and group C 30%. Since each ship has different qualities, you may have to tweak these percentages several times to get the distribution right for your liking.

The next line sets the initial starting formation of each group. For now, there is only one option available: 1 which tells the screensaver to deploy the ships in a gaggle formation. In future releases there will be more formations to choose.

The next two attributes can be somewhat confusing. The first set is the orientation of the group, i.e. where it's looking, and the second is position, i.e. where in space it is. We'll start with position first even though it's the latter of the two attributes because it's easier to think about orientation after you know where each ship group will be in space.

The position array is handled in x, y, z coordinates with 0 0 0 being the center of space in big picture mode and the point the camera pans around. For those you you unfamiliar with 3D space, here's a trick to help you remember: if you hold your hand in the position shown below with your thumb pointing at you, your third finger points in the +X direction (width), your index finger points in the +Y (height) and your thumb points in the +Z (depth). Just as with the grids from grade school, once the axis passes the origin (where all of the axes meet) the values change to negative. Below right is a diagram of the axes of 3D space with labels. The colors of the axes might be different depending on what 3D program you're used to. We're using these colors because they are the same colors the Strat Wars Ship Editor uses.

So, now that you know how 3D space works, you should be able to figure out where in space you want to place each group of ships. Most people tend to put one group on the negative X side and it's (literally) opposing group on the positive X side so that the groups must fly towards each other, giving a feeling of engagement. The numbers are expressed in "distance units", so -800 200 -100 would place a ship group 800 units to the left of center (-X), 200 units above center (+Y), and 100 units behind center (-Z). It's it entirely possible to have ship placements very close to each other for an immediate, "thrust into the thick of battle" feel. Each set of XYZ coordinates should be on its own line, one after the other for each ship group:

-800 200 -100 (Group A)
800 100 -100 (Group B)
900 0 -100 (Group C)

Now that we know where the ship groups will be we can figure out orientation (the set just above position). Orientation is handled in yaw, pitch and roll which are all expressed in degrees (a complete circle is 360 degrees). It might be easier to think of it as in this diagram:

A ship group placed in -X, such as -1000 0 0, should have an orientation of 0 0 0 to point towards the center of space while a ship group placed in the +X, such as 1000 0 0, should have an orientation of 180 0 0. Note that the positions of the X coodinate value in the position array and the yaw value in the orientation array are the same (first value). If your ship groups were placed according to the Y coordinate, you would use the second values (the Y and pitch) to orient the ships towards the center. Roll is a little different. If you place your ships according to the Z coordinate, you should use the yaw value to orient the ships towards the center as both the X and Z axes lie on the same plane. Using this guideline, here are examples for ships placed opposite each other on each axis:

-100 0 0 (position) 0 0 0 (orientation) (X axis)
100 0 0 (position) 180 0 0 (orientation)

0 -100 0 (position) 0 0 0 (orientation) (Y axis)
0 100 0 (position) 0 180 0 (orientation)

0 0 -100 (position) 90 0 0 (orientation) (Z axis)
0 0 100 (position) 270 0 0 (orientation)

Since the screensavers uses the X axis for it's Big Picture camera, it is advisable to set groups up according to the X axis. (This makes orientation easy too.) You shouldn't worry if the ships are upside down or rolled on their sides as long as their front points in the general direction of the center. The ships will pitch and roll anyways as they approach their targets. The initial facing points the ships in the direction you want them to be flying at the start of the screensaver. (Alternatively, you could have both groups of ships flying in the same direction, one behind the other, for an ambush scenario in which the group in front would have to turn around to respond to their aggressors.) So, the orientation array for 3 groups of ships, one placed according to -X and the other two according to +X would look like this:

0 0 0 (Group A)
180 0 0 (Group B)
180 0 0 (Group C)

The jitter array contains a random element to the starting position that helps to distribute the ships in a ship group. This adds a nice randomness to the starts, making the screensaver more interesting. The jitter array defines how far away from the starting point ships may be randomly placed. Due to problems with excessive startup collisions at low jitter array numbers, this option is being phased out. It is advisable to use the default values of 10 40 40 for all groups. The jitter array for a 3 groups of ships could look like this:

10 40 40 (Group A)
10 40 40 (Group B)
10 40 40 (Group C)

Currently, there are no flag settings and this value should always be set to 0. In the future there will most likely be flags that would set scenario options, changing dynamics of the scenario, such as allowing groups to swap positions or possibly different rules altogether.

This is where you tell the screensaver what alliance each ship group belongs to. Ship groups with the same IFF number are allies, while ship groups that differ in IFF number are enemies. Supposing you created a scenario with X-wings, Y-wings, Tie-fighters and Slave I. If you wanted Slave I to act on the part of the Empire, you would list your IFF codes thus: 1 1 2 2, where the X-wings and Y-wings are on the same team (1) and the Tie-fighters and Slave I were on another (2). But suppose the Empire screwed Boba Fett over and he's now mad at both the Rebels and the Empire. Then the list would be: 1 1 2 3. The X-wings and Y-wings are still on the same team, but now Slave I is its own team and will fire on both the Rebels and the Empire. This also means that the Tie-fighters will also fire on Slave I too. If the IFF of another ship is not the same as your own, it is an enemy.

An IFF code of 0 is a neutral ship. Ships will not attack a ship with an IFF of 0. Note that a ship with an IFF of 0 and weapons can quite possibly fire on other ships. Think of this as the "angry Swiss ship". Normally, the 0 IFF code is reserved for truly neutral, unarmed objects such as asteroids.

Each ship group has a minimum and maximum morale value. The initial pilot's morale is affected by fallen comrades, destoyed enemies and other factors, such as being outnumbered locally, as well as globally. How brave the pilot acts depends on his current morale value. A value of 0 is sheer panic. Obviously, a bunch of ships freaking out would not make a very interesting screensaver, so the morale range provides us a way of setting limits to how high and low the morale can get. Typical values are 0.45 for the minimum and 1 for the maximum. If you want a braver set of pilots, you could set the minimum to 0.8 and the maximum to 1.5. Note that there is no limit to how great the maximum value can be. Pilot morale also plays a role in deciding when to break off an attack in cases when two ships of the same group are getting close. The pilot with the lesser morale will be more likely to change its direction than a pilot with a greater morale who will be more likely to play chicken. A pilot with a minimum of 4 and a maximum of 5 is mostly likely going to be a bezerker, blindly going after the enemy and most likely endangering his comrades in the process. The pilot morale range is defined in two sets - first the minimums and then the maximums. So morale for 3 groups would look like this:

0.45 0.55 0.45 (Group A, B and C's minumums)
1 1.2 1 (maximums)

I'm sure you've probably been wondering, "Well. All this is fine and dandy, but where do I tell it I want X-wings?!?" The last set of variables in the file is the ship names of each of the groups. Each ship name is the name of the .shp file. Additionally there are two ship types built in to the screensaver: X-wings and Tie-fighters. To use one of these ships, use the special designators, .DefShip1 for Tie-fighters and .DefShip2 for X-wings. So, in keeping with our 3 group example, the ship definitions of Group A being X-wings, Group B being Y-wings and Group C being Tie-fighters would look like this:

.DefShip2
Y.shp
.DefShip1

If you are going to use the default ships (X-wings and Tie-fighters), remember to put the period before the ship name.

That's it for the main portion of the scenario file. If you don't have any extensions, then you're done! Save the file as MyScenario.scn (or whatever name you want with an .scn extension) and try it out! If you don't have a copy of an already made scenario for a template, you can reference a complete sample scenario file at the end of this document.

The only things that can come after the main section of the scenario are the extensions. In each case, you will tell the screensaver what kind of extension it is and what parameters it takes. You can repeat this as many times as you want, keeping in mind that more stuff always means slower screensaver and that extensions are in not affected by screensaver preferences like the number of ships.

If you're wondering why an extension doesn't appear, a common error is to forget to tell the screensaver an extension exists. Remember, the header for the scenario is AStratWarsScenarioFile 2 [number of extensions] [number of ship types defined in extensions]. So a header of AStratWarsScenarioFile 2 0 will not load any extensions, even if there are extensions after the main section (the screensaver simply doesn't know they're there). If your header is AStratWarsScenarioFile 2 1 0 and you have two extensions, the second extension will not load. If there is an error processing an extension, such as bad formatting, the screensaver will not process that extension and all that follow it. Lastly, if your header does not specify the correct number of additional .shp files that the extensions load, the screensaver may likely crash.

For example, we have five extensions which are: the Slave I, a nebula, a planet, three Star Destroyers and an asteroid field. As we'll see later, the three Star Destroyers and the asteroid field, even though there are multiple objects created, are each one extension for total of five extensions. The Slave I and the Star Destoyers are obviously .shp files, but the asteroids are also too, using rock.shp to create inert 3D objects designed like ships. Therefore the third number in our header should be 3 - we are loading three additional .shp files with our extensions and our header will look like this: AStratWarsScenarioFile 2 5 3.

Again, if your screensaver bombs right after you have selected your scenario, chances are good that the .shp count in the header is wrong. If extensions don't show up in the screensaver, chances are your extension count in the header is wrong.

Great. Now let's look at how to make extensions!

Each extension must start with a descriptor number which tells the screensaver what kind of extension it is. There are currently four types of extensions:

1 = Environmental object, randomly distributed such as asteroids or a mine field (objects that may spin, but do not fly)
2 = Fixed number object (any object or ship where there is X number of them, regardless of the number of ships preference)
3 = Environmental distant object (something nearer than stars, but still far away such as a nebula)
4 = Environmental lit object, such as a planet, that the sun illuminates (this is a texture mapped to a sphere)

Following the descriptor number are settings that depend on what kind of extension we are defining, so let's look at each in turn.

The format for an enviromental object group extension is:

Extension Descriptor Number (1 in this case)
Position of the center of the group of objects in X, Y, Z coordinates
Positive extents of the object in X, Y, Z values (how far in the positive direction of each axis the objects can be distributed)
Negative extents of the object in X, Y, Z values (how far in the negative direction of each axis the objects can be distributed)
Density given as a percentage between 0 and 100 (what percentage objects should exist in the defined area)
IFF for the object (usually 0 for neutral)
Flags (must be 0)
Pilot morale range minimum
Pilot morale range maximum
File for the object

The position array is just like the position array in the main section. The extents arrays are slightly different, utilizing both a positive and negative array for the purpose of being able to create assymetrical boundaries. Both the positive and negative arrays are expressed in positive values. A positive array of 100 50 100 will add those values to the center position to create the positive boundaries, while a negative array of 200 10 300 will subtract those values to create the negative boundaries. If these arrays were applied to a center position of 0 0 0, the resulting boundaries would be -200 to 100 on the X axis, -10 to 50 on the Y axis and -300 to 100 on the Z axis. The density is what percentage of the space just defined is composed of our objects. It's a good idea to start which an extremely small percentage (especially if your defined area is large) like 0.1 or 0.5. Keep in mind that if this number is too big, it could take a very long time to generate all of the objects and that, when thinking about percentages like this, your initial guess is almost always too big. It's much better to guess smaller and increase the percentage later than guess larger and wait and wait for the screensaver to finish creating the objects or running out of memory.

IFF of objects like these are most commonly 0, due to the fact that any ships defined this way would be better off in the main section. However, sometimes you might want to create targets that one group of ships seek to destroy while others try to defend, in which case set the IFF to the same number as the defending group's IFF. The flags variable, just as in the main section, is not implemented yet and should be set to 0. There is talk of adding flags to this type of extension in the future to enable different group behaviors such as mines in a minefield moving towards ships that get too close.

Pilot morale is included for the possibility of actually including ships. Such a situation could be a wall of ships blockading two groups. Unless you plan on having a group of ships in your environmental object, a setting of 0.45 for a minimum and 1 for a maximum is fine. Lastly, the name of the ship file is listed. So, as an example, here's the definition of an asteroid field environmental object group:

1 (extension type)
-200 -170 -200 (position of the center of the group)
335 150 174 (positive range from center of the group)
200 100 200 (negative range from center of the group)
0.5 (density given as a percentage between 0 and 100)
0 (IFF of the object)
0 (Flags)
0.45 (Pilot morale minimum)
1 (Pilot morale maximum)
rock.shp (file for the object)

Fixed number object extensions are used for creating a specific number of objects, regardless of the number of ships setting. Uses include creating one spacestation, one unique ship (such as Slave I) or creating a specific number of ships or objects, such as three Star Destroyers.

The format for the fixed number object extension is:

Extension Descriptor Number (1 in this case)
Number of objects you want created
Formation Type (currently only choice is 1)
Orientation Array (direction the object or objects are pointing)
Position Array (where the object or objects are in space)
Jitter Array (if there is more than one object, how they are spaced apart)
Flags (must be 0)
IFF codes
Pilot morale range minimum
Pilot morale range maximum
File for the object

You've probably noticed that this format looks remarkably like the format for the main section of the scenario file. It is. This is the same way to define a ship group, with the exception that you can specify explicitly how many objects or ships you want. An example for Slave I might look like this:

2 (extension type)
1 (number of ships)
1 (formation type - should always be 1)
0 0 0 (orientation array)
-300 200 0 (position array)
10 40 40 (jitter array)
0 (flags)
1 (IFF of the object)
0.95 (Pilot morale minimum)
1 (Pilot morale maximum)
slaveI.shp (file for the object)

Environmental distant objects are typically used for nebulae and galaxies, existing in between the Strat Wars battles and the stars. They simply help to give space more of a space feel, making it more interesting than just stars and a sun. For now, the images distort slightly for randomization. In the future static images (such as a picture of the Death Star in the distance) may be implemented.

The format for an environmental distant object extension is:

Extension Descriptor Number (3 in this case)
File name of the texture

Textures must be in .jpg format. An example would be:

3 (extension type)
nebulaTexture.jpg (texture name)

Environmental lit object extensions are typically used for planets. They are a texture mapped to a sphere that the sun can illuminate, giving the appearance of a real object in space. For now, only textured spheres are available. In the future, other models (such as a distant dynamically lit spacestation) may be possible.

The format for an environmental lit object extension is:

Extension Descriptor Number (4 in this case)
File name of the texture

Textures must be in .jpg format and are mercator map projections. An example would be:

4 (extension type)
planetTexture.jpg (texture name)

The following is provided for you to cut and paste into a text file as a scenario template. It includes two groups of ships (although more may be easily added) and one of each of the extensions. If you don't need a particular extension, you can delete that part of the file or, if you need two extensions of the same type, you can copy and paste that extension. Remember to update the header file to show the correct number of extensions and additional .shp objects. Lines that begin with // are comments are are ignored by the screensaver. They are used merely to help in editing the scenario file. This template can also be downloaded as a default .scn file (editable with a text editor) here.

// ***** BEGIN SCENARIO FILE *****
AStratWarsScenarioFile 2 4 2
// The first line is the fileheader id, the scenario file revision, number of extensions, and number of extra .shp files
// The current file revision is 2. You shouldn't alter the file revision number.
//
// Note that this scenario will not work without the necessary files requested by the extensions.
// The scenario will will without the extensions (and a header of AStratWarsScenarioFile 2 0).
// The extensions are provided as a guide to build your own.
//
// ***** START MAIN SCENARIO SECTION *****
//
// Number of Ship Groups
2
//
// Ship Probability
// If there are two groups and this array is 0.6, 0.4 then 60% of the ships will be in group 1
// and 40% will be in group 2. The probabilities must sum to 1.0.
0.50 0.50
//
// Formation Type
// For now, the only formation code that will be implimented is 1 which is gaggle.
1 1
//
// Orientation Array
// Which way the ship is facing. The orientations are three angles: yaw, pitch, and roll.
0 0 0
180 0 0
//
// Position Array
// The next information is the starting position of each group in X, Y, Z coordinates.
// 0 0 0 is the center of the space and the middle of the screen when in big picture mode.
-200 100 0
200 100 0
//
// Jitter Array
// Defines an imaginary box in which ships of a group are randomly placed. X, Y, Z coordinates
// are both added and subtracted to the position array to define the boundaries.
10 40 40
10 40 40
//
// Flags
// Not implemented yet. Should always be 0.
0
//
// IFF (Alliance) Codes
// Only ships with identical IFF ID's will consider each other as friends.
1 2
//
// Pilot Morale Range
// These set the limits of morale. 0 is fleeing in panic, greater than 1 is really brave.
// Minimum array
0.45 0.45
//
// Maximum Array
1 1
//
// Ships
// Assignment of ships to the groups
// If any of the files fail to load the scenario will be reset to the default one. If you want to have
// two groups of the same kind of ship, you will have to list the same .shp file twice, once for
// each group. To use the default ships use the filenames .DefShip1 (Tie-fighters) and .DefShip2
// (X-wings).
.DefShip1
.DefShip2
//
// ***** END MAIN SCENARIO SECTION *****
//
// ***** BEGIN EXTENSIONS SECTION *****
//
// Extension descriptor numbers
// 1= environmental object group, randomly distributed (ie asteroid/mine field)
// 2= fixed number object
// 3= environmental distant object. Something nearer then the stars, but still far (ie a nebula)
// 4= enviromental lit object, so in the general area of the sun (ie a planet) and mapped to a sphere
//
// ***** BEGIN EXTENSION TYPE 1 - ENVIRONMENTAL OBJECT GROUP *****
//
// Extension Descriptor Number
// Environmental Object Group ***** ADD 1 TO SHP COUNT *****
1
//
// Position of the Center of the Object Group
-200 -170 -200
//
// Extents of the Object Region
// Positive extents get added to the center, while negative extents get subtracted to define a region
// in which the objects can randomly be placed. These settings will make a box 600 x 300 x 350.
//
// Positive Extents of the Object Group
300 150 175
//
// Negative Extents of the Object Group
300 150 175
//
// Density of Objects in Region (Percentage between 0 and 100)
0.5
//
// IFF for the Objects (Usually 0 for neutral)
0
// Flags
// Currently unimplemented. Should be 0.
0
//
// Pilot Morale Range
// These set the limits of morale. 0 is fleeing in panic, greater than 1 is really brave.
// 0.45 and 1 is sufficient for non-flying objects such as asteroids.
//
// Minimum
0.45
//
// Maximum
1
//
// Ship File to Use for the Objects
rock.shp
//
// ***** END EXTENSION TYPE 1 - ENVIRONMENTAL OBJECT GROUP *****
//
// ***** BEGIN EXTENSION TYPE 2 - FIXED NUMBER OBJECT *****
//
// Extension Descriptor Number
// Fixed Number Object ***** ADD 1 TO SHP COUNT *****
2
//
// Number of Ships/Objects
1
//
// Formation Type
// For now, the only formation code that will be implimented is 1 which is gaggle.
1
//
// Orientation Array
// Which way the ship is facing. The orientations are three angles: yaw, pitch, and roll.
0 0 0
//
// Position Array
// The next information is the starting position of each group in X, Y, Z coordinates.
// 0 0 0 is the center of the space and the middle of the screen when in big picture mode.
0 -60 -50
//
// Jitter Array
// Defines an imaginary box in which ships of a group are randomly placed. X, Y, Z coordinates
// are both added and subtracted to the position array to define the boundaries.
10 40 40
//
// Flags
// Not implemented yet. Should always be 0.
0
//
// IFF (Alliance) Codes
// Only ships with identical IFF ID's will consider each other as friends.
1
//
// Pilot Morale Range
// These set the limits of morale. 0 is fleeing in panic, greater than 1 is really brave.
//
// Minimum
0.45
//
// Maximum
1
//
// Ship
// Assignment of ship file.
// To use the default ships use the filenames .DefShip1 (Tie-fighters) and .DefShip2 (X-wings).
SpaceStation.shp
//
// ***** END EXTENSION TYPE 2 - FIXED NUMBER OBJECT *****
//
// ***** BEGIN EXTENSION TYPE 3 - ENVIRONMENTAL DISTANT OBJECT *****
//
// Extension Descriptor Number
// Environmental Distant Object
3
//
// Texture File Name
otherNebula.jpg
//
// ***** END EXTENSION TYPE 3 - ENVIRONMENTAL DISTANT OBJECT *****
//
// ***** BEGIN EXTENSION TYPE 4 - ENVIRONMENTAL LIT OBJECT *****
//
// Extesnion Descriptor Number
// Environmental Lit Object
4
// Texture File Name
planetTexture.jpg
//
// ***** END EXTENSION TYPE 4 - ENVIRONMENTAL LIT OBJECT *****
// ***** END SCENARIO FILE *****

Back to Strat Wars Home Page