System Populator - Revision history

Diziet Sma: typo fix

2013-04-24T07:16:51Z

typo fix

Eric Walch: corrected typo

2010-08-30T21:10:27Z

corrected typo

Eric Walch: Removed some outdated info about difference between populator and script added ships.

2010-08-30T21:09:18Z

Removed some outdated info about difference between populator and script added ships.

Eric Walch: /* Adding ships with a script */

2007-09-28T12:17:56Z

‎Adding ships with a script

Eric Walch: /* Adding ships by the system populator */

2007-09-28T12:16:04Z

‎Adding ships by the system populator

Eric Walch: /* Adding ships by the system populator */

2007-09-28T12:15:27Z

‎Adding ships by the system populator

Eric Walch: /* Adding System Ships */

2007-09-28T12:10:25Z

‎Adding System Ships

Eric Walch: /* adding ships with a script */

2007-09-28T12:03:33Z

‎adding ships with a script

Eric Walch: /* adding ships by the system populator */

2007-09-28T12:03:16Z

‎adding ships by the system populator

Eric Walch: New page: =Adding System Ships = Adding ships can happen in two ways within Oolite. They can be added with the build in system populator, or they can be added with script commands. It looks the sa...

2007-09-28T12:02:51Z

New page: =Adding System Ships = Adding ships can happen in two ways within Oolite. They can be added with the build in system populator, or they can be added with script commands. It looks the sa...

New page

=Adding System Ships =

Adding ships can happen in two ways within Oolite. They can be added with the build in system populator, or they can be added with script commands. It looks the same but it works differently and also the result could be quite different. As this is often not well understood this goes sometime wrong in OXP's resulting in ships that behave differently than intended by the author.

The common thing for adding ships is the "roles" key. In this key one can define several roles for a ship. When a ship is added by role, Oolite searches all the ships having this role and selects one at random from this list. If you put a number directly behind the role without a space you can also influence the change of selection. 1.0 is normal change. see also [[shipdata.plist]]

e.g. roles: trader(1.0) pirate(2.0) hunter(0.25)

What happens with the ships parameters after selection is however different with the two adding methods.

== adding ships by the system populator ==

When a player enters a system after a witchspace jump or after starting a new game, the system must be populated with ships. First the populator looks at the Government and the Economy to determine how many ships of a kind should be added for that particular system with a large random variation. The groups are:

trading vessels
sun skimming vessels
pirate vessels
sun skim pirates
law/bounty-hunter vessels
sun skim law/bounty hunter vessels
thargoid warships
asterois clusters

The amounts the system came up can you also see in the logfile on your computer. There are two routes populated. Normal ships on route 1: witchpoint->planet and a few sunskiming vessels on route 2: sun<->planet

But now comes the most important part: All ships are defined in the shipdata.plist with only one bounty, one ai_type and one scanClass. However, pirates, traders and police must have complete different AI files to make them behave differently. Also should the bounty be different to make them clean, offender or fugitive. The populator does this by overwriting any existing ai_type and bounty with its own. scanClass is not overwritten but if scanClass was not set it then set as listed below.

For law/bounty-hunter vessels the populator selects ships with role police, interceptor or hunter.

The following changes occur:

trader route1traderAI clean CLASS_NEUTRAL
sunskim-trader route2sunskimAI clean CLASS_NEUTRAL
pirate pirateAI offender CLASS_NEUTRAL
police route1patrolAI clean CLASS_POLICE
interceptor route1patrolAI clean CLASS_POLICE
hunter route1patrolAI clean CLASS_NEUTRAL
targoid no changes offender CLASS_THARGOID
asteroid no changes no changes CLASS_ROCK

Ships numbers added on route 2 are much less as on route 1. The sunskim-trader role is overwritten to just trader for a more uniform interaction with other ships. e.g. pirates only look for ships with role trader. Police, interceptor and hunter get role route2patrolAI if placed on route 2.
The auto selection of a AI by the populator can be overwritten again by a script in the [[scripts_within_shipdata|launch_actions]].
Besides this all the normal ships get a pilot appropriate for its role, even if the ship has no escape_capsule.

== adding ships with a script ==

