Characters.plist

Using characters

Oolite uses characters in the game to fill escape capsules. On populating a system it puts characters with different roles in ships based on the ship role or the system. Starting with oolite version 1.65 it is also possible to add those characters with a script. One scripted character comes with the conhunt mission.

The characters are stored in a character.plist file that resides in the Config folder of a OXP. You can add a character in a ship by defining a pilot for a ship. When the ship has time to launch an escape capsule, this character will be inside. You can also put a character directly into an escape capsule or barrel. Than you must also set the unpiloted key to NO in shipdata.plist.

Structure

characters.plist is a dictionary and the following character data are read in by Oolite.

Example:

{
  "oolite-character" = {
    "bounty" =           10;
    "insurance" =        178;
    "legal_status" =     10;
    "name" =             "Captain Mc Arthur";
    "origin" =           151;
    "random_seed" =      "0 0 0 0 0 0";
    "role"  =              pirate;
    "short_description" = "a unworthy captain from hell";
    "long_description" = "For capturing Captain McArthur, a unworthy captain from hell, you're paid a bounty of 125 credits";
    "script_actions" =   ( 
                           "...code to be executed..."
                           )
  }
}

But it does not make sense to use them all at once. The system always generates a random character based on random_seed and than overwrites this with the data in the character.plist if supplied.

• role can be one of the following: pirate, trader, hunter, police, miner, passenger or slave. Depending on the role, bounty and insurance is set. These values are replaced when an explicit bounty or insurance is defined.

• bounty and legal_status both set the same game value.

• insurance is calculated from role in combination with bounty and random_seed if no insurance value is given.

• name is the name of the character that is showed on capturing.

• origin is the planet number from witch the pilot originates. It is used in a computer generated short_description together with the random_seed.

Random values are always generated from a seed value. The random_seed in the character.plist is used to calculate different character parameters. It is build of 6 integer numbers between 0 and 255 separated by a space.

• short_description is used in the arrival screen. If none is given, one is calculated based on the seed value.

• long_description is the total description line that is shown in the arrival screen, but it is always calculated and as far I have seen, the one in the character.plist is read in but always recalculated before showing so it does not make sense to define it here.

• script_actions are often used for mission specific things. This array holds legacy code (see Methods) to be executed on docking.

But as the seed always stays the same within a certain character.plist it is useless to let the system calculate values based on a fixed seed that always generates the same "random" result. So for a practical use we only need two types of reduced characters. Those with and those without a script_actions.

Simple character

Example XML:

<dict>
  <key>myCharacter</key>
  <dict>
    <key>bounty</key>           <string>0</string>
    <key>insurance</key>        <string>178</string>
    <key>name</key>             <string>Captain Mc Arthur</string>
    <key>random_seed</key>      <string>0 0 0 0 0 0</string>
    <key>short_description</key><string>a unworthy captain from hell</string>
  </dict>
</dict>

Example OpenStep:

{
  myCharacter = {
    bounty = 0;
    insurance = 178;
    name = "Captain Mc Arthur";
    random_seed = "0 0 0 0 0 0";
    short_description = "a unworthy captain from hell";
  };
}

• insurance - used to determine if a pilot is rescued or captured. With insurance the insurance amount is paid on docking. Without it the pilot is captured.

• bounty - player receives a reward for capturing the pilot. (Not the defined value, but a new calculated value that gives higher bounties in higher governments). When both insurance and bounty are zero, the player gets no message and the pilot is added as slave to the inventory.

• random_seed is set to an arbitrary value of zero.
• name is the pilot name and short_description is given on docking.

Such a character will give following response on docking in the arrival screen:

For capturing Captain Mc Arthur, a unworthy captain from hell, you're paid a bounty of x credits.

or

For rescuing Captain Mc Arthur, a unworthy captain from hell, their insurance pays 178 credits.

Scripted character

Most script writers probably want to use the scripted pilot. In this case we even need less info as nothing is printed in the arrival screen.

Example XML:

<dict>
  <key>myCharacter</key>
  <dict>
    <key>role</key>           <string>pirate</string>
    <key>name</key>             <string>Captain Mc Arthur</string>
    <key>random_seed</key>      <string>0 0 0 0 0 0</string>
    <key>script_actions</key>   <array>...code to be executed...</array>
  </dict>
</dict>

Example OpenStep:

{
  myCharacter = {
    role = pirate;
    name = "Captain Mc Arthur";
    random_seed = "0 0 0 0 0 0";
    script_actions = ( ...code to be executed... );
  };
}

On capturing the pilot you get the response "captured name". On docking nothing happens, but the script_actions is executed. You can use this to put up a message on a missionscreen, or you can just set a mission_variable and deal with them later in the normal script. The script will run on the first docking. This could be something else than the main station.