Fuel Tweaks
By phkb

Overview
========
This OXP came out of a BB discussion where the idea was to make fuel scooping both (a) more desirable, and (b) more likely to happen. This OXP seeks to meet these goals in the following ways:
    1. The fuel system can be tweaked in a number of ways. It can operate as normal, or fuel rationing could be in effect, limiting the amount of fuel that can be bought at stations. Refuelling stations can also be installed, which effectively moves the purchase of fuel to be outside the main station. All of these scenarios can be altered by settings in Library Config or Javascript functions (see below).
    2. Scooped fuel can be collected in fuel storage containers and sold for profit.

This is a concept OXP, designed to feed discussion and experimentation.

Commodities
===========
A new trade good has been added to the system: Quirium Fuel. This trade good gets its best price at mainly agricultural systems.

    Item            Description                         Average Price/cr    Units 
    Quirium Fuel    Fuel scooped from a star's corona               30.0    TC

Equipment
=========
The following equipment items have been added to the game:

Quirium Fuel Processor
----------------------
This device replicates some of the fuel scooping system except, rather than putting the fuel into the main tank, processed fuel is stored in specialised fuel storage containers. The Fuel Processor is automatically activated during the fuel scoop process when the ship's main tank is full. 

The Fuel Processor comes equipped with 1 fuel container, so simply by purchasing this item pilots will be able to scoop 1t of quirium fuel.

    Cost:           450.0 Cr
    Availability:   TL4

Quirium Fuel Storage Unit
-------------------------
Fuel storage units can store 1t of Quirium fuel. Until used they will not consume any cargo space. When fuel is scooped and processed the units will expand to hold the fuel. If Quirium Fuel is dumped, a fuel storage unit will be dumped with it. When it is scooped, the fuel storage unit will be scooped as well.

    Cost:           50.0 Cr
    Availability:   TL3

Quirium Fuel Transfer
---------------------
This prime-able device is a slightly unstable method of moving fuel from storage and into the main ship tank. Quirium fuel is highly volatile, and the connection between the fuel processor and all storage units is designed to be one-way during flight. The Fuel transfer device is a third party add-on which breaches some of the containment protocols of the storage units in order to extract fuel and dump it in the main engine fuel tank. There is a chance that cargo loss or equipment damage could result from the transfer process. There have been reports of complete ship destruction in extreme cases, but these reports are rare.

To transfer fuel during flight, prime the "Quirium Fuel Transfer" equipment, then press the "n" (activate) key twice to start transferring fuel. Press the "n" key a third time (or use the "b" (mode) key) to stop the process. For safety reasons, the process will stop automatically if you dock, begin a hyperspace jump or enter a wormhole.

A minimum 1t of Quirium fuel will be used regardless of how much is actually transferred to the main tank. Excess fuel is dumped to prevent any additional damage. For example, transferring 0.4LY of fuel will use 1t of Quirium. Transferring 6.4LY of fuel will also use 1t. Stopping the transfer process will dump the excess fuel from the container, meaning that each time you start the transfer you will use 1t of Quirium fuel.

    Cost:           1380.0 Cr
    Availability:   TL7

Options
=======
The "fuelTweaks_fuelEconomy.js" file contains a variety of functions and settings to control where fuel is sold, how much can be sold, and the presence of refuelling stations. While this file can be manually adjusted to taste, the preferred way is by using the following JavaScript interfaces described below.

Fuel stations
-------------
If fuel stations are enabled for a particular system, they will appear towards the edge of scanner range behind the main station. To get refuelled, simply fly into the station and come to a halt when directed. Fuel will then be transferred. WHen finished, exit the station and your account will be charged.

Fuel rations
------------
Some systems may have introduced a ration system, where a limited amount of fuel is available for purchase at the main station. Once you have purchased your ration, you will be unable to purchase any more fuel in that system until you jump out and come back.

Fuel Collector OXP
------------------
If Frame's Fuel Collector OXP is installed, the Fuel Collector will collect fuel into the Fuel Processor once the ship's tank is full.

Library Config
==============
Many of the settings can be customised via Library Config.

Fuel Availability: Allegiance
-----------------------------
This setting allows you to control which stations will have fuel, based on their allegiance. Select all the allegiances you want fuel to be available at by changing the "0" to a "1" in front of each allegiance type. Selecting no allegiances will effectively mean fuel will be available at any stations, regardless of allegiance (ie. this would be the same as the base game, where all stations that have an F3 screen will offer fuel for sale).

