Targetware: Scenario Development

Scenario File Reference

This document is intended to be a reference to the .scn scenario file format.

1. Scenario Section
2. Weather Section
3. Team Section
4. Team Base Section
5. Team Victory Section
6. Team Mission Section
7. Team Unit Section
8. Team Target Section

Scenario Section

[Scenario]
Required section header

name = [text]
Name of the scenario as it will appear on the server list and in the User Interface.

terrain = [terrain file name, full path]
Terrain filename and path.  For most Target Korea scenarios, the terrain /tk/terrain/terrain_v11/korea.ter.  For other Target Projects, the terrain will be in the /terrain/ folder within each project folder, e.g., Target Rabaul terrain will be in /tr/terrain/.

splash = [graphics file name, full path]
Filename and path of a graphics file (JPG or TGA) that will be displayed over the entire screen during the scenario load process. Should be 128x128, 256x256, 512x512, or 1024x1024. Optional

info = [text file name, full path]
Filename and path of a text file that describes the scenario. This information will be displayed when a player chooses a scenario for offline play, and also online, when players select "Scenario Briefing" from the menu. Optional

image = [graphics file name, full path]
Filename and path of a graphics file (JPG or TGA) that you want displayed in a window on the screen when the player selects Scenario Briefing from the In-Game menu, then "Visual Briefing". Often a map of the scenario area. Should be 64x64, 128x128, 256x256, or 512x512. Optional

num_teams = [number]
The number of teams that will participate in the scenario.

viewpoint = [X km, Y km, Altitude km]
Positions the view when the scenario loads for those who haven't picked a team.  Basically, this is what people see when the scenario first loads.

heading = [degrees]
This is the direction the player will be looking when using the above viewpoint.

time = [number]
Determines the time of day. Time is given in 24 hour style (hhmm): "0830" = 8:30 AM, "1830" = 6:30 PM. This setting greatly affects lighting conditions, so use it with care. Defaults to 12 noon.

time_var = [number]
Allows for variation on the time of day specified above. The number is in the same "hhmm" format: "0130" = 1 hour, 30 minutes; "1200" = 12 hours. For example, if the time of day was set at 1200 (noon), and time_var was set to "0300", each time the scenario ran, the game engine would assign it a time between 9:00 AM and 3:00 PM. Defaults to 0 (no time variation).

time_limit = [minutes]
Duration of the scenario. Can also be 0 to have no time limit.

victory_points = [number]
If a team reaches this number of victory points they win and the scenario is over. This can also be 0, meaning victory point totals are still used to determine the winner, but there is no "hard limit" at which one side wins immediately.

minimum_vp = [number]
If a timed scenario, the minimum number of Victory Points that one side must score before the scenario will come to an end. Example: In a scenario with victory_points = 0, time_limit = 30, and minimum_vp = 500, the scenario will not end once 30 minutes have gone by, unless at least one of the teams has amassed 500 victory points; it will continue until one side reaches 500 points.

Weather Section

[Weather]
Required section header

min_cloud_layers = [number]
Minimum number of cloud layers.

max_cloud_layers = [number]
Maximum number of cloud layers.

min_alt = [meters]
Minimum cloud layer altitude.

max_alt = [meters]
Maximum cloud layer altitude.

cover = [number]
A rough percentage of cloud cover to be used as a base, 0 = 0%, 1 = 100%.

texture = [texture filename]
If this line is left out, or left blank, clouds will be drawn with a generic white color. Specifying a texture here allows you to closer approximate the appearance of actual cloud types.

detail = [detail texture filename]
File name and filepath for a texture file that will be placed on the main cloud texture as a detail texture.

detail_scale = [factor]
The number of times you want the detail texture to repeat on a single square patch of cloud texture.

temperature = [degrees Celsius]
Temperature at Sea Level for this scenario. Default SL temperature is 15.04 deg Celsius.

pressure = [pressure in kiloPascals (kPa)]
The air pressure at Sea Level for this scenario. The kPa for a "standard day" (the conditions under which aircraft performance are always evaluated) is 101.325 kPa.

Team Section

[Team 1]
Required section header.  There must be an entry for each team and the number of teams must match num_teams above.

name = [text]
Name of the Team as it will appear in the UI.

info = [text file name, full path]
Filename and path of a text file that provides a general briefing for the team's activity in the current scenario. This information will be displayed when a player selects "Team Briefing" from the menu. Optional

image = [graphics file name, full path]
Filename and path of a graphics file (JPG or TGA) that you want displayed in a window on the screen when the player selects Team Briefing from the In-Game menu, then "Visual Briefing". Could be a map showing the location of the team's missions in the scenario, etc. Should be 64x64, 128x128, 256x256, or 512x512. Optional

