Unciv

https://github.com/yairm210/unciv
Admin
Unciv is an open-source, moddability-focused remake of Civilization V for Android and Desktop,...
Tokens:14,475
Snippets:94
Trust Score:8.5
License:MPL-2.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Create Desktop Run Configuration in Android Studio

Source: https://github.com/yairm210/unciv/blob/master/docs/Developers/Building-Locally.md

Instructions for manually creating a 'Desktop' run configuration in Android Studio. This is necessary if the configuration is missing after the initial project setup. It involves specifying the module, main class, and working directory, with optional VM options for memory and logging.

```text
Select Run > Edit configurations
Click "+" to add a new configuration
Choose "Application"
Name: "Desktop"
Module classpath: `Unciv.desktop.main` (or `Unciv.desktop` for older versions)
Main class: `com.unciv.app.desktop.DesktopLauncher`
Working directory: `$ProjectFileDir$/android/assets`
Optional VM options: `-Xmx4096m -Xms256m -XX:MaxMetaspaceSize=256m` or `-DnoLog=` / `-DonlyLog=`
```

--------------------------------

### Start Unciv Server with Java

Source: https://github.com/yairm210/unciv/blob/master/docs/Other/Multiplayer.md

Command to start the Unciv server from the command line. Requires Java JDK and UncivServer.jar to be present in the directory. The server will listen on the default port 8080.

```shell
java -jar UncivServer.jar
```

--------------------------------

### Generate Detekt Linting Reports

Source: https://github.com/yairm210/unciv/blob/master/docs/Developers/Building-Locally.md

Commands to generate HTML reports for code smells and linting issues using the Detekt CLI. Requires downloading the detekt-cli tool and specifying configuration files for warnings or errors.

```shell
# For warnings:
PATH/TO/DETEKT/detekt-cli --parallel --report html:detekt/reports.html --config .github/workflows/detekt_config/detekt-warnings.yml

# For errors:
PATH/TO/DETEKT/detekt-cli --parallel --report html:detekt/reports.html --config .github/workflows/detekt_config/detekt-errors.yml

# On Windows, replace detekt-cli with detekt-cli.bat
```

--------------------------------

### Build and Run Unciv Desktop Version (Linux/macOS/PowerShell)

Source: https://github.com/yairm210/unciv/blob/master/docs/Developers/Building-Locally.md

Commands to build a distributable JAR file and run the Unciv desktop application using Gradle in Linux, macOS, or Windows PowerShell terminals. Includes a one-time permission fix for Mac/Linux.

```shell
# For Mac/Linux, run this first if you encounter permission errors:
chmod +x ./gradlew

# To run the application:
./gradlew desktop:run

# To build a distributable JAR:
./gradlew desktop:dist
```

--------------------------------

### Configure Kotlin Code Style Indentation

Source: https://github.com/yairm210/unciv/blob/master/docs/Developers/Building-Locally.md

This guide provides the steps to configure the code style for Kotlin files in Android Studio, specifically setting the continuation indent to 4 spaces. This ensures consistent code formatting across the project.

```text
Settings > Editor > Code Style > Kotlin > Tabs and Indents > Continuation Indent: 4
```

--------------------------------

### Configure Unit Tests in Android Studio

Source: https://github.com/yairm210/unciv/blob/master/docs/Developers/Building-Locally.md

Steps to create a Gradle run configuration in Android Studio for executing and debugging Unciv's unit tests. This involves specifying the Gradle project, tasks, and test arguments.

```text
Run > Edit configurations.
Click "+" to add a new configuration.
Choose "Gradle" and name it, e.g., "Unit Tests".
Set "Gradle Project" to "Unciv".
Set "Tasks" to ":tests:test".
Set "Arguments" to "--tests \"com.unciv.*\"".
Click OK.
```

--------------------------------

### Get Unciv Java Server Help

Source: https://github.com/yairm210/unciv/blob/master/docs/Other/Multiplayer.md

This command displays the available command-line options and arguments for the Unciv Java server. It helps users understand how to configure server settings like port and file storage location.

```bash
java -jar UncivServer.jar --help
```

--------------------------------

### Example Translation Format in .properties

Source: https://github.com/yairm210/unciv/wiki/Translations,-mods,-and-modding-freedom-in-Open-Source

Demonstrates the key-value pair format used in Unciv's translation files, where the source text is separated from its translation by ' = '. Lines starting with '#' are treated as comments, facilitating notes for translators.

```properties
# This is a comment
A pleasure to meet you. = Siamo lieti di fare la vostra conoscenza.
Gold from trade routes = Oro dalle rotte commerciali

```

--------------------------------

### JSON Example for Adding a Cultural Library Building

Source: https://github.com/yairm210/unciv/wiki/JSON-files-for-mods

Demonstrates how to add a new building, 'Cultural Library', to Unciv using JSON. This example shows the use of nested objects for 'percentStatBonus', specifying bonuses for 'science' and 'culture' as integers.

```json
[
    {
        "name": "Cultural Library"
        "percentStatBonus" : {"science": 50, "culture": 50}
    }
]
```

--------------------------------

### Unciv Skin Configuration JSON Example

Source: https://github.com/yairm210/unciv/blob/master/docs/Modders/Creating-a-UI-skin.md

This JSON object defines a custom skin configuration for Unciv. It specifies global settings like baseColor and defaultVariantTint, and allows for detailed customization of individual UI elements through skinVariants. Each variant can override properties like image, foregroundColor, iconColor, alpha, and tint.

```json
{
    "baseColor": {"r":1,"g":0,"b":0,"a":1},
    "defaultVariantTint": {"r":1,"g":1,"b":1,"a":1},
    "skinVariants": {
        "MainMenuScreen/MenuButton": {
            "image": "MyCoolNewDesign",
            "foregroundColor": {"r": 0, "g": 0, "b": 1, "a": 1},
            "iconColor": {"r": 0, "g": 1, "b": 0, "a": 1}
        },
        "TechPickerScreen/TechButton": {
            "image": "MyCoolNewDesign",
            "alpha": 0.7
        },
        "WorldScreen/TopBar/ResourceTable": {
            "alpha": 0.8
        },
        "WorldScreen/UnitTable": {
            "tint": {"r": 1, "g": 0, "b": 0},
            "image": "WorldScreen/TopBar/ResourceTable",
            "alpha": 0.4
        },
        "WorldScreen/Minimap/Background": {
            "tint": {"r": 0.2, "g": 0.4, "b": 0.45, "a": 1}
        }
    }
}
```

