Difference between revisions of "OXP howto plist"

From Elite Wiki
(more tutorial)
(Updating BB links)
 
(8 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
[[Image:plist-XML-ASCII-ill.png|thumb|right|300px|the plist formats, XML and ASCII]]
 
[[Image:plist-XML-ASCII-ill.png|thumb|right|300px|the plist formats, XML and ASCII]]
== To Begin ==
+
== plist ==
  
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).  
+
*[[Property lists]] A more detailed look at the ASCII and XML formats.
  
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"?>
+
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).  
<!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 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 ones found within Oolite and working 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.
+
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.
  
== Correcting with PLUTIL (Macintosh) ==
+
== Finding mistakes ==  
 +
[https://bb.oolite.space/viewtopic.php?p=69589#p69589 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.
 
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 ==
 
 
== Basic Examples ==
 
 
 
 
The plists for a very simple OXP, for instance one containing a space advertising billboard, could contain this:
 
The plists for a very simple OXP, for instance one containing a space advertising billboard, could contain this:
  
Line 31: Line 26:
  
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <?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">
+
  <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "<nowiki>http://www.apple.com/DTDs/PropertyList-1.0.dtd">
  <plist version="1.0">
+
  <plist version="1.0"></nowiki>
 
  <dict>
 
  <dict>
 
     <key>billboard1</key>
 
     <key>billboard1</key>
Line 83: Line 78:
 
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.
 
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''.
+
Because ''roles'' contains asteroid(0.05), this should cause our billboard to have a rare (and weird) appearance in the middle of an [[Asteroid_(Oolite)|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>
 
       <key>roles</key>
Line 89: Line 84:
  
 
and include another plist in order to force an appearance of our model.  This by either a [[script.plist]] or [[planetinfo.plist]].
 
and include another plist in order to force an appearance of our model.  This by either a [[script.plist]] or [[planetinfo.plist]].
 
  
 
=== ''[[script.plist]]'' ===
 
=== ''[[script.plist]]'' ===
Line 98: Line 92:
  
 
  <?xml version="1.0" encoding="UTF-8"?>
 
  <?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">
+
  <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "<nowiki>http://www.apple.com/DTDs/PropertyList-1.0.dtd">
  <plist version="1.0">
+
  <plist version="1.0"></nowiki>
 
  <dict>
 
  <dict>
 
     <key>billboard_at_witchpoint</key>
 
     <key>billboard_at_witchpoint</key>
Line 145: Line 139:
 
=== ''[[planetinfo.plist]]'' ===
 
=== ''[[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.
+
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 [[Shipdata.plist#script_actions|script_actions]] for an entity appearance.
  
 
==== example 1 ====
 
==== example 1 ====
Line 183: Line 177:
  
  
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 even more exactl degree.  To see the pwm coordinates at any time in space, press ''shift-f''.
+
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.
 
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" "<nowiki>http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 +
<plist version="1.0"></nowiki>
 +
<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>
 +
  
  
== WrapUp ==
+
== Seal the deal ==
  
So put 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.   
+
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.
  
 
[[Category:Oolite]]
 
[[Category:Oolite]]
 +
[[Category:Oolite scripting]] [[Category:Legacy scripting]]

Latest revision as of 02:17, 29 February 2024

the plist formats, XML and ASCII

plist


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.