viewpoint = [X km, Y km, Z km]

heading = [degrees]

These work like viewpoint and heading from the [Scenario] section above, only it is the viewpoint you have when you've selected this team, but have not yet selected a unit.

players = [percentage]
The percentage of players currently online who are allowed to join this team.  0 = 0%, 1 = 100%.  Note that the players percentages for all the teams do not have to add up to 1.0  Example: 0.6 means a maximum of 60% of the people currently online can be on this team.

shared_kill = [0/1/2]
max_shared = [number]
This determines how shared kills and assists are scored. If 0, a kill credit is given to the damage leader, no one else receives any credit. If 1, kill credit to damage leader, up to (max_shared-1) assists given to other contributors. If 2, the kill credit is divided amongst up to max_shared people. So if shared_kill is 2 and max_shared is 3, and 3 people score hits, each would receive 1/3 of a kill credit. If shared_kill is 1, and max_shared is 3, then the person who causes the most damage would get a kill credit, and the next 2 contributors would each get an assist credit. shared_kill defaults to 0, max_shared defaults to 3.

initial_vp = [number]
Starting victory points. Because some scenarios are the triggered by the consequence of previous ones (See [Team Victory] section, next_scenario setting), it is possible to accumulate victory points over the course of multiple scenarios. This setting can also be used to give one team a "head start", perhaps when facing an overwhelming numerical disadvantage in aircraft.

num_victory = [number]
The number of different victory levels defined for this team.

num_bases = [number]
The number of landing areas available to this team in this scenario. Each one must be defined with a [Team x Base y] section. Players from this team who land within the confines of one of the defined friendly bases will be counted as having landed safely, with no points being awarded to the enemy.

num_missions = [number]
The total number of Missions available to this Team, each to be described in  separate Team x Mission y sections. To be valid, each team must have at least 1 mission.

Team Bases Section

