Scenario File Format

Scenarios in Anacreon are defined in special scenario-definition files (.scn files) that can be edited in any text editor. The syntax and grammar for the scenario-definition language is described in this appendix.

In describing the scenario format, we use bold to represent text that should be entered literally in the scenario file. We use italics to represent variables that the scenario creator must replace with appropriate text. For example:

CreateNebula  type  xy1  xy2

This means that the CreateNebula command takes three parameters.

Throughout the scenario file, you may use a semi-colon (;) to start a comment in the file. Everything from the semi-colon to the end of the line is ignored. Comments may be placed anywhere in the file except inside a BEGINTEXT/ENDTEXT block.

Many commands use a number to represent tech levels, world classes, etc. Use the following tables to determine the appropriate number for the value that you require:

World Classes

World Types

Technology Levels

Technologies

Scenario Header

All scenario files start with a header that describes the basic properties of the scenario. This header has the following format:

ANACREON version
name
variation
minPlayers  maxPlayers
galaxySize
noOfPlanets
difficulty
minDuration  maxDuration
startingYear

version represents the version number that this scenario format is written in. As Anacreon has evolved over time, the scenario format has changed to support new features. The version number tells the code what kind of features this scenario file is using. This document describes the format of version 20, so that's the version number that you should use in the header. Version 20 currently only works in the Windows version of Anacreon. If you wish to create scenarios for both the Windows and DOS editions of Anacreon, you should specify version 13 in the header. This document will describe the few places where version 20 differs from version 13.

name is the human-readable name of the scenario. This name must be enclosed in double-quotes. Scenario version 13 limits the name to 32 characters. Version 20 and above have no limit.

variation this is the seed for the random number generator. Use 0 to automatically seed the random number generator. Version 20 and above ignore any number other than 0.

minPlayers and maxPlayers define the minimum and maximum number of human players for this scenario. No more than 8 human players may a scenario. If the scenario is a single-player scenario, use the number 1 for both minPlayers and maxPlayers.

galaxySize defines the size of the galaxy in sectors. For example, a value of 50 makes the galaxy a square 50 sectors high by 50 sectors wide. In scenario version 13, the size of the galaxy should not be smaller than 21 or larger than 100. Version 20 is limited only by available memory. In practice, values larger than 100 are impractical.

noOfPlanets defines the number of planets created in the scenario by CreateWorld and CreateRandomWorlds. Version 13 limits this to 200. Version 20 ignores this value.

difficulty represents the difficulty of the scenario. This value is shown to the player in the list of all scenario to give him or her an idea of how hard the scenario is to play. The variable can have one of these values:

0  Beginner
1  Intermediate
2  Advanced
3  Expert

As a rough guideline, scenarios that are played in a small galaxy with a few planets and without most of the advanced features of the game (e.g., gates, ambrosia) should be Beginner. Scenarios with some advanced concepts should be Intermediate. Scenarios that use a large map and/or most of the advanced features should be Advanced or Expert.

minDuration and maxDuration define the average length of the game in years. If the second number (maxDuration) is 0, it indicates an open-ended scenario. For example, 10 20 shows up as 10-20 years, while 50 0 shows up as 50+ years. The duration is only used to give the player a rough idea of how long the scenario will take to play.

startingYear defines the year in which the scenario starts out. For example, most introductory scenarios start at 4021.

Example:

Scenario Description

The text description for the scenario must follow the header. The text should begin with BEGINTEXT on its own line and end with ENDTEXT, again on its own line. Page breaks are denoted by NEWPAGE. For example, this is a two-page scenario description:

Line breaks are honored when displaying the text and the text is displayed in a fixed-pitch font for compatibility with the ASCII art of DOS scenarios.

Empires

One of the first things a scenario must do is create the empires (both player and non-player) that will be in the scenario. Use the CreatePlayerEmpire to create an empire for a player. The scenario must contain as many CreatePlayerEmpire commands as the maximum number of players for the scenario:

