Drones, saxons, wheels, and castiles all involve animated positions and orientations.   Drone lights also involve animated colors during the course of the light effect.  Finale 3D uses the Effect Data field in the script window, and the Motion Data in the position window, to hold the animation information. Both fields have a similar format for storing the information.  The information usually gets filled in as a result of an operation like “Import drone show”, but the information is also readable and editable by users as a text field, which makes it possible for users to animate positions and colors for their own purposes.   Syntax of Motion Data and Effect Data fields The syntax of both the Motion Data and Effect Data fields is a pair of curly braces defining an object with attribute-value pairs in square brackets within the curly braces.  The values for most attributes are lists of numbers that are also in square brackets, leading to a large number of brackets in the text string that must be carefully matched up without typos if you are entering data by hand.  An example that defines the motion path for effect on a 0.5m radius wheel rotating clockwise 10 full 360 degree cycles over 10000ms (10 seconds) is, {[pos2 [0 .5 0 0]] [hpr [10000 0 0 -3600]]} An example defining the animated motion path of a drone over 5 minutes is, {[hash 1908853237] [pos [13000 0.0 7.9 0.0 19500 2.77 11.06 3.33 20500 3.42 12.1 4.59 21500 3.75 13.22 6.22 22000 3.61 13.76 7.17 22500 3.12 14.16 8.1 23000 2.39 14.3 8.74 24500 0.13 14.32 9.82 26000 -2.49 14.32 10.72 27000 -4.54 13.39 11.22 28000 -6.84 12.47 11.58 29500 -10.73 11.07 11.7 31000 -15.06 9.68 11.14 32000 -18.12 8.76 10.27 33000 -21.24 7.83 8.94 34000 -24.34 6.9 7.09 35000 -27.3 5.98 4.68 36000 -30.0 5.14 1.69 37000 -32.31 5.14 -1.88 37500 -33.27 5.14 -3.86 38000 -34.07 5.14 -5.97 38500 -34.69 5.14 -8.2 39000 -35.12 5.14 -10.52 39500 -35.34 5.14 -12.93 40000 -35.33 5.14 -15.4 40500 -35.07 5.14 -17.91 41000 -34.56 5.14 -20.44 41500 -33.77 5.14 -22.95 42000 -32.71 5.14 -25.42 42500 -31.38 5.14 -27.81 43000 -29.76 5.14 -30.08 43500 -27.87 5.14 -32.21 44000 -25.71 5.14 -34.14 44500 -23.31 5.14 -35.86 45000 -20.68 5.14 -37.3 45500 -17.84 5.14 -38.45 46000 -14.84 5.14 -39.27 46500 -11.71 5.14 -39.72 47000 -8.49 5.14 -39.78 47500 -5.24 5.14 -39.43 48000 -2.01 5.14 -38.66 48500 1.15 5.14 -37.46 49000 4.16 5.14 -35.82 49500 5.73 5.37 -34.2 50000 5.33 6.16 -32.54 50500 5.1 6.96 -30.66 51000 5.03 7.75 -28.51 52000 5.33 9.33 -23.28 52500 5.66 9.86 -20.87 53000 6.01 10.17 -18.88 54000 6.53 10.17 -16.47 55000 6.68 10.17 -13.81 55500 6.58 10.17 -12.41 56500 5.99 10.17 -9.54 57000 5.47 10.17 -8.1 58000 3.99 10.17 -5.28 58500 3.01 10.17 -3.96 59500 0.6 10.18 -1.56 60000 -0.83 10.18 -0.53 61000 -4.05 10.18 1.06 61500 -5.82 10.18 1.59 62000 -7.67 10.18 1.92 62500 -9.57 10.35 2.04 63000 -11.41 10.83 1.87 63500 -12.85 11.01 1.21 64500 -15.71 11.18 -0.75 65000 -17.07 11.2 -2.03 65500 -18.33 11.21 -3.5 66000 -19.47 11.24 -5.14 66500 -20.47 11.29 -6.94 67000 -21.29 11.41 -8.87 67500 -21.93 11.61 -10.89 68000 -22.36 11.91 -12.98 68500 -22.59 12.34 -15.1 69000 -22.61 12.9 -17.2 69500 -22.42 13.61 -19.26 70000 -22.04 14.48 -21.22 70500 -21.47 15.51 -23.06 71000 -20.74 16.69 -24.72 71500 -19.86 18.03 -26.2 72000 -18.87 19.5 -27.44 72500 -17.78 21.1 -28.43 73000 -16.63 22.81 -29.15 73500 -15.43 24.59 -29.59 74000 -14.24 26.44 -29.74 74500 -13.05 28.32 -29.6 75000 -11.92 30.2 -29.17 75500 -10.84 32.05 -28.47 76000 -9.85 33.86 -27.51 76500 -8.96 35.59 -26.31 77000 -8.19 37.23 -24.89 77500 -7.54 38.75 -23.29 78000 -7.02 40.13 -21.53 78500 -6.64 41.37 -19.64 79000 -6.39 42.46 -17.66 79500 -6.26 43.38 -15.62 80500 -6.38 44.74 -11.46 81500 -6.93 45.48 -7.39 82500 -7.83 45.68 -3.6 83500 -8.97 45.45 -0.21 84500 -10.26 44.91 2.69 85500 -11.62 44.2 5.05 86500 -12.97 43.42 6.9 87500 -14.25 42.7 8.26 89000 -15.94 41.89 9.51 90000 -17.35 41.62 10.25 90500 -18.44 40.89 10.82 92000 -20.65 39.07 11.72 93000 -22.08 38.17 12.28 94500 -24.17 37.26 13.21 95500 -25.5 36.93 13.91 96500 -25.4 36.82 13.78 99500 -22.78 36.81 12.01 105000 -20.81 29.72 15.0 105500 -19.62 27.8 14.1 106000 -18.18 25.78 13.35 106500 -17.56 25.1 13.48 109000 -17.68 26.2 16.13 110000 -17.62 25.84 17.46 112000 -18.0 25.43 20.1 114500 -18.35 27.07 22.52 115500 -18.67 27.9 23.33 118000 -19.54 28.2 26.17 119500 -20.38 28.71 27.6 120500 -20.83 29.53 28.18 122000 -21.54 30.99 28.63 123500 -22.47 32.21 29.01 124500 -23.47 32.76 29.56 125500 -24.69 33.33 29.93 127000 -26.7 34.29 30.03 128000 -27.35 35.29 29.95 129000 -27.77 36.42 29.78 129500 -28.24 36.88 29.68 130500 -28.87 37.97 29.4 131000 -29.58 38.34 29.28 132500 -31.67 39.48 28.62 134000 -33.62 40.65 27.6 135000 -34.42 41.79 27.19 135500 -35.0 42.68 26.49 137000 -41.73 51.43 14.21 156500 -32.35 49.75 19.48 157000 -30.51 49.22 19.72 158000 -28.05 47.93 17.72 159000 -25.99 46.69 15.27 160000 -24.42 45.55 12.45 161000 -23.38 44.53 9.34 162000 -22.91 43.68 6.05 162500 -22.89 43.32 4.38 163500 -23.29 42.76 1.02 164500 -24.26 42.41 -2.25 165500 -25.77 42.3 -5.33 166500 -27.77 42.43 -8.11 167500 -30.19 42.78 -10.52 168000 -31.54 43.04 -11.55 169000 -34.44 43.71 -13.23 170000 -37.56 44.58 -14.37 171000 -40.79 45.6 -14.92 172000 -44.02 46.75 -14.87 173000 -47.14 47.99 -14.22 174000 -49.79 49.16 -13.13 174500 -51.36 48.62 -14.01 175000 -53.17 48.29 -14.74 176500 -59.26 47.82 -16.54 177000 -61.16 47.56 -17.22 177500 -62.81 47.09 -18.05 178000 -64.12 46.35 -19.07 178500 -65.03 45.28 -20.34 179000 -65.49 43.86 -21.88 179500 -65.21 42.21 -23.46 180000 -64.6 40.3 -25.25 183500 -56.64 33.85 -30.0 190000 -71.73 46.09 -20.99 192000 -69.21 44.05 -22.49 192500 -67.08 43.24 -23.24 193000 -62.26 42.42 -22.64 193500 -57.62 41.03 -21.4 194000 -53.33 39.38 -19.46 194500 -49.73 37.61 -16.51 195000 -46.95 36.12 -12.64 195500 -44.57 35.26 -8.34 196000 -42.09 35.07 -4.01 196500 -39.5 35.49 0.25 197000 -36.85 36.51 4.36 197500 -34.16 38.12 8.25 198000 -31.48 40.37 11.81 198500 -28.89 43.31 14.91 199000 -26.53 46.97 17.36 199500 -24.56 51.26 18.96 200000 -23.31 56.04 19.63 200500 -22.8 60.99 19.24 201000 -22.88 65.72 17.68 201500 -23.35 69.71 14.75 202000 -23.89 72.18 10.48 202500 -24.18 72.69 5.55 203000 -23.96 71.57 0.71 203500 -23.0 69.24 -3.6 204000 -21.17 66.34 -7.22 204500 -18.68 62.77 -9.62 205000 -15.96 58.68 -10.44 205500 -13.33 54.5 -9.76 206000 -10.96 50.63 -7.71 206500 -9.03 47.4 -4.44 207000 -7.08 44.56 -0.83 207500 -4.21 41.52 1.88 208000 -0.61 38.28 3.04 208500 3.15 35.03 2.66 209000 6.72 31.86 1.21 209500 9.9 28.7 -0.99 210000 12.04 25.86 -4.48 210500 13.51 23.21 -8.46 211000 14.44 20.66 -12.65 211500 14.77 18.2 -16.99 212000 14.31 16.11 -21.5 212500 12.69 14.69 -25.99 213000 9.96 13.6 -30.02 213500 6.41 12.65 -33.39 214000 2.2 11.84 -35.95 214500 -2.49 11.21 -37.54 215000 -7.44 10.83 -38.03 215500 -12.38 10.73 -37.35 216000 -17.07 10.85 -35.64 216500 -21.43 11.0 -33.2 217000 -25.32 11.15 -30.07 217500 -28.52 11.32 -26.25 218000 -30.7 11.5 -21.77 218500 -31.44 11.68 -16.85 219000 -30.63 11.88 -11.94 219500 -28.53 12.07 -7.42 220000 -25.5 12.28 -3.46 220500 -21.66 12.5 -0.28 221000 -17.16 12.73 1.86 221500 -12.28 12.94 2.84 222000 -7.3 13.13 2.55 222500 -2.57 13.29 0.98 223000 1.51 13.38 -1.88 223500 4.54 13.42 -5.83 224000 6.42 13.55 -10.45 224500 6.99 13.96 -15.38 225000 5.97 14.73 -20.18 225500 3.35 15.89 -24.25 226000 -0.53 17.42 -26.93 226500 -5.1 19.24 -27.44 227000 -9.58 20.49 -25.68 227500 -13.46 21.09 -22.61 228000 -16.33 21.13 -18.55 228500 -17.52 20.57 -13.76 229000 -16.41 19.49 -9.06 229500 -14.6 17.86 -4.73 230000 -11.69 16.0 -1.2 230500 -7.14 14.82 0.32 231000 -2.28 14.2 -0.49 231500 1.88 13.88 -3.19 232000 4.79 13.7 -7.23 232500 6.5 13.79 -11.91 233000 6.73 14.22 -16.86 233500 5.26 15.07 -21.53 234000 2.23 16.34 -25.27 234500 -1.94 17.99 -27.37 235000 -6.57 19.73 -27.08 235500 -10.89 20.74 -24.83 236000 -14.5 21.16 -21.42 236500 -16.93 21.02 -17.09 237000 -17.41 20.27 -12.21 237500 -15.72 19.09 -7.69 238000 -13.84 17.32 -3.45 238500 -10.31 15.61 -0.45 239000 -5.52 14.61 0.28 239500 -0.81 14.1 -1.19 240000 2.97 13.82 -4.41 240500 5.5 13.7 -8.71 241000 6.76 13.89 -13.52 241500 6.43 14.46 -18.45 242000 4.41 15.45 -22.89 242500 0.95 16.84 -26.16 243000 -1.42 17.81 -26.51 256000 9.53 15.0 14.07 264500 0.0 15.0 0.0 297000 0.0 -3.99 0.0]]} The attribute-value pairs are defined in Table 1, below.   The attributes are the same for the Effect Data field (of effects in the script) and the Motion Data field (of positions), except that the time values for the Motion Data are relative to the beginning of the show, whereas the time values for the Effect Data are relative to the beginning of the effect itself.  Also, the “rgb” color animation attribute only applies in the Effect Data field in the script table, because it doesn’t make sense to apply colors to positions. The “hash” attribute is an optimization for large imported data, such as data from importing a drone show.  If you are entering data by hand, your data should not include a hash attribute.   Property in Motion Data or Effect Data Example Meaning pos [pos [0 0 0 0 1000 0 10 0 2000 10 10 0 3000 10 0 0 4000 0 0 0]]   The syntax is: [pos [t0 x0 y0 z0 t1 x1 y1 z1…]]. The list of numbers in brackets is a list of samples defining a motion path of coordinates in connected line segments from sample point to sample point.  Each sample point is represented as four numbers, so the length of the list is 4N for N sample points.  Each sample point consists of an integer number of milliseconds followed by X, Y, Z coordinates in meters (integers or floating point numbers).  The milliseconds represent an absolute time, not a time delta. If the first sample in the list does not begin at time 0, then the implicit starting point at time 0 is 0, 0, 0 coordinates, and the path will interpolate from there to the first sample point explicitly in the list. Implicitly, the motion path after the last sample point continues with the coordinates of the last sample point. hpr [hpr [10000 0 0 3600]] The syntax is: [hpr [t0 h0 p0 r0 t1 h1 p1 r1…]]. The list of numbers in brackets is a list of samples defining a motion path of orientations.  Each sample point is represented as four numbers, so the length of the list is 4N for N sample points.  Each sample point consists of an integer number of milliseconds followed by heading, pitch, and roll angles in degrees (integers or floating point numbers).  The milliseconds represent an absolute time, not a time delta. Heading, pitch, and roll values are not restricted to 360 degrees.  From sample point to sample point, the intermediate heading, pitch and roll values interpolate between the two samples individually as numbers, and the intermediate orientation is constructed from the interpolated heading, pitch and roll values; as opposed to the intermediate orientations being constructed by interpolating between the orientations defined by the heading, pitch and roll values at the sample points. These interpolation mechanics support “spinning” multiple rotation cycles between sample points.  The example  [hpr [10000 0 0 3600]] means at time 10 seconds (10,000 milliseconds) , the roll is 3600 = 360 degrees * 10.  Interpolating from the implicit identity orientation at time 0 to this sample point at 10 seconds thus rotates the orientation completely around 10 times in the span of 10 seconds. pos2 [pos2 [0 .5 0 0]] The syntax is: [pos2 [t0 x0 y0 z0 t1 x1 y1 z1…]].  The list of numbers has the same syntax and meaning as for pos, except that pos2 defines a position offset that is rotated by the hpr rotation, if present, and then added to the pos position offset. To make a spinning wheel with the pyro effect at the end of a 0.5m spoke, the positions and orientation offsets could be: [pos2 [0 .5 0 0]] and [hpr [10000 0 0 3600]].  This position offset is constant, radially out 0.5m from the origin, but the hpr spins that position offset around the origin 10 cycles over 10 seconds. hpr2 [hpr2 [10000 3600 0 0]] The syntax is: [hpr2 [t0 h0 p0 r0 t1 h1 p1 r1…]]. The list of numbers has the same syntax and meaning as for hpr, except that hpr2 does not affect pos or pos2 offsets.  Hpr2 defines an orientation that is composed with hpr to construct the final orientation of the effect.  Hpr2 applies within the frame of reference of hpr.  In a human arm analogy, the hpr2 is the wrist orientation, and the hpr is the elbow orientation. rgb (in Effect Data only) [rgb [0 255 10000 65280]] The syntax is: [rgb [t0 rgb0 t1 rgb1…]]. The list of numbers in brackets is a list of color samples defining a color animation from sample point to sample point.  Each sample point is represented as two numbers, so the length of the list is 2N for N sample points.  Each sample point consists of an integer number of milliseconds followed by integer RGB value with B represented by the low 8-bits of the number, G represented by bits 8-15, and R represented by bits 16-23.  The milliseconds represent an absolute time, not a time delta. If the first sample in the list does not begin at time 0, then the implicit starting point at time 0 is black, and the color animation will interpolate from black to the first sample point explicitly in the list. Implicitly, the color after the last sample point continues with the color of the last sample point. The RGB colors defined by this syntax apply to effects whose VDL contains the color term, “ScriptRGB” instead of an explicit color like “Red” or “Blue”.  The ScriptRGB term indicates the effect should get its color from the Effect Data field. hash [hash 1908853237] The hash attribute value is an integer identifying full payload of the Motion Data or Effect Data field (excluding the hash value itself).  The hash attribute is an optional optimization for large imported data, such as data from imported drone shows, enabling the Finale 3D renderer to determine quickly whether the data has changed. If you are entering Motion Data or Effect Data manually, your data is probably small enough that the hash attribute optimization is insignificant, so your data does not need to include the hash attribute.  If you are generating large data manually or by some programmatic method, you should calculate and include a hash based on the data content using any hash algorithm that is likely to produce a different hash value for different data.  