Fuel Availability: Economies
----------------------------
This settings allows you to control which systems will have fuel, based on their economy. Select all the economies you want fuel to be available at by changing the "0" to a "1" in front of each economy type.

Fuel Availability: Governments
------------------------------
This settings allows you to control which systems will have fuel, based on their government. Select all the governments you want fuel to be available at by changing the "0" to a "1" in front of each government type.

Fuel Stations: Economies
------------------------
This settings allows you to control which systems will have fuel stations, based on their economy. Select all the economies you want fuel stations to be available at by changing the "0" to a "1" in front of each economy type.

Fuel Stations: Governments
--------------------------
This settings allows you to control which systems will have fuel stations, based on their government. Select all the governments you want fuel stations to be available at by changing the "0" to a "1" in front of each government type.

General Settings
----------------
Switches:
    Apply changes: True means changes made to the fuel availability settings will be saved with the game and will apply when the game is reloaded. False means the settings will only apply in the current game until it is reloaded.
    Normal fuel operation: True means all settings are ignored, and the default fuel system will be in place. False means all settings are applied, and by default, this will create refuelling stations near each main station. Use this to quickly turn the system on or off.
    Fuel rationing: True means there will be limits to the amount of fuel you can purchase. False means no rationing will be in effect.

Values:
    Max fuel ration: When rationing is in effect, set the maximum amount that can be purchased. Integer between 0 and 6.
    Default min TL: The minimum TL of a system where fuel can be purchased. 0 means everywhere.
    Refuel stn cost factor: The cost factor applied to fuel purchases from fuel stations. If 7LY of fuel would normally cost 15cr, a factor 0.15 would mean the actual cost would be (15 x 0.15) 2.25cr.
    Refuel stn min TL: The minimum TL of a system where fuel stations will be present. 0 means everywhere.

Examples
========
1. Using Refuelling Stations for fuel.
In order to move all refuelling functions to refuelling stations, do the following:
    a. Set "General Settings", "Switches", "Apply changes" to true.
    b. Set "General Settings", "Switches", "Normal fuel operation" to false.

2. Only having Refuelling Stations in certain government types.
To limit where refuelling stations will appear by the government type, do the following:
    a. Open "Fuel Stations: Governments", "Flags", and change the flag from 1 to 0 on all government types where you do not want refuelling stations to appear.

3. Allowing normal refuelling at some government types.
In order to allow some governments to have normal fuel operations (ie fuel can be purchased via the F3 Equip Ship screen), do the following:
    a. Open "Fuel Availability: Governments", "Flags", and change the flag from 1 to 0 on all government types where you do not want normal fuel operations.
    b. Open "Fuel Stations: Governments", "Flags", and ensure the opposite value is set for the government. That is, if you turned on fuel availability at Democracies, turn off fuel stations at Democracies.

4. Implementing fuel rationing.
In order to allow fuel rationing, do the following:
    a. Set "General Settings", "Switches", "Fuel rationing" to true.
    b. Set "General Settings", "Values", "Max fuel ration" to the maximum number you want available. The default is 1 (ie only 1 LY of fuel can be purchased at the station per system visit).
Once fuel rationing is in place, any fuel availability settings will apply to rations. That is, if fuel is available in a system, it will be rationed.

JavaScript interfaces
=====================
Note: Changes made to the fuel system via these JavaScript methods will only persist across save games if the "Save settings" option is true.

Fuel
----
The following Javascript methods control access to the sale of fuel through the F3 interface:

    ---------------------------------------------------------------------------------------------------------------------
    worldScripts.FuelTweaks_FuelEconomy.$addFuelAvailability(ecos : array, govs : array, tl : int[, useRations : boolean[, maxRations : int]]);

    Adds a economy/government/min techlevel fuel availability setting. "ecos" and "govs" are arrays containing integers between 0 and 7.
    To ignore the economy or government, pass a null value.
    tl is an integer, being the minimum techlevel required, between -1 and 15 (-1 means no techlevel check is performed)
    useRations is an optional flag indicating that fuel rations will be used at these systems, rather than the standard fuel.
    maxRations is an optional integer indicating the maximum amount of rationed fuel that can be purchased, between 0 and 6.

    ---------------------------------------------------------------------------------------------------------------------
    worldScripts.FuelTweaks_FuelEconomy.$setMaxFuelRation(maxVal : int);

    Sets the default maximum amount of fuel that can be purchased through non-refuelling stations.

    ---------------------------------------------------------------------------------------------------------------------
    worldScripts.FuelTweaks_FuelEconomy.$setFuelAllegiance(alleg: array);

    Sets an array of allegiance types to control what stations can sell fuel.
    An empty array means all stations can sell fuel.

    ---------------------------------------------------------------------------------------------------------------------
    worldScripts.FuelTweaks_FuelEconomy.$addFuelSystemOverride(sysID : int, avail : boolean [, useRations : boolean [, maxRation : int]]);

    Adds a system specific override to the fuel system.
    avail determines whether fuel will be available for sale.
    useRations determines whether fuel rationing is in effect
    maxRation sets the maximum amount of fuel ration that can be sold.

