Control Scripts

Here's where we get down and dirty.  It's perfectly possible to build useful, attractive and sophisticated dashboards in iRDDU without going near a script.  They do however grant you to a great deal of extra functionality, enabling you to do things in your dashboards that would be impossible without writing your own programs.

iRDDU's scripting language is a set of instructions that can be attached to any control of a dashboard.  A control's script is processed every time the control is updated, after the control's "Formula" property has been evaluated.  A script could be used to modify the value set by a formula or you could leave the formula blank and set the value exclusively through the script.

There is a separate Script Editor window with which you create and modify scripts.  It's still a little rough and ready - it will get some work if not a rewrite for version 2.2 - but it does work and you should quickly get the hang of it's foibles. 

To access the script for a control, select the control and click in the Script property.  A button will appear to the right of it with three dots on it. Click on it and the script editor window will open.

Let's work through an example:

This is a script from my Radical SR8 example dashboard available from the "Get Dashes" button.  It's purpose is to set the pitstop tyre and fuel options in iRacing when you enter the pits.  The script is run from the top downwards, there are no loop facilities or jumps.

The logic boils down to the following:

IF the car has just entered the pits

     Reset pitstop options
    Set the tyre change options to what we want
    Clean the windscreen
    IF we want to add fuel
        Set fuel level to add

The first IF checks whether we have entered the pits by checking the IR:ONPITROAD field.  If it has increased since the last time this script was run then it must have changed from 0 to 1.  The only time that can happen is when we enter the pits.  We don't want to set the pitstop parameters when we initially enter the car though, only when we drive in from the track so there is a second part to the IF condition checking we are moving at more than 5 MPH.

If both of those conditions are true iRDDU will execute the commands below the IF.  If not it will jump all the way to it's associated ENDIF command and carry on from there.

The reason this IF statement is there is to stop the commands being run every tiem the dashboard is updated.  Without it this script would updates iRacing's pitstop settings 15 times a second and you'd have a stream of text flowing up your screen while you're driving.  the trick is to figure out which criteria need to change and only do it when that happens.

For example you can link a script to a controller button using the "JOY" field identifier.  The example to the right shows another script from the Radical dash, this time one attached to one of the four invisible control which hold whether the river wants a tyre to be changed.  The script looks at the button referred to by LFTyre.  Joystick Buttons in iRDDU return 0 or 1 depending if they are currently pressed.   In this case I'm looking for a situation where the valeu has decreased since the last time the script was run meaning the button has been released.  If so then I toggle the value between 1 and 0 (1-0 = 1, 1-1 = 0; useful little trick to remember).  If you look back at the original script you'll see the value of iChgLF being used in the ChangeTyres command along with it's three siblings to tell iRDDU which tyres to change.

Going back to the main script you can see there is a second IF indented within the main one.  This is checking whether the driver has asked for any fuel to be added before adding it if the answer is yes.  Have a look at the example and see how the indentation helps you to see which commands apply to each IF, making it easy to see the structure.

The available commands are listed on the dropdowns at the left.  When you select the one you want the appropriate parameter fields will appear to the right ready for you to fill in. 

To add a new line, click the + button to the left and a new line will be added above.  New lines are added as a NOP command.  NOP means No OPeration, it does nothing.  There is currently no direct way to delete a line but there is a workaround.  Set the line's command to NOP and when the script editor closes it will be tidied away for you.

That's really all you need to know about the script editor and scripts apart form what all the commands do.  There are only 16 and four of them combine into one.  As usual it's how you use them that matters.

AddFuel Sets the amount of fuel that your pit crew will add the car the next time you stop in your pitbox.  The required value is in litres, if you work in Imperial then you can use the CONVERT function to do the calculation.

VALUE The volume of fuel to add in litres
ChangeTyres Tells iRacing which tyres you want to be changed at the next pitstop and what pressures to use.

