emoemu 0.1.0

package/docs/config-file-format.md

@@ -0,0 +1,488 @@
+# Configuration File Format (.cfg)
+
+emoemu uses a configuration file to persist user settings across sessions. The format is designed to be compatible with RetroArch's config file format where applicable, making it familiar to users of that ecosystem.
+
+## File Location
+
+The config file is stored in platform-specific standard locations:
+
+| Platform | Path |
+|----------|------|
+| **macOS** | `~/Library/Application Support/emoemu/emoemu.cfg` |
+| **Linux** | `~/.config/emoemu/emoemu.cfg` |
+| **Windows** | `%APPDATA%\emoemu\emoemu.cfg` |
+
+The config file is created automatically on first run with default values. If the file does not exist, built-in defaults are used.
+
+### Alternative Config Paths
+
+emoemu also checks these locations (in order of precedence):
+
+1. `--config <path>` CLI flag (highest priority)
+2. `EMOEMU_CONFIG` environment variable
+3. `./emoemu.cfg` (current working directory)
+4. Platform-specific path (listed above)
+
+## File Format
+
+The config file uses a simple INI-style format compatible with RetroArch:
+
+```ini
+# Comment lines start with #
+key = "value"
+key = value
+key = true
+key = 1.5
+```
+
+### Format Rules
+
+- **Comments**: Lines starting with `#` are ignored
+- **Empty lines**: Ignored
+- **Keys**: Lowercase with underscores (e.g., `video_scale`)
+- **Values**: Can be quoted (`"value"`) or unquoted (`value`)
+- **Booleans**: `true` or `false` (unquoted)
+- **Numbers**: Integer or floating-point (unquoted)
+- **Strings**: Should be quoted if they contain spaces
+
+### Example Config
+
+```ini
+# emoemu Configuration
+# Generated by emoemu
+
+# Video settings
+video_driver = "kitty"
+video_scale = 2
+video_smooth = false
+
+# Post-processing mode: off, crt, or custom
+video_postprocessing_mode = "crt"
+
+# CRT preset values (used when mode is "crt")
+crt_gamma = 1.3
+crt_scanlines = 0.1
+crt_vignette = 0.5
+
+# Custom effect values (used when mode is "custom")
+video_gamma = 1.2
+video_scanlines = 0.3
+
+# Audio settings
+audio_enable = true
+
+# Input settings
+input_joypad_enable = true
+
+# Save data settings
+savestate_auto_load = true
+savestate_auto_save = true
+savestate_compression = true
+battery_save_enable = true
+
+# Emulation settings
+fps_show_enable = false
+fps_limit = 0
+```
+
+---
+
+## Configuration Keys
+
+### Video Settings
+
+| Key | Type | Default | CLI Flag | RetroArch Compatible | Description |
+|-----|------|---------|----------|---------------------|-------------|
+| `video_driver` | string | `"kitty"` | `--kitty`, `--terminal`, `--ascii`, `--emoji` | Yes | Rendering mode |
+| `video_scale` | integer | `2` | `--scale` | Yes | Internal render scale for Kitty mode |
+| `video_smooth` | boolean | `false` | - | Yes | Enable bilinear filtering (reserved) |
+| `video_fullscreen` | boolean | `false` | - | Yes | Full terminal mode (reserved) |
+| `custom_viewport_width` | integer | auto | `--width` | Yes | Display width in characters |
+| `custom_viewport_height` | integer | auto | `--height` | Yes | Display height in characters |
+| `video_color_enable` | boolean | `true` | `--no-color` | No | Enable color output |
+| `video_diff_render` | boolean | `true` | `--no-diff-render` | No | Enable diff-based rendering optimization |
+
+#### Video Driver Values
+
+| Value | Description |
+|-------|-------------|
+| `"kitty"` | Kitty graphics protocol (best quality) |
+| `"terminal"` | Unicode half-block characters |
+| `"ascii"` | ASCII character rendering |
+| `"emoji"` | Emoji character rendering |
+
+### Post-Processing Settings
+
+| Key | Type | Default | CLI Flag | RetroArch Compatible | Description |
+|-----|------|---------|----------|---------------------|-------------|
+| `video_postprocessing_mode` | string | `"off"` | `--crt` | No | Post-processing mode: `"off"`, `"crt"`, or `"custom"` |
+
+#### Post-Processing Mode Values
+
+| Value | Description |
+|-------|-------------|
+| `"off"` | No post-processing effects applied |
+| `"crt"` | CRT preset (uses crt_* config values) |
+| `"custom"` | Custom effects (uses video_* config values below) |
+
+### CRT Preset Values
+
+These values are used when `video_postprocessing_mode = "crt"`:
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `crt_gamma` | float | `1.3` | CRT gamma correction |
+| `crt_scanlines` | float | `0.1` | CRT scanline intensity |
+| `crt_saturation` | float | `1.0` | CRT color saturation |
+| `crt_vignette` | float | `0.5` | CRT vignette darkening |
+| `crt_ntsc` | float | `1.0` | CRT NTSC color bleeding |
+| `crt_curvature` | float | `0.1` | CRT screen curvature |
+
+### Custom Effect Values
+
+These values are used when `video_postprocessing_mode = "custom"`:
+
+| Key | Type | Default | CLI Flag | RetroArch Compatible | Description |
+|-----|------|---------|----------|---------------------|-------------|
+| `video_shader_enable` | boolean | `false` | - | Yes | Master enable for post-processing |
+| `video_gamma` | float | `1.0` | `--gamma` | No | Gamma correction (1.1-1.4 for CRT-like) |
+| `video_scanlines` | float | `0` | `--scanlines` | No | Scanline intensity (0.0-1.0) |
+| `video_saturation` | float | `1.0` | `--saturation` | No | Color saturation multiplier |
+| `video_brightness` | float | `1.0` | `--brightness` | No | Brightness multiplier |
+| `video_contrast` | float | `1.0` | `--contrast` | No | Contrast adjustment |
+| `video_vignette` | float | `0` | `--vignette` | No | Vignette edge darkening (0.3-0.5 for CRT) |
+| `video_bloom` | float | `0` | `--bloom` | No | Phosphor bloom/glow (Kitty only) |
+| `video_bloom_threshold` | float | `0.6` | `--bloom-threshold` | No | Brightness threshold for bloom |
+| `video_ntsc` | float | `0` | `--ntsc` | No | NTSC color artifacts (Kitty only) |
+| `video_curvature` | float | `0` | `--curvature` | No | CRT screen curvature (Kitty only) |
+
+### Kitty-Specific Settings
+
+| Key | Type | Default | CLI Flag | RetroArch Compatible | Description |
+|-----|------|---------|----------|---------------------|-------------|
+| `kitty_png_level` | integer | `4` | `--png-level` | No | PNG compression level (1-9) |
+
+### Audio Settings
+
+| Key | Type | Default | CLI Flag | RetroArch Compatible | Description |
+|-----|------|---------|----------|---------------------|-------------|
+| `audio_enable` | boolean | `true` | `--no-audio` | Yes | Enable audio output |
+| `audio_volume` | float | `1.0` | - | Yes | Master volume (0.0-1.0) |
+| `audio_mute_enable_enable` | boolean | `false` | - | Yes | Mute audio |
+
+### Input Settings
+
+| Key | Type | Default | CLI Flag | RetroArch Compatible | Description |
+|-----|------|---------|----------|---------------------|-------------|
+| `input_joypad_enable` | boolean | `true` | `--no-gamepad` | Yes | Enable gamepad support |
+| `input_autodetect_enable` | boolean | `true` | - | Yes | Auto-detect gamepads |
+
+### Save Data Settings
+
+| Key | Type | Default | CLI Flag | RetroArch Compatible | Description |
+|-----|------|---------|----------|---------------------|-------------|
+| `savestate_auto_load` | boolean | `true` | `--no-save-state` | Yes | Auto-load save states |
+| `savestate_auto_save` | boolean | `true` | `--no-save-state` | Yes | Auto-save states on exit |
+| `savestate_compression` | boolean | `true` | `--no-gzip-state` | Yes | Gzip compress save states |
+| `savestate_directory` | string | `""` | - | Yes | Directory for save states (empty=default) |
+| `savefile_directory` | string | `""` | - | Yes | Directory for battery saves (empty=default) |
+| `battery_save_enable` | boolean | `true` | `--no-battery-save` | No | Enable battery save (.srm) files |
+
+### Directory Settings
+
+| Key | Type | Default | CLI Flag | RetroArch Compatible | Description |
+|-----|------|---------|----------|---------------------|-------------|
+| `system_directory` | string | `""` | - | Yes | Directory for BIOS files (empty=./system) |
+| `screenshot_directory` | string | `""` | - | Yes | Directory for screenshots (empty=default) |
+
+### Emulation Settings
+
+| Key | Type | Default | CLI Flag | RetroArch Compatible | Description |
+|-----|------|---------|----------|---------------------|-------------|
+| `fps_show_enable_enable` | boolean | `false` | `--status` | Yes | Show status bar with FPS |
+| `fps_limit` | integer | `0` | `--fps-limit` | No | FPS limit (0=core native) |
+
+### Core Settings
+
+| Key | Type | Default | CLI Flag | RetroArch Compatible | Description |
+|-----|------|---------|----------|---------------------|-------------|
+| `core_default` | string | `""` | `--core` | No | Default core ID to use |
+| `libretro_directory` | string | `""` | - | Yes | Path to libretro cores |
+| `retroarch_cores_enable` | boolean | `false` | `--retroarch` | No | Load cores from RetroArch paths |
+
+#### Cores Directory
+
+emoemu searches for libretro cores in platform-specific directories that follow the same convention as RetroArch:
+
+| Platform | Default Cores Directory |
+|----------|------------------------|
+| **macOS** | `~/Library/Application Support/emoemu/cores/` |
+| **Linux** | `~/.config/emoemu/cores/` |
+| **Windows** | `%APPDATA%\emoemu\cores\` |
+
+To use a custom cores directory, set `libretro_directory` in your config:
+
+```ini
+# Custom cores directory (RetroArch-compatible key)
+libretro_directory = "/path/to/my/cores"
+
+# Or use ~ for home directory
+libretro_directory = "~/my-cores"
+```
+
+Search order for cores:
+1. Custom path from `libretro_directory` (if set)
+2. `./cores/` (current directory, for development)
+3. Platform-specific emoemu cores directory (see table above)
+4. System library paths (`/usr/lib/libretro/`, etc.)
+5. RetroArch directories (only if `--retroarch` flag is used)
+
+### NES-Specific Settings
+
+| Key | Type | Default | CLI Flag | RetroArch Compatible | Description |
+|-----|------|---------|----------|---------------------|-------------|
+| `nes_sprite_limit` | boolean | `false` | `--sprite-limit` | No | Enable 8-sprite-per-scanline limit |
+
+---
+
+## Post-Processing Modes
+
+emoemu supports three post-processing modes, configurable via `video_postprocessing_mode` or the P key during gameplay:
+
+### Off Mode
+No effects applied. Clean pixel output.
+
+### CRT Mode
+Uses the CRT preset values for an authentic retro look:
+
+```ini
+video_postprocessing_mode = "crt"
+
+# CRT preset values (customizable)
+crt_gamma = 1.3
+crt_scanlines = 0.1
+crt_saturation = 1.0
+crt_vignette = 0.5
+crt_ntsc = 1.0
+crt_curvature = 0.1
+```
+
+The `--crt` CLI flag sets `video_postprocessing_mode = "crt"`.
+
+### Custom Mode
+Uses the user-defined `video_*` effect values:
+
+```ini
+video_postprocessing_mode = "custom"
+
+# Custom effect values
+video_gamma = 1.2
+video_scanlines = 0.3
+video_saturation = 1.1
+video_vignette = 0.4
+```
+
+Custom effect values persist in config even when switching to Off or CRT mode, so you can return to your custom settings later.
+
+---
+
+## Configuration Precedence
+
+Settings are applied in this order (later overrides earlier):
+
+1. **Built-in defaults** (lowest priority)
+2. **Config file** (`emoemu.cfg`)
+3. **CLI flags** (highest priority)
+
+This means CLI flags always take precedence over config file settings.
+
+---
+
+## RetroArch Compatibility Notes
+
+emoemu uses RetroArch-compatible key names where the functionality overlaps. This provides several benefits:
+
+- Familiarity for RetroArch users
+- Potential for shared config snippets
+- Consistent naming conventions
+
+### Fully Compatible Keys
+
+These keys use the exact same names and value formats as RetroArch:
+
+- `video_driver`
+- `video_scale`
+- `video_smooth`
+- `video_fullscreen`
+- `video_shader_enable`
+- `custom_viewport_width`
+- `custom_viewport_height`
+- `audio_enable`
+- `audio_volume`
+- `audio_mute_enable`
+- `input_joypad_enable`
+- `input_autodetect_enable`
+- `savestate_auto_load`
+- `savestate_auto_save`
+- `savestate_compression`
+- `fps_show_enable`
+- `libretro_directory`
+
+### emoemu Specific Keys
+
+These keys are unique to emoemu and not present in RetroArch:
+
+- `video_color_enable`
+- `video_diff_render`
+- `video_gamma`, `video_scanlines`, `video_saturation`, etc. (post-processing)
+- `kitty_*` settings
+- `battery_save_enable`
+- `fps_limit`
+- `core_default`
+- `retroarch_cores_enable`
+- `nes_sprite_limit`
+
+---
+
+## Programmatic Access
+
+### Reading Config
+
+```typescript
+import { loadConfig } from './config.js';
+
+const config = loadConfig();
+console.log(config.video_driver);  // "kitty"
+console.log(config.audio_enable);  // true
+```
+
+### Writing Config
+
+```typescript
+import { saveConfig, getConfigPath } from './config.js';
+
+saveConfig({
+  video_driver: "terminal",
+  video_scale: 3,
+  audio_enable: false
+});
+```
+
+### Config Interface
+
+```typescript
+interface Config {
+  // Video
+  video_driver: 'kitty' | 'terminal' | 'ascii' | 'emoji';
+  video_scale: number;
+  video_smooth: boolean;
+  video_fullscreen: boolean;
+  custom_viewport_width: number | null;
+  custom_viewport_height: number | null;
+  video_color_enable: boolean;
+  video_diff_render: boolean;
+
+  // Post-processing mode
+  video_postprocessing_mode: 'off' | 'crt' | 'custom';
+
+  // CRT preset values (used when mode is 'crt')
+  crt_gamma: number;
+  crt_scanlines: number;
+  crt_saturation: number;
+  crt_vignette: number;
+  crt_ntsc: number;
+  crt_curvature: number;
+
+  // Custom effect values (used when mode is 'custom')
+  video_shader_enable: boolean;
+  video_gamma: number;
+  video_scanlines: number;
+  video_saturation: number;
+  video_brightness: number;
+  video_contrast: number;
+  video_vignette: number;
+  video_bloom: number;
+  video_bloom_threshold: number;
+  video_ntsc: number;
+  video_curvature: number;
+
+  // Kitty
+  kitty_png_level: number;
+
+  // Audio
+  audio_enable: boolean;
+  audio_volume: number;
+  audio_mute_enable: boolean;
+
+  // Input
+  input_joypad_enable: boolean;
+  input_autodetect_enable: boolean;
+
+  // Save data
+  savestate_auto_load: boolean;
+  savestate_auto_save: boolean;
+  savestate_compression: boolean;
+  battery_save_enable: boolean;
+
+  // Emulation
+  fps_show_enable: boolean;
+  fps_limit: number;
+
+  // Core
+  core_default: string;
+  libretro_directory: string;
+  retroarch_cores_enable: boolean;
+
+  // NES
+  nes_sprite_limit: boolean;
+}
+```
+
+---
+
+## Migration from CLI-only Usage
+
+If you've been using CLI flags, here's how to migrate to config file:
+
+| CLI Flag | Config Key |
+|----------|------------|
+| `--kitty` | `video_driver = "kitty"` |
+| `--terminal` | `video_driver = "terminal"` |
+| `--ascii` | `video_driver = "ascii"` |
+| `--emoji` | `video_driver = "emoji"` |
+| `--scale 2` | `video_scale = 2` |
+| `--no-color` | `video_color_enable = false` |
+| `--no-diff-render` | `video_diff_render = false` |
+| `--crt` | `video_postprocessing_mode = "crt"` |
+| `--gamma 1.3` | `video_gamma = 1.3` |
+| `--scanlines 0.3` | `video_scanlines = 0.3` |
+| `--saturation 1.2` | `video_saturation = 1.2` |
+| `--brightness 1.1` | `video_brightness = 1.1` |
+| `--contrast 1.1` | `video_contrast = 1.1` |
+| `--vignette 0.5` | `video_vignette = 0.5` |
+| `--bloom 0.5` | `video_bloom = 0.5` |
+| `--bloom-threshold 0.6` | `video_bloom_threshold = 0.6` |
+| `--ntsc 1.0` | `video_ntsc = 1.0` |
+| `--curvature 0.1` | `video_curvature = 0.1` |
+| `--png-level 6` | `kitty_png_level = 6` |
+| `--no-audio` | `audio_enable = false` |
+| `--no-gamepad` | `input_joypad_enable = false` |
+| `--no-save-state` | `savestate_auto_load = false` and `savestate_auto_save = false` |
+| `--no-battery-save` | `battery_save_enable = false` |
+| `--no-gzip-state` | `savestate_compression = false` |
+| `--status` | `fps_show_enable = true` |
+| `--fps-limit 30` | `fps_limit = 30` |
+| `--core nes` | `core_default = "nes"` |
+| `--retroarch` | `retroarch_cores_enable = true` |
+| `--sprite-limit` | `nes_sprite_limit = true` |
+| `--width 120` | `custom_viewport_width = 120` |
+| `--height 40` | `custom_viewport_height = 40` |
+
+---
+
+## Version History
+
+| Version | Changes |
+|---------|---------|
+| 2 | Added `video_postprocessing_mode` (off/crt/custom), CRT preset values (`crt_*`). Replaced `video_crt_mode` boolean. |
+| 1 | Initial config file format |