Module `exchange`

Utilities for adding, removing, moving, and exchanging resources.

Terminology:

A "source" is a kind of resource that might be exchanged, such as rep, coolant, or HVLI ammo. Each source has a key, such as rep, coolant, or w_hvli.
A "resource list" is a table with source keys mapped to the data type for that source, e.g. {rep = 5} or {w_hvli = 2, w_mine = 1}

To define a source, see exchange.sources. Source definition format:

{
    -- Format data as a string, with a multiplier mult
    format = function(data, mult) ... end,

    -- Return true if data can be taken from ship at least mult times
    canTake = function(ship, data, mult) ... end,

    -- Take data from ship, mult times.
    -- This function may assume that canTake(ship, data, mult) is true.
    take = function(ship, data, mult) ... end,

    -- Return true if data can be added to ship at least mult times
    canAdd = function(ship, data, mult) ... end,

    -- Add data to ship, mult times.
    -- This function may assume that canAdd(ship, data, mult) is true.
    add = function(ship, data, mult) ... end,
}

Functions

exchange.each(resources, fn)	Do something for each entry in a resource list.
exchange.formatString(resources, mult)	Format a resource list in a human-readable format, as a string such as `"3 energy, 5 HVLIs"`.
exchange.format(resources, mult)	Format a resource list in a human-readable format, as a table such as `{"3 energy", "5 HVLIs"}`.
exchange.canTake(ship, resources, mult)	Check whether a ship could supply resources.
exchange.take(ship, resources, mult)	Take resources from a ship.
exchange.tryTake(ship, resources, mult)	Attempt to take resources from a ship.
exchange.canAdd(ship, resources, mult)	Check whether a ship could accept resources.
exchange.add(ship, resources, mult)	Add resources to a ship.
exchange.tryAdd(ship, resources, mult)	Attempt to add resources to a ship.
exchange.canSwap(ship, from, to, mult)	Check whether a ship could swap one set of resources for another.
exchange.swap(ship, from, to, mult)	Swap resources on a ship.
exchange.trySwap(ship, from, to, mult)	Attempt to swap resources on a ship.
exchange.canMove(shipFrom, shipTo, resources, mult)	Check whether two ships could move resources from one to another.
exchange.move(shipFrom, shipTo, resources, mult)	Move resources from one ship to another.
exchange.tryMove(shipFrom, shipTo, resources, mult)	Attempt to move resources from one ship to another.
exchange.canTrade(shipA, resourcesA, shipB, resourcesB, mult)	Check whether two ships could trade resources with each other.
exchange.trade(shipA, resourcesA, shipB, resourcesB, mult)	Trade resources between two ships.
exchange.tryTrade(shipA, resourcesA, shipB, resourcesB, mult)	Attempt to trade resources between two ships.

Values

exchange.infinite A special value for all functions in this module; if passed in place of a ship, acts as an infinite source and sink for all sources.

Sources

exchange.sources

Mapping of source key => source.

Predefined Sources

custom	Forwards method calls to its data.
rep	Faction reputation points.
energy	Ship energy.
hull	Ship hull points.
coolant	Ship coolant.
probe	Ship scan probes.
w_hvli	HVLI ammunition.
w_homing	Homing ammunition.
w_mine	Mine ammunition.
w_emp	EMP ammunition.
w_nuke	Nuke ammunition.
cargo	Ship cargo.

Functions

exchange.each(resources, fn)

Do something for each entry in a resource list. Primarily intended for internal use.
If the provided function returns a non-nil first result for any entry, the iteration is terminated and the results of that call are returned from this function.

Parameters:

resources The resource list to iterate.
fn A function(source, data) to call for each entry.

Returns:

fn

exchange.formatString(resources, mult)

Format a resource list in a human-readable format, as a string such as "3 energy, 5 HVLIs".

Parameters:

resources The resource list to format.
mult A multiplier to apply to each entry in the resource list; default 1.

exchange.format(resources, mult)

Format a resource list in a human-readable format, as a table such as {"3 energy", "5 HVLIs"}.

Parameters:

resources The resource list to format.
mult A multiplier to apply to each entry in the resource list; default 1.

exchange.canTake(ship, resources, mult)

Check whether a ship could supply resources.

Parameters:

ship The ship to check.
resources The resource list to check.
mult A multiplier to apply to each entry in the resource list; default 1.

Returns:

boolean true if the ship could provide the resources; otherwise false
string The reason the ship could not provide the resources, if any

exchange.take(ship, resources, mult)

Take resources from a ship. The behaviour of this function is undefined if exchange.canTake would return false given the same arguments.

Parameters:

ship The ship to take from.
resources The resource list to take.
mult A multiplier to apply to each entry in the resource list; default 1.

exchange.tryTake(ship, resources, mult)

Attempt to take resources from a ship. This operation is atomic; if any resources cannot be taken, then no resources are taken.

Parameters:

ship The ship to take from.
resources The resource list to take.
mult A multiplier to apply to each entry in the resource list; default 1.

Returns:

boolean true if the resources were successfully taken; otherwise false
string The reason the ship could not provide the resources, if any

exchange.canAdd(ship, resources, mult)

Check whether a ship could accept resources.

Parameters:

ship The ship to check.
resources The resource list to check.
mult A multiplier to apply to each entry in the resource list; default 1.

Returns:

boolean true if the ship could accept the resources; otherwise false
string The reason the ship could not accept the resources, if any

exchange.add(ship, resources, mult)

Add resources to a ship. The behaviour of this function is undefined if exchange.canAdd would return false given the same arguments.

Parameters:

ship The ship to add to.
resources The resource list to add.
mult A multiplier to apply to each entry in the resource list; default 1.

exchange.tryAdd(ship, resources, mult)

