# Configuration

Configuration is loaded from classpath properties files in `src/main/resources/config`:

- `application.properties` for runtime behavior
- `logger.properties` for logging behavior

`AppConfigValidator` performs startup validation and fails fast on invalid settings.

## `application.properties`

### Core runtime keys

| Key | Required | Description |
|---|---|---|
| `mqtt.broker.url` | yes | MQTT broker URI (`tcp://...`, `ssl://...`, `ws://...`, `wss://...`) |
| `mqtt.client.id` | yes | MQTT client ID |
| `mqtt.topic` | yes | MQTT topic to subscribe to |
| `streaming.url` | yes | URL for embedded streaming view (`http`/`https`) |
| `animation.output.path` | yes | Target path for animation JSON output |
| `app.mode` | no | Generic runtime mode flag |

### Optional simulator keys (`mqtt_sim.*`)

These become required/validated when `mqtt_sim.enabled=true`.

| Key | Description |
|---|---|
| `mqtt_sim.enabled` | Enable Python simulator startup |
| `python.path` | Python executable path |
| `mqtt_sim.script` | Simulator script path |
| `mqtt_sim.broker` | Broker host passed to simulator |
| `mqtt_sim.port` | Broker port passed to simulator |
| `mqtt_sim.topic` | Simulator publish topic |
| `mqtt_sim.qos` | QoS (`0-2`) |
| `mqtt_sim.interval_seconds` | Publish interval in seconds |
| `mqtt_sim.username` / `mqtt_sim.password` | Optional broker auth |
| `mqtt_sim.start_id` | Optional starting `_id` |
| `mqtt_sim.client_id` | Optional simulator client id |
| `mqtt_sim.log_file` | Optional simulator log path |

### Optional Unreal keys (`unreal.*`)

These become required/validated when `unreal.enabled=true`.

| Key | Description |
|---|---|
| `unreal.enabled` | Enable Unreal startup flow |
| `unreal.executable` | PowerShell launcher script path |
| `unreal.signalling_server.script` | Signalling server BAT path |
| `unreal.target.executable` | Unreal executable path passed to script |
| `unreal.target.working_dir` | Unreal working directory passed to script |
| `unreal.target.args` | Unreal launch arguments |
| `unreal.pid.dir` | Optional PID output directory for script |
| `unreal.pid.file` | PID file used for shutdown cleanup |
| `unreal.signalling.pid.file` | Signalling PID file used for cleanup |
| `unreal.startup.delay.seconds` | Delay before Unreal launch in script |

### Process startup health checks

| Key | Description | Default |
|---|---|---|
| `process.startup.healthcheck.enabled` | Enable startup health checks for managed processes | `true` |
| `process.startup.healthcheck.timeout.millis` | Health-check timeout | `10000` |
| `process.startup.healthcheck.poll.millis` | Poll interval | `250` |

## `logger.properties`

| Key | Description | Typical value |
|---|---|---|
| `logger.level` | Minimum log level | `DEBUG` |
| `logger.file.enabled` | Toggle file logging | `true` |
| `logger.file` | Log file path | `logs/application.log` |
| `logger.max.size.mb` | Rotation threshold in MB | `10` |

## Validation Behavior

The validator checks:

- URI format and scheme for MQTT broker URL
- non-empty required keys
- numeric ranges (`port`, QoS, timeout/poll values, delays)
- file/directory existence for enabled integrations
- optional quote handling and invalid path syntax

Any validation errors are grouped and thrown as a single startup exception.

## Script Environment Mapping

### `mqtt_simulator.py`

App config keys are forwarded as environment variables:

- `mqtt_sim.broker` -> `MQTT_SIM_BROKER`
- `mqtt_sim.port` -> `MQTT_SIM_PORT`
- `mqtt_sim.topic` -> `MQTT_SIM_TOPIC`
- `mqtt_sim.username` -> `MQTT_SIM_USERNAME`
- `mqtt_sim.password` -> `MQTT_SIM_PASSWORD`
- `mqtt_sim.qos` -> `MQTT_SIM_QOS`
- `mqtt_sim.interval_seconds` -> `MQTT_SIM_INTERVAL_SECONDS`
- `mqtt_sim.start_id` -> `MQTT_SIM_START_ID`
- `mqtt_sim.client_id` -> `MQTT_SIM_CLIENT_ID`
- `mqtt_sim.log_file` -> `MQTT_SIM_LOG_FILE`

### `start_avatar.ps1`

App config keys are forwarded as environment variables:

- `unreal.target.executable` -> `VGA_UE_EXE`
- `unreal.target.args` -> `VGA_UE_ARGS`
- `unreal.target.working_dir` -> `VGA_UE_WORKDIR`
- `unreal.signalling_server.script` -> `VGA_SIGNALLING_BAT`
- `unreal.startup.delay.seconds` -> `VGA_SIGNALLING_DELAY`
- `unreal.pid.dir` (or PID parent fallback) -> `VGA_PID_DIR`

## Practical Recommendation

For first-time local runs, keep:

```properties
mqtt_sim.enabled=false
unreal.enabled=false
```

Then enable integrations incrementally after validating local paths and dependencies.