CreatePlayerEmpire
empireNumber
revolution
techLevel
technologies
modifiers

empireNumber defines the number of the empire, starting at 0. Player empires should always be created first and numbers should increase sequentially.

revolution is a measure of the restlessness of the people in the empire. The greater the value, the greater the yearly increase in revolution index for all the empire's worlds. A value of 0 is standard. An empire with a restlessness of 10 would have to be constantly dealing with revolutions. Values above 15 should not be used.

techLevel defines the tech level of the empire. Use the Technology Levels table in this document to determine the constant to use for the tech level that you want.

technologies defines the set of technologies that the empire has discovered for the given tech level. Enter the number of technologies that the empire has discovered, followed by the constant representing each of technology. Use the Technologies table to determine the appropriate constant. Only include technologies of the empire's tech level.

modifiers defines the attributes of the given empire. Enter the number of modifiers that this empire has, followed by the actual modifier. The only modifier defined is central, which specifies that the empire will collapse if its capital is conquered (without this modifier, a new capital will be chosen).

This is a commented example of how to use the CreatePlayerEmpire command

A CreatePlayerEmpire command will be ignored for an empire that is not playing. For example, imagine a scenario for 1 to 2 players. The scenario should have two CreatePlayerEmpire commands: one for empire 0 and one for empire 1. If only a single player plays the game, the first CreatePlayerEmpire command will be executed but the second command (for empire 1) will be ignored since only one person is playing.

You may create non-player empires using a similar command:

CreateNPEmpire
empireNumber
type
name
revolution
techLevel
technologies
modifiers

empireNumber is the same as for CreatePlayerEmpire. If you want to create a non-player empire to stand-in for a player who is not playing, then assign the non-player empire the same number as the player empire. For example, in a scenario for 1 to 2 players the scenario should have two CreatePlayerEmpire commands: one for empire 0 and one for empire 1. If you want to have a non-player empire take over the second empire if only a single player is playing, then add a CreateNPEmpire command for empire 1. Conversely, if you want a non-player empire to exists regardless of the number of players, make sure that the empire number is greater than that of all the player empires (in the example, that would be empire 2).

type defines the kind of non-player empire. The following types are supported:

name is the name of the empire (in double-quotes). If you specify "RndName" for a name, the name of the empire will be randomly generated by the computer.

The rest of the variables are the same as those for CreatePlayerEmpire.

Example:

Worlds

Once empires have been created, the scenario should create one or more worlds. In particular, every empire needs to have one world to be its capital. The syntax for creating a world is as follows:

CreateWorld
worldNumber
location
class
techLevel
type
empireNumber
population
efficiency
trillumReserves

LAMs
defenseSatellites
GDMs
ionCannons

fighters
hunterKillers
jumpships
jumptransports
penetrators
starships
transports

infantry
eliteInfantry
ambrosia
chemicals
metals
supplies
trillum

worldNumber is the number of the world. Version 20 requires this to be a unique number used to identify the world. The easiest way to do this is to start numbering worlds at 1 and increment with each world created. Version 13 requires that world numbers start at 1 and increment sequentially.

location is the position of the world in the galaxy. See Zones and Coordinates below more information.

class defines the class of the world. Use the World Classes table above for the appropriate constant.

techLevel defines the tech level of the world. Use the Technology Levels table above for the appropriate constant.

type defines the type of the world. Use the World Types table above for the appropriate constant.

empireNumber defines the empire that owns this world. Use the number that you specified in CreatePlayerEmpire or CreateNPEmpire. Use the number 8 for independent worlds.

population defines the initial population of the world (in tens of millions). For example, 100 means the planet will start with a population of around 1 billion people. The actual starting population will be plus or minus 15% of this value.

efficiency is the percent efficiency of the world. 100 means 100% efficiency.

