Module cargo
Adds inventory functionality to ships.
To enable a ship to carry cargo, add the cargo comp to it.
To define an item, see cargo.addItems for bulk cargo or item_definition for unique cargo.
Terminology
| item | Any object that can be carried by a ship as cargo. |
| item_definition | A table describing the properties of an item, such as its name and description. |
| item_specifier | A string matching the id of any item_definition previously provided to cargo.addItems, or any item_definition. |
| cargo_list | A map from item_specifier to an integer item count, which may be zero or negative unless otherwise specified. |
Comps
| cargo | Allow an entity to hold cargo. |
Functions
| cargo.addItems(...) | Add items that can be carried in bulk by ships. |
| CargoDrop(ty, timeout) | Create a cargo drop entity. |
| cargo.pairs(ship) | Iterate the cargo on a ship. |
| cargo.count(ship, entries, mult) | Count how many times over a ship has some cargo. |
| cargo.has(ship, entries, mult) | Check whether a ship has some cargo. |
| cargo.hasSpace(ship, n, mult) | Check whether a ship has space for some cargo. |
| cargo.use(ship, entries, mult) | Attempt to remove cargo from a ship. |
| cargo.adjust(ship, entries, mult) | Adjust a ship's cargo by an amount. |
| cargo.formatShort(entries, mult) | Format a cargo list in a short format such as "3Ti, 2Si". |
| cargo.formatLong(entries, mult) | Format a cargo list in a long format such as "3 titanium, 2 silicon". |
Terminology
- item
- Any object that can be carried by a ship as cargo.
- item_definition
-
A table describing the properties of an item, such as its name and description.
Bulk cargo must have a single unique table. Fields not specified here are permitted and preserved.
- id string The id of the item. Required if this definition is passed to cargo.addItems, otherwise forbidden. If present, should be short and descriptive, and must not start with a digit. (optional)
- name string The name of the item, in mid-sentence case.
- desc string The description of the item. May contain newlines.
- item_specifier
-
A string matching the
idof any item_definition previously provided to cargo.addItems, or any item_definition. - cargo_list
- A map from item_specifier to an integer item count, which may be zero or negative unless otherwise specified.
Comps
See ecs for details of how to apply comps to an entity.
- cargo
-
Allow an entity to hold cargo.
- infinite boolean Whether this entity is an infinite source and sink of all items. Default false. (optional)
- limit number The maximum number of items this entity can carry, or zero for unlimited. Default zero. (optional)
- items table A map from item_definition to item quantity. Default empty. (optional)
Functions
- cargo.addItems(...)
-
Add items that can be carried in bulk by ships.
Parameters:
- ... A list of item_definitions, which must have id strings.
- CargoDrop(ty, timeout)
-
Create a cargo drop entity.
Parameters:
- ty An item_specifier specifying the cargo type held by this entity
- timeout The timeout before this drop can be picked up; default 0.
- cargo.pairs(ship)
-
Iterate the cargo on a ship.
Parameters:
- ship The ship to iterate the cargo of.
Returns:
-
A Lua iterator over the cargo of the ship. This iterator will produce
item, countpairs, where item is an item_definition and count is a non-negative integer. - cargo.count(ship, entries, mult)
-
Count how many times over a ship has some cargo.
Parameters:
- ship The ship to check.
- entries The base cargo_list to check for.
- mult The amount to multiply the base cargo list counts by; default 1.
Returns:
-
The number of instances of the cargo the ship has.
- cargo.has(ship, entries, mult)
-
Check whether a ship has some cargo.
Parameters:
- ship The ship to check.
- entries The base cargo_list to check for.
- mult The amount to multiply the base cargo list counts by; default 1.
Returns:
-
Whether the ship has at least the specified cargo.
- cargo.hasSpace(ship, n, mult)
-
Check whether a ship has space for some cargo.
Parameters:
- ship The ship to check.
- n The base number of items to add, or the base cargo_list to add.
- mult The amount to multiply the base counts by; default 1.
Returns:
-
Whether the ship has space for the specified cargo.
- cargo.use(ship, entries, mult)
-
Attempt to remove cargo from a ship.
This operation is atomic; if the ship is missing any cargo from the list, then no cargo will be removed.
Parameters:
- ship The ship to remove cargo from.
- entries The base cargo_list to attempt to remove.
- mult The amount to multiply the base cargo list counts by; default 1.
Returns:
-
Whether the cargo was successfully removed.
- cargo.adjust(ship, entries, mult)
-
Adjust a ship's cargo by an amount.
This operation is atomic; if the ship is missing any removed cargo, or does not have space to accept added cargo, then no cargo will be adjusted.
Parameters:
- ship The ship to adjust cargo for
- entries The base cargo_list to attempt to adjust.
- mult The amount to multiply the base cargo list counts by; default 1.
Returns:
-
Whether the cargo was successfully adjusted.
- cargo.formatShort(entries, mult)
-
Format a cargo list in a short format such as
"3Ti, 2Si".Parameters:
- entries The base cargo_list to format.
- mult The amount to multiply the base cargo list counts by; default 1.
Returns:
-
A short string describing the cargo.
- cargo.formatLong(entries, mult)
-
Format a cargo list in a long format such as
"3 titanium, 2 silicon".Parameters:
- entries The base cargo_list to format.
- mult The amount to multiply the base cargo list counts by; default 1.
Returns:
-
A string describing the cargo.