[PROGRAM] XScript Compiler : V0.4 : 2023-06-17

The place to discuss scripting and game modifications for X³: Farnham's Legacy

Moderators: Moderators for English X Forum, Scripting / Modding Moderators, Moderators for the X3:FL Forums

Post Reply
Cycrow
Moderator (Script&Mod)
Moderator (Script&Mod)
Posts: 22201
Joined: Sun, 14. Nov 04, 23:26
x4

[PROGRAM] XScript Compiler : V0.4 : 2023-06-17

Post by Cycrow » Wed, 30. Mar 22, 18:44

The XScript Compiler allows you to write script files externally and then "compile" them into X3FL scripts for use in the game.

Download

The language uses a simple C-like syntax and a command line tool to compile the code.
It also includes a User Defined Language file for notepad++ to give syntax highlighting and autocomplete of function calls.

Unlike with normal script files, you dont need to separate out each function call on a separate line and can combine them


Compiling Code:

Code: Select all

XScript.exe --load_data Data/XScript_X3FL.dat --compile script.XScript --out my.output.script.xml
without specifying "load_data" it will use the default that's include. You can also create your own data files to use (ie for Different games or mods).

Decompiling Code:
This will convert an existing script file so you can start editing it

Code: Select all

XScript.exe --load_data Data/XScript_X3FL.dat --decompile my.script.file.xml --out decompiled.XSript
The decompiling will do it as in, and wont attempt to simplify or merge any expressions. So if you compile then decompile the same script, it could end up looking alot different. So its best to only work from the source files rather than decompiling the script.

Building new Data File:
The data file contains all the information about functions as well as all the game data like wares, commands, ship/station types, etc
To create a new data file you need to create an xml file which defines all these entries.
There is a data file for X3FL already included, and the xml file it was created from "xml/x3fl.xml"

Code: Select all

XScript.exe --build_data xml/x3fl.xml --out XScript_X3FL.dat
The game data is found in the Data directory and doesn't yet read it from the games directory

Generating notepad++ UDL.
If you need to include new function and other types for use with notepad++ auto complete. You can generate it based on a data file

Code: Select all

XScript.exe --load_data XScript_X3FL.dat --exportudl
This will generated 2 files. The XScript_UDL.xml file you need to be place in the user defined directory
And the xscript.xml which is the auto complete file to go with it. This goes in Program Files/Notepad++/autoCompletion

NOTE: this is currently an early experimental version. The included function names have been auto generated, so will eventually change to use better names

To setup the script parameters like the arguments, version number, etc. You can use build in function calls

Code: Select all

SetArgument($a.ship, "a ship object", SHIP);
SetArgument($a.station, "a station object", STATION);
SetVersion(1);
SetDescrpition("this is my script file");
NOTE: these are only temporary and will eventually change


