Escort Contracts OXP

From Elite Wiki
F4 screen with escort contracts offered
Contract selection screen
Contract selection map screen
Let's go!
Torus drive synchronisation
Escort Contracts5.png
Screenshot by Makara


Allow players to enter into short-term escort contracts with NPC lone wolf traders.


The Independent Traders and Hauliers Association have reacted to demand from lone wolf NPC Traders and introduced a system to allow them to enter into short-term escort contracts with vetted and rated freelance escort pilots.

Players who wish to access these contracts must purchase an I.T.H.A Independent Escort License available to players with a Clean legal status at systems with a Tech Level of 3 or above which and not Anarchies, Feudal States or Multi-Governments.

Once purchased, players whose legal rating is still Clean may be offered short term escort contracts on docking at a system’s main station. The chance of being offered contracts is based on the player’s reputation as an escort. The fees offered are also affected by the player’s reputation as an escort and government type of the target system. Target systems are always within 1 jump of the starting system. Reputation is increased when a contract is successfully fulfilled and reduced when a contract is failed or aborted.

Once a contract is agreed the player has 3 game hours to launch from the station or the contract is failed (be careful about buying equipment – it takes up time). The NPC trader (or mother) will be waiting in the station aegis and will prompt the player to approach as they prepare to jump to the target system. The player can follow them through their wormhole or alternatively jump themselves to the target system. Failure to arrive at the target system by the point the wormhole expires ends the contract.

Once in the target system the player’s task is to escort the mother to the system's main station. Mothers will issue various prompts to players in flight, will request assistance if attacked, and will assist the player if the player is attacked. The contract is fulfilled once the mother has entered the aegis of the target system's main station - unless there are hostile craft in the vicinity - in which case the player must stand by to protect the mother until it has safely docked.

If you have an Advanced Space Compass installed the mother will be marked with an ‘M’ beacon code.

Game Balance and Playability

In order to avoid these contracts being long and rather dull in between hostile encounters, this OXP gives the mother the ability to 'synchronise jump drives' with the player. The mother has been given scan_class CLASS_ROCK (but with custom scanner colours) so it will not mass-lock the player. In flight if there is nothing else to mass-lock the player the mother will prompt the player to approach to between 500m - 2500m and to match heading. If the player does so the mother will synchronise jump drives with the player and both mother and player will travel on the mother’s heading at torus speeds, until the player or mother is mass-locked again.

If the player is mass-locked (but with no hostile contacts in the vicinity) the mother may after a short delay decide to try and use injectors to get out of the mass-locked situation so that the player and mother can take advantage of the mother’s synchronised jump drive capability. This feature will only operate if the player also has working injectors and at least 1 LY of fuel.

Mothers will normally be an Anaconda, Boa, Boa Cruiser or Python and will come equipped with ECM, injectors, and fore & aft beam lasers as standard.

Technical notes

Escort Contracts By Capt Murphy 2011,2012 until version 1.5.6 (07/05/12). Requires Oolite 1.76.

Updated to work with Oolite V1.77's interfaces screen (and other updates) by Keeper, new background images by ZygoUgo and fixes by Norby in version 1.6.1 (01/27/15). Requires Oolite 1.77.

Licence of all versions: CC BY-NC-SA 3.0 : Please visit for more info.

The shipdata.plist is set up to 'like_ship' to the core versions of these ships (or a retextured version if the core versions have been replaced by a retexture OXP), and if installed any of the versions from retexture OXPs that add variants in addition to core ships. Currently supported are Griff's, DeepSpace, Shady Sungs, Smiv's and Neolite Core.

If you have a retexture pack installed that does not replace the core models and want to suppress usage of the core models in this OXP you can edit the shipdata.plist to reduce the roleweighting of the core ships. Instructions are included in the shipdata.plist as comments.

The shipdata.plist is also set up to use these OXP ships as potential mothers if installed: From Neolite Companion : Monitor, Python Cruiser, Python ET Special; From Old Ships 2010 : Monitor, Monitor2; From Far Arm Ships : Tanker; From Clippers: Python Clipper, Boa Clipper; From Staer9's Shipset: Monitor, Python Cruiser, Python ET Special.

