FSImp also supports a text scripting language. Scripts have the ability to add new features to X-Plane and perform some helpful automation. Script files should be placed in the FSImp\scripts folder or its subfolders. They must have a .txt file extension. This folder has a number of example scripts. You may be in the position to write scripts yourself if you have some programming experience. You can also place scripts written by others directly into the FSImp\scripts folder or preferably into a new subfolder.
The script file globals.txt is interpreted first and contains useful definitions which are automatically available to other script files.
During loading, the text of scripts are written to the file FSImp\message.txt. Error detection is minimal. Error messages appear directly after the line which caused the error. Scripts which have errors do NOT run. You may edit scripts file, using a text editor, while X-Plane is running and Restart scripts to reload them. This allows you to correct syntax and logical errors during the development of new scrips.
The plugins FSImp menu can be used to control scripts and to communicate with running scripts.
What can scripts do ?
X-Plane DataRefs
Plugins can access X-Plane's own data using DataRefs. These are grouped into folder-like
categories and have descriptive names. The plugin allows scripts to use this feature to
access X-Plane's own data. Naturally, an amount of care is necessary when accessing X-Plane
data. The script interpreter automatically converts between data types (integer floating-point
text arrays etc) when using DataRefs.
Please be aware that DataRefs change with X-Plane versions.
Existing ones may disappear or change their meaning while new ones may appear.
The latest version of the DataRefs documentation is to be found on the
X-Plane plugins SDK web site www.xsquawkbox.net/xpsdk/
(follow Documentation + DataRefs).
X-Plane keys and buttons
Note that it is generally safer for future compatibility to use one of these commands
than to manipulate the underlying sim data using DataRefs.
Informal language description
| Thing | Definition | Explanation | Example |
| comment | //text | Ignored | //this is a comment |
| name | alpha numeric _ | speed_100 | |
| value | decimal | an integer number, base 10 | 15 |
| hexadecimal | an integer number, base 16 | 0x1af2 | |
| floatingpoint | a floating point number with a decimal point or period | 1.234 | |
| FSImpData | FSImp data | "plugins/FSImp/airFPS" See xpl-param in FSImp.txt | |
| XPlaneDataRef | XPlane data | "sim/flightmodel/position/local_vx" See X-Plane 8.50 DataRefs | |
| "text" | text in double quotes | "this is a string" | |
| name | MAX | ||
| define | #define name value | defines name to be value | #define MAX 20 |
| var | starts a block of variables | ||
| name= value | defines a variable called name with a value | x= 1.5 | |
| sound name | defines a new sound object called name | sound roar | |
| endvar | ends a block of variables | ||
| enum | starts a enumerated list of names, counter set to 0 | ||
| name[=value] | counter set to value if present, defines name to be counter, increments counter | ||
| endenum | ends a enumerated list of names | ||
| function | func menu "text" | This function is added to the scripts menu as "text" and is executed when the user selects it | func menu "tell time" |
| func init | This function is executed automatically | ||
| return | jumps out of the current function | ||
| exit | ends interpretation of this script | ||
| endfunc | |||
| unaryOp | + | unary plus | |
| - | unary minus | ||
| ! | logical inverse | ||
| ~ | bitwise inverse | ||
| abs | absolute | ||
| strlen | string len | ||
| rand | random number in range 0..n-1 (integer) | ||
| sin | sine, parameter in radians | ||
| cos | cosine, parameter in radians | ||
| tan | tangent, parameter in radians | ||
| asin | arc sine, result in radians | ||
| acos | arc cosine, result in radians | ||
| atan | arc tangent, result in radians | ||
| sqrt | square root | ||
| exp | exponent: e to the power | ||
| term | unaryOp value | abs delta | |
| value | delta | ||
| binaryOp | + | add | |
| - | subtract | ||
| * | multiply | ||
| / | divide | ||
| % | modulo (no floating point) | ||
| & | bitwise and | ||
| | | bitwise or | ||
| ^ | bitwise exclusive or | ||
| << | shift left | ||
| >> | shift right | ||
| expression | term | ||
| term binaryOp expression | evaluated from left to right without operator priority | ||
| format | 0w.phx | pad 0, width, places, hex, explode | |
| 5.3 | floating pt width 5, 3 places after the point | ||
| 8 | width 8 | ||
| 8h | width 8, hex | ||
| 08h | pad 0, width 8, hex | ||
| 08hx | pad 0, width 8, hex, explode | ||
| textTerm | value | ||
| value:format | radioFreq:.2x | ||
| textTerms | textTerm ... | a sequence of 1 or more TexTerm | |
| built-in functions | wait seconds | the interpretation of this script pauses | |
| timerstart name | starts a timer so that reading it returns 0 | ||
| timerpreset name seconds | starts a timer so that reading it returns seconds | ||
| speak textTerms | waits for last speak to finish, starts to speak textTerms | ||
| msgFile textTerms | writes textTerms to FSImp\message.txt | ||
| playsound value | waits for last sound to finish, starts to play the sound filename value | ||
| XPLMSpeakString textTerms | starts to speak textTerms immediately | ||
| XPLMCommandKeyStroke key | see globals.txt for enum xplm_key_... | ||
| XPLMCommandButtonPress button | see globals.txt for enum xplm_joy_... | ||
| XPLMSetUsersAircraft textTerms | loads the user aircraft given a path name, relative to X-System, including the .acf extension | ||
| XPLMPlaceUserAtAirport textTerms | place at airport given ICAO 4-letter code | ||
| XPLMGetNthAircraftModel index name path | for aircraft index (0 for user), get filename without .acf, and path relative to X-System but without the filename | ||
| sound object functions | .load value | loads the sound filename value | roar.load "lion roar.wav" |
| .play | starts the sound playing once | roar.play | |
| .loop | starts the sound playing repeadly | roar.loop | |
| .stop | stops the sound | roar.stop | |
| .wait | waits until the sound has stopped playing | roar.wait | |
| .volume value | sets the volume: 1.0 means original | roar.volume 0.7 | |
| .frequency value | sets the frequency: 1.0 means original | roar.frequency 0.85 | |
| .pan value | sets the balance: -1.0 is left, 0 is centred +1.0 is right | roar.pan -0.33 | |
| .changevolume value | changes the volume by value | roar.changevolume -0.05 | |
| .changefrequency value | changes the frequency by value | roar.changefrequency delta | |
| .changepan value | changes the balance by value | roar.changepan +0.2 | |
| assignment | variable= expression | ||
| variable+= expression | |||
| variable-= expression | |||
| variable*= expression | |||
| variable%= expression | |||
| variable&= expression | |||
| variable|= expression | |||
| variable^= expression | |||
| variable<<= expression | |||
| variable>>= expression | |||
| condOp | == | equal to | |
| = | equal to | ||
| != | not equal to | ||
| <> | not equal to | ||
| > | greater than | ||
| >= | greater than or equal to | ||
| < | less than | ||
| <= | less than or equal to | ||
| logicOp | & | and | |
| | | or | ||
| ^ | exclusive or | ||
| conditionTerm | term | closed | |
| term condOp term | x<=MAX | ||
| condition | conditionTerm | closed | |
| conditionTerm logicOp condition | evaluated from left to right without operator priority | x<=MAX | fishing & alpha==pi | |
| iteration | while condition | remain in loop as long as condition is true | |
| break | jumps out of current while loop | ||
| endwhile | |||
| conditional | if condition | if condition is true, execute following statements | |
| elseif condition | |||
| else | |||
| endif |
FSImp plugin for X-Plane