README

Database and utility classes used to access X4: Foundations game data in an OOP way. It is designed to be used as a dependency in other projects (see X4 Tools, for example).

Database features

Faction database
Ware database
Ship database
Station module database
Blueprint database
Translation tool
DLC metadata
Macro file index
Automated database file generation from the game data

Requirements

PHP 8.2 or higher.
Composer.

Installation

Require the package in your Composer project:

composer require mistralys/x4-core

Usage

Raw JSON data files

All extracted game data is stored in JSON files in the data folder.

factions.json - Faction definitions
wares.json - Ware definitions
ships.json - Ship definitions
modules.json - Station module definitions
blueprints.json - Blueprints
macro-index.json - Macro file index
data-sources.json - Data sources (DLC metadata)

The faction classes

All factions available in the game can be accessed through the faction collection.

The faction collection

All factions are available through the FactionDefs collection class.

use Mistralys\X4\Database\Factions\FactionDefs;

echo "Available factions:" . PHP_EOL;

foreach(FactionDefs::getInstance()->getAll() as $faction) {
    echo $faction->getLabel() . PHP_EOL;
}

Faction getter methods

When working with the faction classes, dedicated getter methods exist to access factions instead of using the faction ID constants.

use Mistralys\X4\Database\Factions\KnownFactions;

$argon = KnownFactions::getInstance()->getArgon();

echo $argon->getLabel(); // Outputs "Argon"

The ware classes

All items available in the game, from trade goods to ships, are available in the main ware collection.

The ware collection

All wares are available through the Wares collection class.

use Mistralys\X4\Database\Wares\WareDefs;

echo "Available wares:" . PHP_EOL;

foreach(WareDefs::getInstance()->getAll() as $ware) {
    echo $ware->getLabel() . PHP_EOL;
}

This fetches wares by ID:

use Mistralys\X4\Database\Wares\WareDefs;

$advancedElectronics = WareDefs::getInstance()
    ->getByID('module_gen_prod_advancedelectronics_01');

The ware finder

The ware finder utility class allows selecting search criteria to filter the wares and retrieve specific wares. The following example uses the ware finder to retrieve all ship engines provided by the Boron DLC.

use Mistralys\X4\Database\Wares\WareDefs;
use Mistralys\X4\Database\Wares\WareGroups;
use Mistralys\X4\Database\DataSources\KnownDataSources;

$boronEngines = WareDefs::getInstance()
    ->findWares()
    ->selectDataSource(KnownDataSources::DATA_SOURCE_KINGDOM_END)
    ->selectGroup(WareGroups::GROUP_ENGINES)
    ->getAll();

The ship classes

All ships available in the game can be accessed through the ship collection.

use Mistralys\X4\Database\Ships\ShipDefs;

echo "Available ships:" . PHP_EOL;

foreach(ShipDefs::getInstance()->getAll() as $ship) {
    echo $ship->getLabel() . PHP_EOL;
}

Accessing translations

The official translations are bundled with the package, and can be accessed to translate text codes like {20101,20604} ("Manorina (Gas) Vanguard").

use Mistralys\X4\Database\Translations\Languages;

$english = Languages::getInstance()->getEnglish();

$shipName = $english->t('{20101,20604}');

Development setup

Unpacking game data files

The mod requires the game's data files to be unpacked using the X4 Data Extractor tool. The tool acts as a library to access the extracted information. This includes the DLC metadata necessary to generate the correct mod file structure.

Please refer to the tool's instructions to unpack the game data files.

Configuration

Unpack the data files (see above).
Clone this repository.
Copy dev-config.php.dist to dev-config.php.
Edit the file to set the correct paths.

Database update

To update the bundled database, use the build Composer command to update the JSON files in the data folder.

composer build

X4 Tools and libraries

X4 Game Notes - Docs - Howto, tips and general information about X4.
X4 Core - Library - Access X4 game data in an OOP way.
X4 Data Extractor - Tool & Library - Extract X4 game files.
X4 Savegame Parser - Tool - Parse X4 savegames to extract information.
X4 Cargo Size Mod - Mod - Mod to increase ship cargo sizes.

mistralys / x4-core

Maintainers

Details