Role

This page was last edited in 2012. For current roles see Oolite Ship Roles.
(For more on AIs see the notice on OXP howto AI).

Overview

Currently most common roles encountered in Oolite:

trader, scavenger, hunter, miner, pirate, thargoid, police, wingman, interceptor, escort, shuttle, station, asteroid, missile, cargopod, etc.

Roles are specified in shipdata.plist.

---

Disclaimer: The text below is an impromptu explanation from LittleBear, and he makes a point of noting that he will want to "tidy up" this article in the not-so-far future. As this is as yet the only exhaustive article about this topic on the wiki, however, it might be added that perhaps he is being overly critical about himself here :)

The explanations about scan class and its relation to the roles of police, wingman and interceptor are from Ahruman, "What they do" from Commander McLane.

What they do

The purpose of roles is - simply said - to call an entity into being, with a specific role, like the role some actor plays in a movie or theater. The actor with the role Hero is - in most cases at least - different from the actor with the role Villain, and again different from the actor with the role Gentle Maid. That means that the set of properties attached to each of them is different. Hero: good, Villain: bad, Gentle Maid: helpless and in love with the hero. This set of properties is in Oolite defined in shipdata. So the only logical and convenient way is to have a different shipdata-entry for each role. And a play or movie in which the hero, the villain and the gentle maid are just the same character usually makes not much sense.

How they work

The Role given will determine the ships behaviour and when the game adds it. Oolite will give a ship called as an escort the correct bounty if the bounty key is left out, but will over-ride if one is added. In an entry for a ship with a role “escort” don’t put in any bounty key at all. If the ship is called as a pirate escort then it will be an offender. If called as a clean trader’s escort it will be clean, provided it has no bounty key set in ship data. If you give it a bounty it always has this one. So if you gave a Longshot bounty zero then it will still be clean when escorting a pirate. Escorts really therefore need a separate entry with no bounty key set and only the role escort set for that entry. This is why you really need a separate entry for each type of ship. Just adding roles to the same ship data entry means you get Clean pirates and Offender police ships if the bounty key is included. This is a summary of what the various in-built roles do:

