Changes between Version 1 and Version 2 of PMP_File_Format


Ignore:
Timestamp:
Jun 26, 2012, 4:57:09 AM (12 years ago)
Author:
historic_bruno
Comment:

Some updates and nicer formatting

Legend:

Unmodified
Added
Removed
Modified

  • PMP_File_Format

    v1 v2  
    1 PMP files store a map's elevation and terrain types for each tile. Each map also has an associated XML file that stores objects on the map (entities and actors) as well as environment information (currently, lighting parameters).
     1= Scenario file formats =
    22
    3 PMP file format (version 4), described in something a bit like C:
     3A 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.
     4
     5The 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.
     6
     7== PMP format ==
     8
     9The following described version 4 of the PMP file format with C-like syntax.
    410
    511Basic types:
    … …  
    1117
    1218{{{
     19#!c
    1320 PMP {
    1421     char magic[4]; // == "PSMP"
    … …  
    1926     u32 map_size; // number of patches (16x16 tiles) per side
    2027 
    21      u16 heightmap[(mapsize*16 + 1)^2]; // (squared, not xor) - vertex heights
     28     u16 heightmap[(mapsize*16 + 1)*(mapsize*16 + 1)]; // vertex heights
    2229 
    2330     u32 num_terrain_textures;
    … …  
    4350}}}
    4451
    45 Other data is stored in XML format (with a filename matching the PMP's, except with ".pmp" replaced by ".xml"), with the following structure:
     52== Scenario XML format ==
     53
     54The following outlines version 5 of the scenario XML format.
     55
     56'''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.
    4657
    4758{{{
    48     <?xml version="1.0" encoding="utf-8" standalone="no"?>
    49     <Scenario>
    50         <Environment>
    51             <SunColour r="1" g="1" b="1" /> &lt;!-- range 0..1, though out-of-range values are allowed -->
    52             <SunElevation angle="0.785398" /> &lt;!-- elevation above horizontal, in radians -->
    53             <SunRotation angle="4.71239" /> &lt;!-- angle clockwise from positive-z axis (north), in radians -->
    54             <TerrainAmbientColour r="0" g="0" b="0" />
    55             <UnitsAmbientColour r="0.4" g="0.4" b="0.4" />
    56         </Environment>
     59#!xml
     60<?xml version="1.0" encoding="UTF-8"?>
     61<Scenario version="5">
     62  <Environment>
     63    <LightingModel>standard</LightingModel>
     64    <SkySet>cloudless</SkySet>
     65    <SunColour r="0.847059" g="0.792157" b="0.592157"/>
     66    <SunElevation angle="0.773126"/>
     67    <SunRotation angle="-0.374291"/>
     68    <TerrainAmbientColour r="0.447059" g="0.509804" b="0.54902"/>
     69    <UnitsAmbientColour r="0.501961" g="0.501961" b="0.501961"/>
     70    <Water>
     71      <WaterBody>
     72        <Type>default</Type>
     73        <Colour r="0.294118" g="0.34902" b="0.694118"/>
     74        <Height>21.823</Height>
     75        <Shininess>250</Shininess>
     76        <Waviness>8</Waviness>
     77        <Murkiness>1</Murkiness>
     78        <Tint r="0.639216" g="0.54902" b="0.34902"/>
     79        <ReflectionTint r="0.603922" g="0.529412" b="0.384314"/>
     80        <ReflectionTintStrength>0.525391</ReflectionTintStrength>
     81      </WaterBody>
     82    </Water>
     83  </Environment>
     84  <Camera>
     85    <Position x="246.599" y="91.5253" z="497.928"/>
     86    <Rotation angle="0"/>
     87    <Declination angle="0.610865"/>
     88  </Camera>
     89  <ScriptSettings><![CDATA[
     90{
     91  "CircularMap": true,
     92  "Description": "Northwest India. Nearby rivers swell with monsoon rains, allowing for only a few treacherous crossings...",
     93  "GameType": "conquest",
     94  "Keywords": [],
     95  "LockTeams": false,
     96  "Name": "Punjab 1",
     97  "PlayerData": [
     98    {
     99      "AI": "",
     100      "Civ": "spart",
     101      "Colour": {
     102        "b": 200,
     103        "g": 46,
     104        "r": 46
     105      },
     106      "Name": "Player 1",
     107      "Team": -1
     108    },
     109    ...
     110  ],
     111  "RevealMap": false
     112}]]>
     113  </ScriptSettings>
     114  <Entities>
     115    <Entity uid="12">
     116      <Template>structures/pers_civil_centre</Template>
     117      <Player>2</Player>
     118      <Position x="815.72754" z="384.37818"/>
     119      <Orientation y="2.35621"/>
     120    </Entity>
     121    <Entity uid="13">
     122      <Template>actor|props/flora/grass_tropic_field_tall.xml</Template>
     123      <Position x="154.78473" z="589.32166"/>
     124      <Orientation y="2.35621"/>
     125    </Entity>
     126    ...
    57127   
    58         <Entities>
    59             <Entity>
    60                 <Template>Name</Template>
    61                 <Player>1</Player> &lt;!-- 0 = gaia, higher numbers for other players -->
    62                 <Position x="1.2" y="3.4" z="5.6" />
    63                 <Orientation angle="1.2" />
    64             </Entity>
    65             ...
    66         </Entities>
    67    
    68         <Nonentities>
    69             <Nonentity>
    70                 <Actor>Name</Actor>
    71                 <Position x="1.2" y="3.4" z="5.6" />
    72                 <Orientation angle="1.2" />
    73             </Nonentity>
    74             ...
    75         </Nonentities>
    76     </Scenario>
     128  </Entities>
     129  <Paths/>
     130</Scenario>
    77131}}}
    78132
    79 (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.)
     133=== Environment ===
     134
     135These elements correspond to settings on the [wiki:Atlas_Manual_Environment_Tab environment tab] in Atlas. They affect renderer behavior.
     136
     137=== Camera ===
     138
     139Currently unused?
     140
     141=== !ScriptSettings ===
     142
     143A 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.
     144
     145This data mostly corresponds to the [wiki:Atlas_Manual_Map_Tab map] and [wiki:Atlas_Manual_Player_Tab player] settings tabs in Atlas.
     146
     147'''Note:''' there is intentional symmetry between this data and that used by the [wiki:Random_Map_Generator_Internals random map generator].
     148
     149=== Entities ===
     150
     151This is a list of Entity elements that define all the objects and actors on the map. Each Entity consists of:
     152 * 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`.
     153 * entity template filename. For actors, these are a reference to the actor template instead, prefixed with '''actor|'''
     154 * 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`.
     155 * world position. Only X and Z translation are currently supported.
     156 * world orientation. Only rotation in radians about the Y-axis is currently supported.