Software Documentation

Exporting a firing system scriptDocumentation

IntegrationIntermediate Last updated: August 1, 2019

8 Galaxis

Finale 3D can import and export show files in the GS2 format, which is the interchange format for Galaxis firing systems.  You can design shows in Finale 3D, export them in GS2, and then transfer the firing data to the Galaxis controllers using the Pyrotec Composer software available from Galaxis, or you can design shows in Pyrotec Composer and import the GS2 files into Finale 3D to make simulation videos.  The recent Version 2.6 of the GS2 format includes the device allocation tables in the specifications, removing the need to construct the table manually when importing into Pyrotec Composer, as discussed more fully below.

To create and export a script for the Galaxis firing system, please follow these steps:

  1. Set module type. Choose one module type for the full show in “Show > Set show information…” or in “Addressing > Addres show…”, or choose different module types per-position by right clicking positions and doing “Edit position properties” from the context menu.  If you are using multiple module types in the show, they must either all use steppers, or none use steppers; they must all be v2.6 or all be v2.4.  You cannot mix-and-match the version number or the use of steppers, because your choices must be consistent for the entire exported GS2 file.
  2. Configure show for flames (if using G-Flame). If you are designing a show with G-Flames, each G-Flame device is represented as a separate position exclusively for that device (no pyro from the same position!).  Please (a) add the flame positions for your G-Flame units, and (b) set the positions’ module types to the correct G-Flame module type, and (c) set their “Start Module” to a distinct module number for each flame position.  Choose module numbers for your flame positions that will not conflict with the module numbers used by the pyro positions.  See Flame systems basic instructions and Exporting a firing system script for flame systems and Galaxis G-Flame for further instructions.
  3. Decide if you want steppers. If you have elected to use steppers for your show by choosing the  “… w/Steppers” module types, then Finale 3D will automatically add steppers in the script for sequences with less than 300ms between events.  You do not need to do anything else.
  4. Address show. Use the menu item “Addressing > Address show…” or any of the other addressing methods (see Addressing basic instructions).
  5. Export script. Export the script  as a GS2 (“File > Export > Export firing scripts…“).
  6. Download script. Open the GS2 file in Pyrotec Composer and download to your your hardware.

Step 5 creates the script file, which is a text file with a “GS2” extension.  The format of the file is difficult for a human to read, so Finale 3D provides the function “File > Tools > Open firing system script as generic table…” to view the contents of the GS2 file in a table window.  You can select all in the table window (control-A), then copy (control-C), then paste into an Excel file in order to change the column widths and inspect the data.  You can also open the GS2 file directly in Pyrotec Composer.

 

Figure 1 – Galaxis firing system

 

Table 1 – File format and encoding

File format Extension Text encoding Field delimiter End-of-line
Text file of concatenated tables of concatenated fields .gs2 Code Page 1252 Carriage return  + linefeed (0x0D0A) None

The GS2 script is a text file that you can inspect and edit in a text editor, but it is in a format that is difficult to read. The format consists of three header fields, followed by a script table of firing rows with 70 fields for each row, serialized. All fields are separated by carriage return and linefeed but there’s no end-of-line delimiter, which makes the script quite long in a text editor.  Finale 3D has the function, “File > Tools > Open firing system script as generic table…” which reads the GS2 file into a table format in a window that you can read more easily, or copy/paste into Excel to examine.

Prior to December 2018 the up-to-date version of GS2 was Version 2.4.  This file format contained the header and script table, followed by other optional data that was internal to the Pyrotec Composer software.  The optional data wasn’t necessary for reading the GS2 into Composer, but if the optional data was not present in the file you would need to rebuild your device allocation tables in Composer before downloading to your devices, which was a significant manual effort for large shows.

In December 2018 Galaxis came out with Version 2.6 of GS2, which Finale 3D also supports.  Version 2.6 incorporates the device allocation table information in the defined specification of the format, which allows Finale 3D and other software programs to import and export the device allocation table information along with the script table, eliminating the need for you to rebuild it manually in Composer.  Loosely speaking, if you design and address a show in Finale 3D you will have specified what module device IDs and what types of modules or G-Flame units go at every position, and what hazard classes are associated with the devices referenced in the rows.  Thus by designing a show in Finale 3D you have already created all the information in the Galaxis device allocation tables, so being able to export a Version 2.6 GS2 file format that incorporates this information and doesn’t require you to rebuild it manually is a big time savings. The minimum version number of Pyrotec Composer that supports Version 2.6 of GS2 is V2.3.0.253.