--------------------------------

### Install Android SDK on Debian/Ubuntu/Mint

Source: https://github.com/yairm210/unciv/wiki/Building-locally-without-Android-Studio

Command to update package lists and install the Android SDK on Debian-based Linux distributions. This is a prerequisite if the Android SDK folder is not found.

```shell
sudo apt update && sudo apt install android-sdk
```

--------------------------------

### Configure Android SDK Build-Tools Version 35.0.0

Source: https://github.com/yairm210/unciv/blob/master/docs/Developers/Building-Locally.md

This section details how to manually set the Android SDK Build-Tools to version 35.0.0 within Android Studio. This is a solution for potential sync errors that may occur during the initial Gradle sync. It involves navigating through the SDK settings and selecting the specific version.

```text
File > Settings > Languages & Frameworks > Android SDK
Click "SDK Platforms"
Click "Android 16.0 ("Baklava")"
Click "SDK Tools"
Select "Show Package Details" in the bottom right
Choose version 35.0.0 under "Android SDK Build-Tools"
Click "Apply"
Restart Android Studio
```

--------------------------------

### Build and Run Unciv with Docker Compose

Source: https://github.com/yairm210/unciv/blob/master/README.md

This command builds the Docker image for Unciv using Docker Compose and then starts the containers. After execution, the game can be accessed via a VNC client at the specified URL.

```bash
$ docker compose build && docker compose up
```

--------------------------------

### Create Unciv launch script

Source: https://github.com/yairm210/unciv/blob/master/docs/Other/Installing-on-macOS.md

This script allows for easier execution of the Unciv JAR file, enabling the creation of shortcuts. It assumes the Unciv.jar file is in the same directory and requires a Java Runtime Environment.

```bash
#!/bin/bash
java -jar Unciv.jar
```

--------------------------------

### Build and Run Unciv on Windows with Gradle

Source: https://github.com/yairm210/unciv/wiki/Building-locally-without-Android-Studio

Commands to execute and build the Unciv project on a Windows system using Gradle. Assumes JDK 11 is installed and the project has been cloned or downloaded.

```shell
gradlew desktop:run
```

```shell
gradlew desktop:dist
```

--------------------------------

### Explore Map Tiles in Kotlin

Source: https://context7.com/yairm210/unciv/llms.txt

Provides examples for accessing and checking properties of map tiles, including terrain, features, resources, improvements, and units. Demonstrates how to get tile ownership, neighbors, distances, and yield statistics. Requires a valid Tile instance.

```kotlin
val tile = tileMap[Vector2(10f, 15f)]

// Terrain properties
tile.baseTerrain  // "Grassland", "Plains", "Desert", etc.
tile.getTerrainObject()
tile.terrainFeatures  // ["Forest"], ["Jungle", "Marsh"], []
tile.naturalWonder  // "Mount Fuji", null

// Resources and improvements
tile.resource  // "Iron", "Wheat", "Gold", null
tile.getTileResource()
tile.improvement  // "Farm", "Mine", "Trading Post", null
tile.improvementIsPillaged
tile.getTileImprovement()

// Units
val military = tile.militaryUnit  // MapUnit or null
val civilian = tile.civilianUnit  // MapUnit or null
tile.airUnits.forEach { airUnit -> /* ... */ }

// Ownership
val owner = tile.getOwner()  // Civilization or null
val city = tile.owningCity  // City that works this tile

// Neighbors and distances
tile.neighbors.forEach { neighbor ->
    println("Adjacent tile at ${neighbor.position}")
}
tile.getTilesInDistance(3)
tile.getTilesAtDistance(2)
val distance = tile.aerialDistanceTo(otherTile)

// Yields and stats
val tileStats = tile.stats.getTileStats(city, civ)
println("Food: ${tileStats.food}, Production: ${tileStats.production}")
val startingScore = tile.stats.getTileStartScore(minStatRatings)

// Terrain checks
if (tile.isLand) { /* ... */ }
if (tile.isWater) { /* ... */ }
if (tile.isCityCenter()) { /* ... */ }
tile.isExplored(civ)
tile.isVisible(civ)
tile.isImpassible()
```

--------------------------------

### Run Unciv Java Server with Custom Port and Folder

Source: https://github.com/yairm210/unciv/blob/master/docs/Other/Multiplayer.md

This command executes the Unciv Java server, allowing you to specify the network port and the directory for storing game files. Ensure you have a Java JDK installed and the UncivServer.jar file downloaded. The server performs simple file storage over HTTP and does not automatically clean up old game files.

```bash
java -jar UncivServer.jar -p 8080 -f /some/folder/
```

--------------------------------

### Run Pre-built Unciv Docker Image

Source: https://github.com/yairm210/unciv/blob/master/README.md

This command pulls and runs a pre-built Unciv Docker image from GitHub Container Registry. It starts the game in detached mode and makes it accessible via a VNC client.

```bash
$ docker run -d -p 6901:6901 -p 5901:5901 ghcr.io/yairm210/unciv
```

--------------------------------

### Run Unciv JAR file

Source: https://github.com/yairm210/unciv/blob/master/docs/Other/Installing-on-macOS.md

This command executes the Unciv game by running its JAR file. It requires a Java Runtime Environment (JRE) to be installed on the system. Updates require manual re-downloading of the JAR file.

```bash
java -jar Unciv.jar
```

--------------------------------

### Tileset Configuration JSON Example

Source: https://github.com/yairm210/unciv/blob/master/docs/Modders/Creating-a-custom-tileset.md

