Characters.plist - Revision history

Phkb: /* Using characters */

2015-04-18T19:13:40Z

‎Using characters

Svengali: handler characterDocked

2013-05-11T19:23:09Z

handler characterDocked

SandJ: Just typos

2012-05-08T18:06:10Z

Just typos

Eric Walch: Explained bounty calculation for pilots

2011-01-01T17:36:23Z

Explained bounty calculation for pilots

Eric Walch: Added extra role info

2010-12-04T22:41:48Z

Added extra role info

Eric Walch: typo

2010-11-30T22:02:14Z

typo

Eric Walch: Updated characters with future 1.75 info

2010-11-30T22:01:39Z

Updated characters with future 1.75 info

Eric Walch: Better explanation of pilot role

2010-11-30T09:06:55Z

Better explanation of pilot role

Svengali at 11:43, 6 May 2010

2010-05-06T11:43:26Z

Commander McLane: added category Oolite scripting

2009-09-08T12:38:34Z

added category Oolite scripting

@@ Line 3: / Line 3: @@
 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]].
+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. Then you must also set the '''unpiloted''' key to '''NO''' in [[shipdata.plist]].
 == Structure ==

← Older revision		Revision as of 19:23, 11 May 2013
Line 98:		Line 98:
	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.		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.	+	Starting with Oolite 1.75 we can also use a JS script. On docking the handler: "unloadCharacter()" 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.

@@ Line 1: / Line 1: @@
 == 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.
+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]].
@@ Line 15: / Line 15: @@
      "insurance" =        178;
      "legal_status" =     10;
-     "name" =             "Captain Mc Arthur";
+     "name" =             "Captain McArthur";
      "origin" =           151;
      "random_seed" =      "0 0 0 0 0 0";
      "role"  =              pirate;
-     "short_description" = "a unworthy captain from hell";
+     "short_description" = "an unworthy captain from hell";
      "script_actions" =   (
                             "...code to be executed..."
@@ Line 31: / Line 31: @@
 * '''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)".
+* '''bounty''' and '''legal_status''' both set the same game value. The pilot's bounty undergoes a bitwise OR with the ship's 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.
@@ Line 37: / Line 37: @@
 * '''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.
+* '''origin''' is the planet number from which 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.
+* '''random_seed''' in the character.plist is used to calculate all the different character parameters. It is built 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.
@@ Line 56: / Line 56: @@
      bounty = 0;
      insurance = 178;
-     name = "Captain Mc Arthur";
+     name = "Captain McArthur";
      random_seed = "0 0 0 0 0 0";
-     short_description = "a unworthy captain from hell";
+     short_description = "an 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.
+* '''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 a slave to the inventory.
 * '''random_seed''' is set to an arbitrary value of zero.
@@ Line 69: / Line 69: @@
 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.
+ For capturing Captain McArthur, an 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.
+ For rescuing Captain McArthur, an unworthy captain from hell, their insurance pays 178 credits.
 == Scripted character ==
@@ Line 81: / Line 81: @@
    myCharacter = {
      role = pirate;
-     name = "Captain Mc Arthur";
+     name = "Captain McArthur";
      random_seed = "0 0 0 0 0 0";
      script_actions = ( ...code to be executed... );
@@ Line 91: / Line 91: @@
    myCharacter = {
      role = pirate;
-     name = "Captain Mc Arthur";
+     name = "Captain McArthur";
      script = "myCharacterScript.js";
    };

@@ Line 31: / Line 31: @@
 * '''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.
+* '''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.

@@ Line 29: / Line 29: @@
 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.
+* '''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.
+* '''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.
 * '''insurance''' is calculated from role in combination with bounty and random_seed if no insurance value is given.
@@ Line 47: / Line 47: @@
 * '''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.
-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 '''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.
+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 ==

@@ Line 24: / Line 24: @@
+                            )
      "script" =           "myCharacterScript.js";
+   }
+ }

@@ Line 20: / Line 20: @@
      "role"  =              pirate;
      "short_description" = "a unworthy captain from hell";
      "script_actions" =   (
                             "...code to be executed..."
+                            )
+   }
+ }
@@ Line 39: / Line 40: @@
 * '''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.
+* '''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.
-Example OpenStep:
+Example:
+ {
    myCharacter = {
@@ Line 87: / Line 76: @@
 == 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.
+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 XML:
+Example:
+ {
    myCharacter = {
@@ Line 98: / Line 87: @@
    };
+ }

@@ Line 9: / Line 9: @@
 characters.plist is a dictionary and the following character data are read in by Oolite.
-Example XML:
+Example:
- <dict>
-   <key>oolite-character</key>
+   "oolite-character" = {
-   <dict>
+     "bounty" =           10;
-     <key>bounty</key>           <string>10</string>
+     "insurance" =        178;
-     <key>insurance</key>        <string>178</string>
+     "legal_status" =     10;
-     <key>legal_status</key>     <string>10</string>
+     "name" =             "Captain Mc Arthur";
-     <key>name</key>             <string>Captain Mc Arthur</string>
+     "origin" =           151;
-     <key>origin</key>           <string>151</string>
+     "random_seed" =      "0 0 0 0 0 0";
-     <key>random_seed</key>      <string>0 0 0 0 0 0</string>
+     "role"  =              pirate;
-     <key>role</key>             <string>pirate</string>
+     "short_description" = "a unworthy captain from hell";
-     <key>script_actions</key>   <array></array>
+     "long_description" = "For capturing Captain McArthur, a unworthy captain from hell, you're paid a bounty of 125 credits";
-     <key>short_description</key><string>a unworthy captain from hell</string>
+     "script_actions" =   (
-     <key>long_description</key> <string>For capturing Captain McArthur, a unworthy captain from hell,
+                            "...code to be executed..."
-                                            you're paid a bounty of 125 credits</string>
-     <key>script_actions</key>   <array>...code to be executed...</array>
-   </dict>
 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.
 * '''bounty''' and '''legal_status''' both set the same game value.
@@ Line 38: / Line 40: @@
 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.
@@ Line 55: / Line 55: @@
    <key>myCharacter</key>
    <dict>
-     <key>bounty</key>           <string>10</string>
+     <key>bounty</key>           <string>0</string>
      <key>insurance</key>        <string>178</string>
      <key>name</key>             <string>Captain Mc Arthur</string>
@@ Line 66: / Line 66: @@
+ {
    myCharacter = {
-     bounty = 10;
+     bounty = 0;
      insurance = 178;
      name = "Captain Mc Arthur";
@@ Line 93: / Line 93: @@
    <key>myCharacter</key>
    <dict>
-     <key>bounty</key>           <string>10</string>
+     <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>
@@ Line 103: / Line 103: @@
+ {
    myCharacter = {
-     bounty = 10;
+     role = pirate;
      name = "Captain Mc Arthur";
      random_seed = "0 0 0 0 0 0";

← Older revision		Revision as of 12:38, 8 September 2009
Line 79:		Line 79:

	[[Category:Oolite]]		[[Category:Oolite]]
		+	[[Category:Oolite scripting]]