= Scenario file formats =

A scenario consists of an XML data file and, optionally, a PMP data file. The XML format is text and may be viewed in any text editor, while the PMP is a proprietary binary format. Most scenarios are created with [wiki:Atlas_Manual Atlas scenario editor], which generates one of each file per map.

The PMP files store a map's elevation and terrain texture references for each tile. The XML files store map objects (entities and actors) as well as information for environment (e.g. lighting and water parameters), camera orientation, and various other settings.

== PMP format ==

The following described version 4 of the PMP file format with C-like syntax.

Basic types:
 * char = 8-bit character
 * u32 = 32-bit unsigned int
 * u16 = 16-bit unsigned int

All types are stored in little-endian format. Text is always ASCII.

{{{
#!c
 PMP {
     char magic[4]; // == "PSMP"
     u32 version; // == 4
     u32 data_size; // == filesize-12
     
 
     u32 map_size; // number of patches (16x16 tiles) per side
 
     u16 heightmap[(mapsize*16 + 1)*(mapsize*16 + 1)]; // vertex heights
 
     u32 num_terrain_textures;
     String terrain_textures[num_terrain_textures]; // filenames (no path), e.g. "cliff1.dds"
 
     Patch patches[mapsize^2];
 }
 
 Patch {
     Tile tiles[16*16];
 }
 
 Tile {
     u16 texture1; // index into terrain_textures[]
     u16 texture2; // index, or 0xFFFF for 'none'
     u32 priority; // ???
 }
 
 String {
     u32 length;
     char data[length]; // not NUL-terminated
 }
}}}

== Scenario XML format ==

The following outlines version 5 of the scenario XML format.

'''Note:''' this structure is not rigidly enforced (e.g. by a DTD) - many elements are optional, to preserve backward compatibility with older map formats. However, it should be generated in this latest version of the format whenever possible.

{{{
#!xml
<?xml version="1.0" encoding="UTF-8"?>
<Scenario version="5">
  <Environment>
    <LightingModel>standard</LightingModel>
    <SkySet>cloudless</SkySet>
    <SunColour r="0.847059" g="0.792157" b="0.592157"/>
    <SunElevation angle="0.773126"/>
    <SunRotation angle="-0.374291"/>
    <TerrainAmbientColour r="0.447059" g="0.509804" b="0.54902"/>
    <UnitsAmbientColour r="0.501961" g="0.501961" b="0.501961"/>
    <Water>
      <WaterBody>
        <Type>default</Type>
        <Colour r="0.294118" g="0.34902" b="0.694118"/>
        <Height>21.823</Height>
        <Shininess>250</Shininess>
        <Waviness>8</Waviness>
        <Murkiness>1</Murkiness>
        <Tint r="0.639216" g="0.54902" b="0.34902"/>
        <ReflectionTint r="0.603922" g="0.529412" b="0.384314"/>
        <ReflectionTintStrength>0.525391</ReflectionTintStrength>
      </WaterBody>
    </Water>
  </Environment>
  <Camera>
    <Position x="246.599" y="91.5253" z="497.928"/>
    <Rotation angle="0"/>
    <Declination angle="0.610865"/>
  </Camera>
  <ScriptSettings><![CDATA[
{
  "CircularMap": true,
  "Description": "Northwest India. Nearby rivers swell with monsoon rains, allowing for only a few treacherous crossings...",
  "GameType": "conquest",
  "Keywords": [],
  "LockTeams": false,
  "Name": "Punjab 1",
  "PlayerData": [
    {
      "AI": "",
      "Civ": "spart",
      "Colour": {
        "b": 200,
        "g": 46,
        "r": 46
      },
      "Name": "Player 1",
      "Team": -1
    },
    ...
  ],
  "RevealMap": false
}]]>
  </ScriptSettings>
  <Entities>
    <Entity uid="12">
      <Template>structures/pers_civil_centre</Template>
      <Player>2</Player>
      <Position x="815.72754" z="384.37818"/>
      <Orientation y="2.35621"/>
    </Entity>
    <Entity uid="13">
      <Template>actor|props/flora/grass_tropic_field_tall.xml</Template>
      <Position x="154.78473" z="589.32166"/>
      <Orientation y="2.35621"/>
    </Entity>
    ...
    
  </Entities>
  <Paths/>
</Scenario>
}}}

=== Environment ===

These elements correspond to settings on the [wiki:Atlas_Manual_Environment_Tab environment tab] in Atlas. They affect renderer behavior.

=== Camera ===

Currently unused?

=== !ScriptSettings ===

A special element containing a [wiki:JSON JSON] object. This object gets parsed during game setup to display information about the map such as its name, description, number of players and their civilizations. It's a flexible format which gets updated as we add new map settings.

This data mostly corresponds to the [wiki:Atlas_Manual_Map_Tab map] and [wiki:Atlas_Manual_Player_Tab player] settings tabs in Atlas.

'''Note:''' there is intentional symmetry between this data and that used by the [wiki:Random_Map_Generator_Internals random map generator].

=== Entities ===

This is a list of Entity elements that define all the objects and actors on the map. Each Entity consists of:
 * unique entity ID of type u32. Players are also considered entities, so these don't necessarily start with 1. 0 is reserved for `INVALID_ENTITY`.
 * entity template filename. For actors, these are a reference to the actor template instead, prefixed with '''actor|'''
 * player ID which owns the entity, positive integer of type i32. Gaia is reserved as player 0, typically 1-8 are used for other players, -1 is reserved for `INVALID_PLAYER`.
 * world position. Only X and Z translation are currently supported.
 * world orientation. Only rotation in radians about the Y-axis is currently supported.