Attempt to add resources to a ship. This operation is atomic; if any resources cannot be added, then no resources are added.

Parameters:

ship The ship to add to.
resources The resource list to add.
mult A multiplier to apply to each entry in the resource list; default 1.

Returns:

boolean true if the resources were successfully added; otherwise false
string The reason the ship could not accept the resources, if any

exchange.canSwap(ship, from, to, mult)

Check whether a ship could swap one set of resources for another.

Parameters:

ship The ship to check.
from The resource list to swap from.
to The resource list to swap to.
mult A multiplier to apply to each entry in each resource list; default 1.

Returns:

boolean true if the ship could swap the resources; otherwise false
string The reason the ship could not swap the resources, if any

exchange.swap(ship, from, to, mult)

Swap resources on a ship. The behaviour of this function is undefined if exchange.canSwap would return false given the same arguments.

Parameters:

ship The ship to swap on.
from The resource list to swap from.
to The resource list to swap to.
mult A multiplier to apply to each entry in each resource list; default 1.

exchange.trySwap(ship, from, to, mult)

Attempt to swap resources on a ship. This operation is atomic; if any resources cannot be added or removed, then no resources are added or removed.

Parameters:

ship The ship to swap on.
from The resource list to swap from.
to The resource list to swap to.
mult A multiplier to apply to each entry in each resource list; default 1.

Returns:

boolean true if the resources were successfully swapped; otherwise false
string The reason the ship could not swap the resources, if any

exchange.canMove(shipFrom, shipTo, resources, mult)

Check whether two ships could move resources from one to another.

Parameters:

shipFrom The ship to move resources from.
shipTo The ship to move resources to.
resources The resource list to move.
mult A multiplier to apply to each entry in the resource list; default 1.

Returns:

boolean true if the ships could move the resources; otherwise false
string The reason the ships could not move the resources, if any

exchange.move(shipFrom, shipTo, resources, mult)

Move resources from one ship to another. The behaviour of this function is undefined if exchange.canMove would return false given the same arguments.

Parameters:

shipFrom The ship to move resources from.
shipTo The ship to move resources to.
resources The resource list to move.
mult A multiplier to apply to each entry in the resource list; default 1.

exchange.tryMove(shipFrom, shipTo, resources, mult)

Attempt to move resources from one ship to another. This operation is atomic; if any resources cannot be added or removed, then no resources are added or removed.

Parameters:

shipFrom The ship to move resources from.
shipTo The ship to move resources to.
resources The resource list to move.
mult A multiplier to apply to each entry in the resource list; default 1.

Returns:

boolean true if the resources were successfully moved; otherwise false
string The reason the ships could not move the resources, if any

exchange.canTrade(shipA, resourcesA, shipB, resourcesB, mult)

Check whether two ships could trade resources with each other.

Parameters:

shipA The first ship involved in the trade.
resourcesA The resources that shipA is providing to shipB.
shipB The second ship involved in the trade.
resourcesB The resources that shipB is providing to shipA.
mult A multiplier to apply to each entry in each resource list; default 1.

Returns:

boolean true if the ships could trade the resources; otherwise false
string The reason the ships could not trade the resources, if any

exchange.trade(shipA, resourcesA, shipB, resourcesB, mult)

Trade resources between two ships. The behaviour of this function is undefined if exchange.canTrade would return false given the same arguments.

Parameters:

shipA The first ship involved in the trade.
resourcesA The resources that shipA is providing to shipB.
shipB The second ship involved in the trade.
resourcesB The resources that shipB is providing to shipA.
mult A multiplier to apply to each entry in each resource list; default 1.

exchange.tryTrade(shipA, resourcesA, shipB, resourcesB, mult)

Attempt to trade resources between two ships. This operation is atomic; if any resources cannot be added or removed, then no resources are added or removed.

Parameters:

shipA The first ship involved in the trade.
resourcesA The resources that shipA is providing to shipB.
shipB The second ship involved in the trade.
resourcesB The resources that shipB is providing to shipA.
mult A multiplier to apply to each entry in each resource list; default 1.

Returns:

boolean true if the resources were successfully traded; otherwise false
string The reason the ships could not trade the resources, if any

Values

exchange.infinite: A special value for all functions in this module; if passed in place of a ship, acts as an infinite source and sink for all sources.

Sources

exchange.sources: Mapping of source key => source. To register a new source, assign to exchange.sources[key] with a source definition.

Predefined Sources

custom

Forwards method calls to its data. The data format for this source is similar to the source definition format, with the data parameter removed and with all functions made optional.

format function(mult): Format this entry. If not present, omit this entry from the formatted list.
canTake function(ship, mult): Return true if the entry can be taken. If not present, treat as returned true.
take function(ship, mult): Take this entry. If not present, do nothing.
canAdd function(ship, mult): Return true if the entry can be added. If not present, treat as returned true.
add function(ship, mult): Add this entry. If not present, do nothing.

rep

Faction reputation points. Data type: number.

energy

Ship energy. Data type: number.

hull

Ship hull points. Data type: number.

coolant

Ship coolant. Data type: number, where 1 represents 10% coolant.

probe

Ship scan probes. Data type: integer.

w_hvli

HVLI ammunition. Data type: integer.

w_homing

Homing ammunition. Data type: integer.

w_mine

Mine ammunition. Data type: integer.

w_emp

EMP ammunition. Data type: integer.

w_nuke

Nuke ammunition. Data type: integer.

cargo

Ship cargo. Requires cargo to function. Data type: cargo list.

EEScripts

Contents

Modules

Topics

Module exchange

Functions

Values

Sources

Predefined Sources

Functions

Parameters:

Returns:

Parameters:

Parameters:

Parameters:

Returns:

Parameters:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

Returns:

Values

Sources

Predefined Sources

Module `exchange`