An example JSON configuration file for a custom tileset. This file defines various rendering properties, such as whether to use colors as base terrain, whether to use summary images, colors for unexplored and fog of war tiles, fallback tileset, and scaling options for tiles and specific tile types. It also includes rule variants for combining different tile elements.

```json
{
    "useColorAsBaseTerrain": "false",
    "useSummaryImages": "true",
    "unexploredTileColor": {"r":1,"g":1,"b":1,"a":1},
    "fogOfWarColor": {"r":1,"g":0,"b":0,"a":1},
    "fallbackTileSet": null,
    "tileScale":0.9,
    "tileScales": {
        "City center":1.2,
        "Citadel":1.5
    },
    "ruleVariants": {
        "Grassland+Forest": ["Grassland","ForestForGrassland"],
        "Grassland+Jungle+Dyes+Trading post": ["Grassland","JungleForGrasslandBack","Dyes+Trading post","JungleForGrasslandFront"]
    }
}
```

--------------------------------

### Define Custom Nation in JSON

Source: https://context7.com/yairm210/unciv/llms.txt

Provides an example of a Nations.json file, demonstrating how to define a custom civilization with its name, leader, unique bonuses, starting conditions, and other attributes. This JSON structure is used by the game to load custom nations.

```json
// Nations.json - Define a custom civilization
[
  {
    "name": "MyNation",
    "leaderName": "Great Leader",
    "adjective": ["MyNation"],
    "startIntroPart1": "Welcome, oh great leader!",
    "startIntroPart2": "Will you lead your people to glory?",
    "declaringWar": "You have forced my hand!",
    "attacked": "You dare attack us?",
    "defeated": "We are defeated...",
    "introduction": "Greetings, I am the leader of MyNation.",
    "neutralHello": "How are you?",
    "hateHello": "What do you want?",
    "tradeRequest": "It would be wise to accept this trade.",
    "outerColor": [255, 0, 0],
    "innerColor": [255, 255, 255],
    "uniqueName": "Custom Bonus",
    "uniques": [
      "[+1 Science] from every specialist [in all cities]",
      "Receive a free [Library] [in capital]",
      "[+10]% [Science] [in all cities]"
    ],
    "cities": ["Capital", "Second City", "Third City"],
    "spyNames": ["Agent 1", "Agent 2", "Agent 3"]
  }
]
```

--------------------------------

### Install Unciv using MacPorts

Source: https://github.com/yairm210/unciv/blob/master/docs/Other/Installing-on-macOS.md

This command installs Unciv using the MacPorts package manager. It does not require a pre-installed Java Development Kit (JDK) and is a straightforward method for macOS users.

```bash
sudo port install unciv
```

--------------------------------

### ADB Permissions Setup for Linux

Source: https://github.com/yairm210/unciv/blob/master/docs/Developers/Testing-Android-Builds.md

This section details the steps required to set up ADB permissions on Linux distributions like Mint to allow debugging on physical Android devices. It involves joining the 'plugdev' group and configuring udev rules based on the device's vendor ID.

```shell
groups
sudo usermod -a -G plugdev $USER
lsusb
sudo xed /etc/udev/rules.d/51-android.rules
# Example rule: SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", MODE="0666", GROUP="plugdev"
sudo udevadm control --reload-rules && sudo udevadm trigger
./gradlew --stop
```

--------------------------------

### Configure Android SDK Location in local.properties

Source: https://github.com/yairm210/unciv/wiki/Building-locally-without-Android-Studio

Configuration line to add to the 'local.properties' file to specify the Android SDK directory. This helps the build system locate the installed SDK.

```properties
sdk.dir = /path/to/android/sdk
```

--------------------------------

### Manage Game State with GameInfo API in Kotlin

Source: https://context7.com/yairm210/unciv/llms.txt

Demonstrates how to manage the central game state using the `GameInfo` API in Kotlin. This includes starting new games with setup parameters, accessing current game information like players, turns, and cities, progressing turns, checking for victory conditions, serializing the game state for saving, and cloning the game state for thread-safe multiplayer synchronization.

```kotlin
val gameSetupInfo = GameSetupInfo().apply {
    gameParameters = GameParameters().apply {
        difficulty = "Prince"
        speed = "Standard"
        noCityRazing = false
        oneCityChallenge = false
    }
    mapParameters = MapParameters().apply {
        mapSize = MapSizeNew(MapSize.Medium)
        mapType = MapType.Pangaea
    }
}

val gameInfo = GameStarter.startNewGame(gameSetupInfo)

// Accessing current state
val currentPlayer = gameInfo.getCurrentPlayerCivilization()
val turnNumber = gameInfo.turns
val allCities = gameInfo.getCities()
val civilizations = gameInfo.civilizations

// Turn progression (clones for thread safety)
gameInfo.nextTurn(progressBar = null)

// Victory checking
if (gameInfo.checkForVictory()) {
    val winner = gameInfo.civilizations.firstOrNull { it.victoryManager.hasWon }
    println("${winner?.civName} has won!")
}

// Serialization for save/load
val jsonString = json().toJson(gameInfo)
val loadedGame = json().fromJson(GameInfo::class.java, jsonString)

// Thread-safe cloning for multiplayer
val clonedGame = gameInfo.clone()
```

--------------------------------

### Manage Cities in Kotlin

Source: https://context7.com/yairm210/unciv/llms.txt

Shows how to manage city properties, construction queues, population, tile assignments, and resource production. Includes examples for specialized managers like religion and espionage, and city state changes. Requires a valid City instance.