trillumReserves defines the amount of trillum reserves on this world. This number is expressed as a percent of the average reserves for this class of world. In other words, a value of 100 means that the world will have the average amount of trillum reserves for the class, while a value of 200 means that the world will have twice as much trillum as the average world of this class. In version 20, the limit is 1000000. In version 13, the limit is 100.

LAMs through Trillum are variables specifying the number of units of the given ship or resource. The actual number will vary by 20% in either direction.

Example:

Zones and Coordinates

There are four ways of specifying coordinates for worlds and other objects: absolute, random, point-relative, and zone-relative.

Absolute Coordinates

Absolute coordinates start at 1,1 at the top-left corner of the galaxy, and increase to the right in the x direction, and down in the y direction. Absolute coordinates are always specified as two numbers separated by a comma. No spaces are allowed in the format.

Random Coordinates

Another way to specify a location is to use the syntax R:x,y where x and y are ranges separated by double periods. For example, R:1..5,1..5 represents a random coordinate in the box from 1,1 to 5,5. R:1..5,10 is a random coordinate from 1,10 to 5,10.

Point-Relative Coordinates

Sometimes it is useful to define a point in the galaxy and then create worlds at fixed positions from that point. The DefineXY command defines a point:

DefineXY name xy

name is the name that you want to assign to the point; xy is the point.

Now you specify locations relative to that point using the syntax name:x,y where name is the name of the point and x and y are offsets. For example, if center is a point previously defined, legal coordinates are: center:0,0 and center:-2,3. Random ranges are allowed in the offsets, thus center:1..5,10 is a legal random coordinate.

Zone-Relative Coordinates

It is also possible to define a square zone:

DefineZone zoneNumber xy1 xy2

zoneNumber is a unique number from 2 to 20 assigned to the zone and used to refer to it. xy1 is the upper-left corner of the zone and xy2 is the lower-right corner of the zone. Zone 1 is reserved to mean the entire galaxy.

Use the syntax Z:zoneNumber to specify a random location in the given zone. For example, Z:1 will return a random coordinate inside zone 1 (the entire galaxy). Again, no spaces are allowed in the syntax.

Since the DefineZone and DefineXY commands both take coordinates, it is very easy to combine the three types of coordinates to get interesting effects. For example, a point could be defined as a random coordinate within a zone, and other zones could be defined relative to it.

Make sure that any random ranges that you define are large enough to accommodate all the planets that you want to create. For example, imagine a defining a zone as: DefineZone 2 1,1 1..5,1..5. This zone will vary in size. At its smallest, it will be only one sector in size, while at its largest, it will be a box from 1,1 to 5,5. Most of the time, you will be able to create several world in the zone. But once in a while, the scenario will fail because the zone will be too small to contain the worlds that you want. Make sure that the minimum size of all your zones is large enough to contain all the worlds that you want.

Random Worlds

It would be time-consuming to create hundreds of worlds with the CreateWorld command, so most scenarios use the CreateRandomWorlds command to create dozens of random worlds with one command.

All worlds created by CreateRandomWorlds will be independent (belonging to no empire). The world classes of the worlds will be based on the table defined by the ClassTable command:

ClassTable
percentAmbrosiaClass
percentAridClass
...

The ClassTable command is followed by a number for each world class. The number specifies the percent of worlds that will be of that given class. The numbers must be specified in the same order as the World Classes table. The numbers must add up to 100.

Similarly, the tech levels of the random worlds will be defined by the TechTable command:

TechTable
percentPreTech
percentPrimitive
...

The numbers must be specified in the same order as the Technology Levels table. The numbers must add up to 100.

Once these two commands have defined the probability distribution of worlds, the scenario can create the worlds:

CreateRandomWorlds
numberOfWorlds
zone

numberOfWorlds is the number of worlds to be created by the command; zone is the zone in which the worlds will be created (see Zones and Coordinates).

