# =============================================================================
# NESER Configuration File Example
# =============================================================================
#
# This file shows all available configuration options with their default values.
# Copy this file to one of the following locations:
#
#   ~/.neser/neser.conf    (user-wide settings)
#   ./neser.conf           (project/directory-specific settings)
#
# Or specify a custom path with: neser --config /path/to/config.conf
#
# Configuration priority (later overrides earlier):
#   1. Default values (built-in)
#   2. ~/.neser/neser.conf (if it exists)
#   3. ./neser.conf (if it exists)
#   4. --config <file> (if specified, replaces steps 2 and 3)
#   5. Command-line arguments (highest priority)
#
# Format: key=value (one per line)
# Comments start with #
# Boolean values: true/false, yes/no, 1/0 (case-insensitive)
# Keys accept both dashes and underscores (e.g. cartridge-search-paths
# and cartridge_search_paths are equivalent).
#
# Command-line arguments use the same keys with -- prefix and hyphens:
#   nes-hardware=nes-pal  →  --nes-hardware nes-pal
#   audio=false           →  --audio false  OR  --audio=0  OR  --no-audio  OR  --disable-audio
#   audio=true            →  --audio  OR  --audio true  OR  --audio=1
#   nes-pulse1=true       →  --nes-pulse1  OR  --nes-pulse1 true  OR  --nes-pulse1=1
#   nes-pulse2=false      →  --nes-pulse2 false  OR  --nes-pulse2=0  OR  --no-nes-pulse2  OR  --disable-nes-pulse2
#
# NES-specific settings are prefixed with nes- (e.g., nes-hardware, nes-pulse1).
# Game Boy-specific settings are prefixed with gb- (e.g., gb-hardware, gb-dmg-variant).
# GBA-specific settings are prefixed with gba- (e.g., gba-hardware, gba-bios-path).
# Generic platform settings have no prefix (e.g., audio, ram_init_mode).
#
# CLI boolean flags:
#   - No value (--flag) defaults to true
#   - With value (--flag true/false) sets explicit value  
#   - Prefix negation (--no-flag, --disable-flag) sets to false
# =============================================================================

# -----------------------------------------------------------------------------
# ROM Browser Settings
# -----------------------------------------------------------------------------
# Path to the TheGamesDB metadata SQLite database.
# This database is used to enrich ROM entries with cover art, descriptions,
# genres, and other metadata in the graphical ROM browser.
# The database is generated by scripts/metadata-scraper/.
# Default: ~/.neser/metadata.db
#metadata_db_path=~/.neser/metadata.db

# Path to the directory where downloaded cover art images are cached.
# Cover art is downloaded from TheGamesDB CDN on first launch and cached
# here for subsequent use.
# Default: ~/.neser/image_cache/
#image_cache_path=~/.neser/image_cache/

# Include unofficial ROMs (hacks, homebrew, bootlegs, prototypes, etc.) in the
# ROM browser catalog. When false (default), ROMs with keywords like "(Hack)",
# "(Pirate)", "[Homebrew]", "(Proto)", etc. in their filename are excluded.
#include_unofficial_roms=false

# -----------------------------------------------------------------------------
# Hardware
# -----------------------------------------------------------------------------
# Set to "nes-ntsc", "nes-pal", "famicom", or "dendy".
# NES-NTSC runs at ~60 FPS, NES-PAL at ~50 FPS.
# nes-ntsc is the standard for North American and Japanese NES consoles.
# nes-pal is used for European NES consoles.
# famicom uses Famicom hardware mode and NTSC timing.
# dendy emulates the Soviet-era Dendy clone (~50 FPS, 312 scanlines, ~1.77 MHz CPU).
nes-hardware=nes-ntsc

# -----------------------------------------------------------------------------
# Audio Settings
# -----------------------------------------------------------------------------
# Enable or disable audio output entirely.
audio=true