```kotlin
val city = civ.cities.first()

// Basic information
println("${city.name} - Population: ${city.population.population}")
println("Capital: ${city.isCapital()}")
println("Health: ${city.health}/${city.getMaxHealth()}")

// Construction queue
city.cityConstructions.currentConstructionFromQueue
city.cityConstructions.addToQueue("Library")
city.cityConstructions.constructIfEnough()
city.cityConstructions.builtBuildings.contains("Monument")

// Instant purchases
if (civ.gold >= city.cityConstructions.getGoldCostOfCurrentConstruction()) {
    city.cityConstructions.purchaseConstruction("Library", queuePosition = 0,
        isFreeBuildingOrPurchase = false, isBuyForGold = true)
}

// Population and tile management
city.population.getFreePopulation()
city.workedTiles  // Tiles being worked by citizens
city.tilesInRange  // All tiles this city can work
city.population.autoAssignPopulation()
city.lockedTiles.add(tile.position)  // Manually lock a tile

// Resource production
val stats = city.cityStats.currentCityStats
println("Food: ${stats.food}, Production: ${stats.production}, Gold: ${stats.gold}")
city.getCityResources().forEach { (resource, amount) ->
    println("$resource: $amount")
}

// Specialized managers
city.religion.getMajorityReligion()
city.religion.religionThisIsTheHolyCityOf
city.espionage.getSpyAssignedToCity()
city.expansion.buyTile(tile)

// City state changes
city.puppetCity()
city.annexCity()
city.liberateCity(originalOwner)
```

--------------------------------

### Unciv Tileset Configuration Example (JSON)

Source: https://github.com/yairm210/unciv/wiki/Creating-a-custom-tileset

This JSON configuration allows customization of how Unciv renders tiles. It includes options for using base terrain colors, defining unexplored and fog of war colors, and specifying rule variants for complex tile compositions.

```json
{
    "useColorAsBaseTerrain": "false",
    "unexploredTileColor": {"r":1,"g":1,"b":1,"a":1},
    "fogOfWarColor": {"r":1,"g":0,"b":0,"a":1},
    "ruleVariants": {
        "Grassland+Forest": ["Grassland","ForestForGrassland"],
        "Grassland+Jungle+Dyes+Trading post": ["Grassland","JungleForGrasslandBack","Dyes+Trading post","JungleForGrasslandFront"]
    }
}
```

--------------------------------

### Connect to External Unciv Server

Source: https://github.com/yairm210/unciv/blob/master/docs/Other/Multiplayer.md

Configuration for connecting to a hosted Unciv server from another device or over the internet. Requires the server's IP address and the forwarded port.

```plaintext
Server address: http://<your-real-ip-adress>:<your-forwarded-port>
Example: http://203.0.113.1:1234
```

--------------------------------

### Manage Main Gameplay Screen (WorldScreen) in Kotlin

Source: https://context7.com/yairm210/unciv/llms.txt

Provides examples for creating and interacting with the main WorldScreen in Unciv. It covers initializing the screen with game data, accessing UI components like map and bars, navigating the map, selecting units, updating the UI, handling the 'next turn' action, and managing AutoPlay mode. Dependencies include gameInfo and WorldScreen specific components.

```kotlin
// Create world screen for active game
val worldScreen = WorldScreen(gameInfo, viewingCiv = gameInfo.getCurrentPlayerCivilization())
game.pushScreen(worldScreen)

// Access UI components
val mapHolder = worldScreen.mapHolder
val bottomBar = worldScreen.bottomUnitTable
val topBar = worldScreen.worldScreenTopBar

// Pan to location
worldScreen.mapHolder.setCenterPosition(tile.position)
worldScreen.mapHolder.selectedTile = tile

// Select unit
val unit = tile.militaryUnit
if (unit != null) {
    worldScreen.bottomUnitTable.selectUnit(unit)
}

// Update UI
worldScreen.shouldUpdate = true
worldScreen.update()

// Next turn
worldScreen.nextTurnButton.onClick {
    game.launchOnGLThread {
        gameInfo.nextTurn()
        worldScreen.resetAutoPlay()
    }
}

// Check state
if (worldScreen.isPlayersTurn) {
    // Allow player actions
    worldScreen.bottomUnitTable.enable()
} else {
    // Wait for other players
    worldScreen.bottomUnitTable.disable()
}

// AutoPlay mode
worldScreen.autoPlay = AutoPlay(worldScreen, gameInfo.getCurrentPlayerCivilization())
worldScreen.autoPlay.startAutoPlay()
```

--------------------------------

### Manage Map Units in Kotlin

Source: https://context7.com/yairm210/unciv/llms.txt

Demonstrates how to interact with MapUnit objects for managing unit health, movement, combat, promotions, and actions. Includes examples of automation and ability checks. Requires a valid MapUnit instance.

```kotlin
val unit = tile.militaryUnit!!

// Basic properties
println("${unit.name} of ${unit.civ.civName}")
println("Health: ${unit.health}/100")
println("Movement: ${unit.currentMovement}/${unit.getMaxMovement()}")

// Movement and pathfinding
if (unit.movement.canMoveTo(targetTile)) {
    unit.movement.moveToTile(targetTile)
}
val path = unit.movement.getShortestPath(destinationTile)
unit.movement.headTowards(destinationTile)

// Combat
if (unit.canAttack()) {
    val enemyUnit = targetTile.militaryUnit!!
    Battle.attack(MapUnitCombatant(unit), MapUnitCombatant(enemyUnit))
}
unit.baseUnit.strength  // Melee strength
unit.baseUnit.rangedStrength  // Ranged strength

// Promotions
unit.promotions.XP += 10
if (unit.promotions.canBePromoted()) {
    unit.promotions.addPromotion("Shock I", isFree = false)
}
val availablePromotions = unit.promotions.getAvailablePromotions()

// Actions
unit.fortify()
unit.fortifyUntilHealed()
unit.action = UnitActionType.Sleep.value
unit.destroy()

// Automation
unit.automated = true
UnitAutomation.automateUnitMoves(unit)

// Abilities and checks
if (unit.hasUnique(UniqueType.CanFoundCity)) {
    city = civ.addCity(unit.currentTile.position)
}
unit.cache.canPillage
unit.cache.canEnterForeignTerrain
unit.isEmbarked()
```

--------------------------------

### Uniques Structure Example

Source: https://github.com/yairm210/unciv/blob/master/docs/Modders/Mod-file-structure/1-Overview.md

Illustrates the basic structure of a Unique string in Unciv, showing a combination of an effect with a conditional trigger. This example demonstrates how a 'Gold' bonus is applied only when a city has a garrison.

