Image Support

The plugin provides image reading, preview, rendering, and format conversion for Paradox game mods, and applies these capabilities to quick documentation, inlay hints, editor preview, image conversion actions, and other language features.

Settings Page

In the IDE settings page, go to Languages & Frameworks > Paradox Chronicle > Images to open the image processing settings page.

Here you can configure the image cache cleanup policy, cache size limits, render failure policy, and image materialization timeout.

Go to Languages & Frameworks > Paradox Chronicle > Presentation to open the presentation settings page, which contains text, image, and text icon limits for quick documentation and inlay hints.

Supported Formats

• Standard image formats: PNG, JPEG, GIF, and other formats supported by the IDE and ImageIO.
• Extended image formats: DDS and TGA.

The plugin does not change how the IDE recognizes ordinary image files. It only adds DDS/TGA reading, preview, and rendering support.

Editor Preview

Open an image file in the editor to preview it. DDS and TGA images are loaded through the image reading support provided by the plugin.

You can also use Jump to External Editor in the context menu to open the image in the image editor associated with your operating system.

Tips

If DDS/TGA images cannot be rendered properly, check the image tool integration and cache settings. See Integrations for external tool configuration.

Images in Quick Documentation

Images in quick documentation are loaded through a render session:

• Building the documentation only resolves image sources and rendering requests; it does not perform image IO.
• After the documentation content is built, image rendering and decoding are awaited in the background.
• This avoids executing command-line tools or image rendering in a readAction.

For text icons in localisation text:

• Images with a height no greater than quickDocTextIconHeightLimit are treated as text icons.
• They are scaled to the actual documentation text height for better visual alignment.
• Images taller than this limit are treated as ordinary images and keep their original size, avoiding forced shrinking of large images embedded in localisation text.

The maximum display size of images in quick documentation can be configured with quickDocMaxImageDisplaySize.

Images in Inlay Hints

Text icons in inlay hints are materialized asynchronously:

• Collecting hints only creates a placeholder presentation; image pixels are not read.
• Images are read, rendered, and decoded in a background coroutine.
• After completion, the placeholder presentation is updated to the actual icon on the EDT.
• CachedImageIcon is not lazily loaded on the EDT or in a readAction.

Icons taller than inlayTextIconHeightLimit are not rendered.

Image Format Conversion

The plugin provides the following image format conversion actions:

• Convert selected images to PNG, DDS, or TGA.
• Select multiple images in the project view for batch conversion.
• Confirm the target file name and target directory before conversion.
• Choose to skip or overwrite existing target files.

Image conversion uses the built-in TwelveMonkeys ImageIO implementation first. If the built-in implementation cannot complete the conversion, the configured external image tool may be used as a fallback.

Warning

TwelveMonkeys ImageIO has format limitations, such as not supporting writing DDS or certain newer DDS extension formats. If you need to convert these formats, configure an external image tool. See Integrations.

Implementation Notes

Image Reading and Rendering

Image processing is based on TwelveMonkeys ImageIO and IntelliJ Platform image support:

• Standard image formats are handled by ImageIO and IDE image support.
• DDS/TGA are handled by the ImageReader/ImageWriter SPIs registered by the plugin.
• Image metadata reading, rendering, and decoding are coordinated by ImageRenderService.

External Image Tools

When the built-in implementation cannot handle a specific image or format, external image tools (such as Texconv or ImageMagick) can be enabled.

See Integrations for external tool configuration, downloads, and limitations. This page does not cover command-line details.

Cache

Rendered and sliced PNG images are cached under ~/.windea/chronicle/images.

You can configure the following in the image settings page:

• Cache cleanup policy: none, by TTL, by size, or by TTL and size;
• TTL (days);
• Maximum cache size (MB);
• Maximum number of cache files.

Timeout, Cancellation, and Failure Policy

• Image materialization is limited by renderTimeoutSeconds.
• Image reading, copying, and writing check for cancellation when the byte threshold is reached.
• External tool commands support timeout and cancellation.
• When rendering fails, you can choose to:
  • accept the broken image;
  • remove the image;
  • use a placeholder.

Related Settings

Setting	Description
cacheCleanupPolicy	Image cache cleanup policy
cacheTtlDays	Cache TTL (days)
cacheMaxSizeMb	Maximum cache size (MB)
cacheMaxFiles	Maximum number of cache files
renderTimeoutSeconds	Timeout for materializing one image
renderFailurePolicy	Image render failure policy
presentableTextLengthLimit	Presentable text length limit
quickDocLocalisationTextFontSize	Fallback font size for localisation text in quick documentation
quickDocMaxImageDisplaySize	Maximum image display size in quick documentation
quickDocTextIconHeightLimit	Text icon height limit in quick documentation
inlayLocalisationTextLengthLimit	Localisation text length limit in inlay hints
inlayTextIconHeightLimit	Text icon height limit in inlay hints