# Individual APU channel toggles.
# Useful for isolating specific sounds or debugging audio issues.
nes-pulse1=true
nes-pulse2=true
nes-triangle=true
nes-noise=true
nes-dmc=true

# -----------------------------------------------------------------------------
# Video Settings
# -----------------------------------------------------------------------------
# Enable vertical sync to prevent screen tearing.
# Disabling may reduce input latency but can cause visual artifacts.
vsync=true

# Window window height
# The NES outputs 256x240 pixels. For best visual, set the height of the window to a
# multiple of 240 - vertical_overscan * 2.
# Example: For standard vertical overscan of 8 pixels, use 224, 448, 672, 896, etc.
# Note: Only applies in windowed mode, ignored in fullscreen.
window_height=896

# Run in fullscreen mode.
fullscreen=false

# Display index for fullscreen mode (0 = primary display).
# Only used when fullscreen=true.
display=0

# Shader/filter preset (NES).
# Applies visual effects like CRT simulation or pixel scaling.
# Valid values:
#   - crt    : CRT simulation with scanlines, shadow mask, bloom
#   - ntsc   : NTSC composite video simulation
#   - smooth : Smooth pixel upscaling (xBRZ)
#   - pal    : PAL composite video simulation
#   - none   : No filter, raw pixels
# Leave empty or comment out for no shader.
#nes-filter=crt

# Shader/filter preset (Game Boy).
# Valid values:
#   - dmg    : DMG dot-matrix green-tint LCD simulation
#   - none   : No filter, raw pixels
# Leave empty or comment out for no shader.
#gb-filter=dmg

# Shader/filter preset (Game Boy Advance).
# Valid values:
#   - none          : No filter, raw pixels
#   - gba-lcd       : Default GBA LCD shader
#   - agb001        : AGB-001 handheld preset
#   - nso-gba-color : Nintendo Switch Online GBA color preset
#   - sp101-color   : GBA SP-101 color preset
#   - gba-lcd-grid  : GBA LCD grid + border preset
# Leave empty or comment out for no shader.
#gba-filter=gba-lcd

# -----------------------------------------------------------------------------
# Input Settings
# -----------------------------------------------------------------------------
# Enable gamepad/joystick support.
# Set to false to use keyboard only.
gamepads=true

# Enable Four Score emulation mode.
# When true, NESER emulates 4-player Four Score reads on $4016/$4017.
# Input fallback policy:
#   - 2 physical gamepads connected: gamepads -> players 1-2, keyboard -> players 3-4
#   - 1 physical gamepad connected: gamepad -> player 1, keyboard -> players 2-3
#   - 0 physical gamepads connected: keyboard -> players 1-2
nes-enable_4_score=false

# Controller Type Configuration (Per-Port)
# Each of the two controller ports can be configured independently.
# Valid values: joypad, arkanoid, none
# Default: joypad for both ports
#
# Port 1 (Player 1):
#nes-controller_port1=joypad
#
# Port 2 (Player 2):
#nes-controller_port2=joypad
#
# Auto-detection behavior:
# If a specific port hasn't been explicitly configured, NESER will
# automatically detect known paddle ROMs and configure that port:
#   - Arkanoid (CRC 0x32FB0583) → paddle on port 2
#   - PaddleTest3 (CRC 0x47F9F410) → paddle on port 1
#
# Auto-detection is per-port: if you explicitly configure port 2, auto-detection
# for port 2 is disabled, but port 1 can still be auto-detected (and vice versa).
# This gives you fine-grained control over each port independently.