```json
"uniques":["[+1 Gold] <with a garrison>"]
```

--------------------------------

### Unciv Translation Key-Value Pair Example

Source: https://github.com/yairm210/unciv/blob/master/docs/Other/Translating.md

Demonstrates the format for a translation entry in a .properties file. The key is on the left of the equals sign, and the translated value is on the right. Case sensitivity is important for both keys and filenames.

```properties
The Borg = The Borg
```

--------------------------------

### Check Local Server Connection in Unciv

Source: https://github.com/yairm210/unciv/blob/master/docs/Other/Multiplayer.md

Configuration within Unciv to verify the locally hosted server is running correctly. It involves setting the server address to localhost and checking the connection.

```plaintext
Main Menu -> Options -> Multiplayer
Server address: http://localhost:8080
Click 'Check connection to server'
```

--------------------------------

### NextTurnAutomation: Process AI Turn Decisions (Kotlin)

Source: https://context7.com/yairm210/unciv/llms.txt

This snippet explains the functionality of `NextTurnAutomation`, which handles all AI decisions for a civilization's turn. It outlines the various components automated, including city management, unit actions, research, policy adoption, diplomacy, and resource management. It also shows examples of manual city automation.

```kotlin
// Process AI turn for a civilization
NextTurnAutomation.automateCivMoves(civ)

// Components automated:
// - City management (construction, population, tiles)
// - Unit movement and combat
// - Technology research
// - Policy adoption
// - Diplomacy decisions
// - Gold management
// - Unit production

// Manual city automation
civ.cities.forEach { city ->
    city.cityConstructions.chooseNextConstruction()
    city.population.autoAssignPopulation()
}
```

--------------------------------

### TileMap Operations in Kotlin

Source: https://context7.com/yairm210/unciv/llms.txt

Demonstrates how to interact with the TileMap for accessing tiles, iterating, performing distance and area queries, and pathfinding. It also shows how to access map properties and manage starting locations. Requires a gameInfo object with a tileMap and a unit object.

```kotlin
val tileMap = gameInfo.tileMap

// Accessing tiles
val tile = tileMap[Vector2(10f, 15f)]
val tile2 = tileMap.get(x = 5, y = 7)
val tileOrNull = tileMap.getIfExists(Vector2(100f, 100f))

// Iterating all tiles
tileMap.values.forEach { tile ->
    if (tile.resource != null) {
        println("Resource ${tile.resource} at ${tile.position}")
    }
}

// Distance and area queries
val tilesInRadius = tileMap.getTilesInDistance(centerPosition, radius = 3)
val tilesAtDistance = tileMap.getTilesAtDistance(centerPosition, distance = 2)
val rectangle = tileMap.getTilesInRectangle(
    topLeft = Vector2(0f, 0f),
    bottomRight = Vector2(10f, 10f)
)

// Pathfinding
val pathToDestination = unit.movement.getShortestPath(destinationTile)
val distanceToDestination = unit.movement.getDistanceToTiles()

// Map properties
tileMap.mapParameters.mapSize
tileMap.mapParameters.mapType  // Pangaea, Continents, etc.
tileMap.continentSizes  // Map of continent ID to size
tileMap.naturalWonders  // Set of natural wonders on this map

// Starting locations (used in map generation/editing)
tileMap.addStartingLocation("Babylon", tile)
val startingLocations = tileMap.startingLocationsByNation
```

--------------------------------

### Unciv Translation Override Example

Source: https://github.com/yairm210/unciv/blob/master/docs/Other/Translating.md

Shows how to override a base game translation. Instead of keeping the default value, you provide your own translation on the right side of the equals sign.

```properties
gold = credits ( <- in your language)
NOT:gold = gold ( <- in your language)
```

--------------------------------

### Unciv Extra Translation Example (Traditional Chinese)

Source: https://github.com/yairm210/unciv/blob/master/docs/Other/Translating.md

An example of 'extra translating' which aims to make translations more contextually appropriate for the game. This snippet shows a Traditional Chinese translation that is more elaborate than a direct word-for-word translation.

```properties
Your warmongering ways are unacceptable to us. = 即使在野蠻的荒土世界，窮兵黷武的行徑還是無法容忍的！
```

--------------------------------

### Connect to Unciv Server on Port 80

Source: https://github.com/yairm210/unciv/blob/master/docs/Other/Multiplayer.md

Specific configuration for connecting to an Unciv server when it has been set up to use port 80, which is the default HTTP port. This simplifies the URL as the port number is omitted.

```plaintext
Server address: http://<your-real-ip>
Example: http://203.0.113.1
```

--------------------------------

### Manual Translation Template Addition

Source: https://github.com/yairm210/unciv/wiki/Translating

When new UI elements are created with hardcoded strings (e.g., using `.toLabel()`), these strings need to be manually added to the `template.properties` file. A common example is adding a line like `Hello world = ` to the properties file.

```properties
Hello world = 
```

--------------------------------

### JSON Structure for Unciv Units

Source: https://github.com/yairm210/unciv/wiki/JSON-files-for-mods

Illustrates the basic JSON format for defining units in Unciv. Each unit is represented as an object within a list, with properties like 'name', 'cost', and 'promotions'. The 'promotions' attribute is a list of strings.

```json
[
    {
        "name": "Warrior",
        "cost": 16
    },
    {
        "name": "Spearman",
        "cost": 24,
        "promotions": ["Shock I", "Drill I"]
    }
]
```

--------------------------------

### Example JSON Priorities Definition

Source: https://github.com/yairm210/unciv/blob/master/docs/Modders/Mod-file-structure/2-Civilization-related-JSON-files.md

This JSON snippet demonstrates a valid 'priorities' definition within a personality. It maps policy branches to integer values, indicating the AI's focus on each branch for a preferred victory type. Branches not listed default to a priority of 0.

```json
"priorities": {
    "Tradition": 30,
    "Liberty": 20,
    "Honor": 10
}
```

--------------------------------

### Yield Statistics Example in JSON