On adding ships with a scriptcommand like addShips: or adddSystemShips: thing work a little bit different. The ships are just added with the AI and bounty as defined in shipsdate.plist. If there is no pilot defined it gets one that is completely random. If no scanClass was set it defaults to CLASS_NEUTRAL

For ships of your own design and a private role things will be OK. But if you call ships with one of the standard roles things can go wrong. Look for example in the shipdata.plist of Oolite itself. All ships that can have both a pirate and trader role are by default defined with a pirateAI and a bounty of zero. That means that if the script adds a ship with role pirate is will keep the pirateAI and thus behave like a pirate but it will be clean.

If you however add the ship in its role as trader it will also keep its pirateAI with a clean bounty. Effectively you get the same ship with the same behavior. This means that a script should not call pirate, trader or hunter role as you will get strange results. (unless it is wanted that way).

In Oolite versions 1.69 this is fixed with the introduction of an auto_ai key in shipdata.plist. If this key is set to YES the system switches AI's in the same way as the populator. Or actually it switches them according to an autoAImap.plist that resides inside Oolites config folder.

[[Category:Oolite scripting]]

@@ Line 49: / Line 49: @@
 == Adding cargo to npc ships ==
-Some ships added in one of the above populator roles have branded cargo and not random cargo like most ships. Ships that are known to be heading for the station have a higher likelihood of carrying "[[Shipdata.plist#cargo_carried|SCARCE_GOODS]]", while ships heading from the station have a higher likelihood of carrying "[[Shipdata.plist#cargo_carried|PLENTYFULL_GOODS]]". Since Oolite 1.74 we can define these goods also in [[shipdata.plist]] for custom ships.
+Some ships added in one of the above populator roles have branded cargo and not random cargo like most ships. Ships that are known to be heading for the station have a higher likelihood of carrying "[[Shipdata.plist#cargo_carried|SCARCE_GOODS]]", while ships heading from the station have a higher likelihood of carrying "[[Shipdata.plist#cargo_carried|PLENTYFUL_GOODS]]". Since Oolite 1.74 we can define these goods also in [[shipdata.plist]] for custom ships.
-Cargo is selected by special rules when a ship explodes. First a random container with role "cargopod" is selected. When this container is a scripted container, the code is ready and that scripted container is added to the system. When its not scripted but a normal container, it must be filled with something. For this, a commodity is selected based on the scarce, plentyfull or random selection. When the commodity is selected, there is a 50% chance that the code looks if there exist a pod with the role of the commodity. When yes, that specific pod is selected to put the commodity in, if not the commodity is put in the current random container. This mechanism allows for creating specific containers for certain commodities, without using scripted containers.
+Cargo is selected by special rules when a ship explodes. First a random container with role "cargopod" is selected. When this container is a scripted container, the code is ready and that scripted container is added to the system. When its not scripted but a normal container, it must be filled with something. For this, a commodity is selected based on the scarce, plentyful or random selection. When the commodity is selected, there is a 50% chance that the code looks if there exist a pod with the role of the commodity. When yes, that specific pod is selected to put the commodity in, if not the commodity is put in the current random container. This mechanism allows for creating specific containers for certain commodities, without using scripted containers.
 [[Category:Oolite scripting]]

@@ Line 39: / Line 39: @@
  asteroid       no changes      no changes CLASS_ROCK
-Ships numbers added on route 2 are much less as on route 1. The sunskim-trader role is overwritten to just trader for a more uniform interaction with other ships. e.g. pirates only look for ships with role trader. Police, interceptor and hunter get  route2patrolAI if placed on route 2.
+Ships numbers added on route 2 are much less as on route 1. The sunskim-trader role is overwritten to just trader for a more uniform interaction with other ships. e.g. pirates only look for ships with role trader. Police, interceptor and hunter get  route2patrolAI if placed on route 2. interceptors get a police role after adding.
-The auto selection of a AI by the populator can be overwritten again by a script in the [[scripts_within_shipdata|launch_actions]].
+The auto selection of a AI by the populator can be prevented by setting the auto_ai to false, or changed again by the shipSpawned() event in a ship script.
 Besides this all the normal ships get a pilot appropriate for its role, even if the ship has no escape_capsule.
 == Adding ships with a script ==
 [[Category:Oolite scripting]]