# Paddle Controller Input (SDL frontend)
# When a paddle controller is enabled on a port, mouse input controls it:
#   - Mouse X position → paddle position (0-255, non-linear curve)
#   - Left mouse button → paddle trigger
# Mouse input is routed to ALL ports configured as paddles.
# Keyboard/gamepad input for paddle-configured ports is suppressed.
#
# Configuration examples:
#
# Example 1: Mouse-based paddle on port 1 (for PaddleTest3-style games)
#   nes-controller_port1=arkanoid
#   nes-controller_port2=joypad
#
# Example 2: Mouse-based paddle on port 2 (for Arkanoid)
#   nes-controller_port1=joypad
#   nes-controller_port2=arkanoid
#
# Example 3: Paddles on both ports (both controlled by same mouse)
#   nes-controller_port1=arkanoid
#   nes-controller_port2=arkanoid
#
# Example 4: Force joypad mode even for Arkanoid ROM
#   nes-controller_port1=joypad
#   nes-controller_port2=joypad

# Zapper Light Detection Size
# Controls the size of the square area sampled around the Zapper cursor
# when checking for light detection:
#   0 = single pixel (default)
#   1 = 3×3 square (9 pixels)
#   2 = 5×5 square (25 pixels)
#   n = (2·n + 1)² pixels sampled
#
# Larger values make it easier to hit targets but increase CPU usage.
# Values above 10 may cause noticeable performance impact.
# Valid range: 0-255
nes-zapper_detection_size=0

# -----------------------------------------------------------------------------
# Debugging
# -----------------------------------------------------------------------------
# Open debugger windows (CPU/PPU/APU) on startup.
# The emulator will start paused when this is enabled.
debugger=false

# Load save-state on startup (uses ROM .state path).
# This will automatically restore the emulator state from the last save.
load_state=false

# -----------------------------------------------------------------------------
# Emulation Speed (DISABLED - not supported with current eventloop design)
# -----------------------------------------------------------------------------
# Emulation speed multiplier (1.0 = normal speed).
# Values < 1.0 slow down, > 1.0 speed up.
# Example: 0.5 = half speed, 2.0 = double speed

# -----------------------------------------------------------------------------
# RAM Initialization Mode
# -----------------------------------------------------------------------------
# Controls how all emulated RAM (CPU, PRG, CHR, PPU nametable, and palette) is
# initialized on power-on/hard reset. This affects hardware-accuracy and test
# determinism.
#
# Valid values:
#   - zero: Initialize all RAM to 0x00 (predictable, not hardware-accurate)
#   - random: Initialize all RAM to pseudo-random values (hardware-accurate)
#   - seeded-random:SEED: Initialize RAM with pseudo-random values using a fixed seed
#                         (hardware-accurate and deterministic for testing)
#
# Soft resets preserve RAM contents (no re-initialization).
#
# Default: zero (deterministic for testing and debugging)
#
# Note: For hardware-accurate behavior, set to "random"
#
# Examples:
#   ram_init_mode=zero
#   ram_init_mode=random
#   ram_init_mode=seeded-random:12345
#
ram_init_mode=zero

# -----------------------------------------------------------------------------
# OAM DRAM Decay
# -----------------------------------------------------------------------------
# Enable or disable dynamic OAM DRAM decay emulation.
#
# Notes:
# - This is an explicit emulator feature toggle and defaults to disabled.
# - NTSC behavior is affected when enabled.
# - PAL remains non-decaying due PAL OAM refresh behavior.
#
# Valid values: true, false
#
nes-oam_dram_decay=false

# -----------------------------------------------------------------------------
# Overscan Removal
# -----------------------------------------------------------------------------
# Simulate a CRT television by removing overscan pixels before displaying.
# Pixels are removed symmetrically from both edges.
#
# horizontal_overscan: pixels removed from each of left and right edges.
#   Valid range: 0..=8. Default: 8.
#
# vertical_overscan: pixels removed from each of top and bottom edges.
#   Valid range: 0..=16. Default: 8.
#
nes-horizontal_overscan=8
nes-vertical_overscan=8