Refuelling stations
-------------------
The following methods control the presence of refuelling stations:
Note: Refuel stations will not be present if no fuel is available in the system.
Note: If a refuelling station is present in a system, fuel will not be for sale in other stations.

    ---------------------------------------------------------------------------------------------------------------------
    worldScripts.FuelTweaks_FuelEconomy.$addRefuelStationAvailability(ecos : array, govs : array, tl : int[, factor: float]);

    Adds a economy/government/min techlevel fuel availability setting. "ecos" and "govs" are arrays containing integers between 0 and 7.
    To ignore the economy or government, pass a null value.
    tl is an integer, being the minimum techlevel required, between -1 and 15 (-1 means no techlevel check is performed)
    factor is an optional decimal value that indicates the default fuel cost factor applied to these fuel stations.

    ---------------------------------------------------------------------------------------------------------------------
    worldScripts.FuelTweaks_FuelEconomy.$setRefuelStationCostFactor(cf : decimal);

    Sets the default cost factor applied to fuel sales at refuelling stations. default 0.15

    ---------------------------------------------------------------------------------------------------------------------
    worldScripts.FuelTweaks_FuelEconomy.$addRefuelStationSystemOverride(sysID : int, avail : boolean, costFactor : decimal);

    Adds an refuel station override item for the specified system ID.
    avail = true means a refuel station will always be present, false means it will never be present
    costFactor is the cost factor applied to fuel sales through the refuel station.
    Note: Fuel must be available in the system before a refuelling station can be added.

General methods
---------------
    ---------------------------------------------------------------------------------------------------------------------
    worldScripts.FuelTweaks_FuelEconomy.$isFuelAvailable([sysID : int]);

    Returns true if the passed system ID (or the current system if no value passed) will have fuel available (either at the station itself or via a refuelling station). Otherwise false.

    ---------------------------------------------------------------------------------------------------------------------
    worldScripts.FuelTweaks_FuelEconomy.$fuelRationsInUse([sysID : int]);

    Returns true if fuel rationing is in use in the passed system ID.

    ---------------------------------------------------------------------------------------------------------------------
    worldScripts.FuelTweaks_FuelEconomy.$getMaxFuelRation([sysID: int]);

    Returns the maximum fuel ration permitted in the passed system ID.

    ---------------------------------------------------------------------------------------------------------------------
    worldScripts.FuelTweaks_FuelEconomy.$isRefuelStationAvailable([sysID : int]);

    Returns true if the passed system ID (or the current system if no value passed) will have refuelling stations present. Otherwise false.
    Note: Fuel must be available in the system before a refuelling station can be added.

    ---------------------------------------------------------------------------------------------------------------------
    worldScripts.FuelTweaks_FuelEconomy.$reset();

    Resets all fuel settings back to their default.

Or you can change the data elements directly in fuelTweaks_fuelEconomy.js. ;)

License
=======
This work is licensed under the Creative Commons Attribution-Noncommercial-Share Alike 4.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/4.0/

With thanks to Thargoid for his fly-through WildShips docking port. 

Fuel flow and shutdown sounds from Machine-Shutdown-021.wav by Astounded -- https://freesound.org/s/520810/ -- License: Attribution 4.0

Discussion
==========
This OXP is discussed at this forum link: http://bb.oolite.space/viewtopic.php?f=4&t=18947

Version History
===============
1.18
- Fixed incorrect text lookup key in fuelTweaks_fuelEconomy.js.
- Added a ship library entry for the refuelling station.