You can use these entries as a template to use ships from your favorite OXP. However be wary of doing this with any OXP ship that normally requires its own shipscript, or is too large to dock at a normal station as the results may be unpredictable.

Changes in v1.5.9

No longer will new contracts be shown when you dock at a station (though results of an existing mission will be, as usual). Instead, if a contract is available, you will find an "ITHA Escort Contracts" entry on the interfaces screen (F4 or 4 while docked at a main station) showing you how many are available.

When you view the contracts, you still have the option of viewing the Short Range Chart, but instead of actually going to the real Short Range Chart GUI, it loads the chart as an overlay, so you have an immediate ability to accept or decline the contract while looking at the chart (thanks to cim for the heads-up about this new feature).

That Short Range Chart view also will give you the key information (trader name, destination, pay, and risk) in a terse form at the top of the screen, so you won't have to memorize what the contract entailed. It also will display the economy type, government type, and tech level of both the current and the destination system, to help you decide which contract to accept if you're carrying cargo yourself.

All the menu selections have been aligned to the right of the screen, so that when viewing the chart, the text is out of the way of the planets and your fuel range. Also, all the menu selection positions will be maintained. For example, when you "View next contract", the next page will have "View next contract" pre-selected, so you can page through offers more easily. Also, the "Agree" option will never be pre-selected, so you can't accept an offer by mistake. When you have toggled the chart view on, it will remain on when you view the next or previous offer.

If you decline the contracts, the offers will stay available up to a point. The timer that the OXP had before while you were looking at the chart is still running.

When the timer expires (a random time but usually a few hours), the contract offers will disappear and no new offers will be made. That's different than the original OXP. Fact is I never got it to work right when having it create new offers. Either all the variables were empty or it accumulated a huge number of new offers. I'm sure it's possible to get it right, but in most cases you're not going to be at the station long enough (even doing ship maintenance) for the offers to go away, so it's not a big deal.

Of course, you also can launch from the station, turn around and re-dock, hoping to see new offers turn up... It is left to people who actually are programmers to work out a more robust system of preventing such a "cheat" way of fishing for better contracts.

You may find offers available when you load a saved game, so you may not actually have to go somewhere else to continue your escort work. (I say "continue" because it still will check to make sure that you have purchased an ITHA licence and that you have a Clean legal status.)

There are now three different success screens, so that it won't mention getting a bonus if you made no kills during the trip, and it will use the singular "kill" if you got only one.

The Griff Prototype Boa has been added as a potential mothership. I only used the one that gets decals from the texture's alpha channel, as that "alpha" version is the only one whose role normally always is a trader (the others are or can be pirates), so it looks best that way.

Spelling was corrected, but don't be worried about me being American; I left in the UK spelling of things like "hauliers", "initialising", etc. I simply corrected misspellings of "its", "independent" (adjective), "en route" etc., and added commas where needed and replaced commas with full-stops where needed.

With the initial screen now eliminated, that meant losing one of ZygoUgo's new background images... or at least it would have if I hadn't moved it to the "contract accepted" screen!

There is a harmless quirk you may encounter when loading a saved game. Sometimes, you'll see the IHTA Escort Contracts menu item on the interfaces screen with "0 available". Most of the time, the menu item will not appear when there are no contracts available, but I guess it is possible for you to go to the F4 screen before the menu removal code has run. It doesn't cause any problems, and the line goes away when you go to another screen and then back to the F4 screen.

Change Log

Version 0.9 (24/4/11) - Initial Release.

Version 0.9.1 (29/4/11)

Fixed a bug in detecting player kills (the mother should pay a bonus for hostile kills made during the contract - was broken in version 0.9).

Added code for mother to use injectors to try and escape from mass lock situations after a few minutes.

Made criteria for contract success arrival in target system's station aegis rather than mother safely docked to save player time.

Replaced shield enhancers with shield boosters as standard equipment for mothers as they were a little too uber.

