From d51c0537cdca45771f42528eb8df18b439c30c8a Mon Sep 17 00:00:00 2001 From: yairm210 Date: Thu, 1 May 2025 23:58:31 +0300 Subject: [PATCH] Resolved #13274 - Added examples for all countables --- .../com/unciv/models/ruleset/unique/Countables.kt | 15 +++++++++++++++ .../src/com/unciv/app/desktop/UniqueDocsWriter.kt | 1 + docs/Modders/Unique-parameters.md | 14 ++++++++++++++ 3 files changed, 30 insertions(+) diff --git a/core/src/com/unciv/models/ruleset/unique/Countables.kt b/core/src/com/unciv/models/ruleset/unique/Countables.kt index ecfe100659..612d0fc141 100644 --- a/core/src/com/unciv/models/ruleset/unique/Countables.kt +++ b/core/src/com/unciv/models/ruleset/unique/Countables.kt @@ -5,6 +5,7 @@ import com.unciv.models.ruleset.unique.expressions.Expressions import com.unciv.models.ruleset.unique.expressions.Operator import com.unciv.models.stats.Stat import com.unciv.models.translations.equalsPlaceholderText +import com.unciv.models.translations.fillPlaceholders import com.unciv.models.translations.getPlaceholderParameters import com.unciv.models.translations.getPlaceholderText import org.jetbrains.annotations.VisibleForTesting @@ -37,6 +38,7 @@ enum class Countables( override val documentationHeader = "Integer constant - any positive or negative integer number" override fun matches(parameterText: String) = parameterText.toIntOrNull() != null override fun eval(parameterText: String, stateForConditionals: StateForConditionals) = parameterText.toIntOrNull() + override val example: String = "123" }, Turns("turns", shortDocumentation = "Number of turns played") { @@ -69,6 +71,8 @@ enum class Countables( return stateForConditionals.civInfo?.getHappiness() return stateForConditionals.getStatAmount(relevantStat) } + + override val example = "Science" override fun getKnownValuesForAutocomplete(ruleset: Ruleset) = Stat.names() private fun Iterable.niceJoin() = joinToString("`, `", "`", "`").run { val index = lastIndexOf("`, `") @@ -149,6 +153,8 @@ enum class Countables( override fun matches(parameterText: String, ruleset: Ruleset) = parameterText in ruleset.tileResources override fun eval(parameterText: String, stateForConditionals: StateForConditionals) = stateForConditionals.getResourceAmount(parameterText) + + override val example = "Iron" override fun getKnownValuesForAutocomplete(ruleset: Ruleset) = ruleset.tileResources.keys }, @@ -176,6 +182,7 @@ enum class Countables( engine.getErrorSeverity(parameterText, ruleset) override fun getKnownValuesForAutocomplete(ruleset: Ruleset) = emptySet() + override val example: String = "[Iron] + 2" override val documentationHeader = "Evaluate expressions!" override val documentationStrings = listOf( @@ -209,6 +216,14 @@ enum class Countables( open val documentationHeader get() = "`$text`" + (if (shortDocumentation.isEmpty()) "" else " - $shortDocumentation") + + open val example: String + get() { + if (noPlaceholders) return text + val placeholderParams = text.getPlaceholderParameters() + .map { UniqueParameterType.safeValueOf(it).docExample } + return text.fillPlaceholders(*placeholderParams.toTypedArray()) + } /** Leave this only for Countables without any parameters - they can rely on [matches] having validated enough */ open fun getErrorSeverity(parameterText: String, ruleset: Ruleset): UniqueType.UniqueParameterErrorSeverity? = null diff --git a/desktop/src/com/unciv/app/desktop/UniqueDocsWriter.kt b/desktop/src/com/unciv/app/desktop/UniqueDocsWriter.kt index 990a4f2409..d1da770c63 100644 --- a/desktop/src/com/unciv/app/desktop/UniqueDocsWriter.kt +++ b/desktop/src/com/unciv/app/desktop/UniqueDocsWriter.kt @@ -155,6 +155,7 @@ class UniqueDocsWriter { for (countable in Countables.entries) { if (countable.getDeprecationAnnotation() != null) continue newContent.appendLine("- ${countable.documentationHeader}") + newContent.appendLine(" - Example: `Only available `") // Sublist for (extraLine in countable.documentationStrings) { newContent.append(" - ") // Sublist newContent.appendLine(extraLine) diff --git a/docs/Modders/Unique-parameters.md b/docs/Modders/Unique-parameters.md index 09243e3f5c..1f6c76c9b6 100644 --- a/docs/Modders/Unique-parameters.md +++ b/docs/Modders/Unique-parameters.md @@ -341,25 +341,39 @@ Allowed values: [//]: # (Countables automatically generated BEGIN) - Integer constant - any positive or negative integer number + - Example: `Only available ` - `turns` - Number of turns played + - Example: `Only available ` - Always starts at zero irrespective of game speed or start era - `year` - The current year + - Example: `Only available ` - Depends on game speed or start era, negative for years BC - `Cities` - The number of cities the relevant Civilization owns + - Example: `Only available ` - `Units` - The number of units the relevant Civilization owns + - Example: `Only available ` - Stat name (`Production`, `Food`, `Gold`, `Science`, `Culture`, `Happiness` or `Faith`) + - Example: `Only available ` - Gets the stat *reserve*, not the amount per turn (can be city stats or civilization stats, depending on where the unique is used) - `Completed Policy branches` + - Example: `Only available ` - `[cityFilter] Cities` + - Example: `Only available ` - `[mapUnitFilter] Units` + - Example: `Only available ` - `[buildingFilter] Buildings` + - Example: `Only available ` - `Remaining [civFilter] Civilizations` + - Example: `Only available ` - `Owned [tileFilter] Tiles` + - Example: `Only available ` - Resource name - From [TileResources.json](3-Map-related-JSON-files.md#tileresourcesjson) + - Example: `Only available ` - Can be city stats or civilization stats, depending on where the unique is used - For example: If a unique is placed on a building, then the retrieved resources will be of the city. If placed on a policy, they will be of the civilization. - This can make a difference for e.g. local resources, which are counted per city. - Evaluate expressions! + - Example: `Only available ` - Expressions support arbitrary math operations, and can include other countables, when surrounded by square brackets. - For example, since `Cities` is a countable, and `[Melee] units` is a countable, you can have something like: `([[Melee] units] + 1) / [Cities]` (the whitespace is optional but helps readability) - Since on translation, the brackets are removed, the expression will be displayed as `(Melee units + 1) / Cities`