Source: https://github.com/yairm210/unciv/wiki/Map-related-JSON-files

Illustrates how yield statistics (production, food, gold, science, culture, happiness, faith) are represented in JSON for game elements. It shows both general stats and specialized stats applied through an 'improvementStats' sub-object.

```json
{
	"gold": 2,
	"improvement": "Quarry",
	"improvementStats": {"gold": 1,"production": 1}
}
```

--------------------------------

### Enable Unciv Logging via ADB

Source: https://github.com/yairm210/unciv/blob/master/docs/Developers/Testing-Android-Builds.md

This command allows enabling debug logging for Unciv on an Android device using the Android Debug Bridge (ADB). It starts the Unciv application with a specific intent extra to force debug logging to be true, even in release builds. This is useful for debugging store versions of the application.

```bash
adb shell am start com.unciv.app/com.unciv.app.AndroidLauncher --ez debugLogging true
```

--------------------------------

### Example Priorities Definition JSON

Source: https://github.com/yairm210/unciv/blob/master/docs/Modders/Mod-file-structure/2-Civilization-related-JSON-files.md

This JSON object defines the priority of policy branches for AI-controlled civilizations. It maps victory types (e.g., 'Cultural', 'Scientific') to integer values, influencing the AI's decision-making process when choosing policy branches. Higher values indicate a stronger preference.

```json
"priorities": {
"Neutral": 0,
"Cultural": 10,
"Diplomatic": 0,
"Domination": 0,
"Scientific": 10
}
```

--------------------------------

### JSON Format Disadvantages for Translations

Source: https://github.com/yairm210/unciv/wiki/Translations,-mods,-and-modding-freedom-in-Open-Source

Illustrates why JSON is considered less suitable for human-readable translation files. The example highlights how a single missing quote can render the entire file unreadable, posing challenges for amateur translators.

```json
{
  "DIPLOMACY_GREETING": "Siamo lieti di fare la vostra conoscenza."
  "TRADE_ROUTE_GOLD": "Gold from trade routes +[amount]%"
}
```

--------------------------------

### Configure Texture Packer Settings (JSON)

Source: https://github.com/yairm210/unciv/blob/master/docs/Modders/Images-and-Audio.md

Defines the settings for Unciv's built-in texture packer. This JSON file controls aspects like maximum texture dimensions, padding, and filtering methods for image atlases. It uses settings compatible with Gdx TexturePacker.Settings.

```json
{
	"fast": true,
	"combineSubdirectories": true,
	"maxWidth": 2048,
	"maxHeight": 2048,
	"paddingX": 8,
	"paddingY": 8,
	"duplicatePadding": true,
	"filterMin": "MipMapLinearLinear",
	"filterMag": "MipMapLinearLinear"
}
```

--------------------------------

### UncivGame: Manage Game State, Navigation, and Resources (Kotlin)

Source: https://context7.com/yairm210/unciv/llms.txt

This snippet demonstrates how to interact with the `UncivGame` singleton to manage application state, navigate between screens, load games, access global settings, control music, manage files, and handle multiplayer interactions. It also shows how to access the current game information and perform translations.

```kotlin
val game = UncivGame.Current

// Screen navigation
game.pushScreen(WorldScreen(gameInfo))
game.popScreen()
game.replaceCurrentScreen(MainMenuScreen())
game.resetToMainMenu()

// Load game
game.loadGame(gameInfo, autoPlay = false)

// Access global resources
val settings = game.settings
settings.tileSet = "FantasyHex"
settings.language = "English"
settings.save()

// Music control
game.musicController.chooseTrack(
    mood = MusicMood.War,
    flags = MusicTrackChooserFlags.setSelectNone
)
game.musicController.pause()
game.musicController.resume()

// File management
val saves = game.files.getSaves()
val autosaves = game.files.getAutosaves()
game.files.requestPermissionsAndSaveGame(gameInfo)

// Multiplayer
game.onlineMultiplayer.games.forEach { multiplayerGame ->
    println("Game: ${multiplayerGame.name}")
}

// Current game state
val currentGame = game.gameInfo
val worldScreen = game.worldScreen

// Translations
"Hello World".tr()  // Translate to current language
"Waiting for [civName]".tr(civName = "Babylon")
```

--------------------------------

### Build and Run Unciv on Linux/Mac OS with Gradle

Source: https://github.com/yairm210/unciv/wiki/Building-locally-without-Android-Studio

Commands to execute and build the Unciv project on Linux or macOS using Gradle. Requires appropriate permissions for the gradlew script.

```shell
./gradlew desktop:run
```

```shell
./gradlew desktop:dist
```

--------------------------------

### Create Custom UI Screen with BaseScreen in Kotlin

Source: https://context7.com/yairm210/unciv/llms.txt

Demonstrates how to create a custom screen by extending the BaseScreen class. It shows how to set up a UI layout using LibGDX Scene2D, add widgets like labels and buttons with event listeners, and configure global keyboard shortcuts for navigation. This requires an active game instance and adherence to the BaseScreen's lifecycle methods.

```kotlin
class MyCustomScreen : BaseScreen() {
    private lateinit var contentTable: Table

    init {
        // Create UI using LibGDX Scene2D
        contentTable = Table()
        contentTable.defaults().pad(10f)

        // Add widgets
        contentTable.add("Welcome to My Screen".toLabel()).row()

        val button = "Click Me".toTextButton()
        button.onClick {
            println("Button clicked!")
        }
        contentTable.add(button).row()

        // Center table on stage
        contentTable.setFillParent(true)
        stage.addActor(contentTable)

        // Add keyboard shortcuts
        globalShortcuts.add(KeyboardBinding.Back) {
            game.popScreen()
        }

        globalShortcuts.add(KeyboardBinding.Menu) {
            game.pushScreen(MainMenuScreen())
        }
    }

    override fun render(delta: Float) {
        super.render(delta)
        // Additional per-frame rendering
    }

    override fun resize(width: Int, height: Int) {
        super.resize(width, height)
        // Handle window resize
        contentTable.setSize(width.toFloat(), height.toFloat())
    }

    override fun dispose() {
        super.dispose()
        // Clean up resources
    }
}

// Using screens
val game = UncivGame.Current
game.pushScreen(MyCustomScreen())  // Add to stack
game.replaceCurrentScreen(AnotherScreen())  // Replace current
game.popScreen()  // Go back
```