1.17
- Fixed issue where 5ly and 6ly fuel rations were not being removed from the player ship after purchase.
- Moved all text into descriptions.plist and missiontext.plist for easier localisation.

1.16
- Tweaks to the refuelling station texture.

1.15
- Switched logic for checking economy and government to be more logical. An empty array means everything is turned off, rather than ignored.
- Added Library Config options so player can easily change fuel settings for their game.
- A galactic jump will now not remove default settings, just any settings added via JS.
- Witchspace jumps will now stop any transfer of Quirium fuel from storage.
- Reduced the chance of damage when transferring fuel. Reduced the chance of a catastrophic failure.
- New fuel station model added, to replace old one.
- Added sound effects while fuel transfer in progress.

1.14.6
- Fixed JS error when removing items via the F3 Equip Ship screen.

1.14.5
- Made compatible with MarketScriptInterface.oxz.

1.14.4
- The current state of the Quirium Fuel Processor (ie. how full it is) is now shown on the F5F5 Manifest screen.

1.14.3
- A Quirium Fuel Storage Unit will now automatically be awarded whenever a quirium fuel cargo container is scooped.

1.14.2
- Bug fixes.

1.14.1
- Fixed invalid character in shipdata.plist file.

1.14
- Fixed issue with repairing damaged fuel storage units.

1.13.1
- Removed debug log messages.

1.13
- Fixed issue with Fuel Collector taking too long to fill up accumulator when scooping fuel in free space.
- Fixed issue with Fuel Collector turning off the Quirium Fuel Processor when scooping fuel from the sun.

1.12
- Bug fixes and tweaks to the fuel transfer process.
- Added link to Fuel Collector OXP to enable the fuel collector to collect fuel into the fuel processor.
- Added variable pricing for pirate fuel, based on the amount of fuel required.

1.11
- Excluded fuel items from getting purchase notifications via the Email System.
- Scooping ejected quirium fuel containers will now award the player a Quirium Fuel Storage unit, so they can safely keep the cargo, rather than requiring the cargo be auto-ejected.
- Dumping quirium fuel will now dump a fuel storage unit along with it.
- Adjusted the prices of the Quirium Fuel Storage unit and it's associated removal item.
- Adjusted fuel storage equipment item configuration to handle case where player might have scooped some Quirium fuel and received fuel storage units, but without having a fuel processor.
- Better logic for determining if an escape pod is installed.
- Fixed missing variable definition errors during self-destruct sequence.
- Fixed output messages including a "0" during the self-destruct sequence.
- Corrected readme and wiki page regarding the Quirium Fuel Transfer equipment item and process.

1.10
- Bug fixes.

1.9
- NPC AI not being set to correct file to use fuel stations.
- Updated texture on fuel station, turned off the "smooth" setting.

1.8
- Better handling of interstellar space.
- Fuel can now be purchased at some chaotic and pirate stations in systems where there is some sort of fuel restrictions in place, but at a price.

1.7
- Fixed invalid reference bug after exiting witchspace.

1.6
- Added missing cost factor to refuel station availability code.

1.5
- Message about fuel not being for sale incorrectly being broadcast even when rations are available.
- Added information about fuel availability to the F7 System Data screen.
- Fixed incorrect TL variable reference in various lookup functions.
- Tweaks to checking functions to make them more logical.

1.4
- Bug fixes.

1.3
- Tweaks to the equipment.plist file.
- Added 5 and 6 ly fuel rations.
- Tweaks to the logic of the various properties to make system clearer.
- Added textures from gsagostinho's updated version of Fuel Stations.
- Added reset function to remove any fuel-related settings currently in use.
- Bug fixes.

1.2
- Set the default quantity of Quirium fuel available for purchase at all stations to be zero, to encourage scooping.
- Added the "Quirium Fuel Transfer" equipment item, to allow for fuel to be transferred from cargo to the main tank, but with a risk of cargo and/or equipment damage (and even entire ship destruction!).
- Scooping of Quirium Fuel cargo pods when there is insufficient fuel storage units to hold it will now result in the cargo being auto-ejected.
- Corrected logic for determining when fuel or fuel stations are available.
- Added logic to allow for players without fuel scoops to always have the ability to purchase 4ly fuel rations, even if all other logic says no fuel or rations or fuel stations are allowed in this system.

1.1
- Added options and JS methods to control how and where fuel is sold.

1.0
- Initial release.
