OXP howto plist

the plist formats, XML and ASCII

To Begin

To begin making a Property List, all one needs is a text editor and a purpose. Although any text editor will do, it is helpful to use a specialized plist editor (such as Sub Etha Edit or PlistEdit Pro for the Mac, Vim for Linux/Windows).

The plists that appear in Oolite may be in two formats, XML and ASCII. The favoured format for most plists, XML, will always begin with the Apple header:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">

...the various types of plist data will make up the body, and then in closing...

</plist>

There is no better way to learn the correct way to make plists, than to examine the working ones found within Oolite and OXPs. The format lends itself to easily copy/paste desired items, and change them as fancied. This also minimizes the chance of little parser errors.

Correcting

Since a very small mistake is enough to stop a plist from being accepted, it's important to be exact about every letter and sign. The Mac Terminal utility has a very practical tool for catching parser errors. After opening Terminal, simply type plutil, add one space, and drag and drop the plist in question onto the Terminal window. Hit return, and Terminal will reveal whether or not the plist is OK. If it's not, you will be given a clue what is wrong, and the line number of the error.

Basic Examples

The plists for a very simple OXP, for instance one containing a space advertising billboard, will contain this:

shipdata.plist

Code:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   <key>billboard1</key>
   <dict>
      <key>ai_type</key>
      <string>dumbAI.plist</string>
      <key>bounty</key>
      <integer>0</integer>
      <key>cargo_type</key>
      <string>CARGO_NOT_CARGO</string>
      <key>energy_recharge_rate</key>
      <real>0.0</real>
      <key>forward_weapon_type</key>
      <string>WEAPON_NONE</string>
      <key>has_ecm</key>
      <false/>
      <key>has_escape_pod</key>
      <false/>
      <key>has_scoop</key>
      <false/>
      <key>likely_cargo</key>
      <integer>0</integer>
      <key>max_cargo</key>
      <integer>0</integer>
      <key>max_energy</key>
      <real>100</real>
      <key>max_flight_pitch</key>
      <real>0.5</real>
      <key>max_flight_roll</key>
      <real>0.5</real>
      <key>max_flight_speed</key>
      <real>0.0</real>
      <key>missiles</key>
      <integer>0</integer>
      <key>model</key>
      <string>billboard1.dat</string>
      <key>name</key>
      <string>Billboard</string>
      <key>roles</key>
      <string>billboard advertising asteroid(0.05)</string>
      <key>scanClass</key>
      <string>CLASS_ROCK</string>
      <key>thrust</key>
      <real>0.0</real>
      </dict>
</dict>
</plist>

This is the only mandatory plist inside folder Config, to accompany the model named billboard1.dat in Models, and billboard1_texture.png in Textures, which would complete the minimal billboard.oxp, placing a slow spinning, lifeless object into the game.

Because roles contains asteroid(0.05), this should cause our billboard to have a rare (and odd) appearance in the middle of an asteroid field. This isn't much, so we include another plist.

script.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   <key>billboard_at_witchpoint</key>
   <array>
       <dict>
       <key>conditions</key>
          <array>
            <string>status_string equal STATUS_EXITING_WITCHSPACE</string>
          </array
          <key>do</key>
          <array>
             <string>addShips: billboard 1</string>
          </array>
       </dict>
   </array>
</dict>
</plist>>

This will ensure that one entity with the role 'billboard' will pop up at the Witchpoint every time a player arrives.

Include this in the Config folder which is placed along with Textures and Models in a folder to be named billboard.oxp. These are the bare plist essentials for a model OXP.