TRADER: The game adds traders to the system space lanes. They also witch into systems and then fly to the station. Space Stations (including OXP ones) also launch traders every so often. The ships get either exiting trader or entering trader AI. Exiting traders launch from the station and witch-out (once out of the station's mass-locking effect). About 10% of the exiting traders will not witch-out but go for the sun instead. Entering traders fly to the station. Traders are basically cowards however. Dice are rolled when a ship is attacked. But basically traders are likely to run away from a single shot and will flee (not using weapons – just deploying escorts) if hurt. They also plead for their lives and send distress calls at the drop of a hat. This is so regardless of how well-armed or powerful the ship is. If it is called as a trader it has a trader’s personality. Although not a bug in terms of crashing the game, it causes strange behaviour to give powerful ships the role trader. Although simply adding the role “trader” to the Imperial Courier, Tiger does not crash the game, it introduces strange behaviour. A Condor with the role trader attacked by a single pirate Adder is quite likely to flee and plead for its life rather than swat the irritating ship with its multiple plasma cannons! I would suggest not giving any decent ships the role trader. Better to use these as hunters or pirates. You also shouldn't give big ships this role. They’ll hit the station and the station is sent whizzing off into deep space by the impact. They’re also too big to be launched and can get stuck.

SUNSKIM-TRADER: This is just a variation of a trader. It is only used to select sunskim-capable ships from the installed ships. Once selected, it is assigned a normal "trader" role in game.

SCAVENGER: Scavengers are only ever launched by Stations (including rock hermits, Space Bars and the like) when cargo is detected nearby. Scavengers never appear in the space lanes generally. If you are going to make a ship a scavenger it must have a separate entry with only the role scavenger. It must have fuel scoops and must also be a ship with cargo capacity. Its AI will tell it to scoop up the loot (remember it will not have appeared unless loot is about) and then go back to the station which launched it. If the ship does not have both scoops and a cargo bay, nasty AI bugs happen because the ship is being ordered to do something that it just cannot do. Its AI will hang, causing the ship to freeze and chew up a lot of run time slowing the game down. Scavengers are also cowards. Because they appear near a safe haven, they always run away from attack. Giving powerful ships this role causes weird behaviour. If Commander Jameson with his pulse laser takes a pot shot at a Tiger Scavenger the Tiger is very likely to flee! Personally I wouldn’t give any powerful ship the role Scavenger and big ships given this role are likely to crash on launch.

MINER: When the game adds asteroids there is a random chance that it will also add some miners nearby to the cluster. The Ship will scan for asteroids, shoot them, scan for rocks then scoop the rocks. It must therefore have a separate entry with a Forward Mining Laser (NPCs cannot use left or right guns and rarely use a rear gun) and fuel scoops. Without this its AI will hang as it cannot do what it has been told to do. It also must be a ship that has a cargo bay. Because a mining laser is total pants as a weapon, miners will always flee attack (they are effectively unarmed). Giving powerful ships this role will cause unrealistic results. Better to save it for the medium and low level ships.

PIRATE: A pirate ship needs a separate entry if you are going to set the bounty. It must have fuel scoops and a cargo bay, as its AI will tell it to scoop cargo lying around. Don’t give the role pirate to Police or Navy Ships obviously! Also don’t give a ship with no cargo bay the role pirate (as it will never do any pirating). The pirate AI checks its hold. If full it switches AI, stops hunting and heads for the station. In this mode it won’t attack unless attacked and usually runs for the station. This makes sense as from a pirate's point of view there’s no point fighting if he cannot grab the goodies. If you give a ship with no cargo bay the pirate role, its hold is always full so it doesn’t really behave properly. If its hold it not full, it looks for any cargo pod lying about and grabs them. Having no fuel scoops will cause an AI hang. If no cargo is about it lurks in the space lanes and attacks the nearest ship it spots with the role trader, the player or ships that are on a special pirate-victim-roles list.

ESCORT: Escorts always fly on the wing of ships with escorts and follow 'Mum' about. They will defend Mum against attack and will attack any ship that Mum decides to attack. If Mum is a pirate they’ll act as pirates, but only attacking when Mum decides to attack. Really only fighters (including powerful ships like ICs and Tigers) should be escorts. Don’t give slow ships like Pythons escort roles. It doesn’t really make sense for fighters to be escorts. AI problems will also happen with cruisers (Condors etc.) being given escort roles. The escorts form up with Mum and try to fly on her wing. But if you give a slow ship Escort role, it is likely not to be able to keep up with Mum and you get the escort hanging its AI or just wandering around as it's lost its mother ship. In terms of realism, I’d also make powerful escorts rare. The pilot of a Tiger is one rich commander to have bought the ship. Once in a while a trader might be able hire one, but it should be a rare event. Also it will act as a wingman to a pirate. If an Imperial Courier is a pirate it makes more sense for him to be leading the attack than hanging on the wing of a Python.

SHUTTLE: Shuttles are launched by stations and fly to the planet. They also take off from the planet and dock with stations. Big ships will crash into the station or get stuck in the docking bay. They are also total cowards and NEVER fight back if attacked. This makes sense in the native game as only Worms, Shuttles and Transporters have this role. As these ships are all unarmed, they cannot fight back so it makes sense for the AI to tell them to always run. If you give another ship this role (however powerful it is) it will always run. Condors fleeing Adders doesn’t really look good. When a ship with a shuttle role collides with a planet, this is interpreted as a landing, any other role would just crash.

HUNTER: These ships cruise the space lanes and attack offenders and ships with bounties (including the player, of course). They are pretty brave in combat only fleeing if really badly hurt and sometimes fight to the death. I’d use powerful ships here. Hunters, like police, can accept escorts of the same scan_class as itself, even when the ship was defined with zero escorts.

POLICE & INTERCEPTOR: Police and interceptors are ships that search the system for offenders and ships that attack clean ships. Interceptor should be an advanced version of plain police ships. Whenever Oolite wants to add police, it first looks at the technical level of a system. In low-tech systems it adds ships with role police, while in high-tech systems it becomes more likely that interceptors are added. The interceptor role is only used for selecting superior police ships among the installed ships. After adding interceptors to the game, they get a "police" role like the normal police. police & interceptor roles are also used to select the default defense ships of stations. On launch all defense ships will get a "defense_ship" role. Creators of ships should avoid to assign both a police and interceptor role to the same ship. They should make a choice between them. This will help the system to better differentiate the choice of ships between high and low-tech systems. The role choice that the populator uses, reads in JS code:

var role = (Math.random()*7+6 <= system.techLevel) ? "interceptor" : "police";

WINGMAN: ONLY police ships should be given this role. A wingman forms up on the wing of a ship with the role POLICE. It is random whether a police ship has Wingmen (and how many), but this is how the game creates the little squadrons of cops that you sometimes see flying in formation. Really only small police ships should have this role. A Viper flying lead to a Condor doesn’t look that good (the Condor is also likely to get an AI failer as a wingman – as it cannot keep up with the Viper). It's better really not to use powerful ships as wingmen - use them as police instead. That way a cop Super Cobra or Condor will be the lead ship with a few small ships on his wings. When after a fight the lead-ship was destroyed, one of the wingman will change to police role and the remaining wingman will follow him.

HERMIT-SHIP: hermit-ship is the default role for defense ships of stations with a rock scan-class (like rock hermits). The "hermit-ship" role is only used to select ships from the installed ships. On launch all hermit-ships ships will get a "defense_ship" role.

CARRIER: The role 'carrier' was used in the past to define a ship as being a carrier. This role however is deprecated in favour of the shipkey 'is_carrier'. and should no longer be used. Carriers should be given a customAI. But really it's not a good idea to call carriers by a standard game role as they’ll get launched and get stuck. You’d need to give them a custom AI and it would be better really to place them by script.

CARGOPOD & 1t-CARGOPOD: cargopod is the default role for cargo. 1t-cargopod is a special role that is exclusively used to fill up the player ship when he launches from a station. Besides cargopod, cargo can also have a commodity role. Whenever Oolite want to fill pods with a specific commodity it first has a 50% chance of selecting a cargopod that uses that commodity in its roles. The other 50% a pod with role 'cargopod' is used.

ALLOY: alloy is the role used by metal pieces that are released and remain in the system when a ship explodes. The total amount of alloy that is released in explosions depends on the ships mass.

WRECKAGE: wreckage is the role used by metal pieces that are released at a high temperature when a ship explodes. Wreckage only lives for a short moment (0.25s till 1.25s) and is scaled on explosion to a certain percentage of the size of the exploding ship. The total amount of wreckage that is released in explosions depends on the ships mass and the shipkey 'fragment_chance'.

Special cases

How the police roles (police, wingman, interceptor) & police scan class (police) work:

The only supported configuration for police is scan class police, bounty 0 and one of the roles police, interceptor or wingman. Interceptors are generated in addition to police in high-tech systems, while wingman is used instead of escort for police ships with an escort's property. The primary distinction between wingmen and escorts is that wingmen turn into police with route1patrolAI if their owner dies.

---

Links

• OXP howto AI - and see links at page bottom
• Qs about Roles/AIs (2013) with examples explained line by line
• See here for more detail on how "auto-weapons" links with the roles

Role and probability of appearance

• Commander McLane on how role-probability works (2009) Why globe stations will almost never show up if you have PAGroove's Stations loaded too.