System Populator - Revision history

Cholmondely: Added note

2025-07-08T22:00:11Z

Added note

Cholmondely: Added Links

2025-06-05T01:28:01Z

Added Links

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

← Older revision		Revision as of 22:00, 8 July 2025
Line 1:		Line 1:
		+	This page dates back to before 2013 and focuses on legacy methodology. For more recent populatory possibilities see [[Oolite System Populator]].
		+
	=Adding System Ships =		=Adding System Ships =

← Older revision		Revision as of 01:28, 5 June 2025
Line 52:		Line 52:

	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.		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.
		+
		+	== Links ==
		+	*[[Oolite System Populator]] - more on this
		+	*[[Configurable Populator]] - OXP for adjusting some populations in-game
		+
		+	*[https://bb.oolite.space/viewtopic.php?f=3&t=8117 System.addShips] (2010 BB discussion)
		+	*[https://bb.oolite.space/viewtopic.php?t=8104 Placing objects in Oolite space - understanding the co-ords] (2010 BB discussion)
		+	*[https://bb.oolite.space/viewtopic.php?t=8188 ship populator code] (2010 BB analysis)

	[[Category:Oolite scripting]]		[[Category:Oolite scripting]]

@@ 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 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 ==
-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
+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.
-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.
+== Adding cargo to npc ships ==
-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).
+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.
-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.
+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.
 [[Category:Oolite scripting]]

@@ 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 43: / Line 43: @@
 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 ==
+== 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