questshock/CONFIG.md

Persistent configuration (questshock.config.json)

QuestShock can load a persistent, human-editable configuration file at startup, in addition to (and independent of) the engine's own prefs.txt.

• Location: /sdcard/questshock/questshock.config.json - the same folder you already copy res/data/res/sound into (see README.md section 5.1).

• Format: plain JSON, grouped by concern. Each top-level key is a group; each key inside a group is one option.

• Loading: read automatically at app startup, before the splash screen, if the file exists. If it doesn't, questshock.config.default.json (same folder) is used instead - a copy bundled with the app, refreshed on every launch, never overwriting your own saved questshock.config.json. If neither file exists, the engine behaves as it did before this file existed (driven by prefs.txt as usual).

• Saving: never automatic. In-headset, open the menu (controller menu button) and press Save Configuration to write the file from your current live settings, overwriting it if present. Press Load Configuration to re-read the file and apply it without restarting the app.

• Live vs. restart-required: every option below is tagged as either live-appliable (applying it while already playing takes effect immediately) or restart-required. Pressing Load Configuration applies every live-appliable change straight away; if the file also changes something restart-required, a dialog lists exactly which option(s) need it and offers:

  • Dismiss - keep playing with the live-appliable changes already applied; the restart-required option(s) stay as they were.
  • Restart Now - relaunches the app, which re-runs this same startup load and so applies every group in the file, including the restart-required ones.

  (Every option currently documented below is live-appliable, so this dialog won't actually appear yet - it's built in for options added in a future version that do need a restart.)

• Unrecognized groups/keys are ignored (harmless if you're editing the file in advance for a future version). An invalid value for a specific option (see each option's possible values below) is logged and that one option is skipped - every other valid option in the file still applies. A file that isn't valid JSON at all is ignored entirely, with nothing applied.

• questshock.config.json and prefs.txt are fully independent - loading or saving one never reads or writes the other.

Example

{
  "video_options": {
    "renderer": "opengl",
    "resolution": "1024x768",
    "initial_screen_width_m": 1.6,
    "initial_screen_distance_m": 2.0,
    "game_screen_width_m": 2.8,
    "game_screen_distance_m": 2.0,
    "screen_width_offset_m": 1.0,
    "screen_width_step_m": 0.6,
    "screen_distance_offset_m": 1.0,
    "screen_distance_step_m": 0.5
  },
  "general": {
    "language": "english"
  },
  "player_position": {
    "x": 0.0,
    "z": 0.0,
    "yaw_degrees": 0.0
  }
}

Video Options (video_options)

renderer

Which renderer the game uses to draw the 3D view.

• Type: enum
• Possible values: "software", "opengl"
• Restart required?: No (live-appliable)

resolution

The game's internal rendering resolution.

• Type: enum
• Possible values: "320x200", "320x400", "640x400", "640x480", "1024x768"
• Restart required?: No (live-appliable)

initial_screen_width_m, initial_screen_distance_m, game_screen_width_m, game_screen_distance_m

The virtual screen's physical width and distance from the player (both in meters) - the game shows two independently configurable screen "profiles", switched automatically based on what's currently on screen:

• Initial Screen (initial_screen_*) - the splash screen, intro cutscenes, and the game's own main menu.
• Game Screen (game_screen_*) - actual gameplay (the 3D view, automap, cyberspace, etc.).

Switching happens automatically - no player action needed - the instant the game itself transitions between these (e.g. starting/loading a game, or returning to the menu).

• Type: number (meters)
• Possible values: the in-headset Video Options tab offers 5 presets each - widths 1.0, 1.6 (the original, pre-this-feature default), 2.2, 2.8, 3.4; distances 1.0, 1.5, 2.0 (the original, pre-this-feature default), 2.5, 3.0 - but a hand-edited value doesn't need to match a preset exactly (it's clamped to a sane range - width [0.2, 10.0], distance [0.5, 10.0] - rather than snapped or rejected; the Video Options tab just shows no button selected for an in-between value).
• Restart required?: No (live-appliable)
• Note: the screen is always flat - there's no curve option.

screen_width_offset_m, screen_width_step_m, screen_distance_offset_m, screen_distance_step_m

Reshapes the 5 preset buttons the Video Options tab offers for width and distance (above) - config-file-only, there's no in-headset control for these. Shared by both Initial Screen and Game Screen (both columns' buttons show the same 5 values per row) - this only changes what the buttons offer, not either profile's current value.

Preset button index (0-4) shows offset + step * index. For example, a distance offset of 0 and step of 2 shows buttons 0, 2, 4, 6, 8; the defaults below reproduce this feature's original launch presets exactly.

• Type: number (meters)
• Default values: width offset 1.0, step 0.6 (buttons 1.0, 1.6, 2.2, 2.8, 3.4); distance offset 1.0, step 0.5 (buttons 1.0, 1.5, 2.0, 2.5, 3.0).
• Restart required?: No (live-appliable)
• Note: not clamped - an unusual offset/step (e.g. negative step) is accepted as-is. A resulting preset value outside the current value's own clamp range (see above) still clamps normally when that preset button is actually pressed.

General (general)

language

The game's UI/text language - both the game's own resource strings and this project's own menu/keyboard chrome text (title bar, buttons, etc.).

• Type: enum
• Possible values: "english", "french", "german"
• Restart required?: No (live-appliable) - applies the same way the game's own in-game options menu applies a language change (reloads the language-specific resource files and refreshes the inventory/MFD/side-icon UI immediately).
• Note: French and German both need their own full resource pack (frnstrng.res/mfdfrn.res, gerstrng.res/mfdger.res under res/data/) - if any of those files aren't present, the switch is refused (logged, questshock.config.json and the current language are left unchanged) rather than leaving the game with no valid resource file open. See README.md section 3 ("Game assets") for where mfdfrn.res/ mfdger.res come from - the GOG Enhanced Edition installer alone doesn't include them.

Player Position (player_position)

Where the player is virtually standing/facing, independent of - and not reset by - starting a new game or loading a save (same independence from prefs.txt/savegames as every other group here). Set by moving around in-headset (menu open, left thumbstick snap-turns, right thumbstick smooth- moves) to line yourself up with the game quad ("virtual screen"). Height is never included here - it always comes from your real tracked headset height, not this file.

Startup fallback: only applied at startup if all three fields (x, z, yaw_degrees) are present - a config file with none of them (or none at all), or a partial/hand-edited one missing any of the three, falls back to an automatic recenter instead (see Reset Position below), using your real head pose at that moment. A complete saved position is applied as-is, with no such recenter.

Reset Position (Main Menu tab) is a separate, live-only action, not a config value: it recenters using your current real head pose, so the game quad ends up directly ahead of wherever you're actually standing/ facing right now - not a plain "go back to (0, 0, 0)" (which would only undo thumbstick movement, not any physical drift/rotation since the session started). It's unrelated to questshock.config.json - it never reads or writes this file.

x, z

Horizontal position, in meters, on the play space's floor plane.

• Type: number
• Restart required?: No (live-appliable)

yaw_degrees

Which way the player is virtually facing, in degrees.

• Type: number
• Restart required?: No (live-appliable)