Software Documentation

Software Documentation

Firing System AddressingDocumentation

Lite Hobbyist Pro Last updated: June 3, 2024

12 Addressing algorithm

The “Addressing algorithm” is the procedure the computer follows to assign modules, pins, racks and tubes to the events of the show.  The basic procedure is a lot like what a human would do:

  1. Decide in what sort order you will assign addresses to effects.
  2. Take the first effect in that order, and assign it the lowest number module, pin, rack, and tube that satisfy all the constraints.
  3. After the assignment, look ahead to assign any same-time or same-chain effects to the same module and pin and the lowest number rack and tube that satisfy constraints.
  4. Repeat from step (2) until finished.
  5. Rearrange the tubes in the single-shot racks to avoid collisions between tubes with crossing angles.

If you turn off step (5) rearrangement, the results of the algorithm are fully transparent and 100% determined by the sort order and the constraints specified in the addressing dialog, meaning that a human could follow these same steps to get the same result.  You can fall back on this truth if you ever question the results of the addressing algorithm: follow the same steps and see if you get the same result.


Sort order

The sort order is a list of criteria, sorting first by criterion 1, then breaking ties by criterion 2, then breaking further ties by criterion 3, etc.  Sort criteria include attributes like Position Name, Size, and Part Number.  In fact it is easy to imagine assigning modules and pins sorted by those exact criteria, and many people do.

Sort criteria can also include conditional terms, like “Size >= 50mm (If Single-Shot)”, which sorts single-shot items of size >= 50mm first; then other single-shot items; then non-single-shot items in their original order.  The purpose of conditional sort terms with phrases like “(If Single-Shot)” is to apply some criteria to some kinds of effects without affecting others.  For example, it may be important to assign racks and tubes to large (>= 50mm) single-shots before others if a launch position has a limited number of racks capable of holding the larger effects, which you wouldn’t want to fill with smaller effects until ensuring you have dealt with all the large effects.

Sort criteria can also include derived terms like “Rack Number”, which prioritize effects that fit in the next rack according to the Rack Numbers.  The precise definitions and calculations of derived terms like Rack Number are often complicated.  If the meaning isn’t obvious or if you are trying to step through exactly what the computer is doing, you can refer to the list of terms and their definitions here: Special sort terms.



Unlike the list of sort order terms, constraints come from multiple places.  The addressing dialog provides lists of constraint fields applying to modules, slats, pins, and racks, and provides the constraint, “Max. e-matches per pin”.  The rack definition dialog for the “Create/edit rack” functions includes pre-wired pins, various size constraints, usable length of rack row constraints for Pyrolamas-like racks, and constraints related to angles.  Effects have a Type property that must be compatible with the rack structure (cake racks vs. single-shot racks, etc.).  Positions can have pre-wired rails.  Script rows can have Rack Type values that are required to match the Rack Type properties of the racks.

Like sort terms, constraint fields applying to modules, slats, pins, and racks can refer to attributes like Position, Size and Part Number, or other more complicated conditional and derived terms like “Rack (If Single-Shot)” or “Chain-Or-Not” (see Special constraints).

The important characteristic of constraints is that they combine in a principled manner.  The combination of constraint 1 and constraint 2 means simply that constraint 1 and constraint 2 must both be satisfied by any assignment of modules, pins, racks, and tubes.  Because of this characteristic, you can configure the addressing algorithm to take into account a staggeringly large and complex set of considerations while still being able to rely on the predictability and verifiability of the result.


Example sort order and constraints for single-shot racks with pre-wired pins

Addressing for pre-wired pins on racks with angle range constraints requires a significant amount of sort order and constraint calculation which illustrates the complexity.   The specific terms are listed in Table 1 of Racks with pre-wired pinsFigure 1 is an excerpt:


Figure 1 – Example sort order and constraints for pre-wired pins.


The “Tilt > 50° — Single-Shot” sort term guarantees that single-shots angled more than 50° get to allocate the tube holders on the ends of the rows that are the only holders capable of rotating to those extreme angles.  Similarly, the “Size >= 50mm — Single-Shot” sort term ensures large holder single-shot racks are allocated first to the large effects that need them.  The “One Single-Shot Rack” constraint restricts a module to zero or one single-shot rack but allows pins to be shared with other non-single-shot racks.  See Racks with pre-wired pins for the full explanation of the terms in this example.