Anacreon

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

ConstantClass
0ambrosia
1arid
2artificial
3barren
4class J
5class K
6class L
7class M
8desert
9earth-like
10forest
11gas giant
12hostile life
13ice world
14jungle
15ocean
16paradise
17poisonous
18ruins
19underground
20volcanic

World Types

ConstantType
0agricultural
1abrosia
2base
3(reserved)
4capital
5chemical
6independent
7jumpship base
8(reserved)
9metal mine
10elite academy
11(reserved)
12raw material
13(reserved)
14starship base
15(reserved)
16transport base
17(reserved)
18university
19(reserved)
20trillum mine

Technology Levels

ConstantTech Level
0pre-tech
1primitive
2pre-atomic
3atomic
4pre-warp
5warp
6jump
7bio-tech
8starship
9pre-gate
10gate

Technologies

ConstantTechnology
1LAM
2defense satellite
3GDM
4ion cannon
5fighter
6hunter-killer
7jumpship
8jumptransport
9penetrator
10starship
11transport
12infantry
13elite infantry
14ambrosia
15chemicals
16metal
17supplies
18trillum
19SRM
20command base
21fortress
22industrial complex
23outpost
24gate
25warp link
26disrupter

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:

ANACREON 20
"The Nebula"
0     ; ignored
1 4   ; 1-4 players
40    ; 40x40 galaxy
179   ; 179 planets
3     ; expert
100 0 ; 100+ years
1791  ; starting year

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:

BEGINTEXT
This is a really cool scenario.
This first page describes the basic setting of the scenario.
NEWPAGE
This second page continues the description of the setting.
ENDTEXT

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

CreatePlayerEmpire 0
; 0 means this is the first empire

0         ; 0 means normal revolution index
8         ; starship tech level
1         ; 1 starship-level technology...
19        ; LAM technology
0         ; no modifiers

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:

TypeDescription
1Pirate: This empire will send out battle fleets to all parts of the galaxy looking for undefended transport fleets.
2Kingdom: This is a defensive empire; kingdoms will only attack if provoked.
3Aggressor: Aggressor empires will attempt to expand their dominion over independent worlds, and will occasionally attack other empires without provocation.
4Berserker: These empires command one or more command bases or fortresses and use them to attack worlds indiscriminately.
5Guardian: Guardian empires do nothing except attack enemy fleets with LAMs if they approach within range.

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:

CreateNPEmpire 2
1         ; pirate empire
"Jakarta"
0         ; revolution
8        ; starship level
0         ; no technologies
1         ; modifiers
CENTRAL   ; empire destroyed
          ; if capital conquered

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:

CreateWorld 1
3,3       ; at coordinates 3,3
9         ; earth-like
9         ; pre-gate tech
2         ; base planet
1         ; empire 1
2200      ; 22 billion pop.
34        ; 34% efficiency
100       ; 100% trillum reserves

; LAM  def  GDM  ion
    0 1000 1000 2000

; fgt  hkr  jmp  jtn  pen  str  trn
 1000 1000 1000 1000 1000 1000 1000

; inf  elt  amb  che  met  sup  tri
 1000 1000 1000 1000 1000 1000 1000

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:

ConstantType of Starbase
20command base
21fortress
22industrial complex
23outpost

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

Example:

CreateStarbase 1
3,3       ; at coordinates 3,3
22        ; industrial complex
9         ; pre-gate tech
2         ; base planet
1         ; empire 1
2200      ; 22 billion pop.
34        ; 34% efficiency

; LAM  def  GDM  ion
    0 1000 1000 2000

; fgt  hkr  jmp  jtn  pen  str  trn
 1000 1000 1000 1000 1000 1000 1000

; inf  elt  amb  che  met  sup  tri
 1000 1000 1000 1000 1000 1000 1000

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:

ConstantType of Starbase
24gate
25warp link
26disrupter

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:

BEGINDESCRIPTION

WorldBackgroundIndex
2:1 E:0  1 ; empire 0 capital
EndIndex

TEXT 1
History: This world, now known as "Jerhad" by the local inhabitants...
ENDTEXT

ENDDESCRIPTION

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:

TEXT 1
The stargate is at [C4:1].
ENDTEXT

displays as (for example):

The stargate is at 5,10.