Appendix: Config Formats Reference

Summary

To be completed.

Configs

To be completed.

Config Expressions

This section explains the purpose, syntax, default and edge-case behaviors of "config expressions" used in CWT config files (.cwt) and extension capabilities, helping mod authors write configs correctly.

Basic concepts and scope

• Definition: a config expression is a structured syntax inside string fields of configs to describe the value shape or matching pattern.
• Families:
  • Schema expressions: declare the value shape for RHS.
  • Data expressions: parse data types or dynamic fragments.
  • Template expressions (data-driven): patterns concatenating constants and dynamic fragments.
  • Cardinality expressions: declare occurrence ranges and strict/relaxed checks.
  • Location expressions: locate resources such as images and localisations.

---

Schema expressions

Describe the allowed value shapes at the right-hand side (often used by data types or placeholders in .cwt).

Supported forms:

• Constant: a raw string without '$'.
• Type: starts with a single '$', such as $any, $int (empty name is allowed).
• Constraint: starts with $$, such as $$custom (empty name is allowed).
• Enum: starts with $enum: and ends with $, such as $enum:ship_size$.
• Template: contains paired $...$ segments, the other parts are treated as constants, e.g. a $x$ b $y$.

Defaults and edge cases:

• Odd number of '$': treated as an invalid template and handled as a constant.
• Both ends have '$': prefer Template over Type ($any$ -> Template, pattern is *).
• Enum embedded in a larger string: the whole becomes a Template (e.g. prefix $enum:ship_size$ suffix).
• Escaped dollar \$: does not participate in placeholders and is not replaced by *. If only escaped dollars appear, it is not a template and is handled as a constant.
• Template pattern: replace every unescaped $...$ segment with *.

Examples:

$int             # type
$$custom         # constraint
$enum:class$     # enum
a $x$ b $y$      # template (pattern: "a * b *")
a \$x\$ b       # has escaped dollars, not a template, treated as constant

Pitfalls:

• A single '$' (or any odd count) does not form a parameter placeholder; the whole is treated as constant.
• $...$ inside a template must be paired and unescaped; otherwise it is not a parameter position.

---

Data expressions

Describe the shapes for keys/values in configs. It can be a constant or a dynamic fragment driven by configs (e.g. value[...], enum[...], scope[...], icon[...], <definition>).

Key points:

• Key/value context: parsing distinguishes key (isKey=true) and value (isKey=false).
• Types: resolve into concrete types such as int, float, scalar, enum[...], scope[...], <type_key>, etc.
• Extended metadata: may carry numeric ranges or case policies depending on type (e.g. int[-5..100], float[-inf..inf], ignoreCase).

Examples (excerpt):

count = int
acceleration = float
class = enum[shipsize_class]
who = scope[country]
for_ship = <ship_size>
pre_<opinion_modifier>_suf

Note: this document does not enumerate all base types and forms; follow the conventions defined here.

---

Template expressions (data-driven)

Constructed by concatenating ordered "snippets": constant snippets + dynamic snippets (defined by dynamic configs of data expressions such as value[...]/enum[...]/scope[...]/icon[...]/<...>).

Defaults and constraints:

• No whitespace: if any whitespace appears, it is an invalid template.
• Snippet cardinality: a single snippet (pure constant or pure dynamic) does not constitute a template.
• Matching strategy: split using all dynamic configs (those with both prefix and suffix) with a "leftmost-earliest" strategy.

Examples:

job_<job>_add
xxx_value[anything]_xxx   # roughly equals a wide regex like a_.*_b
a_enum[weight_or_base]_b

Pitfalls:

• When a constant snippet is immediately followed by something that looks like a config name, prefer correct recognition of dynamic configs to avoid treating "symbol + config-name" as a single constant.
• If whitespace is needed, use a more appropriate matcher (e.g. ANT/regex).

---

Cardinality expressions

Declare the allowed occurrence count range, supporting relaxed checks and an infinite upper bound.

Format:

min..max           # e.g. 0..1, 1..inf
~min..max          # below min produces warnings only (relaxed)
min..~max          # above max produces warnings only (relaxed)

Defaults and edge cases:

• Negative min: clamped to 0.
• max is inf (case-insensitive): unlimited.
• No .. separator: treated as invalid and no constraint is produced.
• min > max: treated as invalid and no constraint is produced.

Examples (from comment conventions):

## cardinality = 0..1
## cardinality = 0..inf
## cardinality = ~1..10

---

Location expressions (resource lookup)

Locate target resources (images / localisations). If $ appears in location, it denotes a placeholder and is typically substituted later (e.g. with definition names or attribute values).

Defaults and edge cases:

• Placeholder count: at most one is recommended; if multiple exist, all placeholders are replaced.

Image location expressions

Syntax and conventions:

• Use | to separate arguments: <location>|<args...>.
• Arguments starting with $ specify name paths (comma-separated) to substitute the placeholder; stored as namePaths.
• Other arguments specify frame paths (comma-separated) for sprite frames; stored as framePaths.
• When duplicate arguments of the same kind appear (all starting with $, or all not starting with $), the later one overrides the earlier ones.

Examples:

gfx/interface/icons/modifiers/mod_$.dds
gfx/interface/icons/modifiers/mod_$.dds|$name
GFX_$
icon
icon|p1,p2

Note: icon can resolve to a file path, a sprite name, or a definition; for a definition it resolves to its most relevant image.

Localisation location expressions

Syntax and conventions:

• Use | to separate arguments: <location>|<args...>.
• Arguments starting with $ specify name paths (comma-separated); stored as namePaths.
• Argument u forces the final name to upper case.
• When $ arguments are duplicated, the later one overrides the earlier ones.

Examples:

$_desc
$_desc|$name
$_desc|$name|u
title