--------------------------------

### Build and Run Unciv with Docker (Standalone)

Source: https://github.com/yairm210/unciv/blob/master/README.md

This command builds a standalone Docker image for Unciv and then runs it as a detached container, exposing the necessary ports. The game is then accessible through a VNC client.

```bash
$ docker build . -t unciv && docker run -d -p 6901:6901 -p 5901:5901 unciv
```

--------------------------------

### Grant Execute Permissions to Gradle Wrapper

Source: https://github.com/yairm210/unciv/wiki/Building-locally-without-Android-Studio

A one-time command to grant execute permissions to the Gradle wrapper script on Linux or macOS systems. This is necessary if 'Permission denied' or 'Command not found' errors occur.

```shell
chmod +x ./gradlew
```

--------------------------------

### Building Android APK with Gradle

Source: https://github.com/yairm210/unciv/blob/master/docs/Developers/Testing-Android-Builds.md

This command line instruction demonstrates how to build a debug APK for the Android version of Unciv using Gradle. The resulting APK can be found in the specified output directory.

```shell
./gradlew android:assembleDebug
```

--------------------------------

### Technology: Interact with Tech Tree System (Kotlin)

Source: https://context7.com/yairm210/unciv/llms.txt

This snippet shows how to access and manipulate individual technologies within the game's tech tree. It covers retrieving technology details, checking prerequisites, calculating costs, initiating research, adding technologies instantly, and querying researched or upcoming technologies.

```kotlin
val tech = ruleset.technologies["Writing"]!!

// Properties
println("Name: ${tech.name}")
println("Cost: ${tech.cost}")
println("Era: ${tech.era()}")
println("Column: ${tech.column.columnNumber}")
println("Row: ${tech.row}")
println("Quote: ${tech.quote}")

// Prerequisites
tech.prerequisites().forEach { prereqTech ->
    println("Requires: ${prereqTech.name}")
}

// Cost calculation with game speed
val actualCost = tech.cost(gameSpeed = ruleset.speeds["Standard"]!!)

// Research
if (civ.tech.canBeResearched(tech.name)) {
    civ.tech.currentTechnologyName() = tech.name
}

// Add technology (instant)
civ.tech.addTechnology(tech.name, notify = true)

// Check if researched
if (civ.tech.isResearched("Writing")) {
    println("Writing is researched!")
}

// Technologies to research next
val techs = civ.tech.techsToResearch()
techs.forEach { nextTech ->
    println("Can research: ${nextTech.name}")
}
```

--------------------------------

### Manage Online Multiplayer Games in Kotlin

Source: https://context7.com/yairm210/unciv/llms.txt

Shows how to interact with the online multiplayer API to manage games. This includes creating new games, joining existing ones, downloading and loading games, updating game state after a turn, resigning, kicking players, and listing available multiplayer games.

```kotlin
val multiplayer = UncivGame.Current.onlineMultiplayer

// Create new multiplayer game
multiplayer.createGame(gameInfo)
println("Game created with ID: ${gameInfo.gameId}")

// Join existing game
multiplayer.addGame(gameId = "abc123", gameName = "Epic Game")

// Download and load multiplayer game
multiplayer.downloadGame(gameId = "abc123") { result ->
    when (result) {
        is OnlineMultiplayerGameResult.Success -> {
            val gameInfo = result.gameInfo
            game.loadGame(gameInfo)
        }
        is OnlineMultiplayerGameResult.Error -> {
            println("Error: ${result.message}")
        }
    }
}

// Update game after taking turn
multiplayer.updateGame(gameInfo) { result ->
    when (result) {
        is OnlineMultiplayerGameResult.Success ->
            println("Turn uploaded successfully")
        is OnlineMultiplayerGameResult.Error ->
            println("Upload failed: ${result.message}")
    }
}

// Check if it's user's turn
if (gameInfo.isUsersTurn()) {
    // Enable turn controls
    worldScreen.nextTurnButton.enable()
}

// Resign from game
multiplayer.resignPlayer(
    game = multiplayerGame,
    playerCivName = "Babylon"
)

// Kick player (host only)
multiplayer.kickPlayer(
    game = multiplayerGame,
    playerCivName = "Rome"
)

// Get all multiplayer games
val games = multiplayer.games
games.forEach { game ->
    println("${game.name}: Turn ${game.preview?.turns}")
}
```

--------------------------------

### Create Popups and Dialogs in Kotlin

Source: https://context7.com/yairm210/unciv/llms.txt

Illustrates various ways to create and display popup dialogs within the Unciv application, including confirmation prompts, custom dialogs with added widgets, text input requests, number input requests, and non-blocking toast notifications. These popups are typically associated with a screen and provide user feedback or input mechanisms.

```kotlin
// Simple confirmation popup
ConfirmPopup(
    screen = worldScreen,
    question = "Are you sure you want to delete this save?",
    confirmText = "Delete",
    restoreDefault = { /* cancelled */ }
) {
    // User confirmed
    UncivFiles.deleteSave(saveGame)
}.open()

// Custom popup
val popup = Popup(worldScreen)
popup.addGoodSizedLabel("Hello World").row()
popup.addButton("OK") { popup.close() }
popup.open()

// Ask for text input
AskTextPopup(
    screen = worldScreen,
    label = "Enter city name:",
    defaultText = "New City"
) { cityName ->
    city.name = cityName
}.open()

// Ask for number input
AskNumberPopup(
    screen = worldScreen,
    label = "Enter amount of gold:",
    defaultValue = 100,
    minValue = 0,
    maxValue = 1000
) { amount ->
    civ.addGold(amount)
}.open()

// Toast notification (non-blocking)
ToastPopup("Turn complete!", worldScreen)
```

--------------------------------