LF Pressure The pressure to add to the new left front tyre.  A value of -999 tells iRDDU not to change that particular tyre.
RF Pressure As LF but for the right front.
LR Pressure As LF but for the left rear.
RR Pressure As LF but for the right rear.
ClearPitCommands Resets any pending pitstop commands in iRacing.
GlobalReset Resets all functions which retain their state (min, max, increased etc) to their initial values. This is a global setting so will reset all running dashboards.

One possible use for this is as a reset for atell-tale on an analogue rev counter.  You could create a gauge control based on MAX([SIM|RPM]) to show the maximum value the revs have reached then add a script to the control to call GlobalReset if a button is pressed to reset it.
IF is the only conditional command but the form I've chosen should cover everything you might want to do.

You start with an IF statement.  If the condition is true (in actual fact iRDDU takes any non zero value to mean true) then the script continues from the following line.  If not iRDDU jumps to the next clause which could be ELSEIF, ELSE or ENDIF.

ELSEIF is essentially another IF.  For example if you wanted to select one of a number of different bitmaps based on the value of a number you could use an IF and a number of ELSEIFs, each checking for one value.

ELSE is the catch all at the end of the IF statement and ENDIF closes off the IF statement.

There should be one IF at the start then optionally as many ELSEIFs as you like, an optional ELSE then an ENDIF at the end.
SendKeys This enables you to send keystrokes to the running sim.

It's fairly simple to use, just call SENDKEYS with a string representing the keys you want to send.  Special keys are supported by inserting their name in curly brackets.  Here are a couple of examples:

Open the chat window then type Thanks followed by enter:


Open the chat window then thank the person behind you on the track:

SENDKEYS("TThanks " + [SIM|DriverName#T+1])

The process which sends the keys to iRacing runs in it's own thread so your dashboards won't stop updating while it's typing.  Any running dashboard can send key strings and they will be processed in arrival order so iRDDU will never try to type two key strings at the same time.  The keys are sent to the currently focussed window which should be iRacing. If it isn't then the keystrokes will go somewhere else. 
SetActive With SetActive you can set a control's Active property on the fly.

An active control will not have it's value recalculated when the dashboards is updated, it's script wil  not be run and it won't be drawn.
Value 0 = inactive, any other number = active.
Target The name of the control to be activated/deactivated.  The default is the current control.
SetDimensions This enables you to reposition a control based on API values or formulae meaning you can move controls round the dashboard based on API values. In addition to the X and Y parameters in the example below you can also set the WIDTH and HEIGHT. You can set as many or as few of the parameters as you wish, those you miss out stay at their previous setting.

X The horizontal position of the left hand edge of the control. 
Y The vertical position of rht top edge of the control.
Width The width of the control in pixels.
Height The height of the control in pixels.
Target The name of the control which should be moved/resized.  The default is the current control.
SetFlashPeriod The best way to illustrate SetFlashPeriod is with an example:


What this does is if the revs exceed 98% of the rev limit the control will flash on or off every 300 milliseconds, otherwise it won't flash at all.

always remember that the smoothness of the flashing is dependent upon the update rate of the dashboard.  If you're updating it at 5FPS it's pointless setting a control to flash 1 times a second.
SetTextFmt Sets the formatting attributes of a control.  All parameters are optional, any left blank will stay as they are.

Colour A string defining a Hexadecimal RGB value.
Font The name of a Windows font.
Italic 0 = non italic, 1 = italic.
Bold 0 = notmal, 1 = bold.
Target The name of the control to be reformatted.  The default is the current control.
SetValue Sets the value of a control.

Value A formula defining the value to be assigned.
Target The name of the control to be modified.  The default is the current control.
SetVisibility Similar to SetActive but only affects the visibility.  The value will still be recalculated on each dash update and any attached script will still be run.
Value A formula defining the value to be assigned.  0 = invisible, any other value = visible.
Target The name of the control to be modified.  The default is the current control.
WipeWindscreen Politely ask your pit crew to clean the windscreen or your visor at the next pitstop.