Taking into consideration Version 2.4 and Version 2.6 of the GS2 file format, we can say that the format consists of a header, followed by a script table, then either (a) followed by optional Galaxis internal information for the Version 2.4 format, or (b) followed by device allocation tables and then followed by exactly 18775 Galaxis internal information fields for the Version 2.6 format.  The Finale 3D function, “File > Tools > Open firing system script as generic table…” will show you all the data of all the defined tables in Version 2.4 and Version 2.6, and will add a header and remove and count the unused rows to make the tables easily readable in glance.

For backward compatibility, Finale 3D will export Version 2.4 or Version 2.6 files.  You can select which file format by your selection of what type of Galaxis modules to use in the show.  The module type selector in the addressing dialog and the position properties dialog gives you options for Version 2.4 modules, or Version 2.6 modules; choose whichever you like.  Similarly, the selector gives you options for “with steppers” or “without steppers,” which defines whether the exported format will include steppers or not (you can add steppers in the Pyrotec Composer software if you prefer to do it there).

 

Table 2 – Special characteristics

Special characteristics Description
Time representation Certain fields in the GS2 file (Event Time, and Effect Time) are represented as integers in the Galaxis integer time representation format: an integer whose last two digits represent hundredths of a second, whose next two digits represent seconds, and whose next one or two digits represent minutes. For example, the representation of 1 minute, 20 seconds, 10/100ths is 12010, not 8010.  Other fields (Dt and Step Time) are represented simply as integers in hundredths of second.
Sort order of rows Rows sorted ascending by event time (ignition time).
What rows represent Each firing row represents a quantity of one or more same-type effects at a unique event time, or an additional effect possibly of a different type or angle or position at the previous row’s event time. Thus each event time is represented by one or more sequential rows. The event time count (Field #0) is 1 for the first event, and increments for each new event time. The following “Dt” field (Field #1) is the time delta to the next event time, or blank for additional effects at the previous event time.
Chains counting as one unit Some display companies follow the convention that one chain is one unit for stock keeping records; others follow the convention that a chain of five shells is five units.  The GS2 file has a Quantity field that represents the number of units.  The meaning of this field for chains — whether it is the number of shells in the chain or just one per chain — cannot be determined from the file intrinsically.  When you export a GS2 file from Finale 3D, the Quantity field will always represent the number of shells in the chain.  However, if you import a GS2  file into Finale 3D, you are given the option for whether chain quantities indicate the number of chains or devices.
Header The file contains a header consisting of three fields: version, date, and available_SC_ID.  The Version is “V2.6” for Version 2.6, and “V2” otherwise.  The date is a user-text string, in the format, “8/27/2009-4:42:18 PM”.  The available_SC_ID is an integer 10000 + the number of used rows in the script table.
Pyrotec Composer Versions The minimum version number of Pyrotec Composer that supports Version 2.6 of GS2 is V2.3.0.253.
Galaxis internal information Version 2.4 of the GS2 file contains optional Galaxis internal information fields after the script rows. Version 2.6 contains exactly 18775 opaque fields of Galaxis internal information after the device allocation tables, which optionally can be blank fields.
Steppers Galaxis addresses the issue of wireless transmission times by combining rapid sequences of ignition events into short programs (“steppers”) triggered by the first ignition time event in the sequence. Galaxis also supports using steppers to combine a user-defined sequence of events as one cue number, so as to reduce the number of cues required for large shows (Galaxis’ cue number limit is 999) or to support manual triggering of one sequence at a time (semi-automatic).

Finale can export scripts with or without steppers, but if your script contains sequences of events with less than 0.3 seconds between them then you need to export the script with steppers or add the steppers using a command in Pyrotec Composer before downloading to your modules. When you address and export the show in Finale using the “… w/Steppers” modules, Finale 3D will automatically add steppers as required for wireless transmission. If you want to add user-defined stepper sequences, then unhide the “Track” field in the script table, and assign an identifier such as a number or letter to any sequence of rows you would like to make into a stepper sequence. When Finale exports the GS2, any sequence of rows with the same track identifier will be made into a stepper sequence.

When converting the script to use steppers, the “Cue” (Field #0), “Dt” (Field #1), “Step Cue” (Field #8), and “Step Delay” (Field #9) fields are changed to represent the stepper programs. Only the first event time in a stepper program counts, so the Cue field is blank for all but the first row in a stepper sequence and any immediately following rows at the same event time. The Dt field for stepper rows is blank except for the first row, which contains the delta to the next counted event time. The Step Cue and Step Delay fields of the first row and immediately following rows at the same ignition time are blank; for subsequent rows the Step Cue is the Cue of the first row, then colon, then the SC-ID of the first row (e.g., 1:10001), and the Step Delay is the time delta between the row’s ignition time and the event time of the first row in the stepper sequence.

Finale 3D will automatically optimize the stepper sequences to make them as short as possible.  For example, if you have a sequence of nine shots at 100ms intervals, Finale 3D will create three steppers, the first stepper handling the first shot at time T, the second shot at T + 100ms, and the third shot at T + 200ms; the second stepper handling the three shots at T + 300ms, T + 400ms, and T+ 500ms; the third stepper handling the three shots at T + 600ms, T + 700ms, T + 800ms.  The three stepper sequences are separated by 300ms each, satisfying the Galaxis hardware requirement, and it is not possible to make the stepper sequences any shorter than that.  If you would the entire sequence of nine shots be on a single stepper, you set the “Track” field of the nine shots to any unique name or number, and then Finale 3D will keep them together in a single (longer) stepper sequence in the exported GS2 file.

“Start Show” row Galaxis firing hardware requires an initial “Start Show” row in the script table at time 0 to initiate the hardware.  Finale 3D adds this row to the script table automatically at time of export if the script doesn’t contain an explicit firing event at time 0.
Split-matrix boards Galaxis firing systems support partitioning a device’s range of outputs into 10-output “split-matrix boards.”  Finale 3D supports split-matrix boards using virtual slats, so you can take advantage of Finale 3D’s powerful addressing and racking features for reasoning with constraints relating to slats (split-matrix boards) being at different physical locations (see Slats, virtual slats, and splitter boxes).

For example, suppose you have one device with 100 outputs that are distributed out to ten launch positions by ten split-matrix boards with ten outputs each.  It would be important when addressing the show to apply the constraint that each split-matrix board is restricted to addressing shots at a single launch position, for otherwise you might have wires running from position to position.  But it would be too restrictive to constrain each device (module) to a single launch position, because that would defeat the whole idea of using split-matrix boxes to distribute the device’s outputs among multiple positions.  Using virtual slats to represent split-matrix boards allows you to arrange slats (split-matrix boards) at various positions while having their device ID and outputs refer to the output range of the parent device.

In the Finale 3D script, split-matrix boards’ Rail Addresses are two-part addresses, such as 1-A meaning device ID 1, first split-matrix board; or 1-B meaning device ID, second matrix board.  The Pin Addresses (outputs) of each split-matrix board are numbered 1-10 in the Finale 3D script, but are converted to the corresponding 10 output sub-range of the parent device’s range of outputs 1-100 when exported to the GS2 file.

G-Flame The GS2 file represents G-Flame devices just like any other firing system device, with a device ID and a G-Flame device name (9). For G-Flame units, shots are represented by unique output numbers beginning with 1 and increasing sequentially up to 999. As a special consideration for G-Flame units (but not other Galaxis device types), Finale 3D adjusts event times if necessary to guarantees 0.3 second separation between events on the same G-Flame device, as required by the G-Flame hardware.

To design a show with G-Flame devices using Finale 3D, please address the show with “G-Flame Unit” module types if the show is entirely G-Flame effects, or assign “G-Flame Unit” as the module type of specific positions (by editing their position properties) if the show is partially G-Flame effects and partially pyrotechnics. Any single position will be entirely G-Flame or entirely pyrotechnic, depending on its module type.

From the effects window, add pyrotechnic effects to the pyrotechnic positions, and add flame effects to the G-Flame positions. Any effect with Type = flame will work, such as the generic effects GFX9800, GFX9801, GFX9802, and GFX9803. The duration of the effect definition will carry through into the exported GS2 file and will control how long the fuel nozzle is open.

The script table consists of N * 70 fields concatenated together, where N is the number of rows, each field terminated with the end-of-field delimiter.  Version 2.4 may include up to 10,000 rows and nothing more, or exactly 10,000 rows followed by optional internal Pyrotec Composer information.  Version 2.6 includes exactly 15,000 rows, followed by device tables, followed by optional internal Pyrotec Composer information.  GS2 scripts exported by Finale 3D will contain valid values for the following fields, shown with field numbers counting from 0 (i.e., 0-69). The remaining fields will be empty.

 

Table 3 – Specifications of script fields

Field name Description
Field #0, Cue (int or blank) A counting number, beginning with one, of unique event times.  Multiple rows with the same event time will have the same count.  Often referred to as a “Cue” or “Cue number.”  Finale 3D writes this field but ignores it when importing GS2 shows.
Field #1, Dt (int or blank) Time delta between events, represented as an integer in hundredths of a second. Finale 3D writes this field but ignores it when importing GS2 shows.
Field #2, Event Time (int or blank) The ignition time, represented in Galaxis integer time representation.  Finale 3D writes this field and reads it when importing GS2 shows.
Field #3, Effect Time (int or blank) The visual effect time, represented in Galaxis integer time representation.  Finale 3D writes this field and reads it when importing GS2 shows.
Field #4, Delay (comma-radix float) The time delay between the Event Time and Effect Time, represented in the format 0,00. The time delay equals the item’s prefire time plus any external delay such as a fuse delay.  Finale 3D writes this field but ignores it when importing GS2 shows, because it is redundant with the Event Time and Effect Time.
Field #5, Duration (comma-radix float) The duration of the effect or chain, in the format 0,00.  If the effect is a chain, the duration is the time from first to last shot in the chain.
Field #8, Step Cue (int or blank) A parameter for triggering a sequence of events (see “Steppers”, above).  Finale 3D writes this field but ignores it when importing GS2 shows.
Field #9, Step Delay (int or blank) A parameter for triggering a sequence of events, represented as an integer in hundredths of a second. Finale 3D writes this field but ignores it when importing GS2 shows.
Field #10, Category (string up to 80 characters) A user-defined type.  Finale 3D writes the effect’s Type from the Finale script, e.g., shell, comet, mine, etc. Finale ignores this field when importing. NOTE: since Finale ignores this field when importing, please include the type of the effect in the description field (Field #12) if you are going to import the GS2 file into Finale, so it has enough information to create a simulation.  For example, the description needs to be “Crackling Comet”, not just “Crackling”, even if the Category is “Comet”.
Field #11, Name (string up to 80 characters) The name of the effect as you would read it on the label or on a price list or in reports.  Finale 3D reads and writes this field, which may be in a non-English language.  When importing, Finale 3D constructs the simulation from the Description field (Field #12) unless it is blank, in which case Finale 3D constructs the simulation based on the Name, as a fallback.
Field #12, Description (string up to 80 characters) A description of the effect for the purpose of creating a simulation.  Finale 3D reads and writes this field into VDL field of the script, and when importing constructs the simulation on the basis of this field, along with the Size (Field #13), Duration (Field #5), Event Time and Effect Time to calculate lift time (Field #2 and #3), the Angle (Field #23), and in the case of chains the Devices field (Field #21) for the chain count.  The Category (Field #10) does not affect the constructed simulation, so the description must indicate what the type of effect is.  For example, the description needs to be “Crackling Comet”, not just “Crackling”, even if the Category is “Comet”.  The description can be in any language, though when importing Finale 3D constructs accurate simulations most reliably from English descriptions.
Field #13, Size (string up to 80 characters) The size of the effect in inches or millimeters.  Finale 3D reads and writes this field.  Finale 3D writes the effect size string with units, e.g., 100mm or 4″, and constructs accurate simulations most reliably when importing if the field includes the units designation, so Finale 3D doesn’t have to guess whether it is inches or millimeters.
Field #21, Quantity (int) The number of devices represented by the row (e.g., number of shells), except for chains, in which case either (a) the number of chains each counting as one unit (in which case it must be “1”), or (b) the number of devices in the chain.  When importing into Finale 3D, the user specifies whether “Chains count as one unit” in a configuration dialog to disambiguate (a) versus (b).  When exporting, Finale 3D always writes the device count, meaning (b).
Field #22, Position (string up to 80 characters) The name of the launch position from which the effect is fired.  Finale 3D reads and writes this field.
Field #23, Angle (string up to 80 characters) The angle of the trajectory for all devices represented by this row.  A chain or flight of shells in a fan must be split into multiple rows so that each can have an independent angle represented in this field.  Finale 3D reads and writes this field in degrees, followed by symbol font arrow characters that indicate left versus right: dG (up), dF (left), and dH (right), e.g., up = 0dG.
Field #28, Device Number (int from 1 to 999) Finale 3D reads and writes the module number from the rail address into this field.  Shows addressed in Finale 3D for split-matrix boards use virtual slats to identify and separate the ranges of outputs for the split-matrix boards .  For 10×10 split-matrix boards , the rail address in the Finale 3D script for each board will be of the form 1-A, where the digit is the module number and the letter (A-J) identifies the split-matrix boards..  In the Finale 3D script, the pins of each split-matrix board are 1-10, but when exported to the GS2 file, the rail address and pin address are combined and converted into the device number and output number of the parent device.  For example, pin 1 of split-matrix board 2-D would be device number 2, output number 41.
Field #29, Output Number (int from 1 to 999) Finale 3D reads and writes the pin number into this field.  For G-Flame units, shots are represented by unique pin numbers (output numbers) beginning with 1 and increasing sequentially.
Field #30, SC-ID (int) An internal GS2 row identifier.  Finale 3D writes this field when exporting but ignores it when importing. See explanation below.
Field #42, Part Number (string up to 80 characters) Finale 3D reads and writes this field.

Like the script table, the device allocation tables in the Version 2.6 GS2 format consist of N * M fields concatenated together, where N is the number of rows in each table and M is the number of fields per row, each field terminated with the end-of-field delimiter.  The tables are all fixed-size tables, with default values for unused fields.

 

Table 4 – Specifications of device allocation tables

Table Description
Position Names (1000 strings; default value = blank) An array of the position names referenced by the script rows
Device IDs At Positions (10000 ints; default value = 0) A table of 1000 rows corresponding to the 1000 entries in the Position Names table; each row of this table consisting of 10 fields, each field being the integer value of a device ID used at that position; or 0 for unused entries.  Device IDs can be used at multiple positions, as is the case for split-matrix boards at multiple positions connected to the same parent device.
Device Types Corresponding To IDs At Positions (10000 ints; default value = 0) A table of 1000 rows corresponding to the 1000 entries in the Position Names table; each row of this table consisting of 10 fields; each field representing the device type (“device name”) of the corresponding device ID in the Device IDs At Positions table; or 0 for unused entries.  Integer field values correspond to the following enumerated device types:

6 = PFE Advanced – 10 Outputs
7 = PFE Advanced – 50 Outputs
8 = PFE Advanced – 100 Outputs
9 = G-Flame
12 = PFE Advanced Mini – 5 Outputs

In Finale 3D, the module type selected in the addressing configuration dialog or position properties dialog and shown in the script’s Module Or Slat Type column will determine the device type in the exported GS2 file.  When importing GS2 files into Finale 3D, the Module Or Slat Type Column will be determined by the device type values in this device allocation table.

Hazard Zone Of Each Device ID (1000 single letter fields A-P; default value = blank) An array of hazard zones corresponding to Device IDs 1 to 1000 (i.e., the first entry in the table  is Device ID 1)
Position Angle In Degrees (1000 ints or blanks; default value = blank)  An array of ints corresponding to the heading angle around the Up-axis of the positions in the Position Names table, in degrees.  Blank is also a valid entry and is the same as 0.  An angle of 0 is facing the audience, such that a right-angled effect trajectory shot from a 0-angle position will be angled right from the audience perspective.
Position X Coordinates In Millimeters (1000 ints or blanks; default value = blank) An array of ints corresponding to the X-coordinates (the axis aiming right from audience perspective) of the positions in the Position Names table, in millimeters.  Blank is also a valid entry and is the same as 0.
Position Y Coordinates In Millimeters (1000 ints or blanks; default value = blank) An array of ints corresponding to the Y-coordinates (the axis aiming up) of the positions in the Position Names table, in millimeters.  Blank is also a valid entry and is the same as 0.
Position Z Coordinates In Millimeters (1000 ints or blanks; default value = blank) An array of ints corresponding to the Z-coordinates (the axis aiming forward toward the audience) of the positions in the Position Names table, in millimeters.  Blank is also a valid entry and is the same as 0.

An example script is shown below in Version 2.6 format.  The script contains only three actual shots, but Finale 3D automatically adds a “Start Show” row at the start to initiate the firing hardware, bringing the total number of rows in the script table to four.

In the actual GS2 file these tables are fixed length, but to make them readable each table as shown below is truncated to the number of used rows, with a comment in braces indicating the number of used rows.  The comments in brackets, including the header row, are not part of the saved file. Also as shown below, the field delimiters 0x0D0A have been changed to vertical bars to make the text more readable.

You can see the array of three positions, Pos-01, Pos-02, Pos-03 following the script rows.  After the comment you can see the Device IDs At Positions table, then the Device Types Corresponding To IDs At Positions, and so on.

{Event Time Count|Dt|Event Time|Effect Time|Delay|Duration|6|7|Step Cue|Step Delay|Category|Name|Description|Size|14|15|16|17|18|19|20|Quantity|Position|Angle|24|25|26|27|Device Number|Output Number|SC-ID|31|32|33|34|35|36|37|38|39|40|41|Part Number|43|44|45|46|47|48|49|50|51|52|53|54|55|56|57|58|59|60|61|62|63|64|65|66|67|68|69}
1|276|0|0|0,00|0,00||||||Start Show|||||||||||||||||||10000
2|10|276|500|2,24|1,02|||||shell|Red Chrysanthemum|Red Chrysanthemum|2"||||||||1|Pos-01|45dF|||||1|1|10001||||||||||||G2SH1000
3|10|286|510|2,24|1,02|||||shell|Red Chrysanthemum|Red Chrysanthemum|2"||||||||1|Pos-02||||||2|1|10002||||||||||||G2SH1000
4||296|520|2,24|1,02|||||shell|Red Chrysanthemum|Red Chrysanthemum|2"||||||||1|Pos-03|45dH|||||3|1|10003||||||||||||G2SH1000
{Script rows : 4}
Pos-01
Pos-02
Pos-03
{Position rows : 3}
1|0|0|0|0|0|0|0|0|0
2|0|0|0|0|0|0|0|0|0
3|0|0|0|0|0|0|0|0|0
{Device IDs at position rows : 3}
7|0|0|0|0|0|0|0|0|0
7|0|0|0|0|0|0|0|0|0
8|0|0|0|0|0|0|0|0|0
{Device names at position rows : 3}
A
B
C
{Hazard zone per device rows : 3}
0
0
0
{Position rotation angle rows : 3}
-50000
-37500
-25000
{Position X rows : 3}
0
0
0
{Position Y rows : 3}
-8000
-8000
-8000
{Position Z rows : 3}
{Remaining characters in file : 18775}

Figure 2 – Example Galaxis GS2 Version 2.6 script (with comments in braces)

 

Table 5 – Example files

Download link Explanation
galaxis_tiny_v2p6.gs2 Example exported file in Version 2.6 GS2 format
galaxis_tiny_v2p4.gs2 Example exported file in Version 2.4 GS2 format (rename extension as gs2)
galaxis_tiny.fin Example show file
g_flame_galaxis_standard.fin Show file for G-Flame and pyro example
g_flame_galaxis_standard.gs2 Exported GS2 file for G-Flame and pyro example