OXP howto plist

the plist formats, XML and ASCII

plist

• Property lists A more detailed look at the ASCII and XML formats.

To begin making an Oolite plist, all one needs is a text editor and a purpose. Many text editors will do the job, but it is helpful to use a specialized plist editor (such as Sub Etha Edit or PlistEdit Pro for the Mac, Vim for Linux/Windows).

A good way to learn the correct way to make plists, is to examine the ones found within Oolite and working OXPs. The format is ideal to freely copy/paste items between various lists, and alter them as desired. This also minimizes the chance of little parser errors.

Finding mistakes

Macs use Cocoa to parse property lists, while other platforms use GNUstep. Their parsers work differently and are sensitive to different errors. - see post above, too!

OXP Verifier

A cross-platform utility for finding errors in some of the plists. See section in OXP howto

plutil (Macintosh Terminal)

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. This will cause the 'address' of the plist to be shown. Hit return, and Terminal will reveal whether or not the plist is OK. If it's not, you will be given a clue to what is wrong, and the line number of the error.

Basic Examples of plists

The plists for a very simple OXP, for instance one containing a space advertising billboard, could 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>asteroid(0.05)</string>
      <key>scanClass</key>
      <string>CLASS_ROCK</string>
      <key>thrust</key>
      <real>0.05</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 weird) appearance in the middle of an asteroid field. This is a little awkward and not much chance of seeing our model frequently, so we would make a small addition to roles.

      <key>roles</key>
      <string>asteroid(0.05) billboard</string>

and include another plist in order to force an appearance of our model. This by either a script.plist or planetinfo.plist.

script.plist

Example 1

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>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. A very simple 'rendezvous' script.

Example 2

Or one could begin with an alternate simple script, this one in the ASCII format:

Code:

{
   "billboard_near_station" = (
       {
           conditions = (
               "status_string equal STATUS_LAUNCHING"
           ); 
           do = (
               "addSystemShips: billboard 1 1.0"
           ); 
       }
   );
} 

Since addSystemShips is used instead of addShips, it will be followed by a number that gives a spawn destination at some point on the space lane between the Witchpoint (0.0) and the station (1.0). This script will make our entity show up somewhere in the Aegis every time the player leaves the station.

planetinfo.plist

As the above scripts are a very general method of summoning our entity (although scripts could easily be a great deal more specific!), the planetinfo.plist gives an easy oportunity to be specific within a system. Used for many things including customizing planets and system data, its also simple to add script_actions for an entity appearance.

example 1

Code:

{
    "0 7" = {
           "script_actions" = (
                "checkForShips: billboard", 					
                {
                     conditions = ("shipsFound_number lessthan 1");
                     do = ( "addSystemShips: billboard 1 1.0" );
                }
          ); 
     }
}

Consulting the Oolite planet list tells us that 0 7 is galaxy:1, planet:Lave. Using the action of checkForShips with the condition that shipsFound_number is zero prior to adding our model, will ensure that only 1 billboard will be waiting outside the Lave station, and no more (in the unlikely event that the engine has a deja vu and spawns one or two more billboard models).

example 2

Code:

{
    "0 7" = {
           "script_actions" = (
                "checkForShips: billboard", 					
                {
                     conditions = ("shipsFound_number lessthan 1");
                     do = ( "addShipsAt: billboard 1 pwm 18175 66430 22320" );
                }
          ); 
     }
}

This is unnecessarily complex for a virgin planetinfo experiment, but goes to show how specific one may be. In this case, addSystemShips is replaced with addShipsAt, and what follows is a quite exact destination using the coordinate scheme (as described in Methods) . The numbers following pwm plots a point very close to the Lave station buoy, and using addShipsAtPrecisely would do so to an even more specific degree. To see the pwm coordinates at any time while flying in space, press shift-f.

Note that coordinates such as these are not interchangable between planets, as stations will be located at different places from system to system.

example 3

The same planetinfo using script_actions, but here expressed in XML.

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>0 7</key> 
   <dict> 
      <key>script_actions</key> 
      <array> 
         <string>checkForShips: billboard</string> 
            <dict> 
                <key>conditions</key> 
                <array> 
                <string>shipsFound_number lessthan 1</string>       
                </array> 
                <key>do</key> 
                <array> 
                    <string>addShipsAtPrecisely: billboard 1 pwm 18175 66430 22320</string> 
                </array> 
            </dict> 
      </array> 
   </dict> 
</dict> 
</plist>

Seal the deal

Place your shipdata and your script or planetinfo into the Config folder which, along with Textures and Models, is placed in a folder to be named billboard.oxp. These are just a very few of the plist options for a model OXP, but enough to introduce an entity into the game universe.

Links

• Property list contains notes on such things as arrays and dictionaries - and how to format them.