Software Documentation

Exporting a firing system scriptDocumentation

IntegrationIntermediate Last updated: August 28, 2018

4 Pirotex script file format

The Pirotex script is a text file that supports 32, 64, 128, and 256-pin modules, and 10-pin slats (AKM-10).  The pins on the modules themselves are triggered by the channel number associated with the pin, which is just the pin number.  The pins on the slats fire in order from first to last, triggered by successive triggers of the channel number on the module associated with the slat.   

Each row of the script specifies only a module number and channel number as the firing address.  If a slat is attached to the channel number, then the row triggers the next unfired pin on the slat.  If no slat is attached to the channel number, then the row triggers any effects that are wired directly to the pin on the module.

 

Table 1 – File format and encoding

File format Extension Text encoding Field delimiter End-of-line
Text .txt UTF-8 Tab CRLF

The script contains rows for the firing events, i.e., unique combinations of module, channel, and ignition-time.  Multiple effects can be combined on a single cue. The special characteristics of the script are shown in the following table:

 

Table 2 – Special characteristics

Special characteristics Description
Sort order of rows Rows sorted ascending first by Event Time.
What rows represent Rows represent firing events, i.e., unique module-channel-ignition-time events.  If multiple effects are triggered on the same cue, the effects are combined in name field, but the row is still just one row.
Special characters If a field contains a double-quote character (“), then the field will be enclosed in “ on both ends, and any internal “ characters will be doubled up, following the Excel quoting convention.
Minimum separation between cues None
Multi-hit pins Supported in the script format and with manual addressing in Finale 3D, for non-pyro effects like flames and relays that can be triggered multiple times.  Finale 3D handles multi-hit pins in the Pirotex exporter the same as it handles single-hit pins — whatever pin address is in the script row in Finale 3D will be copied to the exported script row for Pirotex, whether or not the pin address is unique.  The standard pyro addressing functions in Finale 3D assign pins sequentially, so it may be easiest to address multi-hit pins in Finale 3D by editing the script table by hand and then locking the edited rows so the show can be re-addressed for pyro without affecting them.
Slats The pins on the Pirotex AKM-10 slats fire in order from first to last, triggered by successive triggers of the channel number on the module associated with the slat.   

Each row of the script specifies only a module number and channel number as the firing address.  If a slat is attached to the channel number, then the row triggers the next unfired pin on the slat.  If no slat is attached to the channel number, then the row triggers any effects that are wired directly to the pin on the module.

It is easy to assign firing system addresses automatically in Finale 3D for a Pirotex show that uses only pins on the modules, or a show that uses only pins on the slats.  It is also not so hard to assign addresses automatically for a show that uses pins on both modules and slats, but only if the slats are connected to different modules. If the show uses pins on modules and on slats connected to the same modules, then you have to assign firing system addresses manually.

If your show uses only the pins on the modules themselves, no slats, then simply address the show using any of Finale 3D’s addressing functions, and choose the “Pirotex 32 Pin Module” module type to be used throughout (or choose 64 or 128 or 256 pin).

If your show uses only the pins on the slats, ignoring the pins on the modules, then simply address the show using any of the Finale 3D’s addressing functions, and choose “Pirotex AKM-10” module type (slats).

If your show uses the pins on the modules at some positions, and uses AKM-10 slats at other positions but does not use any pins on modules to which the slats are attached, then select the positions at which you want to use the modules’ pins, right click on them and do “Edit Properties”.  Set their module type to “Pirotex 32 Pin Module” (or other 64 or 128 or 256). Select the other positions, right click on them and set their module type to “Pirotex AKM-10”. Then address the show using any of the addressing functions.

Slats connected in series AKM-10 slats connected in series act as a single slat with all the pins combined (gaps from unused pins are ignored).  The pins are triggered by a single channel for the whole series, which means the slat numbers assigned to the individual slats by the addressing function are NOT the channel numbers for series.

The Custom Position Field, which you can set by editing position properties, is a “channel override” for the Pirotex exporter.  It enables you to specify a single channel number to use for all firing rows at the position: whatever channel would have been exported (the pin number for pins on the module, or the slat number for pins on the slat) will be overwritten by the value of Custom Position Field.

EXAMPLE: Consider three positions with 16 shots per position, addressed for AKM-10 slats in position order.  The first position would have slat 1 and 2; the second would have 3 and 4; the third would have 5 and 6. If the user wants to attach 1 and 2 in series and assign them to channel 1, the user sets the Custom Position Field for position 1 to 1.  Similarly, he sets the Custom Position Field for position 2 to 2; and 3 to 3.

RULE: For any positions with AKM-10s (in series or not), you must sort shots at the positions first by event time (e.g., sorting by “Position then Event Time”).  If the AKM-10s are in series you must also avoid any slat constraints that could result in pin numbers across the series being non-chronological.

The rule for slat constraints on positions with AKM-10s in series is tricky.  In general you cannot safely constrain slats to any effect property (size, part number, etc.) with AKM-10s in series, because that could result in non-chronological shots between the slats.  You can constrain slats to the same rack or rack cluster if all the racks at the position are equivalently compatible with the shots at the position (e.g., all tubes are the same size). This constraint, which is useful to avoid e-matches running between racks or rack clusters, is the only slat constraint that is prudent to use with AKM-10s in series if you use the automatic addressing functions.  If you use the fill-down addressing method, you can use all constraints if you uncheck the “Backfilling allowed” box in the fill-down dialog.

The Pirotex script has no header, just a list of rows corresponding to the firing events.  Each row has four fields, defined as follows:

 

Table 3 – Specifications of script fields

Field name Description
Event Time Time in the format H:MM:SS:FFF from the beginning of the show (millisecond resolution)
Module Number Module number, beginning with 1.
Channel Number If the row refers to a terminal on a module, then this field is the pin number, beginning with 1, up to 32, 64, 128, or 256, depending on the module type.  If the row refers to a terminal on a slat (i.e., the AKM-10 slat), then this field is the channel number of the slat or slats connected in series. The pins on a slat are triggered in sequence by successive triggers of the slat’s channel number.
Effect Name The effect name.

The example script below is from a show with two positions.  One position has 16 shots, a tenth second apart, shot from two AKM-10 slats on channel 1 and 2 of module 10.  The first 10 sequential shots all have module 10, channel 1 in the script; the next 6 sequential shots all have module 10, channel 2.  These are the first 16 rows in the script.

The second position has 2 shots, a tenth second apart, shot using the pins directly on module 20.  In the script, these two rows have module 20, and channel 1 and 2 corresponding to pins 1 and 2 on the module itself.

 

0:00:02.800	10	1	Red Chrysanthemum
0:00:02.900	10	1	Red Chrysanthemum
0:00:03.000	10	1	Red Chrysanthemum
0:00:03.100	10	1	Red Chrysanthemum
0:00:03.200	10	1	Red Chrysanthemum
0:00:03.300	10	1	Red Chrysanthemum
0:00:03.400	10	1	Red Chrysanthemum
0:00:03.500	10	1	Red Chrysanthemum
0:00:03.600	10	1	Red Chrysanthemum
0:00:03.700	10	1	Red Chrysanthemum
0:00:03.800	10	2	Red Chrysanthemum
0:00:03.900	10	2	Red Chrysanthemum
0:00:04.000	10	2	Red Chrysanthemum
0:00:04.100	10	2	Red Chrysanthemum
0:00:04.200	10	2	Red Chrysanthemum
0:00:04.300	10	2	Red Chrysanthemum
0:00:16.116	20	1	Blue Chrysanthemum
0:00:16.216	20	2	Blue Chrysanthemum

Figure 1 – Example Pirotex script