Paradox Chronicle
Overview
Paradox Chronicle (formerly Paradox Language Support) is the IntelliJ IDEA plugin designed for mod developers of Paradox Interactive games.
As the guidebook to the paradox universe, the plugin strives to provide a powerful and comprehensive infrastructure, along with a smart, efficient, and feature-rich development experience.
The plugin automatically detects game directories and mod directories, analyzes the files within to build caches and indexes.
After completing the necessary configuration (game type, game directory, mod dependencies, etc.) and project analysis (scanning files, building indexes), you can enable and experience the full range of language features.
The plugin implements core language features based on its own config system.
The CWT config files it uses follow a syntax and format largely consistent with CWTools, with certain improvements and extensions.
It comes with the latest version of built-in configs, ready to use out of the box, while also supporting customization and importing of config files to meet personalized development needs.
Core Features:
- Multi-language support: Supports the script language, localisation language, and CSV language used for mod development, as well as the CWT language for writing configs.
- Advanced language construct support: Supports parameters, scopes, complex expressions, inline scripts, definition injections, and other advanced language constructs.
- Rich language features: Supports code highlighting, code navigation, code completion, code refactoring, intention actions, code inspections, quick documentation, inlay hints, gutter icons, code hierarchy, diff viewing, diagrams, and many other language features.
- Flexible code navigation: Navigates to various targets, including files, definitions, localisations, related localisations, related images, related configs, etc., through navigation actions, quick documentation, inlay hints, gutter icons, code hierarchy, search everywhere, and more.
- Enhanced information hints: Shows key information such as localisation text, images, scopes, parameters, etc., through quick documentation, inlay hints, gutter icons, and more.
- Extensible config system: Supports customizing and importing config files to refine and enhance features like highlighting, navigation, completion, inspections, information hints.
- Image processing: Supports previewing and rendering DDS and TGA images, and can convert between different image formats (PNG, DDS, TGA).
- Tool integration: Integrates useful tools such as Image Magick, Translation Plugin, Tiger, etc., to boost development efficiency.
- AI assistance: Preliminary integration of AI technology for translating and polishing localisation text.
Getting Started
Installation
- Using the IDE built-in plugin system:
Settings/Preferences > Plugins > Marketplace > Search for “Paradox Chronicle” > Install
- Using JetBrains Marketplace: Go to JetBrains Marketplace and install it by clicking the
Install to ... button.
- Manual Installation: Download the latest release and install it manually (No need to unzip):
Settings/Preferences > Plugins > ⚙️ > Install plugin from disk...
Usage Steps
- Open your mod’s root directory in the IDE.
- Open the mod descriptor file (
descriptor.mod, or .metadata/metadata.json for VIC3 and EU5).
- Click the mod settings button in the floating toolbar at the top right of the editor.
- Configure the mod’s game type, game directory, and required mod dependencies.
- Confirm the configuration and wait for the IDE to finish project analysis.
- Start your mod development journey.
Practical Tips
- Global Search:
- Use
Ctrl + Shift + R or Ctrl + Shift + F to search within the current project, directory, or a specified scope.
- Use
Shift + Shift (Search Everywhere) to quickly find files, definitions, scripted variables, and other symbols.
- Code Navigation:
- Use
Ctrl + Click to jump to the declaration or usage of a target.
- Use
Ctrl + Shift + Click to jump to the type declaration of a target.
- Use
Alt + Click to jump to the declaration of the related configs for a target.
- Use
Shift + Alt + Click to jump to the declaration of the related localisations for a target.
- Use
Ctrl + Shift + Alt + Click to jump to the declaration of the related images for a target.
- Use the
Navigate menu (or the Go To option in the editor’s right-click menu) for quick navigation.
- Use
Navigate > Definition Hierarchy to open the type hierarchy window and view definitions of specific types.
- Use
Navigate > Call Hierarchy to open the call hierarchy window and view the call relationships of definitions, localisations, scripted variables, etc.
- Select the
Paradox Files view in the project panel to browse aggregated game and mod files.
- Select the
CWT Config Files view in the project panel to browse aggregated config files.
- Code Inspection:
- By clicking
Editor > Inspections on the settings page, you can browse detailed descriptions of code inspections, configure their enabled status and options, and manage profiles.
- For file-level code inspection: after file analysis finished, view issues for the current file in the problems panel.
- For global code inspection: use
Code > Inspect Code… to run a global inspection in a specified scope, and view the detailed report in the problems panel.
- Open the plugin’s global settings page via:
- Selecting
Languages & Frameworks > Paradox Chronicle on the settings page.
- Open the plugin’s tool menu via:
- Selecting
Paradox Chronicle from the editor’s right-click menu.
- Selecting
Tools > Paradox Chronicle from the main menu.
- Open the mod settings dialog via:
- Clicking the blue gear icon in the editor’s top-right floating toolbar.
- Selecting
Paradox Chronicle > Open Mod Settings... from the editor’s right-click menu.
- Selecting
Tools > Paradox Chronicle > Open Mod Settings... from the main menu.
- Modify preferred locale, default game type, default game directory and other functional details in the global settings.
- Adjust game directory, mod dependencies and other configurations in the mod settings.
Troubleshooting
- Ensure both the IDE and the plugin are updated to the latest versions.
- If the issue might be index-related, try to invalidate caches and restart the IDE.
- If the issue might be config-related, try to write custom config files.
- If the issue might be plugin configuration-related, try deleting the plugin’s configuration file (
paradox-language-support.xml, recommended to locate using Everything).
- Feedback is welcome through GitHub, Discord and other channels.
Technical Details
- Primarily developed using the Kotlin programming language.
- Built on the IntelliJ Platform SDK, implementing deep semantic analysis and rich language features based on PSI (rather than LSP).
- Uses JFlex for lexical analysis and BNF for syntax analysis.
- Built-in rich custom extension points for flexible feature extension, making it easy to customize and enhance plugin behavior.
- Built-in code injection system for implementing functionalities, fixes, and optimizations that cannot be achieved through conventional means.
- Built-in image processing module (DDS, TGA) for previewing, rendering, and processing additional image formats.
- Built-in tool integration module (image processing, translation, inspection tools) for optimizing and extending plugin capabilities.
- Built-in AI integration module (preliminary, MVP status) for translating and polishing localisation text.
Known Limitations
- The plugin is intended for IntelliJ IDEA (and other JetBrains IDEs such as PyCharm) and does not work with VSCode or other text editors, and there are no relevant development plans.
- The plugin’s support for some complex high-level language constructs in script files and localisation files is not yet complete, and is still being improved.
- For example, the plugin currently does not support definitions declared in inline scripts in Stellaris, or complex localisation commands in Jomini.
- The quality of the plugin’s core language features (such as code completion, code inspection, and quick documentation) largely depends on the completeness and timeliness of the config files. Incomplete or faulty configs may lead to missing features and false positives.
- Currently, the configs for Stellaris, Victoria 3, Europa Universalis V and Hearts of Iron IV are actively maintained, while the configs for other games may be rather incomplete or out of date.
- For detailed maintenance of config files, please refer to
CONTRIBUTORS.md.
Contribution and Support
We welcome various forms of contribution and support, including but not limited to:
For a detailed guidance for contributing, please see CONTRIBUTING.md.
For a detailed list of contributors, please see CONTRIBUTORS.md.
Contributing Code
Given the plugin’s large codebase and high complexity, contributing core code is highly challenging.
Nevertheless, by referencing existing documentation, code, configuration files and config files, leveraging AI assistance, and exploring on your own, it is still possible to consider and practice contributions to certain parts of the codebase.
For example, by viewing the reference documentation and configuration files (e.g., plugin.xml and the including XML configuration files), combined with keyword searching, you can try adding and improving various language features, or enhancing the plugin’s capabilities and compatibility.
Contributing Config Files
Given the plugin’s config-driven architecture, contributing config files is one of the most effective ways to improve support for specific games.
Config files define the semantic information (definitions, modifiers, scopes, effects, triggers, etc.) that drives code completion, code inspections, and information hints. Keeping them up to date directly improves the user experience for all users of that game.
For reference, please read the documentation for the config system, the syntax reference manual, and the config format reference manual.
Contributing Documentation
The project documentation is mainly divided into general documentation (such as README.md), maintainer documentation (located in the documents directory), and reference documentation (located in the docs directory).
These documents inevitably contain errors, shortcomings, missing details, and areas needing supplementation. Contributions to improve documentation quality are welcome, especially for the project’s reference documentation.
Reference Links
Official Documentation
Plugin Development
Image Processing
Tutorials & Wiki
About
Developed by
Windea - The dragon knight who with the title of breeze.
Powered by
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)
评论