{"id":24540666,"url":"https://github.com/mistralys/x4-core","last_synced_at":"2026-02-15T18:02:41.747Z","repository":{"id":62549568,"uuid":"485889117","full_name":"Mistralys/x4-core","owner":"Mistralys","description":"Core files for my X4 tools.","archived":false,"fork":false,"pushed_at":"2024-05-29T05:45:40.000Z","size":210,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-23T02:46:40.143Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mistralys.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-26T17:42:47.000Z","updated_at":"2024-05-29T05:45:43.000Z","dependencies_parsed_at":"2024-05-29T07:08:46.946Z","dependency_job_id":null,"html_url":"https://github.com/Mistralys/x4-core","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mistralys%2Fx4-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mistralys%2Fx4-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mistralys%2Fx4-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mistralys%2Fx4-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mistralys","download_url":"https://codeload.github.com/Mistralys/x4-core/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243830914,"owners_count":20354850,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-22T18:14:37.972Z","updated_at":"2026-02-15T18:02:41.742Z","avatar_url":"https://github.com/Mistralys.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# X4 Database Core\n\nDatabase and utility classes used to access X4: Foundations game data in \nan OOP way. It is designed to be used as a dependency in other projects\n(see [X4 Tools](#x4-tools-and-libraries), for example).\n\n## Version\n\n**Current Version:** 1.0.1\n**Documentation:** [Project Manifest](docs/agents/project-manifest/README.md)\n\n## Database features\n\n- Faction database\n- Ware database\n- Ship database\n- Station module database\n- Blueprint database\n- Translation tool\n- DLC metadata\n- Macro file index\n- Automated database file generation from the game data\n\n## Requirements\n\n- PHP 8.4 or higher.\n- [Composer](https://getcomposer.org/).\n\n## Installation\n\nRequire the package in your Composer project:\n\n```bash\ncomposer require mistralys/x4-core\n```\n\n## Usage\n\n### Raw JSON data files\n\nAll extracted game data is stored in JSON files in the `data` folder.\n\n- [factions.json](./data/factions.json) - Faction definitions\n- [wares.json](./data/wares.json) - Ware definitions\n- [ships.json](./data/ships.json) - Ship definitions\n- [modules.json](./data/modules.json) - Station module definitions\n- [blueprints.json](./data/blueprints.json) - Blueprints\n- [macro-index.json](./data/macro-index.json) - Macro file index\n- [data-sources.json](./data/data-sources.json) - Data sources (DLC metadata)\n\n### The faction classes\n\nAll factions available in the game can be accessed through the faction collection.\n\n#### The faction collection\n\nAll factions are available through the `FactionDefs` collection class.\n\n```php\nuse Mistralys\\X4\\Database\\Factions\\FactionDefs;\n\necho \"Available factions:\" . PHP_EOL;\n\nforeach(FactionDefs::getInstance()-\u003egetAll() as $faction) {\n    echo $faction-\u003egetLabel() . PHP_EOL;\n}\n```\n\n#### Faction getter methods\n\nWhen working with the faction classes, dedicated getter methods exist to access\nfactions instead of using the faction ID constants.\n\n```php\nuse Mistralys\\X4\\Database\\Factions\\KnownFactions;\n\n$argon = KnownFactions::getInstance()-\u003egetArgon();\n\necho $argon-\u003egetLabel(); // Outputs \"Argon\"\n```\n\n### The ware classes\n\nAll items available in the game, from trade goods to ships, are available in the\nmain ware collection.\n\n#### The ware collection\n\nAll wares are available through the `Wares` collection class.\n\n```php\nuse Mistralys\\X4\\Database\\Wares\\WareDefs;\n\necho \"Available wares:\" . PHP_EOL;\n\nforeach(WareDefs::getInstance()-\u003egetAll() as $ware) {\n    echo $ware-\u003egetLabel() . PHP_EOL;\n}\n```\n\nThis fetches wares by ID:\n\n```php\nuse Mistralys\\X4\\Database\\Wares\\WareDefs;\n\n$advancedElectronics = WareDefs::getInstance()\n    -\u003egetByID('module_gen_prod_advancedelectronics_01');\n```\n\n#### The ware finder\n\nThe ware finder utility class allows selecting search criteria to filter the\nwares and retrieve specific wares. The following example uses the ware finder to \nretrieve all ship engines provided by the Boron DLC.\n\n```php\nuse Mistralys\\X4\\Database\\Wares\\WareDefs;\nuse Mistralys\\X4\\Database\\Wares\\WareGroups;\nuse Mistralys\\X4\\Database\\DataSources\\KnownDataSources;\n\n$boronEngines = WareDefs::getInstance()\n    -\u003efindWares()\n    -\u003eselectDataSource(KnownDataSources::DATA_SOURCE_KINGDOM_END)\n    -\u003eselectGroup(WareGroups::GROUP_ENGINES)\n    -\u003egetAll();\n```\n\n### The ship classes\n\nAll ships available in the game can be accessed through the ship collection.\n\n```php\nuse Mistralys\\X4\\Database\\Ships\\ShipDefs;\n\necho \"Available ships:\" . PHP_EOL;\n\nforeach(ShipDefs::getInstance()-\u003egetAll() as $ship) {\n    echo $ship-\u003egetLabel() . PHP_EOL;\n}\n```\n\n\n\n### Accessing translations\n\nThe official translations are bundled with the package, and can be\naccessed to translate text codes like `{20101,20604}` (\"Manorina (Gas) Vanguard\").\n\n```php\nuse Mistralys\\X4\\Database\\Translations\\Languages;\n\n$english = Languages::getInstance()-\u003egetEnglish();\n\n$shipName = $english-\u003et('{20101,20604}');\n```\n\n## Development setup\n\n### Unpacking game data files\n\nThe mod requires the game's data files to be unpacked using the\n[X4 Data Extractor][] tool. The tool acts as a library to access the\nextracted information. This includes the DLC metadata necessary to\ngenerate the correct mod file structure.\n\nPlease refer to the tool's instructions to unpack the game data files.\n\n### Configuration\n\n1. Unpack the data files (see above).\n2. Clone this repository.\n3. Copy `dev-config.php.dist` to `dev-config.php`.\n4. Edit the file to set the correct paths. \n\n### Database update\n\nTo update the bundled database, use the `build` Composer command\nto update the JSON files in the `data` folder.\n\n```bash\ncomposer build\n```\n\n## X4 Tools and libraries\n\n- [X4 Game Notes][] - _Docs_ - Howto, tips and general information about X4.\n- [X4 Core][] - _Library_ - Access X4 game data in an OOP way.\n- [X4 Data Extractor][] - _Tool \u0026 Library_ - Extract X4 game files.\n- [X4 Savegame Parser][] - _Tool_ - Parse X4 savegames to extract information.\n- [X4 Cargo Size Mod][] - _Mod_ - Mod to increase ship cargo sizes.\n\n[X4 Data Extractor]: https://github.com/Mistralys/x4-data-extractor\n[X4 Game Notes]: https://github.com/Mistralys/x4-game-notes\n[X4 Core]: https://github.com/Mistralys/x4-core\n[X4 Savegame Parser]: https://github.com/Mistralys/x4-savegame-parser\n[X4 Cargo Size Mod]: https://github.com/Mistralys/x4-mod-cargo-sizes\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmistralys%2Fx4-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmistralys%2Fx4-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmistralys%2Fx4-core/lists"}