Oolite System Populator

The Oolite System Populator has three parts:

1. Via planetinfo.plist populator and repopulator functions are defined. Different functions may be defined for different systems.
2. The populator function is called whenever a new system (or region of interstellar space) needs populating: immediately after the startUp world event, and immediately before the shipWillExitWitchspace world event. It acts like a world event itself, but does not have a fixed name. This function should use system.setPopulator() to set up system population.
3. The repopulator function is called every twenty seconds of game real time. This function should use functions like system.addGroup() and station.launchShipWithRole() to add new ships to the system as required to replace those which have been destroyed, or for other new arrivals.

Defining populator functions

There are three default populator and repopulator functions.

• For normal systems: systemWillPopulate and systemWillRepopulate
• For interstellar space: interstellarSpaceWillPopulate and interstellarSpaceWillRepopulate
• For nova systems: novaSystemWillPopulate and novaSystemWillRepopulate

OXPs which intend to add additional content to "normal" systems should define these functions in a worldscript, and use them to add to or amend the default population.

OXPs which wish to "take over" a system or systems should use planetinfo.plist to set a different populator function which is unique to their worldscript(s). This then prevents normal system population, including modifications from other more generic OXPs (provided those OXPs have been written to use this new population method, of course)

The system populator function

The system populator is a dictionary of populator definitions set by using the system.setPopulator() function. Existing definitions may be overwritten by specifying a new definition for that key, and the definitions set up so far may be read in system.populatorSettings

Each definition has the following required parameters:

• callback : a function which takes a single parameter, a Vector. This function when called should then add entities to the system at or near the Vector passed to it using the standard system.addShips or system.addGroup functions.

...and the following optional parameters:

• priority : a number. The default is 100. Populator definitions will be run in priority order, with ties broken randomly. Values below 100 should be considered reserved for Oolite if you are using the default populator functions, and only used with an understanding of the implications.
• location : a string which must either be "COORDINATES" (the default) or a region name. Region names are listed below.
• locationSeed : a number. The default is zero. If this is zero, the location is picked entirely randomly within the named region. Otherwise, it is picked using a seeded random number generator, guaranteed to give the same answer every time it is used in this system (but not the same answer as in other systems). If the groupCount is greater than zero and a locationSeed is set, an appropriate number of deterministic locations within the region will be picked, always in the same order.
• coordinates : this must be a valid Vector expression if location is "COORDINATES". It is ignored otherwise.
• groupCount : a number, default 1. This is the number of times the callback function will be called. It is only really useful with locations other than "COORDINATES".
• deterministic : a boolean, default false. If this is true (only possible when using "COORDINATES" or a non-zero locationSeed, and not in nova systems or interstellar space) this is a promise to Oolite that this populator function will always be called with these parameters if the player revisits this system, provided the OXP has the power to do so, and will always have the same effect when it is called. (i.e. it has not been uninstalled, had the system populator function changed under it, has its populator entries removed by another OXP, etc.). Currently secondary stations added by deterministic populators may allow the player to save and load the game. If the player saves the game at such a station, which is then not there when they reload the game, they will be returned to the main station as a safety measure.

Named regions

The following named regions exist in Oolite 1.79 or later.

• WITCHPOINT : A position within scanner range of the witchpoint. In interstellar space and nova systems, all named regions are equivalent to this. Unrecognised region names will also be treated as "WITCHPOINT"
• LANE_PS, LANE_WP, LANE_WS : A position on the space lane between the planet, sun and witchpoint, within two scanner ranges of the centre of the lane, and not within three radii of the planet or sun, or scanner range of the witchpoint.
• LANE_WPS : Picks one of the lane parameters, weighted to the lengths of the three lanes.
• STATION_AEGIS : A position within two scanner ranges of the main station, but not too close to the planet.
• PLANET_ORBIT, PLANET_ORBIT_HIGH, PLANET_ORBIT_LOW : A position less than 1 radii from the main planet's surface (low orbit), between 1 and 3 radii (orbit), or between 3 and 7 radii (high orbit)
• STAR_ORBIT, STAR_ORBIT_HIGH, STAR_ORBIT_LOW : As the planet orbits, but relative to the system's star's position and radius.
• TRIANGLE : A position in the the triangle described by the sun, main planet, and witchpoint, at least three radii from the sun and planet and three scanner ranges from the witchpoint.
• INNER_SYSTEM, INNER_SYSTEM_OFFPLANE : A position at least as close to the sun as the planet is, but no closer than three radii. If "OFFPLANE" is not specified, the position will be close to the plane described by the sun, main planet and witchpoint.
• OUTER_SYSTEM, OUTER_SYSTEM_OFFPLANE : A position at least as far from the sun as the planet is, but no further than 10,000km from it. Note that coordinates in this area may take the player 15 minutes or more to reach at full torus speeds, and ships travelling at conventional speeds may take several hours or even days to reach these locations from the inner system.

The system repopulator function

The system repopulator function will be called approximately every twenty seconds, and can be used to replace ships that have been destroyed. Generally such replacements should enter the system in a believable way - exiting witchspace near the witchpoint, by being launched from an appropriate station or the planet, or by some similar method. It is important for smooth gameplay that this function runs very quickly. If calculations are needed, run as many as possible in the populator function to save the result.

Comment

I hope that this is the right place for this note!

One of the reasons for the changes to the populator back in Oolite v.1.80 was to make it easier for stations to be placed individually at consistent per-system positions without them being also always being placed at the same consistent per-system positions as each other or even the same position in every system they're in. I'm not sure any of those OXPs have been updated enough since then to take advantage of that, however. Cim 2017

Links

• System.addShips (2010 BB discussion)
• Placing objects in Oolite space - understanding the co-ords (2010 BB discussion)