Oolite System Populator - Revision history

Debresser: Category:Oolite

2016-01-22T01:20:51Z

Category:Oolite

Debresser: Page moved. No need for _ in links.

2016-01-16T20:52:26Z

Page moved. No need for _ in links.

Cim: Remove 1.79 warning

2015-02-05T20:02:57Z

Remove 1.79 warning

Cim: /* The system populator function */ clarify deterministic

2014-04-14T19:48:08Z

‎The system populator function: clarify deterministic

Cim: System populator documentation

2013-10-04T21:31:10Z

System populator documentation

New page

'''This page describes the Oolite System Populator in version 1.79 or later'''. It is currently subject to change without notice.

The Oolite System Populator has three parts:
# Via [[planetinfo.plist]] populator and repopulator functions are defined. Different functions may be defined for different systems.
# The populator function is called whenever a new system (or region of interstellar space) needs populating: immediately after the [[Oolite_JavaScript_Reference:_world_script_event_handlers#startUp|startUp]] world event, and immediately before the [[Oolite_JavaScript_Reference:_world_script_event_handlers#shipWillExitWitchspace|shipWillExitWitchspace]] world event. It acts like a world event itself, but does not have a fixed name. This function should use [[Oolite_JavaScript_Reference:_System#setPopulator|system.setPopulator()]] to set up system population.
# The repopulator function is called every twenty seconds of [[Time_scales_in_Oolite#Game_real_time|game real time]]. This function should use functions like [[Oolite_JavaScript_Reference:_System#addGroup|system.addGroup()]] and [[Oolite_JavaScript_Reference:_Station#launchShipWithRole|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''': <code>systemWillPopulate</code> and <code>systemWillRepopulate</code>
* '''For interstellar space''': <code>interstellarSpaceWillPopulate</code> and <code>interstellarSpaceWillRepopulate</code>
* '''For nova systems''': <code>novaSystemWillPopulate</code> and <code>novaSystemWillRepopulate</code>

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 [[Oolite_JavaScript_Reference:_System#setPopulator|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 [[Oolite_JavaScript_Reference:_System#populatorSettings|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 <code>system.addShips</code> or <code>system.addGroup</code> 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 <code>groupCount</code> is greater than zero and a <code>locationSeed</code> 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 <code>location</code> 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 <code>location</code>s other than "COORDINATES".
* '''deterministic''' : a boolean, default false. If this is true (only possible when using "COORDINATES" or a non-zero <code>locationSeed</code>, 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. (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.

← Older revision		Revision as of 01:20, 22 January 2016
Line 45:		Line 45:

	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.		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.
		+
		+	[[Category:Oolite]]

← Older revision		Revision as of 20:02, 5 February 2015
Line 1:		Line 1:
−	'''This page describes the Oolite System Populator in version 1.79 or later'''. It is currently subject to change without notice.
−
	The Oolite System Populator has three parts:		The Oolite System Populator has three parts:
	# Via [[planetinfo.plist]] populator and repopulator functions are defined. Different functions may be defined for different systems.		# Via [[planetinfo.plist]] populator and repopulator functions are defined. Different functions may be defined for different systems.

@@ Line 1: / Line 1: @@
 The Oolite System Populator has three parts:
 # Via [[planetinfo.plist]] populator and repopulator functions are defined. Different functions may be defined for different systems.
-# The populator function is called whenever a new system (or region of interstellar space) needs populating: immediately after the [[Oolite_JavaScript_Reference:_world_script_event_handlers#startUp|startUp]] world event, and immediately before the [[Oolite_JavaScript_Reference:_world_script_event_handlers#shipWillExitWitchspace|shipWillExitWitchspace]] world event. It acts like a world event itself, but does not have a fixed name. This function should use [[Oolite_JavaScript_Reference:_System#setPopulator|system.setPopulator()]] to set up system population.
+# The populator function is called whenever a new system (or region of interstellar space) needs populating: immediately after the [[Oolite JavaScript Reference: World script event handlers#startUp|startUp]] world event, and immediately before the [[Oolite JavaScript Reference: World script event handlers#shipWillExitWitchspace|shipWillExitWitchspace]] world event. It acts like a world event itself, but does not have a fixed name. This function should use [[Oolite JavaScript Reference: System#setPopulator|system.setPopulator()]] to set up system population.
-# The repopulator function is called every twenty seconds of [[Time_scales_in_Oolite#Game_real_time|game real time]]. This function should use functions like [[Oolite_JavaScript_Reference:_System#addGroup|system.addGroup()]] and [[Oolite_JavaScript_Reference:_Station#launchShipWithRole|station.launchShipWithRole()]] to add new ships to the system as required to replace those which have been destroyed, or for other new arrivals.
+# The repopulator function is called every twenty seconds of [[Time scales in Oolite#Game real time|game real time]]. This function should use functions like [[Oolite JavaScript Reference: System#addGroup|system.addGroup()]] and [[Oolite JavaScript Reference: Station#launchShipWithRole|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 ==

@@ Line 30: / Line 30: @@
 * '''coordinates''' : this must be a valid Vector expression if <code>location</code> 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 <code>location</code>s other than "COORDINATES".
-* '''deterministic''' : a boolean, default false. If this is true (only possible when using "COORDINATES" or a non-zero <code>locationSeed</code>, 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. (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.
+* '''deterministic''' : a boolean, default false. If this is true (only possible when using "COORDINATES" or a non-zero <code>locationSeed</code>, 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===