# -----------------------------------------------------------------------------
# Game Boy Settings
# -----------------------------------------------------------------------------
# Game Boy hardware target selection.
# Valid values: dmg, cgb, gba
# Determines which hardware to emulate:
#   - dmg: Original Game Boy (forces DMG mode even for dual-compatible ROMs)
#   - cgb: Game Boy Color (enables CGB features for compatible ROMs)
#   - gba: Game Boy Advance in GBC mode (currently same as cgb)
# Default: auto-detect from ROM (DMG-only → dmg, dual-compatible/CGB-only → cgb)
# Note: CGB-only ROMs cannot run with gb-hardware=dmg (will return an error).
#gb-hardware=cgb

# DMG hardware variant to emulate.
# Valid values: dmg-0, dmg-a, dmg-b, dmg-c
# DMG-A, DMG-B, DMG-C share identical software-visible behavior (same boot ROM
# and post-boot register state). DMG-0 is the first-generation variant with a
# different boot ROM and different post-boot register values.
# Default: dmg-b (most common hardware revision)
# Note: This only applies when using gb-hardware=dmg or when a DMG-only ROM
# is auto-detected. It has no effect on CGB mode.
#gb-dmg-variant=dmg-b

# CGB (Game Boy Color) hardware variant to emulate.
# Valid values: cgb-0, cgb-a, cgb-b, cgb-c, cgb-d, cgb-e
# CGB-0 is the first-generation variant (rare), with different boot ROM and
# post-boot register state compared to production variants.
# CGB-A through CGB-E are production variants, with CGB-E being the latest.
# Default: cgb-e (latest/most common production variant)
# Note: This only applies when using gb-hardware=cgb or when a CGB ROM is
# auto-detected. It has no effect on DMG mode.
#gb-cgb-variant=cgb-e

# Show the Game Boy boot ROM animation (logo + chime).
# When enabled, the emulator will play the full boot animation with the
# Nintendo logo scrolling and the boot chime before starting the game.
# Default: false (skip boot animation for faster startup)
# Valid values: true, false
#gb-boot-animation=false

# -----------------------------------------------------------------------------
# Game Boy Advance Settings
# -----------------------------------------------------------------------------
# GBA hardware model.
# Valid values: agb, sp, micro
# Default: agb
#gba-hardware=agb

# Path to an external GBA BIOS image (optional).
# NESER includes a built-in open-source BIOS that is used by default.
# Set this option to override with a proprietary BIOS dump (must be
# exactly 16384 bytes). If this path is omitted, NESER also tries
# ~/.neser/gba_bios.bin before falling back to the built-in BIOS.
# If the configured path exists but is invalid, an error is reported.
# Use the special value "embedded" to force the built-in BIOS even when
# an external BIOS file exists at the default path.
#gba-bios-path=/absolute/path/to/gba_bios.bin
#gba-bios-path=embedded

# Skip the GBA BIOS intro (logo display + boot jingle).
# When enabled, the BIOS still performs full hardware initialization
# (stack setup, register clearing, SoundBias ramp, POSTFLG, etc.) but
# skips the visual/audio splash screen for faster boot.
# Default: false (intro is shown).
#skip-bios-intro=false

# GBA LCD color correction.
# When enabled, BGR555 → RGB888 conversion uses a gamma ≈ 4 lookup table
# that simulates the GBA TFT LCD's physical non-linear response. Per GBATek,
# values 0–14 appear nearly black on the GBA TFT display; the correction
# concentrates most visible output in the upper half of the intensity range
# (15–31). This is an optional post-processing step; the default linear
# expansion is technically correct for the digital color values.
# Default: false (linear expansion).
#gba-color-correction=false

# GBA trace channels for emulator diagnostics.
# Higher levels may emit more detail as channel-specific tracing grows.
# Valid values: 0-5 (values above 5 are clamped).
# Default: 0 (disabled)
#gba-trace-cpu=0
#gba-trace-bus=0
#gba-trace-dma=0
#gba-trace-swi=0
#gba-trace-mgba-log=0
