[MODDING TOOL] JSON to TShips Editor 1.06

The place to discuss scripting and game modifications for X³: Terran Conflict and X³: Albion Prelude.

Moderators: Moderators for English X Forum, Scripting / Modding Moderators

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

[MODDING TOOL] JSON to TShips Editor 1.06

Post by Joubarbe » Fri, 3. Apr 20, 11:34

OVERVIEW
Image

Warning: this is a tool for advanced users. You must know what TShips refer to and how to edit ship stats. You also need to know how to run a script in game, and have a general understanding of how JSON works.
The following sections can all be found inside the readme file in the archive.


This program is able to apply a lot of modifications to any TShips files, via a JSON script (editor.json). It has some special variables and constants, and it can handle conditional statements.
The script you write is applied to every single line of the TShips. If you want to skip some ships, you have to specify special conditions.
This tool does not overwrite or mess with your game. It takes any TShips.txt, parses the data you write from editor.json, and creates another TShips.txt in an output folder.
All the editable values are the ones you see in-game, and not the raw values you find in TShips. For instance, speed = rawValue / 500 (eg. Mammoth has 43800 as rawValue and 87.6 as in-game speed). All the conversions are done by the program.

From 1.06, the archive also contains a new tool that generates the editor.json file from CSV file. See this post.

Download
(Google Drive)

INSTALL
Image

1/ Unpack the archive in any folder you want.
2/ You need to extract TShips.txt from your game. You will need X3 Editor 2
3/ Put TShips.txt into the same folder.
4/ You also need the file 9978-L044.xml, which can be exported by running the script '\Ship data export scripts\Mayhem.ExportShipSizes.xml'. This file is mandatory to use several properties. You will need to copy all three scripts inside X3\addon\scripts.
5/ Write your script in editor.json.
6/ Launch this program with "JSON To TShips Parser.exe".
7/ Add your new output\TShips.txt into your game via X3 Editor 2. Choose .pck compression and open it in the editor to make sure there's no mistake.

THE SCRIPT
Image

The JSON file that comes within this archive has already an example to show you the structure of the file. It is important that you understand JSON and that you do not change its structure. It contains an object called "sets" which includes an array of several "instruction sets", and each of them has two other arrays: "conditions" and "instructions". You can write as many conditions and instructions as you want. If one condition is not TRUE, the instructions of the set will be ignored and the system will go to the next set. If you do not need a condition, the conditions array must be left empty (do not erase it). Remember that the script is applied to every TShips entry. Consider that everything is case-sensitive.

Image

In this example, the script does ALL the following:
1/ If the ship is an Argon TL, its hull is increased by a random value going from 5,000 to 150,000, and it gains 1 additional shield. var1 is defined in customVars.txt:
Image
2/ If the ship is a Boron that uses a 200MJ shield-bay, it is changed to a 1GJ shield-bay.
3/ If the ship is an M3 that can be equipped with more than 1 shield, this value is doubled. We use the function "ceil" that rounds the output up.
4/ If the ship is NOT an M4 AND NOT an M5 (notice the "<>", please don't use "!="), its hull is increased by 150%.

Image

In this other example, the goal is to scale the hull of the ship to its physical size. I multiply all ship size by 4,000, except for M3, M4 and M5, who have respectively a 3,000, 2,000, 1,000 multiplier.

VARIABLES, CONSTANTS AND FUNCTIONS
Image

This tool cannot edit all the values that come from TShips. It only allows the editing of the most common properties:

yaw
pitch
roll
speed
acceleration
angularAcceleration
hull
cargoMin
cargoMax
shieldType
shieldCount
generator
laserEnergy
laserReload
relVal
race
variationIndex


You can use these properties for read and write. The following properties, however, are read-only:

size
class
subtype


For conveniency, there are three persistent variables that you can write to and read from.

var1
var2
var3


These variables are defined in customVars.txt. You can add your own variables into that file. For demonstration purposes, I've also added in this file a variable called "halfMoreHull" which equals to "hull * 1.5". This means that hull here will be replaced by the hull property of every TShips entry.

There are also some constants you can use to make things easier. The number they replace is between parentheses:

#1MJ (0)
#5MJ (1)
#25MJ (2)
#200MJ (3)
#1GJ (4)
#2GJ (5)
#Argon (1)
#Boron (2)
#Split (3)
#Paranid (4)
#Teladi (5)
#Xenon (6)
#Kha'ak (7)
#Pirates (8)
#Goner (9)
#Player (10)
#HostileRace (11)
#NeutralRace (12)
#FriendlyRace (13)
#Unknown (14)
#Phanon (15)
#OCV (16)
#ATF (17)
#Terran (18)
#Yaki (19)
#M1 (0)
#M2 (1)
#M3 (2)
#M4 (3)
#M5 (4)
#M6 (5)
#M7 (6)
#M8 (7)
#TL (8)
#TM (9)
#TP (10)
#TS (11)
#Vanguard (1)
#Sentinel (2)
#Raider (3)
#Hauler (4)
#Miner (5)
#SuperFreighter (6)
#Tanker (7)
#XL (12)
#TankerXL (14)
#SuperFreighterXL (15)
#Advanced (21)
#Prototype (22)
#Experimental (23)
#Enhanced (24)


Some functions can also be used, as well as pi and e (exponent):

sqr()
log()
ceil()
floor()

min() - Unlimited number of values separated by a comma.
max() - Same.
sum() - Same.
random([max], [min]) - You can specify 1/ only max, 2/ max and min, or nothing to get a random float (0.0 to 1.0).
debug()

debug() is a special function that prints the given arguments — as raw values — into a file named "debug.txt". Note that the ship name is automatically added to the debug line, so that "debug()" without any argument could still be useful if, for instance, you'd like to see what ships meet your conditions.
Last edited by Joubarbe on Wed, 19. Jul 23, 19:15, edited 17 times in total.

User avatar
XenonArchitect7
Posts: 110
Joined: Fri, 5. Jul 19, 07:19

Re: [TOOL] JSON to TShips Editor 1.0

Post by XenonArchitect7 » Fri, 3. Apr 20, 15:39

Excellent work, Joubarbe. This will be most useful!

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

Re: [TOOL] JSON to TShips Editor 1.0

Post by Joubarbe » Fri, 3. Apr 20, 15:59

And here's the full script I'm using to rebalance Mayhem 3.0 (plus my custom variables). (EDIT: updated)

EDIT: 1.04 adds variationIndex (useful to get the miners, for instance), and all constants now requires # as prefix.
EDIT: 1.05 fixes the ID duplicate error caused by the <language> node in 9978.
EDIT: For Mayhem 3, here is the original TShips on which I apply the script. All manual work (laser compatibility, mostly) is done.

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

Re: [MODDING TOOL] JSON to TShips Editor 1.05

Post by Joubarbe » Fri, 22. Apr 22, 10:40

Updated with the tool I've used to edit ship stats from Mayhem 3.17. All included in the main archive.

This new tool generates an editor.json file from CSV file that you can edit from Google Sheets or Excel, or just as a normal text file. Then the main program is automatically launched to generate a TShips in the output folder. Also makes two new t-files: 1/ Ship description. 2/ People requirement per ship, used in Mayhem.

Take a look at the new customVars.txt if you want to use this, as it includes essential constants.

Post Reply

Return to “X³: Terran Conflict / Albion Prelude - Scripts and Modding”