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";
    "script_actions" =   ( 
                           "...code to be executed..."
                           )
    "script" =           "myCharacterScript.js";
  }
}

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. Values are: pirate never insured, always bounty, trader 75% insured, hunter 25% insured, police always insured, miner always insured, passenger always insured, slave never insured. These values are replaced when an explicit bounty or insurance is defined.

• bounty and legal_status both set the same game value. The pilots bounty undergoes a bitwise OR with the ships bounty on launch. This means that even a clean pilot will always end up with a bounty when the ship has a bounty. On docking the paid-out amount of credits is: "bounty * (0.5 + government_number / 10)".

• 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_seed in the character.plist is used to calculate all the different character parameters. It is build of 6 integer numbers between 0 and 255 separated by a space. Because it is a fixed seed value, all the generated values will always be the same for this seed. Useful to always generate the same character without defining it readable in the plist.

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

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

• script is new in Oolite 1.75. It is the filename of a JS script in the Scripts folder. When present, any script_actions will be ignored.

Because 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. For a practical use, we only need two types of reduced characters. Those with and those without a scripts. With Oolite 1.74 and older, the keys origin and random_seed were always needed to generate a valid pilot. Starting with 1.75 these keys can be dropped. When they are missing, Oolite will generate random values for the key.

Simple character

Example:

{
  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 by itself.

Example:

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

Or with 1.75 upwards:

{
  myCharacter = {
    role = pirate;
    name = "Captain Mc Arthur";
    script = "myCharacterScript.js";
  };
}

On capturing the pilot you get the response "captured name". On docking no messages are written to the arrival report for a scripted pilot, but the script_actions is executed instead. 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.

Starting with Oolite 1.75 we can also use a JS script. On docking the handler: "characterDocked()" is executed. You can display a mission page here, but it is discouraged to use the mission page to prevent conflicts with other pilots that may also want to show a mission page. For short messages it is better to use the Arrival Report because this can be a multi page report. For long messages it is better to just set a missionVariable and generate a mission screen from within a worldScript.