Compiled release (64-bit Windows):
Full documentation (describing settings and transform parameters):
https://github.com/bvbohnen/X4_Customiz ... ntation.md
X4 Customizer 1.15.2
This tool offers a framework for modding the X4 and extension game files programmatically, guided by user selected plugins (analyses, transforms, utilities). Features include:
- GUI to improve accessibility, designed using Qt.
- Integrated catalog read/write support.
- XML diff patch read/write support.
- Automatic detection and loading of enabled extensions.
- Three layer design: framework, plugins, and control script.
- Framework handles the file system, plugin management, etc.
- Plugins include analysis, transforms, and utilities.
- Plugins operate on a user's unique mixture of mods, and can easily be rerun after game patches or mod updates.
- Transforms can dynamically read and alter game files, instead of being limited to static changes like standard extensions.
- Transforms are parameterized, to adjust their behavior.
- Analyses can generate customized documentation.
- Transformed files are written to a new or specified X4 extension.
- Utilities offer extension error checking, cat pack/unpack support, and automated diff generation from pairs of files.
Running the compiled release:
- This starts up the Customizer GUI.
- Equivelent to running "bin/X4_Customizer.exe"
- "Run_Script.bat [script_name] [args]"
- This runs a script directly without loading the GUI.
- Call from the command line for full options (-h for help), or run directly to execute the default script at "Scripts/Default_Script.py".
- Script name may be given without a .py extension, and without a path if it is in the Scripts folder.
- "Clean_Script.bat [script_name] [args]"
- Removes files generated in a prior run of the given or default control script.
- "Check_Extensions.bat [args]"
- Runs a command line script which will test extensions for errors, focusing on diff patching and dependency checks.
- "Cat_Unpack.bat [args]"
- Runs a command line script which unpacks catalog files.
- "Cat_Pack.bat [args]"
- Runs a command line script which packs catalog files.
- "Generate_Diffs.bat [args]"
- Runs a command line script which compares pairs of xml files, and outputs suitable diff patches.
- "python Framework\Main.py [script_name] [args]"
- This is the primary entry function for the python source code, and equivalent to X4_Customizer.exe.
- When no script is given, this launches the GUI.
- "Script" displays the current control script, alongside documentation on available plugins. Drag plugins to the script window for a fast templated copy. Scripts can be opened or saved, and default to the Scripts folder. Syntax is highlighted as Python code. Press "Run Script" to run the current script; other tabs displaying game information will be updated automatically with the script changes.
- "Config" allows customization of settings. These are saved to a json file in the main tool directory when the window closes.
- The "Edit" menu opens up tabs with editable tables of game object information. Objects may be displayed individually or in a table. See further below for details. All edits made are saved in a json file in the main tool directory when a script is run or the window closes.
- The "Utilities" menu currently has one option, the Virtual File System. This shows which game files the Customizer has loaded, patched from other extensions (blue), or modified itself (red). Right click a file for the option to view its contents.
- The File Viewer tabs display individual file contents, in their pre-diff patch, post-diff patch, and post-customizer versions. Select two versions and press "Compare" to get a summary on lines changed. Press "Reload" to force the file to be reloaded from disk, including any diff patches; this may be used to test customize diff patch files in another extension.
- This tool is primarily controlled by a user supplied python script which will specify the desired plugins to run. Generally this acts as a build script to create a custom extension.
- The key control script sections are:
- "from Plugins import *" to make all major functions available.
- Optionally call Settings() to change paths and set non-default options; this can also be done through a setttings.json file or through the GUI.
- Call a series of plugins with desired input parameters; see plugin documentation for available options.
- Call Write_Extension() to write out any modified files, formatted as diff patches.
- Scripts of varying complexity are available in the Scripts folder, and may act as examples.
- In addition to script selected transforms, game information can be directly edited for select objects on the appropriate edit tabs. Tabs include "weapons", "wares", and others as time goes on.
- Press "Refresh" on the tab to load the game information.
- The "vanilla" column shows the object field values for the base version of the game files loaded.
- The "patched" column shows field values after other extensions have had their diff patches applied.
- The "edited" column is where you may change values manually.
- Running a script that includes the Apply_Live_Editor_Patches plugin will apply edits to the game files.
- The "current" column will show the post-script field values, and mainly exists for verification of hand edits as well as other transform changes.
- This framework may be used to write custom file editing routines.
- The general steps are: use Load_File() to obtain the patched file contents, use Get_Root() to obtain the current file root xml (which includes any prior transform changes), make any custom edits with the help of the lxml package, and to put the changes back using Update_Root().
- Existing plugins offer examples of this approach.
- Edits made using the framework will automatically support diff patch generation.
- Non-xml file support is more rudimentary, operating on file binary data pending further support for specific formats.
- Routines may be written as plugin functions and put up for inclusion in later Customizer releases to share with other users.
Example input file:
Code: Select all
''' Example for using the Customizer, setting a path to the X4 directory and running some simple transforms. ''' # Import all transform functions. from Plugins import * # This could also be done in settings.json or through the gui. Settings( # Set the path to the X4 installation folder. path_to_x4_folder = r'C:\Steam\SteamApps\common\X4 Foundations', # Set the path to the user documents folder. #path_to_user_folder = r'C:\Users\charname\Documents\Egosoft\X4\12345678', # Switch output to be in the user documents folder if needed. output_to_user_extensions = False, ) # Reduce mass traffic and increase military jobs. Adjust_Job_Count( ('id masstraffic*', 0.5), ('tags military' , 1.3) ) # Make weapons in general, and turrets in particular, better. Adjust_Weapon_Damage( ('tags turret standard' , 2), ('*' , 1.2), ) Adjust_Weapon_Shot_Speed( ('tags turret standard' , 2), ('*' , 1.2), ) # Get csv and html documentation with weapon changes. Print_Weapon_Stats() # Write modified files. Write_To_Extension()
Print out statistics for objects of a given category. This output will be similar to that viewable in the gui live editor pages, except formed into one or more tables. Produces csv and html output. Will include changes from enabled extensions.
Gather up all ware statistics, and print them out. This is a convenience wrapper around Print_Object_Stats, filling in the category and a default file name.
Gather up all weapon statistics, and print them out. This is a convenience wrapper around Print_Object_Stats, filling in the category and a default file name.
Adjusts generic mission chance to reward a mod instead of credits. The vanilla chance is 2% for a mod, 98% for credits.
Adjusts generic mission credit and notoriety rewards by a flat multiplier.
Adjusts job ship counts using a multiplier, affecting all quota fields. Input is a list of matching rules, determining which jobs get adjusted.
Change the size of the maps by moving contents (zones, etc.) closer together or further apart. Note: this will require a new game to take effect, as positions become part of a save file.
This will apply all patches created by hand through the live editor in the GUI. This should be called no more than once per script, and currently should be called before any other transforms which might read the edited values. Pending support for running some transforms prior to hand edits.
Adjusts the speed and acceleration of ships, in each direction.
Applies coloring to selected text nodes, for all versions of the text found in the current X4 files. Note: these colors will override any prior color in effect, and will return to standard text color at the end of the colored text node.
Adjusts ware min to max price spreads. This primarily impacts trading profit. Spread will be limited to ensure 10 credits from min to max, to avoid impairing AI decision making.
Adjusts ware prices. This should be used with care when selecting production chain related wares.
Adjusts damage done by weapons. If multiple weapons use the same bullet or missile, it will be modified for only the first weapon matched.
Adjusts weapon rate of fire. DPS and heat/sec remain constant.
Adjusts weapon range. Shot speed is unchanged.
Adjusts weapon projectile speed. Range is unchanged.
Packs all files in subdirectories of the given directory into a new catalog file. Only subdirectories matching those used in the X4 file system are considered.
Unpack a single catalog file, or a group if a folder given. When a file is in multiple catalogs, the latest one in the list will be used. If a file is already present at the destination, it is compared to the catalog version and skipped if the same.
Calls Check_Extension on all enabled extensions, looking for errors. Returns True if no errors found, else False.
Checks an extension for xml diff patch errors and dependency errors. Problems are printed to the console. Returns True if no errors found, else False.
Generate a diff of changes between two xml files, creating a diff patch.
Generate diffs for changes between two xml containing folders, creating diff patches.
Write all currently modified game files to the extension folder. Existing files at the location written on a prior call will be cleared out. Content.xml will have dependencies added for files modified from existing extensions.