Added code to stop the I.T.H.A. Independent Escort License being damaged in combat.

Added an additional world script which displays the players escort reputation on the manifest screen.

Version 0.9.2 (29/4/11)

Fixed a small bug in calculation and display of contract prices.

Version 1.0 (8/5/11)

Added a cap to escort reputation.

Removed shield boosters as standard equipment for mothers and gave them fore beam lasers instead of military lasers. Mothers now really do need your help to survive an encounter with multiple hostiles.

Many improvements to the AI for the mother using injectors feature.

Fixed a cosmetic bug in the mission screen timing.

Fixed a bug where the mother could still be found waiting to dock after the player had docked, met the mother’s pilot in the bar, got their reward and re-launched.

Improvements and bug fixes to the combat AI, mainly relating to mother - player communication.

Removed player auto targeting mother’s primary aggressor (potential for confusion if other auto target-locking OXP’s are installed).

Adjusted criteria for contract success. If no hostiles in vicinity the contract is fulfilled once the mother is in the station aegis. If there are hostiles in the vicinity when the mother arrives in the aegis the player must not dock until the mother is safely docked to fulfill the contract. The mother will explicitly tell the player this on arrival at the station aegis.

Added code so that if repeatedly attacked by the player, the mother will eventually ‘turn’ and attack the player. The contract is immediately failed at this point.

Added code so the timer that checks to see if the player has followed the mother through it’s wormhole kicks as the wormhole closes. Uses same calculation as oolite engine to work out wormhole expiry time depending on the mother ship mass.

Version 1.1 (15/6/11)

Various improvements to AI following tester reports of occasional anomalous docking and route finding behaviour.

Added a pilot and cargo to the mother (thanks to Eric Walch for the tip).

Added code to gradually reduce a positive or negative escort reputation over time.

Added code so that any fire from a players ‘Hired Guns’ from the OXP of the same same are treated as Friendly Fire.

Version 1.2 (13/7/11)

Fixed dockingAI that would not parse correctly on Mac systems.

Tweaked and tidied the synchronised jump code. Player must be between 500m-2500m and on approximately same heading as mother before synchronised jump will happen. The minimum distance has been introduced to avoid mother making course changes whilst hopping due to avoiding ‘collision’ with the player.

Added an additional check to avoid anomalous communication from the mother when docked.

Version 1.3 (7/8/11)

Added code to Mission Screen handling to allow access to Short Range Chart whilst perusing contracts.

Added check to avoid contract being offered to post-Nova system.

Version 1.3.1 (7/8/11)

Fixed missiontext.plist that would not parse correctly on Mac systems.

Version 1.4 (19/9/11)

Changed synchronised jump mechanism to use ship.velocity and a frame callback to simulate synchronised jump behaviour rather than a ‘teleport/hop’. Change prompted by reports of original method causing a crash to desktop on some systems (seemingly caused by changing the mother’s ship.position by script), and retained as the effect is more pleasing. Thanks to FleurdeMal for reporting the crash and testing the revised version.

If player leaves mission screen to access short range chart and does not return within a fairly short time period there is a chance that the contracts on offer will have changed.

Tweaked AI for initial hyperspace jump to reduce incidence of mother trying to jump when jumps are blocked by the station’s mass.

Version 1.4.1 (24/9/11)

Minor tweaks. Can now access both short range and long range charts and return to mission screens.

Tweaked the AI, so mother more likely to use injectors if mass-locked repeatedly by same NPC.

Version 1.4.2 (20/11/11)

Some tweaks to the mother ship-script to reduce processing overhead.

Fixed small bug where player was rewarded extra for a ‘hostile’ kill even if the kill was an asteroid or boulder.

Version 1.5 (28/1/12)

Made JS strict mode compatible.

Made Save Anywhere OXP compatible.

Reduced use of missionVariables.

Tweaked calculation of contract rewards - average is 25% lower than previous versions but with significant random variation.

Kills are only counted by the mother if the player is within 3 x her scanner range.