Planned future features:
  • Increment/Decrement symbols ($variable++, $variable--)
  • Renaming all function calls
  • Local scoped function calls
  • #include preprocessor
  • define preprocessor conditionals, #ifdef, #else, #endif
  • reading of all scripts files in the game for better understanding of arguments and return types
  • Full IDE for writing and building script files and whole projects
  • Function Macros
  • Function Overrides (multiple functions with same names but different arguments
  • Support for CallName vs String in script call functions
  • Extracting game data when generating data file
  • Improvements to various warning messages
Some Example code:

Example 1:
To set a ships position based on another object

Code: Select all

$ship->setPosition($object->posX(), $object->posY(), $object->posZ());
Example 2:
Getting random item from array (ignore the existing function to already do that in FL)

Code: Select all

$value = $array[random($array->size())];
Example 3:
Using Functions and arrays within Expressions

Code: Select all

$value = $array[($i * 10) / 2] * random(20);
Example 4:
Conditional

Code: Select all

if ($random(100) > 10 && $array[10] != 2) {
 ...
}

Cycrow
Moderator (Script&Mod)
Moderator (Script&Mod)
Posts: 22201
Joined: Sun, 14. Nov 04, 23:26
x4

Change Log

Post by Cycrow » Sat, 9. Apr 22, 14:03

V0.2
  • Added PCK supports for compiling/decompiling script files
  • Updated function data id 100-500
v0.3
  • Updated function data id 500-600
  • Added namespaces to constants
  • Improved error messages for loading xml data
v0.4
  • Added object properties
  • Updated function data id 600-900
  • Added #define

Cycrow
Moderator (Script&Mod)
Moderator (Script&Mod)
Posts: 22201
Joined: Sun, 14. Nov 04, 23:26
x4

Re: [PROGRAM] XScript Compiler : V0.2 : 2022-04-09

Post by Cycrow » Sat, 9. Apr 22, 14:03

XScript Compiler Programming Syntax

Termination:
All lines are terminated with a semi colon ';'

Variables:
All variables need to begin with dollar symbol '$', ie $variable
They can contain letters, numbers, underscore and fullstop/Period.
The first character after the $ must be a letter

Arrays/Tables:
To use an array or table, you use the subscript operators '[' and ']'.
IE, $array[10]
The subscript can be a single value, or an expression/function. If the variable is an array, a warning will be displayed with the value is anything but a number.
Tables will allow any value.
Arrays can be used within any expression or function
Arrays can be used against variables, or functions (if the function returns an array type)

Functions:
The functions will translate to the various X3 script commands, the arguments are between brackets '(' ')' and seperated by commas ','.
IE, functionName(argument1, argument2);
The arguments can be other function calls, arrays or expressions

Object Functions:
When using functions from objects, you use '->'
IE, $object->functionName();

Numbers:
The X3 scripts only support integer values (no floating-point)
So a number is only valid if it contains nothing but '0' to '9'

Assignments:
The assignment symbol is a single equals '='. This must be preceded with a variable or an array
$variable = 10;
$array[1] = 10;

Constants:
Constants uses a namespace symbol '::' with the constant group name and constant name.
TextPage::Menus

Special Constants:
There are a number of special constants, which are specific to the object the scrpit is being run on. IF the script is running globally, these will be null
this The current object
ThisHomebase The homebase of the current object
ThisEnvironment The environment of the current object (ie sector or docking ship/station)
ThisSector The sector of the current object
ThisOwner The owner race of the current object
DOCKEDAT The current docking ship/station
TRUEOWNER The "true" owner race. IE if the object is hiding thier actualy race, like pirates.
There are also some global constants
PLAYERSHIP The current player ship object (the ship the player is currently in)
TRUE 1
FALSE 0
NULL


Conditionals:
Conditions use the conditional keyword, with the conditional stationment in brackets.
Keywords:
if
else
not
while
Keywords can be combined, ie.
if not
else if
else if not
Unlike in X3, do if and skip if dont exist, these will be used automatically by the compiler depending on the size of the block.

Blocks:
Blocks are defined using the braces '{' and '}'. This allows multiple statements to be used with a conditional.
if(...)
{
...
...
}

Comments:
a single line comment uses '//'
You can also use a multiline comment starting with '/*' and ending with '*/'. Anything between these will be ignored by the compiler

Expression Operators:
Most operators are only valid when using with integer values or variables. Everything else will be converted to a string, and only the '+' is valid for strings.
+ Addition (valid for integers and strings)
- Subtraction
/ Divide
* Multiple
% Modulus
^ Bitwise XOR
& Bitwise AND
| Bitwise OR
~ Bitwise Negate

Logical Operators:
For use in comparisons and conditional statements
&& And
|| Or
! Not
== Equals
!= Not Equals
> Greater Than
>= Greater Than or Equals
< Lesser Than
<= Lesser Than or Equals

Properties:
You can use properties for getting and settings values on objects instead of the direct function calls

Code: Select all

$desination = $ship->destination

Code: Select all

$ship->destination = $sector
Pre-processors:
Pre-processor commands and run before compiling so wont get getting the final script.
#define - Defines values to replace code, which can be used for constants/macros
#undef - Undefines a previous defined value

User avatar
Joubarbe
Posts: 4796
Joined: Tue, 31. Oct 06, 12:11
xr

Re: [PROGRAM] XScript Compiler : V0.3 : 2022-04-18

Post by Joubarbe » Thu, 2. Mar 23, 22:48

Wow! I need to try that...

Do you have the source of that?

Cycrow
Moderator (Script&Mod)
Moderator (Script&Mod)
Posts: 22201
Joined: Sun, 14. Nov 04, 23:26
x4

Re: [PROGRAM] XScript Compiler : V0.4 : 2023-06-17

Post by Cycrow » Sat, 17. Jun 23, 02:01

New update

v0.4
  • Added object properties
  • Updated function data id 600-900
  • Added #define

Cycrow
Moderator (Script&Mod)
Moderator (Script&Mod)
Posts: 22201
Joined: Sun, 14. Nov 04, 23:26
x4

Re: [PROGRAM] XScript Compiler : V0.3 : 2022-04-18

Post by Cycrow » Sat, 17. Jun 23, 02:51

Joubarbe wrote:
Thu, 2. Mar 23, 22:48
Wow! I need to try that...

Do you have the source of that?
you can download the source here
https://xpluginmanager.co.uk/XScript_source.zip

Post Reply

Return to “X³: Farnham's Legacy - Scripts and Modding”