Introduction Main
elements
Scripts Reference
Version française

Principles

With IanniX, you can write your own scripts to more easily create your complex projects. Scripts are written in Javascript but even with a limited knowledge of Javascript, many types of useful scripts can be created. In addition to this documentation you are reading, many example scripts are provided for you study. They can be found in the Examples section of the Scripts and Styles browser in the Inspector.

To open a script for viewing, right click on a script in the browser and choose Open. The context menu also contains other commands for working with scripts. In addition you can run a script by double clicking on its name in the Inspector.

If you wish to learn more Javascript for more advanced scripting there are many books, online tutorials and reference msterials available to help you. Also, feel free to inquire on the IanniX forum for further information on the conventions used in writing JavaScript, or for tips in writing IanniX scripts.

Here is a link to the complete language reference of the version of Javascript used in IanniX: Reference

Controlling IanniX From a Script

The Javascript run() Command

The run() function is used to send most commands to IanniX from scripts. Commands must be provided to run() as a single string, so command text must be enclosed quotation marks. Example:

run("zoom 100"); Set the display zoom to 100 percent

To combine numeric parameters with text commands to produce a string to pass to run(), use the concatenation operator. In the following example center_x and center_y are in numeric variables and must be concatenated to the command string.

run("setPos current " + center_x + " " + center_y + " 0");

Other examples:

Remember the «;» at the end of each line. Note that constant numeric or string parameters may be included directly in the command string, whereas values in variables must be joined with the concatentation operator. Be sure to include spaces in concatenated strings so that commands and parameters in the resulting string are separated by at least one space.

See the Functions Index for a list of the functions you can use in the run() command to control IanniX.

The title() and ask() Commands

In addition to run(), two other Javascript functions are provided for script writing:

The Structure of a Script

IanniX executes a script in several phases. You can control the phase in which your commands are performed by grouping them under functions that are called at specific phases of execution. The functions are:

Here is an example of a simple script:


          //Setup of the script
          function onConfigure() {                
              title("My new script");             //Name the script
              
              //Ask for parameters to customize the script behavior
              iannix.ask("Triggers", "Trigger x-position", "trigger_xPosition", 3);
          }
          
          //Creation of the score
          function onCreate() {
              run("clear");                       //Clear score objects
              run("center 0 0");                  //Center on score origin
              run("zoom 100");                    //100% zoom
  
              run("add trigger 1");               //Add a trigger with ID 1
              run("setPos current 1 2 0");        //Move the trigger to coordinates (1, 2, 0)
  
              addATrigger();                      //Call a your custom function
          }
          
          //Define a custom function
          function addATrigger() {
              //Insert the code to add and configure a trigger here
              //Normally the function addATrigger() would have parameters to pass
              //it the required features of the trigger to add.
          }
                

The only two functions that should be in the configure() function are title() and ask(). All the rest of your code to be executed should be placed in the create() function. In addition you can define your own functions, define constants, etc. outside of any of the main functions. For example, the function addATrigger(), above.

Creating your own functions

Example: This function provides a random number between parameters min and max.

function randomFloat(min, max) {
      return Math.random() * (max-min) + min;
}

Creating your own libraries of functions

Iannix provides the ability to predefine libraries of frequently used functions for use in writing scripts. Files of type <name>.js in the Tools folder are scanned during IanniX startup and variables, classes and function definitons are made available for use in scripts. Note that if a library file is edited while IanniX is running, IanniX must be restarted for the changes to take effect.

Drawing Curves with Straight Line and Cubic Bezier Segments

The IanniX setPointAt() function allows scripts to create 2D and 3D paths from a sequence of straight line and curved (cubic Bezier) segments.

Creating a Curve

Start a new curve with:
run("add curve id");
Creates a curve object with the specified ID. The curve has not yet been given any points. The location of a new object defaults to (0,0,0).

The setPointAt Function

The setPointAt function is used to add points to or change points on a curve. There are several behaviors of the setPointAt() function depending the parameters passed to it:

All forms of setPointAt specify the location of the point as x y <z>. The forms that specify Bezier segments include two other points, cx1 cy1 <cz1> and cx2 cy2 <cz2>, that describe the curvature. The direction of the curve leaving its start point is tangent to the line from the start point to the first control point cx1 cy1 <cz1>. The direction of the curve arriving its end point is tangent to the line from the control point cx2 cy2 <cz2> to the end point x y <z>.

Example of Creating a Curve With 2D and 3D Segments

The following is the code of the example "Learn - Curve points" that can be found in the Inspector script browser. It creates a path with with five segments and five points. The first segment is a 2D straight line, the next is a 2D Bezier, the next is a 3D straight line, and the fourth segment is a 3D Bezier. Run the example script to see what the curve looks like. To see its shape in 3D hold down the Alt key and drag the mouse on the score area. You can reset the viewing angle by running the "Reset orientation" script in the Tools section of the script browser.

   
          //Creation of the score   
          function onCreate() {
              //Viewport setup
              run("clear");
              run("center 0 0");
              run("zoom 100");
              run("rotate 0 0 0");
                  
              //Create a curve
              run("add curve  1000");
          
              //Point number 0
              //Location x0 = -2, y0 = 1
              run("setPointAt current  0  -2 1");
          
              //Draw a 2D straight segment from point number 0, to
              //point number 1, which is at (x1,y1) = (-2,3)
              run("setPointAt current  1   -2  3");
          
              //Draw a 2D bezier segment from point number 1, to
              //point number 2, which is at (x2,y2) = (2,3)
              //Segment start is tangent to a line from (x1,y1) to (x1+2, y1+2)
              //Segment end is tangent to a line from (x2,y2) to (x2+0,x2+3)
              run("setPointAt current  2    2  3   +2 +2   +0 +3 ");
          
              //Draw a 3D Straight segment from point number 2, to
              //point number 3, which is at (x3,y3,z3) = (0,2,1)
              run("setPointAt current  3    0 2 1");
          
              //Draw a 3D bezier segment from point number 3, to
              //point number 4, which is at (x4,y4,z4) = (-2,-1,0) 
              //Start tangent to a line from (x3,y3,z3) to (x3+0,y3-1,z3+2)
              //End tangent to a line from (x4,y4,z4) to (x4+4,x4+0,z4+0)
              run("setPointAt current  4   -2 -1 0   +0 -1 +2   +4 +0 +0");
          
              //Add a cursor on the curve
              run("add cursor 1");
              run("setCurve   current lastCurve");        
              run("setSpeed   current auto 10");
          }