If mother is 'abandoned' by the player for any length of time there is a chance she will be ambushed by pirates - frequency is higher in more dangerous government types.

Added a little randomness to some of the comms messages from the mother.

Eliminated unneccesary and irritating repeat comms messages, particulary the 'Jump Drive Synchronised' message.

Added a background image to mission screens.

Made the code to remove mother ship from ooniverse on contract failure more robust.

Found and fixed a few potential bugs if the player does something 'weird' such as not dock to collect the reward at the end of a contract.

Version 1.5.1 (05/02/12)

Fixed small bug in display of reputation introduced in last release.

Reduced frequency of some other comms messages in response to user feedback.

Expanded shipdata.plist to use ship variants as mothers from the 5 main retexture shipsets if available, and several other OXP ships if available.

Version 1.5.2 (05/03/12)

Tweaked AI to stop mother injecting indefinately in fleeing from attack in starting system.

Reduced max speed of escort contracts variant of Boa Clipper.

Enabled entries for the addition version of Smiv's v4 shipset.

Version 1.5.3 (05/03/12)

Fixed small bug where player was rewarded extra for a ‘hostile’ kill even if the kill isCargo.

Version 1.5.4 (21/04/12)

Tweak to the chances of contracts being offered. Was in a range of 25% to 100% depending on escort reputation, now a range of 20% to 80%.

Set specific spawn position for mother of 19km directly behind main station to avoid issues with bigger stations (e.g the Torus) (thanks to cim for bug report and suggestion for appropriate fix).

Version 1.5.5 (05/05/12)

Added Staer9 shipset versions of the Monitor, Python Cruiser, & Python ET Special as potential mother variants if the OXP is installed.

Made the Escort License transferable equipment when buying a new ship.

Version 1.5.6 (07/05/12)

Mother spawn position set to sphere radius 4km centred on a spot 14km directly behind main station.

Mother will hold this position until player approaches and then start moving directly away from station/planet rather than towards witchpoint, whilst preparing to jump.

If mother's maxSpeed is greater than 95% of player.ship.maxSpeed she will limit her cruising speed and injector speed to 95% of equivalent player.ship.maxSpeeds (apart from in combat).

Fixed logic bug with behaviour controlling when to start/stop injecting. Starting was based on player's mass lock status, ending on the mothers. Ending now checks both.

Increased frequency of check to stop injecting to every second - previously every 3 seconds.

Thanks to Lone_wolf and cim for highlighting the issues leading to these tweaks.

Version 1.5.9 (2013-05-05)

Unofficial update to work with Oolite V1.77's interfaces screen (and other updates) by Keeper and new background images by ZygoUgo.

Version 1.6.1 (2015-01-27)

Fixes by Norby.

Version 1.6.2 (2015-06-09)

Fixes by Chimrod.

Version 1.6.3 (2015-08-25)

Fixes by phkb.

Version 1.7.1 (2015-12-04)

Several fixes and other changes by Fritz. Most non-bugfix changes apply to the comms messages which are now randomly variable and won't be repeated too often anymore.

Download Links

Version 1.7.1: Escort_Contracts_1.7.1.oxz (downloaded 2779 times)

Older versions:

Version 1.6.3: (a fix for the mission screen by phkb, only for use with Xenon HUD)

Version 1.6.2: Escort_Contracts_1.6.2.oxz (downloaded 1459 times).

Version 1.6.1: Escort_Contracts_1.6.1.oxz (downloaded 954 times).

Version 1.5.9 OXZ: here for Oolite 1.79 or later (downloaded 1760 times).

Version 1.5.9 OXP: Zy&K Escort Contracts for Oolite 1.77.

Version 1.5.6: for Oolite 1.76. Also mirrored on JazHaz's Box.

Feedback can be left on the OXPs discussion topic at Oolite BB.

Quick Facts

Version Released License Features Category Author(s) Feedback
1.7.1 2015-12-04 CC BY-NC-SA 3.0 Contracts for escorting and protecting NPC traders Missions OXPs Capt. Murphy and others BB-Link