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

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 route2patrolAI if placed on route 2. interceptors get a police role after adding. 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

In the past script added ships behaved different than populator added ships, but since Oolite 1.69 this is fixed by the introduction of an auto_ai key in shipdata.plist. If this key is set to YES, the system switches AI's and bounties in the same way as the populator. Or actually it switches them according to an autoAImap.plist that resides inside Oolites config folder. In current Oolite versions the addition by the populator or by a script will result in the same settings.

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 "SCARCE_GOODS", while ships heading from the station have a higher likelihood of carrying "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, 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.