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. See also shipdata.plist

character structure

The following character data are read in by oolite.

<key>oolite-character</key>
<dict>
    <key>bounty</key>           <string>10</string>
    <key>insurance</key>        <string>178</string>
    <key>legal_status</key>     <string>10</string>
    <key>name</key>             <string>Captain Mc Arthur</string>
    <key>origin</key>           <string>151</string>
    <key>random_seed</key>      <string>0 0 0 0 0 0</string>
    <key>role</key>             <string>pirate</string>
    <key>script_actions</key>   <array></array>
    <key>short_description</key><string>a unworthy captain from hell</string>
    <key>long_description</key> <string>For capturing Captain McArthur, a unworthy captain from hell,
                                           you're paid a bounty of 125 credits</string>
</dict>

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

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.

Role can be one of the following: pirate, trader, hunter, police, miner, passenger or slave.

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.

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_action.

Simple character

<key>oolite-character</key>
<dict>
    <key>bounty</key>           <string>10</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>

Bounty is used to determine if a pilot is rescued or captured. Insurance is the hight of the bounty/insurande on docking. 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 "name", "short_description", you're paid a bounty of "insurance" credits. or For rescuing "name", "short_description", their insurance pays "insurance" 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.

<key>oolite-character</key>
<dict>
    <key>bounty</key>           <string>10</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></array>
</dict>

On capturing the pilot you get the response "captured name". On docking nothing happens, but the script_action 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.