The Pro version of Finale 3D has the capability of importing drone shows (file type “.vviz”) created externally in drone design software. In Finale 3D you can combine the imported drone shows with fireworks in the 3D view for the purpose of designing hybrid shows or making videos.   Exporting from your drone design software Finale 3D is not used to design drone animations. Drone shows must be designed in third-party software that supports exporting to the VVIZ format. Finale 3D imports these VVIZ files for the purpose of combining drones with fireworks in hybrid shows or for making simulations and videos. For platform-specific instructions on exporting VVIZ files from your drone design software, see: Exporting VVIZ from Verge Aero Exporting VVIZ from Drone Show Software (DSS) Exporting VVIZ from Skybrush Studio for Blender If you don’t see your drone design software listed here, contact the developer of your software for instructions. If your software does not yet export in the VVIZ format, please tell developers they can use the information in our VVIZ programmer documentation to add VVIZ export support to their software.   Importing your drone show in Finale 3D Once you have a drone show in the VVIZ format, you can import it in Finale 3D by going to “File > Import > Import drone show”. The function will import or re-import the drone show, merging it into the active show which may already contain pyro or drones. When importing a drone show, you have the option of merging with or replacing drones in the active show while leaving pyro unaffected. Figure 1 – Example drone show imported into Finale 3D to combine with fireworks   In Finale 3D, drones are represented as positions. In Figure 1, the pink positions in the shape of a heart in the sky are the drones. If you import a drone show with 300 drones, the import function will add 300 positions to the show you are working on, with position names identifying the drones, like D001 and D002. Drones may contain pyro payloads or colored LED light effects or both. Thus, in addition to importing positions to represent the drones themselves, the import function also imports effects in the script window and the Per-show effects collection to represent the visual effects attached to the drones. To avoid overwhelming the timeline and script window with so many events as to make scripting pyro difficult, the import function automatically groups the imported drone effects into a single row in the script window, and hides the trajectories and timeline bars of the drone effects in the 3D view and timeline. You can see all the drone effects as individual rows or collapse them into a single row by clicking the blue gear icon in the upper right of the script window and toggling “Show groups as one row”. If you want to unhide the drone effects’ timeline bars and trajectories, you can do the menu item “Script > Unhide all”. To re-hide them, do “Edit > Select special > Select drone effects” and “Script > Hide special > Hide timeline bars and trajectories as group”.   Importing or adding pyro payloads for the drones In addition to the LED light values specified as RGB colors, VVIZ files may contain pyro payloads for the drones. A pyro payload is typically a gerb, but it could also be a comet shooting down or at an angle, or a comet “cake” that shoots comets out radially. A drone can have multiple pyro payloads. In Finale 3D, pyro payload effects are imported aiming down by default since that is the usual case, though the VVIZ file can specify pan and tilt angles. Finale 3D supports two workflows for pyro payloads: The user specifies all pyro payload information in the drone-related software outside of Finale 3D. The user specifies template pyro payload information such as firing system and shooting angle information without the ignition times or specific effects in the drone-related software, and then fills in the ignition times and specific effects in the script rows in Finale 3D. When the designer imports a drone show into Finale 3D, if the existing show contains pyro payloads, Finale 3D will present a dialog asking, “Preserve existing pyro on drones?” If following the first workflow, re-importing the drone show will replace any existing pyro payloads in Finale 3D with updated information. If following the second workflow, choose to preserve the existing pyro since it has been modified in Finale 3D. Selecting this option causes the import process not to delete the existing pyro script rows and effect definitions and to ignore any pyro payloads in the file being imported. If drone IDs have changed, the designer will need to update script rows manually. The two pieces of information required for a pyro payload are the VDL (specifying visual appearance) and the optional part number (used for inventory tracking or matching with effects in your inventory). The VDL is a text description like “10s Gold Gerb” or “25mm Red Comet”. Finale 3D creates a visual simulation based on this description.   File size and resolution The file size for an exported drone show may be large, containing motion paths and color changes for hundreds of drones. Compression settings in the export process affect file size. Since drones move smoothly, compression algorithms can reduce size substantially without visual difference. Table 1 – Recommended sample rates Data type Lower bound Upper bound Position data 4 FPS 10 FPS Color data 4 FPS 20 FPS Finale 3D can import sample rates up to 100 FPS, but higher frame rates require more memory and may exceed your machine’s resources. Generally, 10 FPS for position and 20 FPS for color work well for shows under 20 minutes. Longer shows may require lower rates.   Table 2 – Special fields of imported drone data Field Name Value Explanation Custom Part Field of effects imported into the Per-show effects collection drone The Custom Part Field helps the import function decide whether to overwrite or delete effect definitions in Per-show effects if you are re-importing a drone show.  Since importing a drone show is intended to replace any previously imported drone data in the active show, the import function deletes existing effects in the Per-show effects collection that have “drone” in the Custom Part Field.  Any new effect added by the import function will have “drone” in the Custom Part Field to ensure that re-importing will delete or overwrite it with newer content from the file being imported. All LED effects and any pyro payload effects that do not have part numbers in the imported script file will be imported, and will thus have Custom Part Field of “drone”.  Pyro payload effects that do have part numbers will also be imported — unless their part numbers match part numbers of existing effects that do not have Custom Part Field of “drone”, in which case the effect definitions being imported are ignored in lieu of the existing effect definitions for the same part numbers. If you are importing drone shows with LED effects exclusively, you don’t need to pay attention to the Custom Part Field.  However, if you are importing drone shows with pyro payload effects that correspond to effects in your inventory collections then you probably want to use the effect definitions from your inventory collections rather than the placeholder effect definitions constructed from the VDL in the imported script file.  In this case, the best workflow is: 1) In your drone show design, use part numbers for the pyro payload effects that match your inventory part numbers, 2) Import the drone show into Finale 3D, 3) Do “Effects > Update per-show effects…” to update the imported effect definitions to match your inventory, 4) If and when you re-import the drone show into Finale 3D, you will not need to repeat step (3) since the re-imported effects will not overwrite the updated effect definitions that do not have “drone” in the Custom Part Field. Custom Script Field of events imported into the script window drone The Custom Script Field helps the import function decide whether to overwrite or delete events in the script window.  Since importing a drone show is intended to replace any previously imported drone data in the active show, the import function deletes existing events in the script that have “drone” in the Custom Script Field.  Any new event added by the import function will have “drone” in the Custom Script Field to ensure that re-importing will delete or overwrite it with newer content from the file being imported. Type of positions imported into the positions window drone The Type of the imported positions representing drones is “drone” as opposed to “pyro” or “fixture” or “slave”.   Positions with Type of “drone” are drawn in the magenta color, to make them recognizable from pyro or fixture positions.  The Type value also supports the “Edit > Select special > Select drone effects” function and similar functions that recognize events as applying to drones based on the Type of position that houses them.  Lastly, the position Type also affects addressing.  Since pyro payloads of drones generally need firing system addresses (something has to ignite them!) but LED light effects on drones do not need firing system addresses, the addressing functions in Finale 3D do not assign firing system addresses to effects of Type “light” if they are on positions of Type “drone” (see Why is ‘Type’ so important? What depends on it?). Duration of events in the script window Duration of LED light effects Imported pyro effects contain their duration in the VDL itself, as in “10s Gold Gerb”.  Imported drone LED lights turn on and off and change colors during the show continuously, so Finale 3D represents the LED light effects that change over time as long duration, animated effects.  Finale 3D divides the total LED effect duration into segments of maximum 60 seconds, and creates individual animated effects for each segment. The LED effects’ color animation information is stored in the Effect Data field of the script window.  Since imported LED light effects are limited to 60s duration, a flight path of a drone lasting longer than 60s will require multiple events, back to back in the script. Effect Data of events in the script window RGB color animation information Imported LED light effects for drones have a VDL description that includes the term ScriptRGB, as in the VDL, “ScriptRGB Point Light”.  That term indicates the color of the light effect, which may animate over time, is specified by information in the Effect Data field of the script event. VDL of effects in the Per-show effects collection Pyro payload description like “10s Gold Gerb” or LED light description, “ScriptRGB Point Light” The VDL of imported LED light and pyro effects specifies the visual description of the effect.  All LED light effects use the same effect in the Per-show effects collection.  The effect’s color animation and duration are specified by fields in the script window (Effect Data and Duration). Motion Data of imported positions in the positions window Position and optionally orientation animation information Imported drones are represented as positions whose motion paths are specified in the Motion Data field of the positions.   Compression and troubleshooting Finale 3D‘s table cells are limited to 16k characters per cell. As of June 2024, Finale 3D automatically compresses Motion Data and Effect Data during import to stay within this limit. Recommended sample rates help prevent exceeding system resources. Compression uses a high-quality variable sample rate algorithm and GZIP encoding to reduce data size. Motion Data appears encoded as a “blob” unless blob compression is disabled. Up to 48 minutes of drone flight can be compressed within the 16k limit before noticeable artifacts occur. You can disable or configure compression using variables in the Per-Show Settings prior to import.   Table 3 – Variables in Per-Show Settings for troubleshooting compression Variable Value Range Explanation vviz_do_not_compress true or false If true, prevents variable sample rate compression. Finale 3D will import the file, but if the data cells exceed 16k characters, then the drone show will not be saved along with the show file when the show file is saved. vviz_disable_blobs true or false If true, prevents the GZIP blob compression of Motion Data; making Motion Data in the Positions window human readable (like “{[pos [250 0.0 0.0 0.0 10000…” instead of “{[blob #[“{PH4sAACmVZSa5lNQ…”) but at the cost of fitting only about half as many samples within the character limit. vviz_max_data_size 1000 – 100000 If you want to test the compression of the motion data to a threshold other than 16k characters, set this field to your desired limit. If your limit is greater than 16k, then the drone show will import but will not be saved along with the show file when the show file is saved. vviz_max_rgb_samples 3 – 100000 Each RGB sample can take 15 characters to represent, depending on the size of the numbers. Thus the 16k character limit allows approximately 1092 samples. Finale 3D‘s default max RGB samples limit is 1088. You can change it with this variable. The drone lights are represented in Finale 3D as one-minute long effects with color animation provided by the Event Data. Thus unlike the motion samples the sample limit for RGB samples applies to at most one minute of data. The 1088 sample limit is 1088/60 = 18.13 FPS, which is obviously a fairly high resolution already.  

Effect macros are snippets of a show that you can re-insert as easily as inserting an individual effect.  Effect macros have a variety of uses, including: Saving re-usable script segments as building blocks from which to build new show designs with just a few clicks Saving short script sequences as motifs that can be re-inserted in the same positions or different positions Saving short DMX script sequences that always apply to the same fixtures in a show, no matter what fixtures (positions) are selected Saving effects or sequences that have keyboard shorts that you trigger in real time while playing or looping the show simulation to build a show on the fly Technically, effect macros are just effects in the effects window.  Like other effects, effect macros have part numbers that identify them; and they can be inserted into the show by clicking on their effect icon in the effect window.  Unlike other effects, inserting an effect macro doesn’t add an instance of the effect macro’s part number to the script; instead it adds instances of all the effects that the effect macro represents.   Effect macros are like copy/paste In a sense, effect macros are a lot like copy and paste.   Creating an effect macro is a lot like copying a sequence of effects from the script.  Inserting an effect macro is a lot like pasting the copied effects into the show.  In fact, effect macros are implemented by way of storing a compressed copy buffer in the VDL field, so it is no accident that effect macros and copy/paste are such similar operations.   Figure 1 – The “Script > Effect macros > Create effect macro from selection in script…” dialog   The effect macro functions in the Script menu include “Script > Effect macros > Create effect macro from selection in script…” which creates an effect macro from the selected effects and your choices in the dialog shown in Figure 1.  Like the copy/paste operation, effect macros contain within them not just the copied effects but also references to the positions from which the effects were copied. Copy/paste has some complicated rules about what happens you paste, as fully explained in Copy/paste.  In brief, if the copied effects all stem from a single position, then they will be pasted in whatever positions are selected at the time of pasting, yielding duplicates if more than one position is selected.  If copied effects stem from multiple positions, then they will be pasted into the selected positions if exactly the same number of positions are selected as are referenced by the copied effects; otherwise the copied effects will be pasted into their original referenced positions no matter what.   Inserting at the recorded positions versus the currently selected positions Effect macros work exactly like the paste operation if the checkbox “Applies to recorded positions no matter what positions are selected” is not checked.  If the checkbox is checked, then the effect macros always insert into the original positions.  The checkbox is generally ON for use cases like (1) and (3) and (4) as described above.  However use case (2) requires the checkbox OFF.  A common example of case (2) is a fanned flight or chain of shells.  Finale 3D has many features for inserting effects and creating fans, but if you create an effect macro from effects that are already in a fan, then inserting the fan is as easy as a single click. Since effect macros created with the checkbox ON are bound to their original positions, the positions themselves play a role in the meaning of the macro.  Instead of calling such a macro “My Sequence 1” it would make more sense to call the macro “My Sequence 1 at front left ceiling fixtures” or something like that in order to make the positions explicit in the name of the macro.  Otherwise you would never know by looking at the macro what it applies to.  Since including the positions in the name of the macro makes so much sense, the create macro dialog automatically adds the positions to the macro name if the “Applies to recorded positions” checkbox is ON.   The name “My sequence 1” entered into the dialog becomes “My Sequence 1 [P01 P02 P03]” if it applies to those three positions.   Looping Since effect macros can be bound to their original positions, you can build a show on the fly by clicking on effect macros or pressing their keyboard shortcuts while the show simulation is playing.  Each effect macro is like an instrument in music composition software, and clicking on the effect macro is like playing a note with the instrument.  Since it is nearly impossible to click on positions while a show simulation is playing, the only way the “on the fly” method works is if triggering an effect macro indicates not just the effects, but where they go — which is exactly what the “Applies to recorded positions” checkbox guarantees. If you decide to try the “on the fly” scripting method, consider the “Looping” options in the show menu.  You can add loop start/stop markers to the show, and then play a section over and over again, layering in the effects by pressing the effect macro keyboard shortcuts while the show simulation is playing.   Changing the effects or position references contained within effect macros Especially with DMX scripting but also possible with pyro, you may find yourself defining a set of effect macros for one group of effects or positions, and then wanting to create an entire duplicate set of the effect macros for a different set of effects or positions.   (If, for example, you want to create a set of 20 effect macros for various color par light effects — red, blue, yellow, etc. — then creating 20 effects for every single color would be tedious.  The “Find and replace inside macros” function provides another way. Using the replace function, you can replace the effects or positions in a single effect macro or an entire batch of effect macros all at once, which can significantly cut down on the work required.  I find it useful to save my effect macro collections for different position sets as separate FDB effect files.  With that approach, I can duplicate the file, select all the effects in it, and use the replace function to create the variations of the entire file.   Figure 2 – The “Find and replace inside macros…” function changes the positions or effects contained in the macro.   The macro payload Effect macros store their payload of information as a compressed copy buffer in their VDL field.  If you need to see the payload information of a macro in human readable form, for programmer-like purposes, you can do the menu item, “File > Admin > Decompress macros” to decompress the macro payloads in all selected effect macros in the effect window.  The maximum payload size is 10KB, so if decompressing would result in a larger size (for very large macros), the decompression operation will not work.  

If creating effect definitions one at a time using the dialog of Creating fixture definitions and effects for your own fixtures is too slow, programmers can create batches of effects manually by copying effects for existing fixtures and modifying them.   This article lays out instructions for the manual process.   Step 1: Find a similar fixture that is already supported Look over the lists here for lights and here for flames and sparks to find a fixture similar to yours that is already supported.   First narrow the candidates down by general category — par light, moving head light, sparks machine, moving head flame projector, etc.  Within that category, find the candidates that have similar properties to your own fixture.  For example, does the par light have RGB, or RGBW, or RGBW + Amber + UV, a color wheel, etc. Next, decide whether the effects lists for the candidates match what you are looking for.  Create a new show and right-click a position to configure it as a fixture.  Configure the position as the type of fixture you want to examine, and then right-click the position again to do “Filter effects window to compatible DMX effects”.  Look at the effects in the effect window to see if they match what you’d like for your own fixture. If the effects look like a good match, find the documentation for the fixture in the Light fixtures articles or Flame and spark fixtures articles in the documentation here.  Compare the DMX channel specifications (DMX personality) of the fixtures in the documentation to your fixture’s user manual.  The more similar they are, the easier the task of creating your fixture definition from an existing starting point.  Choose the similar fixture that looks like the best starting point for making your own fixture.   Step 2: Choose a fixture ID for your fixture Fixture IDs and effect IDs make it possible to convert effects from one fixture to another (Fixture cloning).  The fixture IDs also make it possible for the Finale 3D user interface to filter the effect choices that can be added to a fixture according to their compatibility, and to error check at times of addressing and exporting that the show does not contain any incompatibilities. The Standard Fixture IDs for pre-defined fixtures are integers from 1 to 999,999 excluding 100-199 (see Standard Effect IDs and Standard Fixture IDs).  User-defined fixture IDs are in the range 100-199, so you can simply give your fixture the fixture ID 100.  If you are implementing multiple new fixture types, the next can be 101, and so on, counting up.   Thus all your user-defined fixtures will be distinguished from one another and none of them will conflict with the fixtures already defined in Finale 3D.   Step 3: Copy the effects from the similar fixture and modify the part numbers and fixture IDs Create a new show to work with if haven’t already done so in Step 1.  In the effects window, copy the effect rows from the similar fixture, in whatever collection they are in, into the Per-show effects collection of your own show.   You can copy rows by selecting them, and then pressing Control-C, then switching to the Per-Show effects collection and pressing Control-V to paste. Rename all the part numbers of the effects to unique new part numbers, to avoid conflicts.  There’s no rule, but it is a good idea to make part numbers all upper case, with no spaces or special characters, and fewer than sixteen characters.  It is also useful to make the part numbers recognizably linked to your fixture or the fixture’s manufacturer by starting out with a few characters that are the initials of the manufacturer or brand.  For example, the part number “TS11211” identifies one of the effects for Tomshine light fixtures. To edit the part numbers, you can double click on the part number field of a row and edit it directly in the table, or you can select the entire column of part numbers and copy/paste it into a text editor or into Excel, edit the part numbers there, and then copy them back over the selected column of cells. After editing the part numbers, the next step is to edit the descriptions of the effects to change the fixture ID references to the fixture ID you decided on in Step 2.  The fixture ID is the first number in square brackets in the description.  For example, the Tomshine part number TS11211 in the Generic Effects collection has the description, TSMHG80W [027/1011] Red Flash (lg) In your copied effects, if your fixture ID is 100 then change the description to the following (and change the word “MYFIXTURE” to a short nickname of your fixture): MYFIXTURE [100/1011] Red Flash (lg) You may find it easier to copy the effect descriptions into a text editor or Excel, and then make the changes there and copy them back since you can use find and replace functions to make the substitutions in a text editor.  The second number inside the brackets (1011 in this example) is the effect ID.  Assuming your modified effect is equivalent to the original except applying to a different fixture, the effect IDs should stay the same.  In this example, just leave the 1011 as is.   Step 4: Write a “Fixture Definition” and copy it into the Custom Part Field of all the effects Unhide the Custom Part Field column in the effects window and replace or modify the fixture definitions with a fixture definition for your own fixture.  Fixture definitions for pre-defined fixtures in Finale 3D are incorporated directly into the program, so if you are basing your fixture off a pre-defined fixture it is likely the Custom Part Field will be empty.  The exception is the Explo X2 Wave Flamer and compatible fixtures from other manufacturers, which use the Custom Part Field for a different purpose (see Explo X2 Wave Flamer).  If you are basing your fixture on the Explo X2 Wave Flamer, please contact Finale for assistance. For user-defined fixtures, the fixture definition will be stored in the Custom Part Field of every effect for the fixture.  A show with multiple effects for the same user-defined fixture may therefore contain multiple copies of the same fixture definition in its effects.  The redundancy serves to ensure that even if a show contains just one of the effects for your fixture, it is sure to have a fixture definition stored in the effect itself. Please see User-defined fixture definitions for instructions to create your fixture definition.  It is just a single line of text that you can copy into the Custom Part Field cells of your effects, along side the modified part numbers and descriptions.  An example Custom Part Field for the Tomshine fixture is: {[name "Tomshine [] Moving Head Gobo 9CH"][fixtureId 100][numChannels 9][defaultEffectPartNumber TS11301][channelLabels {[0 "Pan"][1 "Tilt"][2 "Motor Speed"][3 "Dimmer"][4 "Strobe"][5 "Color"][6 "Gobo"][7 "Set To Zero"][8 "Set To Zero"]}]} Fixture definitions in the Custom Part Field are case-sensitive and unforgiving with respect to missing punctuation, so please ensure you have matching brackets, double quotes, etc.   Step 5: Write DMX Patches for your fixture’s effects Unhide the DMX Patch column of the effects window.  The effects you are working on will already have DMX Patches for their original fixture.  You’ll need to replace the DMX Patches with the equivalents that work with your fixture.  DMX Patches are small computer programs that calculate the DMX channel values that implement the effect for your fixture, taking into consideration (for certain types of effects) the angle of the dotted line effect trajectory in the user interface and the duration of the effect if the user has modified it in the timeline or script window.  An example DMX Patch for the Tomshine fixture is, [setupBeginEndPatch 1000 0 :pan540 :pan540 :pan540 1 :rTilt230 :rTilt230 :rTilt230 2 0 0 0 3 0 255 0 5 12 12 12] The terms and numbers in the DMX Patches are explained in The DMX Patch field, which provides the instructions you’ll need to implement your own DMX Patches.   Step 6: Modify the VDL of your fixture’s effects if necessary If the effects you are creating for your own fixture have the same visual appearance as they do for the fixture you are copying, then you don’t need to modify the VDL at all.  Just leave it as is.  If the effects are different — taller, bushier, etc. — then you can edit the VDL to customize the appearance, just as you can edit any of the pyro effects.  If the effects are modifier effects or relate to Move-To effects, please add the keywords described in VDL for special DMX effects like “Move-To” and “With Strobing’.   Step 7: Save your effects Once you’ve defined all your new effects, copy them out of the test show into their own FDB file (“File > Effects files > New effects file” to create the effects file) or into your My Effects, so you have them available for scripting.  After you have defined your effects in Steps 1-7, the next time you right-click on a position and choose “Configure position as DMX fixture” you’ll have the option of picking the fixture that you defined in your effects.  Here’s an example of a user-defined fixture I created for an imaginary fixture manufacturer, WillCo:   Figure 1 – The “Configure position as DMX fixture” menu item will include your user-defined fixtures as options  

Effect libraries for light fixtures contain a set of pre-defined effects to use in your show, like “Red Flash (lg)” for a par light or perhaps a “Green Move-To (lg)” for a moving head fixture.   If a fixture supports strobing, then its effect library will likely include effects with names like “With Strobing (Fast)” or “With Strobing (Medium)”.  These strobing effects don’t make any light on their own; they are modifier effects.  They modify the behavior of light effects that are playing on the fixture at the same time.   Figure 1 – The yellow dotted lines overlaying the second set of effects on the timeline cause them to strobe.   To add strobing effects to your show, first add whatever light effects you want to the fixtures, and then add “With Strobing” effects to those same fixtures.  The “With Strobing” effects need to begin at the same time or before the effects that they modify, and to avoid confusion they should extend long enough cover the full extent of the effects that they modify.  The effect simulations and DMX output for an effect are determined by the strobing modifiers overlapping the beginning of the effect.  The modifiers at that time will apply for the full duration of the effect.  If a strobing modifier ends in the middle of an effect’s duration, the strobing will continue to the end of the full duration anyway, both for the simulation and in the exported DMX script, as illustrated in Figure 2.   Figure 2 – If the dotted line overlaps the beginning of the solid line, then the full duration of the solid line effect will be strobing.   “With Strobing” effects typically have a default duration of 10 seconds, which is probably too short or too long.  After inserting the “With Strobing” effects, grab the the right end of their timeline bars one at a time and drag them to adjust the durations; or edit the duration field of the “With Strobing” effects in the script table.  As you can see in Figure 1, the durations of the yellow dotted lines representing the “With Strobing” effects don’t need to be exact; they just need to cover the red lines representing the light effects that they modify.   Strobing effects that strobe according to their own definitions While the more common approach to strobing is with modifier effects like “With Strobing” that overlap and apply to other effects like “Red Par Light”, it is also possible to create an effect that is strobing according to its own definition and therefore doesn’t require an overlapping modifier effect.  An effect like “Strobing Red Par Light” if present in the effect library can be inserted onto the timeline just like a “Red Par Light” effect, and the only difference will be that it is strobing.  The VDL for strobing DMX effects and modifiers is a little complicated if you are creating your own effect libraries; a full description is here: Creating fixture definitions and effects.    

Some fixtures require a “Reset Fixture” effect to set certain DMX channels to initial values.  If you see an effect called “Reset Fixture” in the effect library for a fixture, please add one of the effects to the fixture at the beginning of the show.  Finale 3D will give you a warning when you export a show script if you are using a fixture that requires initialization and are missing the “Reset Fixture” effect.  The fixtures requiring a “Reset Fixture” effect are listed in Table 1 of Supported light fixtures (and Standard Fixture IDs).   Explanation It is most common for DMX channel values of 0 to correspond to natural default values, but that’s just not the case for some fixtures.  For example, the 30W Tomshine moving head fixture’s “no gobo” pattern does not correspond to the DMX gobo channel value of 0; it corresponds to values between 16 and 23!    The flash effects for this fixture do not themselves set the gobo channel, in order to allow “With Gobo” effects to apply the gobo as a modification.  Thus if the gobo channel value of 0 corresponds to a gobo, the user is in for a surprise gobo unless the user adds a “Reset Fixture” effect that sets the gobo channel value to a number that nullifies the gobo pattern.

Step by step instructions for defining your own fixture definitions and effects in Finale 3D manually are in the article, Creating fixture definitions and effects for your own fixtures.  One step in that process involves writing a line of code called a “Fixture Definition” and storing it in the user-defined effects for your fixture.  This article provides the specifications for that line of code. The line of code specifies, The name of the fixture The fixture ID Number of channels Part Number of the default effect Labels of DMX channels in the DMX personality Part Number of “initialize fixture” effect, if required Part Number of safety channel effect, if required A short nickname for the fixture (optional) Boolean flag indicating whether the safety channel’s address is independent of the DMX Channel Base (optional) All of this information is easy to find in the user manual of your fixture.   Syntax An example fixture definition for a Tomshine moving head light fixture is: {[name "Tomshine [] Moving Head Gobo 9CH"][fixtureId 100][numChannels 9][defaultEffectPartNumber TS11301][nickname "TSGOBO"][channelLabels {[0 "Pan"][1 "Tilt"][2 "Motor Speed"][3 "Dimmer"][4 "Strobe"][5 "Color"][6 "Gobo"][7 "Set To Zero"][8 "Set To Zero"]}]} The fixture definition is written in a programming language in which curly brackets define set of attributes and their values.  Each attribute/value pair is in square brackets.  Thus in this example, the first attribute is, name and its value is, "Tomshine [] Moving Head Gobo 9CH" (double quotes included).  The square brackets inside the double quotes are just part of the string.  If the string contains any embedded double quotes, they are preceded by backslash, as in “2\” Red Peony”.  The attributes are case-sensitive, so be careful to type fixtureId, not FixtureId.   Attributes The name attribute should begin with a short, upper case abbreviation or nickname of the fixture brand or manufacturer with no spaces or special characters, followed by square brackets with nothing in them, followed by the fixture description itself. The fixtureId attribute is the fixture ID number.  User-defined fixture IDs are in the range 100-199. The numChannels attribute is the number of channels of your fixture’s DMX channel map, which is called its “DMX personality”.  Fixtures often have multiple DMX personalities that you can choose from.  When you make a fixture definition and set of effects for that fixture definition in Finale 3D, it is specific to a single DMX personality, and thus has a specific number of channels.  If you notice in the syntax example above, the name of the fixture is “Moving Head Gobo 9CH”, which indicates that it represents the 9 channel DMX personality of the fixture.  If you use effects in Finale 3D that are made for one DMX personality of your fixture, and yet you configure your fixture to a different DMX personality, then the exported DMX script will be incorrect. The defaultEffectPartNumber attribute is the part number of the effect that Finale 3D will use when it cannot find an effect for your fixture to match a need of the “Change DMX fixture and convert effects” function.  If you use that function to convert a show from some other fixture to your fixture, and the show contains effects for the other fixture that you have not defined for your fixture, the defaultEffectPartNumber is what will be used as a placeholder.  The part number is a symbol, not a string, so it is not surrounded by double quotes.  If the part number contains spaces or double quotes within it, then it can be written in an alternate syntax: #<"TS11301">.  The alternate syntax allows for spaces and double quotes as part of the part number.  Contained double quotes should be preceded by backslash, as in #<"2\" RED PEONY">.  Although Finale 3D supports all characters in part numbers, it is generally a bad idea to have double quotes or spaces in part numbers since they can cause trouble if you export to Excel or use barcodes or other systems. The channelLabels attribute is an object (curly brackets!) that contains as its attribute/value pairs the list of DMX channel offsets beginning with zero, and their meaning as a short description of just a few words.  The description needs to be short because it is included in the exported DMX scripts to make the scripts more readable, and many firing systems have character limits of the description fields.  The DMX channel offsets begin with zero.  Your fixture’s user manual may have a DMX channel specification that begins with channel 1 and counts up.  Please renumber them when you add them to the channelLabels field of your fixture definition, so the first channel is 0, the second is 1, and so on. The requiredInitializeFixturePartNumber (only if required!) attribute is a part number symbol, similar to the defaultEffectPartNumber (i.e., not in quotes).  Most fixtures do not require an effect to initialize the fixture, so most fixture definitions do not include this attribute.  Some fixtures have a DMX personality that requires an initial configuration for some of the DMX channels.  For these fixtures, the user needs to add an effect at the beginning of the show to reset/initialize the fixture by setting those channel values.  On the basis of this attribute in the fixture definition, Finale 3D will warn the user if the user has forgotten to add any required reset/initialize fixture effects before attempting to export a DMX script.  An example attribute value for the 30W Tomshine moving head fixture is,  [requiredInitializeFixturePartNumber TS12295]. The requiredSafetyChannelPartNumber (only if required!) attribute is a part number symbol, similar to the defaultEffectPartNumber (i.e., not in quotes).  Most flame projector fixtures require a safety channel effect to enable the fixture.  On the basis of this attribute in the fixture definition, Finale 3D will warn the user if the user has forgotten to add the required safety channel before addressing or export a DMX script.  An example attribute value for the Galaxis G-Flame flame projector is,  [requiredSafetyChannelPartNumber GFX9899]. The safetyChannelConfiguredSeparately (only if safety channel is required!) attribute is a boolean flag with value true or false that is true if the fixture’s safety channel number can be set independently of the fixture’s DMX Channel Base that is the base address for the channels in the DMX personality.  An example attribute value for the Galaxis G-Flame flame projector is,  [safetyChannelConfiguredSeparately true]. The optional nickname attribute should be a short, upper case string 3-8 characters long, which will be appended to the beginning of effect names for the fixture so the effect names contain within themselves an indication of what fixture they are meant for, as a convenience for the designer when looking through rows in the script window or exported script.    

If you have a fixture that is not yet supported in Finale 3D, you can reach out to Finale support by email for assistance or you can create fixture definitions and effects yourself using the menu item, “DMX > Create DMX effect…“. If you create DMX effects for pre-defined fixtures, you’ll fill the channel values in the pre-defined channel map, which indicates for example in Figure 1 that channel 1 is “Red”, channel 5 is “Strobe”, etc.  If you create DMX effects for your own user-defined fixtures, you’ll also fill the channel descriptions in channel map, typing in the word “Red” for channel 1 and “Strobe” for channel 5, etc.  The channel map you define will be embedded in the effect itself in its Custom Part Field property when the effect is saved.  The next time you create an effect for the same user-defined fixture, the channel map you already created will pop up, so you do not need to type the channel descriptions again every time. Figure 1 – The “Edit DMX effect…” dialog for a pre-defined fixture has read-only fields for the fixture properties.   Typing the words “Red” or “Strobe” into the channel map doesn’t actually have any bearing on the exported scripts, because the words you type are just labels for your own convenience.   The channel values are what matters to the exported script.  As you can see in Figure 1, each channel has an option for the “Begin value” and “End value”.  “Begin” and “End” refer to the beginning and end of the effect.  If you stretch an effect on the timeline to be 20 seconds long, then the “Begin” value will be set at the beginning of the effect and the “End” value will be set 20 seconds later.  Thus, even if you need five different duration variations of an effect, you only need to create the effect once, and you can adjust the durations of the events in the script, or you can copy/paste the effect definition in the effects window and change the Duration column values to create the effect variations.   Creating effects for new fixtures versus existing fixtures When you select “New fixture” in the “Fixture type” field of the dialog (about five rows down from the top of the dialog), the fields related to the fixture properties become editable for you to define the fixture itself as shown in Figure 2. Figure 1 – The “Create DMX effect…” dialog for a new fixture has fields to define the fixture in addition to the effect.   The fixture related fields are the Fixture ID and the four rows immediately below the “Fixture type” field, and the channel descriptions at the bottom of the dialog.  To create your own fixture definition, fill in these fields as follows: “Fixture ID” is a number from 100-199 of your choice.  Just start 100 for your first fixture definition and count up for your other fixtures.  This range of numbers does not conflict with any of the pre-defined fixtures. “Fixture name” is what will appear in menus for selecting fixtures, like the menu in the “Configure position as DMX fixture” dialog of Figure 3 or the edit and create dialogs of Figure 1 and Figure 2.  Throughout the application, any functions that involve selecting a fixture type will present a dialog that includes all the application-defined fixture options and all the user-defined fixture options that are present in any of the effects in the script or any of the effects collections. “Fixture manufacturer” is just a label for your own convenience to help identify fixtures.  Together, the fixture manufacturer, Fixture ID and fixture name are combined in the menu items as in, “TOMSHINE [027] Moving Head Gobo”. “Nickname for the fixture” is a short, usually uppercase, abbreviation for the fixture like “TSMHG”, which is combined with the Fixture ID, Effect ID, and effect name as in “TSMHG [027/1011] Red Flash (lg)” to construct the effect description. The nickname is useful because you may have different fixtures that each have their own “Red Flash” effect, and it is nice to be able to tell at a glance what fixture an effect applies to. “Fixture total number of DMX channels” is the total number of DMX channels in the fixture’s DMX channel map.  This is the number of channels that need to be allocated for each fixture in a 512 channel DMX universe.  For example, if the fixture has 20 channels then two fixtures back-to-back in a 512 channel DMX universe may allocate channels 1-20 and 21- 40.   DMX channels to set The bottom section of the dialog defines the channels that will be output in the exported script to implement the effect.  It is important to keep in mind that the DMX channels in the exported script control what happens in the real world.  The VDL, Duration and Height fields at the top of the dialog control what the simulation will look like, but absent the channel values they are decoupled from the real world.  When you create a DMX effect in Finale 3D, you are actually defining two things — what the simulation looks like and what DMX channels are output.  You would like the two things to match.  After all, if you are designing a show with a red par light, it would be confusing if the red par light simulation corresponded to a different color in the real world! To help keep the simulation and real world matching, the channel rows in this dialog include a “Begin value” and an “End value”, which are the channel values for the beginning and end of the effect.   If you change the duration of the effect on the timeline or in the effects window, the duration will apply both to the simulation and also to exported DMX channels, keeping them consistent.  Look at channel 7 in Figure 1.  The “Dimmer” channel is set to 255 at the beginning of the effect (on) and 0 at the end (off), which is what you would expect. The “Channel setting options” field in the dialog above the channel rows has three options.  The “Set for the duration of the effect” option indicates that channels will need a value set at the beginning and end of the effect.  The “Set forever” option indicates that only a beginning value is required, which will hold forever or until a subsequent effect changes the channel to something else. The “Set prior to effect” option applies the “Setup value” in advance of the effect’s beginning time in order to give the fixture enough time to prepare for the effect.  Light fixtures with gobos or color wheels, and any fixtures with moving heads or nozzles need preparation time to position the wheel or head at the desired angle prior to the effect, so that when the effect turns on it is already aiming in the right direction and showing the right color or gobo.   For this option, please see Programmer documentation: The DMX Patch field and Programmer documentation: Special VDL terms for DMX effects like “Move-To” and “With Strobing” for more instructions. If you are defining a new fixture, you should fill in descriptions for all the channels of the fixture’s channel map whether or not the specific effect you are defining applies values to the channels.  If the effect does not apply a value to a channel, uncheck the checkbox for the channel so the effect leaves it alone.  The example in Figure 1 leaves channel 5 unchecked so that strobing can be turned on or off independently using a “With Strobing” modifier effect.  Alternatively, instead of defining “Magenta Flash (lg)” that is independent of the fixture’s strobing characteristic you could define a “Strobing Magenta Flash (lg)” that is intrinsically strobing.  You would then check the checkmark of channel 5 and set the strobing channel value to a value corresponding to a strobing frequency at the beginning of the effect, and zero at the end of the effect to turn off the strobing characteristic. The VDL of the effect should match what the effect’s DMX channel specifications actually do.  A “With Strobing” effect should have VDL that modifies other effects that the “With Strobing” effect overlaps (e.g., “Nonphysical Modifier DmxStrobing10Hz”).  By contrast a “Strobing Red Flash” effect should have VDL that creates the red light in addition to making it strobe (e.g., “Red Par Light Modifier DmxStrobing10Hz”).  The special VDL terms are described in Programmer documentation: Special VDL terms for DMX effects like “Move-To” and “With Strobing”.   Special DMX channels values: variables The channel value menus include numbers 0-255 and also include a list of variables like :duration10 or :pan540.  As explained in Programmer documentation: The DMX Patch field, these variables can hold channel values from 0-255 corresponding to aspects of the effect as is used in the show.  The variable :duration10, for example, is the duration of the effect in hundredths of a second.  The variable :pan540 is the pan angle of the effect in the show after converting 0-360 degrees to channel values 0-170, i.e., based on a 540 degree range of the fixture.  In general, for types of fixture effects that cannot be represented as simple numbers from 0-255 at the beginning and end of effects, the variables translate the necessary effect characteristics to channel values or channel offsets. There are some types of effects that are too complicated to represent with simple numbers or variables for the channel values.  The “MagicFX [003] Mode 1 Flamaniac” fixture, for example, has five on/off channels that control the flame output of five nozzles at five pre-defined angles from -45 to 45 degrees.  Thus, depending on the tilt angle of an effect in the show design, a different channel needs to be set on to match the angle.  If the effect in the show is aiming up, channel 3 needs to turn on.  If the user drags the effect’s trajectory angle to -45 degrees left, channel 1 needs to turn on.  Since the angle controls which channel turns on, it is not possible to represent effects for this fixture mode directly in the channel rows of the dialog.  The solution requires a variable for the channel offset, as opposed to a channel value.  The offset is based on the angle of the effect.  The “Additional parameters (optional)” field just above the channel rows in the dialog provides a place for all the parameters that don’t fit in the channel rows.  For this particular effect, the channel rows are all unchecked and the “Additional parameters (optional)” field contains:  :tilt45ToChannelOffset0To4 255 0. For the majority of effects, simple numbers are sufficient for channel values.  The channel value variables and the additional parameters field accommodate the more complex effects.  If you are trying to define effects for a new fixture that needs some new channel value variables that aren’t in the list of Table 2 of Programmer documentation: The DMX Patch field, please contact support@finale3d.com and ask the Finale support team to add additional variables to the software to support your fixture.   Effect specifications Returning now to the effect specifications at the top of the dialog, the nine fields define the effect specifications as follows: “Visual description (VDL)” is the visual description, like “Red Par Light” or “Green Spotlight Move-To”; or for more esoteric effects like “With Strobing” the visual descriptions may look like “Nonphysical Modifier DmxStrobing10Hz”, as explained in Programmer documentation: Special VDL terms for DMX effects like “Move-To” and “With Strobing”. “Part Number” and “Collection” define where the effect is stored, same as for non-DMX effects “Name for this effect” is just the name of the effect.  It will be combined with the fixture nickname, Fixture ID, and Effect ID to construct the full effect description field, like “TSMHG [027/1011] Red Flash (lg)” “Standard Effect ID (optional)” is a number that defines the meaning of the effect, to support features like Fixture cloning which converts a fixture in a show to a different type by translating the effects for the old fixture into effects with the same Standard Effect ID for the new fixture type, and to support warning messages for missing safety channels for fixtures that need them.  The Standard Effect ID is optional; just leave the field blank or use the value 0 if you don’t care.  If you do care, you can look up the lists of Standard Effect IDs in Standard Effect IDs for flames and sparks and Standard Effect IDs for lights; please email support@finale3d.com if you would like to add some Standard Effect IDs to the list that Finale maintains. “Duration” and “Height” are effect attributes that affect the simulation and that may also affect the DMX channel outputs if linked by way of DMX channel value variables. “Prefire” should be zero for any DMX effects other than Move-To effects.  This attribute has a special meaning for DMX effects: it is the maximum “reach back” of a Move-To effect (see Move-In-Black (MIB) and Move-To) that limits how far back the effect that defines the starting point of the movement can be (usually a Move-In-Black effect).  The prefire does not affect the begin time of effects. “Effect Type” for DMX effects is one of four values that make sense for DMX effects: “sfx”, “light”, “flame”, and “other_effect”.  The “sfx” is the default, and can be used for everything.  “light” is the same as “sfx” except that it is just a different word, which can be useful for filtering.  “flame” effects are also the same except they have fixed durations that cannot be changed on the timeline for individual events (so if you see “flame” effects of a particular part number on the timeline, you know for sure they are all the exact same duration; whereas if you see different “sfx” or “light” effects you don’t know that for sure because their durations could have been modified); for “other_effect” and further explanation, see Why is ‘Type’ so important? What depends on it?.   What to do after defining your effects Once you’ve defined your effects, right-click on a position and choose “Configure position as DMX fixture” and you’ll have the option of picking any application-defined or user-defined fixture that is present in the loaded effect collections, including your My Effects and Per-Show Effects.   Figure 3 – The “Configure position as DMX fixture” menu item will include your user-defined fixtures as options  

The standard report templates like the Wiring Script employ text wrapping for the Description field, as you can see in Figure 1.  In this example, the seventh row has a short description that doesn’t wrap around.  Most of the other rows have text that wraps around to two or more lines.  The report formatting is configured to support one extra line of wrapped text, keeping the overall height of the rows constant.   Figure 1 – The 7th and 11th row in this report have short descriptions that fit in a single line; the other rows wrap the text.   The labels in Figure 2. illustrate text wrapping applied to the Description field in a label format.  Whereas the standard report templates all employ text wrapping for the Description field by default, the standard label templates do not employ text wrapping.  So to get a result like the labels in Figure 2 you will need to customize the label template as described in Labels basic instructions.   Figure 2 – The label in the lower right has a short description requiring a single line; the others require two or more.   The report templates can also be customized to employ text wrapping — or not — in any of the fields.  The customization parameters for reports are different from labels, so please see Labels basic instructions for instructions to customize labels and continue with this article for instructions to customize reports. Reports and labels alike use the padding space to accommodate the wrapped lines of text.  If a report row has a single line of text that doesn’t wrap, the line of text is centered with padding above it and below it.  If a row has multiple lines of text, the additional lines will overwrite the padding space.  To configure reports for text wrapping, you need to adjust two fields in the report customization dialog accessed from the menu item “Edit report template” in the blue gear menu in the upper right of the script or effects window, as in Figure 3.   Figure 3 – Choose the fields for text wrapping, and set the padding to accommodate the number of lines you want.   Calculating the padding for text wrapping in reports You can calculate the amount of padding required based on how many lines of text you want to allow for.   The equation is different for reports and for labels.  For reports, the height of the row is calculated to be the font size plus twice the vertical padding, where the vertical padding is specified as a fraction of the font size.  The larger the vertical padding, the larger the row height.  A padding fraction of 0.5 means the combined padding above and below will add up to the font height, providing room to wrap one extra line of text.  A padding fraction of 1.0 provides room for two extra lines of text.  For reports, the padding calculation is simple.  To calculate the vertical padding for N total lines of text,  the padding should be: (N - 1 ) / 2 For both reports and labels, Finale 3D makes a slight adjustment to text wrapping placement to improve the visual appearance.  It looks better to have a small amount of whitespace (one point) above the text lines even in the cases that they are consuming the entire padding.   So Finale 3D protects a one point sliver of the padding above the text lines from being overwritten, which therefore requires an extra one point of padding below to accommodate the shift.  It is possible to calculate the precise adjustment required, but generally it is easier to fine tune the proportions by eye, starting with the calculated values.        

To create and export a script for the Jingduan firing system, please follow these steps: Address the show (“Addressing > Address show”). Export the script (“File > Export > Export firing scripts“). Step 2 creates the script file, which is a standard format CSV file with a “CSV” extension. Please note: older versions of the Jingduan firing system do not support CSV script files.  Please contact your Jingduan dealer to upgrade to a version that supports CSV files.    Figure 1 – Jingduan firing system   Table 1 – File format and encoding File format Extension Text encoding Field delimiter End-of-line Text .CSV UTF-8 Comma CRLF The script contains rows for the firing events, i.e., unique combinations of module, pin, 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 by event time, then by module number, then by pin number. What rows represent Each row represents a unique firing event, a module/pin/event-time combination.  For example, a chain of five shells will be one row, not five.  A pair of shells shot together from the same position will be one row, not two, even if the shells are different effects.  A flight of shells shot together from multiple positions with the same module-pin using scab wire is still one row. Header The file contains a single header row with the column names: Ignition Event Time,Prefire Delay,Host Address,Module Address,Pin Address,Effect Name,Caliber,Category,Angles,Position Name. Addresses The Jingduan system addresses are Host (1-99), Module (1-99), and Pin (1-32). Time resolution Millisecond resolution. Host The Jingduan system supports multiple controllers (“Hosts”) represented in the same firing system script.  In Finale 3D, the “Universe” column in the script and in position properties partitions the show into multiple controllers, so the Universe column is the most natural column in Finale 3D to hold the Host number.  For most firing systems, when Finale 3D exports the script files for the show it exports a separate script file for each unique Universe, but for the Jingduan firing system Finale 3D exports a single script file that combines all the Universes; and in that script file the Host column contains the Universe values. To create a show for multiple hosts, 1) Right click on the launch positions and edit “Position properties” from the context menu, 2) In the Position Properties dialog, type the Host number into the Universe column, 3) Re-address the show from Addressing menu, which will assign module and pin addresses and additionally will copy the Universe values from the positions into the script, 4) Export the script from the File menu. Special characters The CSV file follows Excel rules for quoting double quotes and commas within the fields. Except for those two characters, all other printable UTF-8 characters are allowed. Unprintable characters (control characters like linefeed and tab) are filtered out. After the header, each row in the script has a number of fields separated by the comma character.   If any field contains a comma or double quote character, the field will be surrounded in double quotes and any internal double quotes will be doubled-up, following the Excel CSV convention.  The names of the fields and their descriptions are the following: Table 3 – Specifications of script fields Field name Description Ignition Event Time The launch time of the event; floating point number with up to millisecond resolution. Prefire Delay The prefire time of the effect; floating point number with up to millisecond resolution. Host Address Host number, starting with 1.  The host identifies the controller.  This number comes from the Universe field in Finale 3D. Module Address Module number, starting with 1. Pin Address Pin number, starting with 1. Track Identifier Track number or blank. Effect Name Description.  If the row represents multiple effects, the description begins with the number of effects in parentheses, continues with the first effect name, and ends with elipsis (…) as an indication the row represents more than is being displayed in this single field. Caliber Size. Category The Type of the effect in Finale 3D, or blank. Angles Angle graphic in ASCII art, showing the angles of the represented effects in backslash, vertical line, and slash characters. Position Name Position name. An example script containing nine shells across nine firing rows is shown in Figure 1 and included for download in Table 4. Ignition Event Time,Prefire Delay,Host Address,Module Address,Pin Address,Track Identifier,Effect Name,Caliber,Category,Angles,Position Name 2.76,2.24,1,1,1,,Red Chrysanthemum,"2""",shell,|,Pos-01 3.344,2.24,1,2,1,,Red Chrysanthemum,"2""",shell,|,Pos-02 3.928,2.24,1,3,1,,Red Chrysanthemum,"2""",shell,|,Pos-03 4.512,2.24,1,4,1,,Red Chrysanthemum,"2""",shell,|,Pos-04 5.096,2.24,1,5,1,,Red Chrysanthemum,"2""",shell,|,Pos-05 5.68,2.24,2,1,1,,Red Chrysanthemum,"2""",shell,|,Pos-06 6.264,2.24,2,2,1,,Red Chrysanthemum,"2""",shell,|,Pos-07 6.848,2.24,2,3,1,,Red Chrysanthemum,"2""",shell,|,Pos-08 7.432,2.24,2,4,1,,Red Chrysanthemum,"2""",shell,|,Pos-09 Figure 1 – Example Jingduan script with two universes — Host 1 and 2   Table 4 – Example files Download link Explanation test-jingduan.fin Example show file test-jingduan.csv Example exported file (CSV) Data sheet