Module track
[hook-sys] Utility for tracking collections of entities.
Required hooks: newPlayerShip
, probeLaunch
.
Functions
track.set(name, entity[, data]) | Add an entity to the tracked set of a named tracker. |
track.remove(name, entity) | Remove an entity from the tracked set of a named tracker. |
track.get(name, entity) | Get the data associated with a tracked entity in a named tracker. |
track.each(name, f) | Call a function for each tracked entity in a named tracker. |
track.any(name, f) | Check whether any entity in a collection matches a predicate. |
track.pairs(name) | Iterate over entities in a collection. |
Tracker
Tracker() | Create a new entity tracker. |
tracker:set(entity[, data]) | Add an entity to the tracked set. |
tracker:remove(entity) | Remove an entity from the tracked set. |
tracker:get(entity) | Get the associated data for a tracked entity. |
tracker:each(f) | Call a function for each tracked entity. |
tracker:any(f) | Check whether any entity in a collection matches a predicate. |
Predefined named trackers
cpuship | Contains all existing instances of CpuShip . |
playership | Contains all existing instances of PlayerSpaceship . |
ship | Contains all existing instances of CpuShip or PlayerSpaceship . |
station | Contains all existing instances of SpaceStation . |
probe | Contains all existing instances of ScanProbe . |
Functions
- track.set(name, entity[, data])
-
Add an entity to the tracked set of a named tracker.
Parameters:
- name string The name of the tracker.
- entity entity The entity to track.
- data The data to associate with the entity. (optional)
- track.remove(name, entity)
-
Remove an entity from the tracked set of a named tracker.
Parameters:
- name string The name of the tracker.
- entity entity The entity to remove.
- track.get(name, entity)
-
Get the data associated with a tracked entity in a named tracker.
Parameters:
- name string The name of the tracker.
- entity entity The entity to get data for.
- track.each(name, f)
-
Call a function for each tracked entity in a named tracker.
This function has the same concurrency requirements as tracker:each.
Parameters:
- name string The name of the tracker.
- f
A
function(entity, data)
to call for each tracked entity.
- track.any(name, f)
-
Check whether any entity in a collection matches a predicate.
This function has the same concurrency requirements as tracker:any.
Parameters:
- name string The name of the tracker.
- f
A
function(entity, data)
to call for each tracked entity.
Returns:
-
The return values of the first invocation of
f
whose first return value was notnil
orfalse
, if any; otherwisenil
. - track.pairs(name)
-
Iterate over entities in a collection.
This function has the same concurrency requirements as
pairs(tracker)
.Parameters:
- name string The name of the tracker.
Returns:
-
Values suitable for an iteration loop
for entity, data in track.pairs(...) do
Tracker
Tracks a set of entities, with optional data associated with each tracked entity. Deleted entities are automatically removed.
Tracker supports pairs()
, producing entity, data
pairs. Entities may not be added or removed from the tracked set during execution of such a loop, with the exception that the current iteration's entity
may be removed from the tracked set.
- Tracker()
- Create a new entity tracker.
- tracker:set(entity[, data])
-
Add an entity to the tracked set.
Parameters:
- entity The entity to track.
- data The data to associate with the entity. (optional)
- tracker:remove(entity)
-
Remove an entity from the tracked set.
Parameters:
- entity The entity to stop tracking.
- tracker:get(entity)
-
Get the associated data for a tracked entity.
Parameters:
- entity The entity to get data for.
Returns:
-
The associated data for the entity, if tracked; otherwise
nil
. - tracker:each(f)
-
Call a function for each tracked entity. Entities may not be added or removed from the tracked set during execution, with the exception that
f
may remove its argument entity from the tracked set.Note that trackers support pairs, iterating the same data; this function is equivalent to:
for entity, data in pairs(tracker) do f(entity, data) end
Parameters:
- f
A
function(entity, data)
to call for each tracked entity.
- f
A
- tracker:any(f)
-
Check whether any entity in a collection matches a predicate.
Entities may not be added or removed from the tracked set during execution.
Parameters:
- f
A
function(entity, data)
to call for each tracked entity.
Returns:
-
The return values of the first invocation of
f
whose first return value was notnil
orfalse
, if any; otherwisenil
. - f
A
Predefined named trackers
Entities should not be added or removed from these trackers. They are provided for read access only.