Note that it is possible to change class or tech level distributions by issuing addition ClassTable or TechTable commands followed by more CreateRandomWorlds commands.

Nebulae

Use the CreateRandomNebula command to create random nebulae in the galaxy:

CreateRandomNebula
distribution
min  max

distribution is the shape of the nebula:

1 means that the nebula will be a strip about seven sectors wide and going from top to bottom at a random angle up to 45 degrees (in either direction).

2 means that the nebula will be a patch about ten sectors in size and in a random location.

min and max are the minimum and maximum number of nebulae to create.

In all cases, the nebulae will be normal nebulae (i.e., not dark or dense).

You can also use the CreateNebula command to create a nebula in a specific place:

CreateNebula
type
xy1
xy2

This command will cover the area from xy1 to xy2 with nebula of the given type. The following types are supported:

1  Normal
2  Dark Nebula
3  Dense Nebula

You may use any of the coordinate methods to specify the position of the nebula (see Zones and Coordinates.

SRMs

Use the following command to create SRM fields:

CreateSRMs
empireNumber
xy1
xy2

This command will create an SRM field from xy1 to xy2 belonging to the given empire.

Starbases

Use the following command to create starbases:

CreateStarbase
starbaseNumber
location
starbaseType
techLevel
type
empireNumber
population
efficiency

LAMs
defenseSatellites
GDMs
ionCannons

fighters
hunterKillers
jumpships
jumptransports
penetrators
starships
transports

infantry
eliteInfantry
ambrosia
chemicals
metals
supplies
trillum

starbaseNumber is the number of the starbase (used to identify the starbase later). Start with 1 and increment for each starbase created.

location is the position of the starbase (see Zones and Coordinates)

starbaseType may be one of the following:

All other characteristics are identical to those use in a CreateWorld command (although note that starbases do not have trillum reserves).

Example:

Stargates

Use the following command to create stargates:

CreateStargate
stargateNumber
location
stargateType
empireNumber

stargateNumber is the number of the stargate. Start with 1 and increment for each stargate. Note that version 13 did not support this variable. Omit the number in that case.

location is the position of the stargate (see Zones and Coordinates).

stargateType may be one of the following:

empireNumber is the empire that owns this stargate.

Descriptions

You may optionally want to add descriptive text to the worlds in your scenario. Such text adds flavor to the game and can even serve to reveal useful information to players. The description section of a scenario has the following format:

BEGINDESCRIPTION

WorldBackgroundIndex
id   criteria   pageNumber
id   criteria   pageNumber
...
EndIndex

TEXT pageNumber
text
...
ENDTEXT

TEXT pageNumber
text
...
ENDTEXT

...

ENDDESCRIPTION

The WorldBackgroundIndex section contains a line for each world, starbase, or stargate with a description.

The id identifies the object in question. The id is always a string of the format: objectType:number. The objectType is 2 for worlds, 3 for starbases, and 4 for stargates. number is the number specified in the create command for the object. For example, imagine that the scenario creates a world with CreateWorld 7 ... The identifier for that world will be: 2:7 (because 2 is the objectType for worlds and 7 is the world number).

criteria defines the conditions under which the description will be shown to the player. The criteria can be one of the following:

E:empireList specifies that the description will show up as long as the object belongs to one of the empires on empireList. empireList can be the string ALL or it can be a comma-separated list of one or more empire numbers.

O:empireList specifies that the description will show up as long as the object belongs to one of the empires on empireList and as long as it is being viewed by the owner of the world.

A:empireList specifies that the description will show up when the world is conquered by one of the empires on empireList.

pageNumber is the page number to display when the criteria condition is satisfied.

Example:

The text contained inside TEXT/ENDTEXT blocks may have object variables that are replaced when the description is shown to the user. The variables can be one of the following:

[Cid] is replaced with the coordinates of the given object.

[Nid] is replaced with the name of the given object.

For example, the text:

displays as (for example):

The stargate is at 5,10.