@@ Line 45: / Line 45: @@
 == Adding ships with a script ==
-On adding ships with a scriptcommand like addShips: or adddSystemShips: thing work a little bit different. The ships are just added with the AI and bounty as defined in shipsdate.plist. If there is no pilot defined it gets one that is completely random. If no scanClass was set it defaults to CLASS_NEUTRAL
+On adding ships with a scriptcommand like addShips: or addSystemShips: things work a little bit different. The ships are just added with the ai_type and bounty as defined in shipsdate.plist. If there is no pilot defined it gets one that is completely random. If no scanClass was set it defaults to CLASS_NEUTRAL
 For ships of your own design and a private role things will be OK. But if you call ships with one of the standard roles things can go wrong. Look for example in the shipdata.plist of Oolite itself. All ships that can have both a pirate and trader role are by default defined with a pirateAI and a bounty of zero. That means that if the script adds a ship with role pirate is will keep the pirateAI and thus behave like a pirate but it will be clean.

@@ Line 20: / Line 20: @@
  sun skim law/bounty hunter vessels
  thargoid warships
- asterois clusters
+ asteroid clusters
 The amounts the system came up can you also see in the logfile on your computer. There are two routes populated. Normal ships on route 1: witchpoint->planet and a few sunskiming vessels on route 2: sun<->planet

@@ Line 3: / Line 3: @@
 Adding ships can happen in two ways within Oolite. They can be added with the build in  system populator, or they can be added with script commands. It looks the same but it works differently and also the result could be quite different. As this is often not well understood this goes sometime wrong in OXP's resulting in ships that behave differently than intended by the author.
-The common thing for adding ships is the "roles" key. In this key one can define several roles for a ship. When a ship is added by role, Oolite searches all the ships having this role and selects one at random from this list. If you put a number directly behind the role without a space you can also influence the change of selection. 1.0 is normal change.  see also [[shipdata.plist]]
+The common thing for adding ships is the "roles" key. In this key one can define several roles for a ship. When a ship is added by role, Oolite searches all the ships having this role and selects one at random from this list. If you put a number directly behind the role without a space you can also influence the chance of selection. 1.0 is normal chance.  see also [[shipdata.plist]]
  e.g.  roles:        trader(1.0) pirate(2.0) hunter(0.25)
@@ Line 24: / Line 24: @@
 The amounts the system came up can you also see in the logfile on your computer. There are two routes populated. Normal ships on route 1: witchpoint->planet and a few sunskiming vessels on route 2: sun<->planet
-But now comes the most important part: All ships are defined in the shipdata.plist with only one bounty, one ai_type and one scanClass. However, pirates, traders and police must have complete different AI files to make them behave differently. Also should the bounty be different to make them clean, offender or fugitive. The populator does this by overwriting any existing ai_type and bounty with its own. scanClass is not overwritten but if scanClass was not set it then set as listed below.
+But now comes the most important part: All ships are defined in the shipdata.plist with only '''one''' bounty, '''one''' ai_type and '''one''' scanClass. However, pirates, traders and police must have complete '''different''' AI files to make them behave differently. Also should the bounty be different to make them clean, offender or fugitive. The populator does this by overwriting any existing ai_type and bounty with its own. scanClass is not overwritten but if scanClass was not set it then set as listed below.
 For law/bounty-hunter vessels the populator selects ships with role police, interceptor or hunter.

@@ Line 9: / Line 9: @@
 What happens with the ships parameters after selection is however different with the two adding methods.
-== adding ships by the system populator ==
+== Adding ships by the system populator ==
 When a player enters a system after a witchspace jump or after starting a new game, the system must be populated with ships. First the populator looks at the Government and the Economy  to determine how many ships of a kind should be added for that particular system with a large random variation. The groups are:
@@ Line 42: / Line 42: @@
 The auto selection of a AI by the populator can be overwritten again by a script in the [[scripts_within_shipdata|launch_actions]].
 Besides this all the normal ships get a pilot appropriate for its role, even if the ship has no escape_capsule.
 == adding ships with a script ==