Unciv Documentation

Unciv uses LibGDX for rendering. Images are displayed via a SpriteBatch which binds textures to memory.

Key Performance Concept:

• Texture Binding: The process of loading textures into memory is slow, while the actual rendering is fast.
• Optimization Strategy: To minimize performance hits, the game minimizes texture rebinds (swapping between different categories). This is achieved by compiling images into large PNGs using ImagePacker.packImages().
• Texture Limits: Due to chipset limitations, textures are capped at 2048*2048 pixels. Images are therefore categorized (e.g., Images.Flags, Images.Tech) and compiled into separate PNG files in the android/assets folder to balance proximity and size.

Unciv is built using LibGDX for multi-platform support. The project is organized into several key directories:

• core: Contains 99% of the code, representing all platform-independent logic.
• desktop: Contains platform-specific code for desktop environments.
• android: Contains platform-specific code for Android, as well as the game Images and Assets (required for both Android and Desktop).
• server: Contains the source for UncivServer, which enables communication between multiplayer game instances.
• tests: Contains tests that can be executed via Gradle.

Unciv mods are categorized based on how they interact with the game rules:

• Extension mods: Add new nations, units, buildings, or resources to an existing ruleset (either the default or another mod's ruleset).
• Base Ruleset mods: Replace the entire existing ruleset (tech tree, units, policies, etc.) to provide a completely different experience. These require setting "isBaseRuleset": true in the ModOptions.json file.
• Ruleset-agnostic mods: Do not contain ruleset JSONs. These focus on audiovisual changes (tilesets, unitsets, UI skins) or map mods.

If you add text directly in code (e.g., popup.add("Hello world".toLabel())) that is not contained in a JSON file or the UniqueType system, you must manually add it to template.properties to make it translatable.

Formatting Rules:

• Add the text followed by an equals sign and a space: Hello world = .
• Crucial: The space after the = is absolutely required. Ensure your editor does not strip trailing whitespace.
• Avoid leading spaces or multiple spaces between the text and the = unless those spaces are a required part of the string, as translators may overlook them.

When translating, check if the base game uses an override in English.properties. If a term is overridden in English, you must translate it relative to that override, not the original base game key.

Example: If English.properties contains gold = credits, and you are translating into your language:

• Correct: gold = [your translation for credits]
• Incorrect: gold = gold (This ignores the English override and will result in incorrect terminology).

Always ensure exact case sensitivity for both the translation keys (left of the =) and the filenames.

Unciv uses .properties files for translations, with one file per language. This avoids merge conflicts and human error common in JSON.

Format Rules:

• Use the format Source Text = Translated Text to make it easy for translators to see the context.
• Use = as the delimiter.
• Use lines starting with # for comments to provide guidance to translators.
• Do not use JSON for translation files as it is prone to syntax errors.

Edge images are drawn when a tile is adjacent to another tile in a specific direction.

Location: Images/Tilesets/<tileset name>/Edges/

Naming Convention: <tile name>-<origin tile filter>-<destination tile filter>-<neighbor direction>.png

Components:

• Directions: Bottom, BottomLeft, BottomRight, Top, TopLeft, TopRight.
• Filters: Terrain name, Feature name, or Terrain type (Land/Water).

Example: Cliff-Hills-Coast-Top.png will be drawn on a Hills tile if a Coast tile is at its Top position.

A standard mod directory should be located in the /mods folder. It typically contains two main subfolders:

• jsons/: Contains files that alter game object data. The file order should match the base JSON files.
• Images/: Contains game images, following the structure of the base image files.

To remove objects from the game, you must create a ModOptions.json file within the jsons subfolder.

Civilization icons are used for instant identification in the UI.

• Format: 100x100 pixels, white on a transparent background.
• Location: Place files in the Images/NationIcons folder of your repository.
• Legal Note: Ensure icons are from open sources or properly licensed. Credits should be listed in a Credits.md file.