FlyingSticks extends the power of Lua by adding a small library of functions and global variables to provide access to the inner workings of the calculator.
Most parameters seen in the user interface are accessible via their name prefixed with "pv." - implying all the parameters are contained within the "pv" global table. Thus, reading or writing the bow draw weight is done in following examples:
pv.BowMyDrawForce = 250.5 --assigns a new value in SI units
force = pv.BowMyDrawForce --the current value in SI units
A list of accessible parameters is provided below, and is also available in the Action>Scripts>.. menu where selection of a variable will insert its name at the insertion point in the scripts area.Some functions require an index to FlyingSticks parameter variables. An index can be discovered in two ways:
vi.BowMyDrawForce -- by a table (vi), or
"BowMyDrawForce" -- by quoting the variable name
The first form is fastest as the vi table is built once on launching Lua and employs Lua's efficient table indexing capability. The second form needs to conduct a binary text search on each call.
Note: an index can be used directly, however the mapping between parametric variable and its index is not guaranteed to remain constant with different versions of FlyingSticks. For this reason, direct index use is not recommended.
It should be remembered that FlyingSticks conducts all internal calculations in strict SI units. Parameters accessed in this way are always in strict base SI units without any prefixes like "k", "M" etc. For example, all length or distance measurements are internally in meters, no matter how large or small. If other length units are required, then use the "fly.get()" and "fly.set()" functions described below.
The small set of custom Lua functions are prefixed with "fly.". The most commonly used functions are:
fly.get("name"|index|vi.name, ["text"|"SI"|"CU"])
fly.set("name"|index|vi.name, value|"valueStr",
["text"|"SI"|"CU"])
fly.button("command", [arg, ...])
fly.printCSV("name"|"index"|value, ...)
fly.printT("name"|"index"|value, ...)
fly.pPlot(plot, xAxis, yAxis, cPara)
where:
"name" is variable name text in quotes,
pv.name value of the named variable,index is a number 0 to ~440 for quicker access,
vi.name index of the named variable in FlyingSticks,
value is the numeric value of the variable,
"valueStr" is equivalent to any valid GUI field parameter entry,
| is an option separator in a list of options,
[ ] items enclosed in square brackets are optional,
arg, ... one or more arguments, up to a maximum of 15,
"text" indicates input or output as a string as per data field, in quotes,
"SI" for a number in strict SI units, and is the default, in quotes,
"CU" for a number in the current field units, in quotes,
plot a table of plot information - see fly.pPlot() below,
xAxis a table of x-axis details - see fly.pPlot() below,
yAxis a table of y-axis details - see fly.pPlot() below,
cPara a table of control parameter details - see fly.pPlot() below.
These functions essentially mimic user actions in the graphical user interface (GUI) and indeed will be visible in the GUI. For those not familiar with "weakly typed" languages such as Lua, some behaviours may seem a little strange.
This function retrieves the current value of the named or indexed parameter with various units options.
fly.get("name"|index|vi.name, ["text"|"SI"|"CU"])
For the second and optional argument, one of three options may be passed. If "text", the function returns the string exactly as seen in the parameter's calculator field. A text string is most suitable for display or printing as it manages the number of significant digits and units sensibly.
If "SI" is passed, a numeric value in SI units is returned. If "CU" is passed a numeric value in the parameter's current units will be returned. Numeric values can be used in any Lua expression.
This function loads the named or indexed parameter with the value passed. It can also change the current measurement units.
fly.set("name"|index|vi.name,
value|"valueStr",
["text"|"SI"|"CU"])
The value in the second argument may be a Lua number or a text string (in quotes with optional units. If a Lua number, the optional third argument indicates the units of the value. If the second argument is in quotes without units, then the units are derived from the optional third argument (defaults to "SI". If the second argument contains units, then these are applied and the third argument is unnecessary or set to "text" in quotes.
Thus:
fly.set(vi.BowMyDrawForce, "22.5 kgf")
print(pv.BowMyDrawForce, fly.get(vi.BowMyDrawForce,"text"))
will return:
220.6496 22.50 kgf
the first value being the force in internal SI units (Newtons) and the
second in current units of kgf (kilogram force).
This function does what is typically done with a button in the calculator.
fly.button("command", [arg, ...])
The command may be followed by options. Valid commands include:
Calculates the launch elevation and azimuth for current range and wind.
This function launches an arrow with the current setup, running the full ballistics model.
Enables or disables the simulated group shooting and associated scoring.
Refreshes the screen based on the current setup. This can be relatively slow compared to other commands, so should be used sparingly.
Clears the results panel, ready to receive more script output.
Calculates the ethical range without loading it to the current range.
Based on current form, estimates the likely FITA 1440 round.
Calculates gravity and various atmospheric parameters such as pressure, air density, viscosity, temperature and humidity. These parameters may subsequently be changed if desired.
Does a first estimate of spine tuning by adjusting the current arrow's static spine, shaft length and point mass. Sometimes may fail to find a sensible solution.
Leaving static spine and point mass unchanged, adjusts the shaft length within sensible limits to find a solution.
Leaving shaft length and point mass unchanged, adjusts the static spine
within sensible limits to find a solution.
Leaving static spine and shaft length unchanged, adjusts the shaft
length within sensible limits to find a solution.
Sets the target height to the peep or eye height.
One an arrow's shaft diameter(s) have been loaded, can be used to set the point, insert and nock diameters.
Calculates the ethical range for the current kit and game type.
Calculates the FITA 1440 Round score for the current archer's form.
Needs to be called after changing wind speed, direction, inclination or gusting, or after changing the land surface.
Ensures script is run each time the calculator does a full recalculation. Use with caution as it can consume excessive CPU time.
Turns autoRun mode off.
This function a provides simple means to print the named parameters to the results screen as a row of comma separated values (CSV).
fly.printCSV("name"|"index"|value, ...)
The number format, resolution and units are identical to that seen in the parameter's calculator field except the units text is removed. If additional formatting control is required, use print(string.format(...)) - see the Lua documentation.
A parametric plot function that generates its own data by running the
currently configured ballistic calculator and plotting the results. The
function inputs are an independent variable (x-axis), a dependent variable
(y-axis) and an optional control variable. The control variable will
generate a trace for each control value. The variables may be any of
FlyingStick’s valid parameters, however care needs to be taken in ensuring
sensible selections.
The function generates a plot similar to that in the
Analysis>Parametric_Plots panel, but with greater flexibility. A pPlot is
defined by three or four arguments:
fly.pPlot ( plot, xAxis, yAxis [, cAxis ] )
where:
The required plot argument defines the general plot style or simply the plot’s title:
plot = “title” | {title=“title”, autoSight=f, autoUpdate=f, precision=f, multiPlot=f, grid=f }
The required independent variable argument:
xAxis = “var” | { var=“var”, label=“varName”,min=f, max=f, step=f | {f, f, f...} }
The required dependent variable argument:
yAxis = “var” | { var=“var”, label=“varName”, min=f, max=f, step=f | {f, f, f...} }
The optional control variable argument:
cPara = “var” | { var=“var”, label=“varName”, min=f, max=f, step=f | {f, f, f...} }
and where:
title |
title text placed at top of plot area. |
|
autoSight |
=1 re-sight target for each point generated,
|
|
autoUpdate |
=1 re-runs the Lua script each time FlyingSticks recalculates. Defaults to 0. |
|
precision |
=0 standard precision (default), |
|
multiPlot |
=1 allows multiple plots in window, |
|
grid
|
=0 no grid, =1 vertical grid, =2 horizontal grid, |
|
label
|
the axis label. If not provided will be created from parameter name. |
|
min
|
minimum axis value. If not provided, is set to 1/2 of current value. |
|
max
|
maximum axis value. If not provided, is set to 2x current value. |
|
step |
step size in incrementing independent or control variable, or alternatively a table of specific steps. If not provided, set for 5 equal steps. |
The function builds a Script Plot window into which the plot is placed. If the script generates more than one plot (i.e. multiple pPlot() calls, then by default a new window will be created for each plot. If multiPlot=1 has been set, then all plots will be placed as a vertical stack in a single window. A maximum of 8 plots can be generated.
The following is a list of approximately 400 variables that may be accessed by a script. Basically, any variable seen in a calculator panel may be accessed.
The content of this table is available in varName.html which can be exported with the Reports folder.