### Pantheon Cost Formula

Source: https://github.com/yairm210/unciv/blob/master/docs/Modders/Mod-file-structure/5-Miscellaneous-JSON-files.md

Calculates the cost to found a pantheon. It includes a base cost adjusted by the number of civilizations that already have a religion and a growth factor.

```text
pantheonBase + CivsWithReligion * pantheonGrowth
```

--------------------------------

### Manage Rulesets and Mods in Kotlin

Source: https://context7.com/yairm210/unciv/llms.txt

Demonstrates how to load, retrieve, combine, and validate rulesets and mods using the RulesetCache singleton. This includes fetching base rulesets, merging mods, checking compatibility, and listing available mods. Reloading is also supported.

```kotlin
// Initial loading (done at startup)
RulesetCache.loadRulesets(printOutput = true)

// Get vanilla ruleset
val vanilla = RulesetCache.getVanillaRuleset()

// Get specific base ruleset
val civVGods = RulesetCache["Civ V - Gods & Kings"]!!

// Combine base ruleset with mods
val gameRuleset = RulesetCache.getComplexRuleset(
    mods = linkedSetOf("DeCiv Redux", "Better AI", "More Buildings"),
    optionalBaseRuleset = "Civ V - Vanilla"
)

// Validate mod combination before game start
val (ruleset, errors) = RulesetCache.checkCombinedModLinks(
    mods = settings.gameParameters.mods,
    baseRuleset = settings.gameParameters.baseRuleset
)

if (errors.isNotEmpty()) {
    errors.forEach { error -> println("Mod error: $error") }
    throw UncivShowableException("Mod compatibility issues detected")
}

// Get all available mods
val availableMods = RulesetCache.values.filter { !it.modOptions.isBaseRuleset }
availableMods.forEach { mod ->
    println("${mod.name}: ${mod.getSummary()}")
}

// Reload after installing new mods
RulesetCache.loadRulesets()
```

--------------------------------

### Control Civilization with Civilization API in Kotlin

Source: https://context7.com/yairm210/unciv/llms.txt

Illustrates how to manage individual civilizations (player or AI) using the `Civilization` API in Kotlin. This covers technology research, adopting social policies, managing resources and economy, handling diplomacy (war, peace, open borders), interacting with cities and units, tracking victory progress, and checking civilization properties like human-controlled status, city-state, or defeated state.

```kotlin
val civ = gameInfo.getCivilization("Babylon")

// Technology research
civ.tech.addTechnology("Writing", notify = true)
if (civ.tech.isResearched("Pottery")) {
    println("Pottery unlocked!")
}
civ.tech.currentTechnologyName() = "Philosophy"
civ.tech.addScience(25)

// Social policies
civ.policies.adopt(policy = ruleset.policies["Tradition"]!!, force = true)
civ.policies.addCulture(50)

// Resources and economy
civ.addGold(500)
civ.gold -= 200
val resources = civ.getCivResources()
val happiness = civ.stats.happiness

// Diplomacy
val rome = gameInfo.getCivilization("Rome")
if (civ.isAtWarWith(rome)) {
    civ.diplomacy[rome.civName]?.makePeace()
}
civ.diplomacy[rome.civName]?.hasOpenBorders()

// Cities and units
civ.cities.forEach { city ->
    println("${city.name}: Pop ${city.population.population}")
}
civ.units.getCivUnits().filter { it.baseUnit.isMilitary() }

// Victory progress
civ.victoryManager.getVictoryTypeAchieved()
civ.victoryManager.hasWon

// Checking properties
if (civ.isHuman()) { /* Enable UI */ }
if (civ.isCityState()) { /* City-state specific logic */ }
if (civ.isDefeated()) { /* Handle elimination */ }
```

--------------------------------

### Ruleset Management in Kotlin

Source: https://context7.com/yairm210/unciv/llms.txt

Covers loading game rulesets, accessing specific game objects like units, buildings, and technologies, browsing available content, and handling complex rulesets with mods. Also includes validating mod compatibility and reloading rulesets. Requires access to RulesetCache.

```kotlin
// Load base ruleset
val ruleset = RulesetCache.getVanillaRuleset()

// Access specific game objects
val spearman = ruleset.units["Spearman"]!!
val library = ruleset.buildings["Library"]!!
val writing = ruleset.technologies["Writing"]!!
val babylon = ruleset.nations["Babylon"]!!

// Browse available content
ruleset.nations.values.filter { it.isMajorCiv() }
    .forEach { nation -> println(nation.name) }

ruleset.units.values.filter { it.unitType.isMilitary() }
    .forEach { unit -> println("${unit.name}: ${unit.strength} strength") }

ruleset.buildings.values
    .filter { it.hasUnique(UniqueType.Unbuildable) }

// Complex rulesets with mods
val modList = linkedSetOf("DeCiv Redux", "Civilization VI Units")
val modRuleset = RulesetCache.getComplexRuleset(
    mods = modList,
    optionalBaseRuleset = "Civ V - Vanilla"
)

// Validate mod compatibility
val (combinedRuleset, errorList) = RulesetCache.checkCombinedModLinks(
    mods = modList,
    baseRuleset = "Civ V - Vanilla"
)
if (errorList.isNotEmpty()) {
    println("Mod errors: ${errorList.joinToString()}")
}

// Reload rulesets (after installing new mods)
RulesetCache.loadRulesets(printOutput = true)
```

--------------------------------

### Custom Mod Directory Structure

Source: https://context7.com/yairm210/unciv/llms.txt

Illustrates the required directory structure for creating custom mods. This includes placing JSON definition files, image assets, and other mod-specific files in their designated locations within the 'Mods' folder.

```bash
# Mod directory structure
Mods/
  MyCustomMod/
    jsons/
      Nations.json
      Buildings.json
      Units.json
      Technologies.json
      TileImprovements.json
      TileResources.json
      Terrains.json
      Policies.json
    Images/
      NationIcons/
      UnitIcons/
      BuildingIcons/
      TileIcons/
    game.atlas
    game.png
```
Tokens:
Raw