[Team 1 Base #]
Required section header.

name = [text]
The name of the airfield/base. When a friendly pilot lands at this location, they will see "Welcome to [name]" in the text buffer.

location = [X km, Y km]
Location on the terrain where the base is to be defined. Is NOT relative to the mission location, it is measured from the SW corner of the terrain map.

radius = [km]
A defined radius around the location specified above, within which friendly planes that land will be given a "safe landing". If planes land outside this radius, they will be counted as having ditched, and points will be awarded to the enemy.

Team Victory Conditions

[Team 1 Victory #]
Required section header.  Multiple victories can be specified, each will need all of the parameters in the section (margin, message, and next_scenario).  The total number of these is num_victory from above.

margin = [number]
The teams total victory points must be at least margin times the other teams total victory points to acheive this level of victory. For example: 1.5 means if the enemy team has 6 vp, this team must have at least 9 vp (1.5 * 6) for this victory level.  If you win the victory level with the highest margin you've acheived is the one you go with.

message = [text]
Message displayed in the UI when Team 1 wins.  For example: "The UN has won."

next_scenario = [scenario_filename.scn]
The scenario that will begin next as a consequence of Team 1 Victory Conditions in the Team Unit Settings.  You can use the next_scenario setting to create a branching network of scenarios.  This creates a Campaign.

Mission Section

[Team 1 Mission #]

name = [text]
Name of the Mission as it will appear in the list of missions for a scenario.

player_threshold = [number]
The minimum number of players that need to join this mission, before the next mission becomes available for selection. If set to 0, the next mission will be selectable as soon as this mission is. On scenarios with multiple missions, this setting can be used to keep a limited player pool from being spread too thin.

player_cap = [number]
The maximum number of players that can join this mission before it closes. Must be higher than the threshold number, unless it's zero, in which case there is no limit to the number of players that can join the mission.

info = [text file name, full path]
Filename and path of a text file that gives an overview of the mission. This information will be displayed when a player selects "Mission Briefing" from the menu. Optional

image = [graphics file name, full path]
Filename and path of a graphics file (JPG or TGA) that you want displayed in a window on the screen when the player selects Mission Briefing from the In-Game menu, then "Visual Briefing". Could be a map with objectives circled, could be a checklist of mission objectives, etc. Should be 64x64, 128x128, 256x256, or 512x512. Optional

location = [X km, Y km]
This defines the location of the mission within the designated terrain.  The values are X, Y coordinates in kilometers. These coordinates are the distance from the lower left corner of the terrain (X increases to the East, Y increases to the North).

location_var = [X km, Y km]
These values can be used to add randomness to the mission location. Example:  50, 50 means that each time the scenario runs, the actual mission location will be chosen by picking a random location in a 50 km by 50 km box around the 'location' specified above. The following diagram shows how the mission location settings are used in the Yalu Duel scenario.  The base settings are defined in the Team Unit section.

viewpoint = [X km, Y km, Z km]

heading = [degrees]

These work like viewpoint and heading from the [Scenario] section above, only it is the viewpoint you have when you've selected this mission, but have not yet selected a unit.

disengage dist = [kilometers]
The distance from the mission start point (defined at location) at which a player will be ruled as having 'disengaged.' A disengaged player has left the combat area and is counted as having safely returned to base (unless he used too much fuel, and is judged to have failed to return to base). Having disengaged, a player can select a new airplane, and rejoin the fight.  If this setting is set to 0, players must crash, bail, ditch, or land before they can get a new airplane.  The mission area is defined by a circle of disengage_dist radius around the mission start point.

enemy_dist = [kilometers]
This setting only comes into play if you are already disengage_dist kilometers from the mission start point, but there are enemy planes in your immediate vicinity. This setting prevents players from disengaging from a fight unless they are a safe distance from any enemy aircraft. Can be set to 0.

num_units = [number]
The total number of aircraft Units on the Team, each to be described in separate Unit sections.

num_targets = [number]
The total number of ground/sea Targets owned by the Team, each to be described in separate Target sections.

Unit Section

[Team 1 Mission # Unit #]
Required section header. Each mission can have one or more units.

name = [text]
Name of the unit as it will appear in the user interface.  For example: "336th > FS (F-86F-30)".  It is helpful to indicate here the type of aircraft flown by the unit.

info = [text file name, full path]
Filename and path of a text file that gives information on the unit and it's objectives. This briefing will be displayed when a player selects "Unit Briefing" from the menu. Optional

image = [graphics file name, full path]
Filename and path of a graphics file (JPG or TGA) that you want displayed in a window on the screen when the player selects Unit Briefing from the In-Game menu, then "Visual Briefing". Could be a map with targets circled, a checklist of mission objectives, etc. Should be 64x64, 128x128, 256x256, or 512x512. Optional

file = [.acm filename, fullpath]
The .acm file of the aircraft and path.  For example: "/tk/planes/f86f30.acm".

skin = [skin filename]
The starting skin for the unit.  No entry will select the default skin.

change_skin = [0/1]
If Off (0) you're stuck with whatever skin is above (which may be the default). If On (1) you can use any skin you want, including ones not on the server. Other players who have that skin will see it.  Players who do not have the skin will see the default skin.

options = [option number, option number]
The numbers of the loadout option available to the aircraft in the unit.  Loadout options are specified in the aircraft's .acm file.

change_opts = [0/1]
Ability of players to modify default loadout options of aircraft in the unit.

points = [number]
Victory points one of these units is worth to another team if destroyed.

players = [percentage]
Percentage of players on this team that can choose this unit. 0 = 0%, 1 = 100%.  Note that, like teams, these do not have to total 1.0 for all the units on a side.

start_time = [seconds]
This unit cannot start flight until this many seconds after the mission has begun.

start_cutoff = [seconds]

If 0, players will be able to launch aircraft any time after flight operations are enabled for this unit (as long as they have lives left). If a number "n" is specified, flight operations for the unit will be shut down "n" seconds after the unit's start time. For example, putting in "300" would enable new flights for only 5 minutes, thereafter, players in flight could keep flying, but new flights could not be launched.

lives = [number]
You can only fly this unit if you have died less than this number of times. Set to "0" to enable unlimited lives.

base = [X km, Y km]
Where you start from and have to return to, fuel wise. This determines how much fuel you have when you start the scenario, and how much fuel you will need to get home.  The diagram in the Mission section above displays the base locations used in the Yalu Duel scenario.

location = [X km, Y km, Altitude km]
Where members of this unit will start flying. If location_abs is set to 0, then this location will be relative to the mission location.

location_abs = [0/1]
If (1) location for the unit is relative to the lower left (SW) corner of the terrain map. If (0), then the unit location is relative to the mission location. 

location_var = [X km, Y km, Altitude km]
Just as with the mission location, a unit can have a variable starting location.

bearing_var = [0-180 degrees]
A second way of adding variation to the starting location of a unit, when combined with range_var. First, the unit's location and location_var are calculated. Next, the heading of the unit is taken, and a the bearing_var is applied to it. For example, if a unit's heading was 0 degrees (due north), and the bearing_var was 30 degrees, the unit heading would be between 330 degrees and 30 degrees. Next, the range_var is applied, which moves the unit back or forward along it's heading. For example, a range_var of 20 km would mean that a unit could be anywhere along a 40 km line along the line of flight calculated by heading and bearing_var.

range_var = [km]
See bearing_var above.

heading = [degrees]
Initial heading of the unit.

speed = [kph]
Initial speed of all aircraft in the unit. If 0, the aircraft will start with gear down and engine shut off.

formation = [formation name]
Starting formation of aircraft, e.g., "fingerfour."  Below are the available formations.  See the reference page on Targetware Formations for diagrams.

trail, abreast, echelon, vee, vic, fingerfour, box, wedge, stagger, twocolumns

spacing = [meters]
Left/right spacing for aircraft within the formation.  Can have negative values.

trail = [meters]
Forward/aft spacing for aircraft within the formation.  Can have negative values. If unspecified, will use value give for spacing above.

step = [meters]
Vertical spacing for aircraft within the formation.  Can have negative values.

wrap_position = [number]
This setting determines how many formation positions will be filled before succeeding aircraft begin to wrap, and start over from the beginning of the formation. If 0, aircraft will never wrap. If 1, all aircraft will be drawn on the same spot. If 10, the first ten aircraft will be drawn in formation, then every aircraft after that will wrap to those 10 spots, as necessary.

wave_timer = [seconds]
Waves are disabled by default. To enable waves, set this value to anything but 0. If waves are enabled, a player will only be able to launch once during each wave. If a player has already died/ditched/bailed during the current wave, he will have to wait for the next wave before flying again. Players that land safely will be able to launch again with no restrictions. The wave interval is counted from the unit start time. So if a unit has a start time of T+4, and a wave timer of 300 seconds (5 minutes), then the first wave will start at T+4, the second at T+9, the third at T+14, etc.

[Team 1 Mission # Target #]

name = [text]
Name of the target.  For example: "Cargo Truck."  If the object is destroyed or damaged, this name will be used to identify it in the damage log and text buffer.

file = [filename, fullpath]
The .acm file of the target object.  For example: "/tk/objects/vehicles/zis5.acm".

skin = [skin filename]
The starting skin for the target.  A blank entry will select the default texture.

options = [option number, option number]
The numbers of the loadout option available to the target object.  Loadout options are specified in the object's .acm file.

count = [number]
A target can specify any number of copies of the original object, all of which are valid targets. Location of objects 2 and higher is determined by the formation and spacing settings below.

points = [number]
The number of victory points given to the enemy team each time one of these targets is destroyed. If the target has more than one object (count is greater than 1), then this many points will be awarded for each object destroyed, and not spread out among the objects. For example, a tank target with a count of 4 could yield a total of 100 points if all 4 tanks are destroyed.

kill_message = [0/1]
If "0", this will prevent a target destruction credit being given in the radio buffer. If "1", when the target is destroyed, the player who did the most damage to it will be given credit for the kill in the radio buffer. If "0", no killed message will be sent, and nothing will be recorded in the server log. Defaults to "1" (ON).

location = [X km, Y km]
Where this target will be placed on the terrain. If location_abs is 1, then positioning will be relative to the lower left (SW) corner of the terrain map. If location_abs is 0, then the target's position will be relative to the mission location. Target objects are placed at ground level by default.

location_abs = [0/1]
If (1) location for the target is absolute, not relative to the mission location.

location_var = [X km, Y km]
See the unit section above for an explanation.

bearing_var = [0-180 degrees]
See the explanation of bearing_var in the Unit section above.

range_var = [km]
See the explanation of bearing_var in the Unit section above.

heading = [degrees]
Initial heading of the target.

speed = [kph]
Initial speed of the target. Buildings and stationary vehicles should have speed of 0. Note: Target AI is not yet functional in the Targetware Engine, so this setting is ignored.

formation = [formation name]
Starting formation of target objects. See Targetware Formations Reference for available formations and diagrams.

spacing = [meters]
Left/right spacing for targets within the formation.  Can have negative values.

trail = [meters]
Forward/aft spacing for targets within the formation.  Can have negative values. If unspecified, will use value give for spacing above.

step = [meters]
Vertical spacing for targets within the formation.  Can have negative values.

wrap_position = [number]
This setting determines how many formation positions will be filled before succeeding targets begin to wrap, and start over from the beginning of the formation. If 0, units will never wrap. If 1, all objects will be drawn on the same spot. If 10, the first ten objects will be drawn in formation, then every object after that will wrap to those 10 spots as necessary.

[Team 2]  

Identical in format and function to those described above.