Configuration System

The configuration system serves four requirements: game modules reading runtime properties, schedulers managing task queues, the WebUI generating forms, and developers extending options declaratively. It achieves this through a three-stage pipeline: YAML schemas → Code generator → Runtime binding.

task.yaml  argument.yaml  default.yaml  override.yaml  gui.yaml  dashboard.yaml
      │            │             │            │           │          │
      └────────────┴─────────────┴────────────┴───────────┴──────────┘
                                   │
                    uv run -m module.config.config_updater
                                   │
     ┌──────────────┬──────────────┼──────────────┬──────────────┐
     ▼              ▼              ▼              ▼              ▼
  args.json     menu.json   config_generated.py  template.json  i18n/*.json
     │              │              │
     ▼              ▼              ▼
  WebUI Forms   Sidebar Menus  Python Defaults
                                   │
                                   ▼
                          AzurLaneConfig (Runtime)

Schema Definitions: Six YAML Files

Schema File	Purpose	Authoring Role
task.yaml	Task definitions, parameter group bindings, menu hierarchies	Developers
argument.yaml	Parameter types, defaults, options, and validations	Developers
default.yaml	Task-specific default value overrides (user-modifiable)	Developers
override.yaml	Enforced overrides, display toggles, and locked types	Developers
gui.yaml	WebUI localization keys	Developers
dashboard.yaml	Resource telemetry definitions	Developers

Distinction between default.yaml and override.yaml:

• default.yaml specifies initial defaults that users can modify in the WebUI.
• override.yaml enforces locked values that cannot be altered in the WebUI, used for task-mandated invariants or hidden internal states.

Parameter Schema Syntax

Campaign:
  Name: 12-4
  Mode:
    value: normal
    option: [normal, hard]
  UseAutoSearch: true

Field	Function
value	Default value
type	Form input type: checkbox, input, textarea, datetime, stored, etc.
option	Selectable dropdown enumeration
validate	Numeric range bounds [min, max]
display	Visibility flag: hide suppresses display; stored tracks internal state
valuetype	Explicit type coercion (e.g. str)

Schema Compilation

uv run -m module.config.config_updater

Generated compilation artifacts:

Output	Consumer
module/config/argument/args.json	WebUI form generation and server-side validation
module/config/argument/menu.json	WebUI navigation sidebar
module/config/config_generated.py	Python default property classes
config/template.json	New instance template
module/config/i18n/*.json	5-language localization dictionaries
config/deploy.template*.yaml	Server deployment templates

Never Edit Generated Artifacts Manually

CI validates schema compilation via git diff. Manual changes will be overwritten on the next compile pass. The sole exception is i18n/*.json: the compiler preserves existing translations while inserting new keys as untranslated path strings that require manual translation across all five supported locales.

Runtime: AzurLaneConfig

Parameter Paths & Property Access

Parameter paths follow <Task>.<Group>.<Argument>. Once bound to an active task, options are accessed via snake_case attributes:

# Reads Campaign.Name
name = self.config.Campaign_Name

# Modifies memory and marks state dirty
self.config.Campaign_Name = '12-4'

bind(task) exposes only the parameters belonging to the active task. Business modules cannot access private parameters of other tasks directly; cross-task queries require explicit cross_get calls.

Transactional File Persistence

Configuration changes are not written immediately to disk; they queue inside a modified list and commit atomically under cross-process file locks:

Worker modification → modified queue → Transaction lock → Atomic write to config/<instance>.json
WebUI edit → config.patch (with revision) → Concurrency check → Same lock

WebUI edits utilize optimistic concurrency tracking: conflicting concurrent edits fail with conflict alerts, requiring users to refresh.

Schema Loading & Migrations

Loading follows a strict pipeline:

1. Parse config/<instance>.json.
2. Merge with defaults from config_generated.py (filling missing fields).
3. Apply migration rules from redirect_utils/ (renames, type changes, option mappings).
4. Coerce types (string numerals to integers, normalize datetime formats).
5. Generate runtime properties.

Initializing AzurLaneConfig may write to disk to persist migration results. Test harnesses must use temporary configuration paths to prevent altering production settings.

Hot Reloading

The scheduler checks file modification times (mtime) at two points:

• During the 5-second polling interval in wait_until();
• Following task completion, when the config cache is cleared.

Detected modifications trigger complete reconstruction of the AzurLaneConfig object. In-flight tasks do not switch configurations mid-execution; tasks requiring mid-flight detection invoke check_task_switch().

Adding a Configuration Option

01

Update argument.yaml

Add the property under the target group, defining value, type, and option / validate. Use CamelCase naming, which translates into property attribute names.

01

Configure defaults and overrides

If the property requires custom defaults on specific tasks, update default.yaml; if it must be immutable on specific tasks, update override.yaml.

01

Assign group to tasks

Add the group to target task lists in task.yaml. Entry order governs display order in the WebUI.

01

Add localization strings

Run the compiler, then populate translations across all five files in module/config/i18n/*.json (including select option labels).

01

Compile schemas

uv run -m module.config.config_updater

Inspect git diffs on args.json and template.json to verify changes match expectations.

01

Validate changes

uv run python -m unittest tests.test_config_transaction tests.test_config_batch
uv run python -m dev_tools.import_smoke_test

Launch the WebUI and confirm the option appears in forms, saves properly, and reloads cleanly.

Common Configuration Pitfalls

Issue	Root Cause
Field missing from WebUI	Group not assigned in task.yaml, or configured with display: hide
Value reverts after editing	Value is locked in override.yaml
Attribute raises AttributeError	Property name misspelled, or group is not bound to active task
Value vanishes after migration	Missing migration rule in redirect_utils/
UI renders raw schema keys	Missing translations in i18n/*.json
CI fails on schema diff	Modified YAML without compiling, or manually edited generated files

Source Code References

File	Core Responsibility
module/config/config.py	AzurLaneConfig: loading, binding, atomic persistence, scheduler primitives
module/config/config_updater.py	Schema compiler and version migration engine
module/config/transaction.py	Cross-process file locking transactions
module/config/task_priority.py	Priority parser
module/config/server.py	Server package mappings
module/api/config_service.py	WebUI configuration validation services