System Populator

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 chance of selection. 1.0 is normal chance. 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 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.