Dethrace

DETHRACE FOR AROS - README
==========================

Dethrace is an open-source reimplementation of the Carmageddon game engine.
This document describes all available options for running the game on AROS.

---

QUICK START
-----------

Place the dethrace executable in the game data directory (where the DATA
folder is located) and run it:

    dethrace

Or use the GUI launcher (recommended):

    dethrace_gui

---

USAGE MODE
----------

You can use dethrace in four ways:
- GUI Mode (recommended):
  Start dethrace_gui and use it, this will create/modify dethrace.ini under
  PROGDIR:, dethrace executable must be in PROGDIR:, if not using "Custom" it
  will search for c1, c1demo, spdemo or spxmasdemo drawers from PROGDIR:.
- INI Mode:
  Modify ini and start dethrace icon, dethrace.ini must be in PROGDIR:.
- Command line mode:
  Read the docs and use the flags, better use a script and call it with
  Execute specifying at least "stack 1000000" before launching dethrace.
- Standalone:
  Put dethrace where your game is and use dethrace icon instead of using 
  CARMA.EXE, if you want to change some options enable USE_TOOLTYPES and 
  set other TOOLTYPES.

Four default drawers are already available:
- c1 -> Carmageddon or Carmageddon + Splat Pack or Carmageddon High Octane or
  Carmageddon Max Pack (at the time of writing, sold on GOG)
- c1demo -> Carmageddon original demo (downloadable from network)
- spdemo -> Splat Pack demo (default, a rare zombie demo is provided)
- spxmasdemo -> Splat Pack xmas demo (downloadable from network)

To play with dethrace "the standard way" you ONLY need DATA directory 
just put it in the correct drawer.


COMMAND LINE OPTIONS (single dash)
----------------------------------

These flags go directly to the game engine:

  -hires              Force 640x480 resolution mode
  -lores              Force 320x200 resolution mode (AROS only)
  -yon <number>       Yon factor, between 0 and 1 (0.5 default)
  -simple <number>    Car simplification level, 0 to 4
  -sound <number>     Sound detail level, 0 to 2
  -robots             Enable boring/zombie/robots mode
  -german             Same as -robots
  -lomem              Force low memory mode (reduced quality)
  -nosound            Disable all sound
  -spamfritter        Allocate extra 2MB for optimal spam frittering
  -nocutscenes        Skip intro and between-race cutscenes
  -noreplay           Disable replay recording
  -novoodoo           Disable 3DFX/Voodoo mode, force software renderer
  -vgraphics          Force Voodoo Graphics mode
  -vrush              Force Voodoo Rush mode

Example:
    dethrace -hires -robots -nocutscenes


COMMAND LINE OPTIONS (double dash)
----------------------------------

These flags control engine behaviour and platform features:

  --game <name>           Select game: c1, c1demo, spdemo, spxmasdemo
  --dir <path>            Custom game directory path
  --cdcheck               Enable original CD check
  --debug=<n>             Set debug verbosity level
  --fps=<n>               Frame rate limit (30, 40, 50, 60, 0=unlimited default)
  --freeze-timer          Freeze the game timer
  --no-signal-handler     Disable crash signal handler
  --demo-timeout=<n>      Demo timeout in seconds (240 default, 0=unlimited)
  --i-am-cheating         Enable cheat/edit mode
  --enable-diagnostics    Enable developer diagnostics
  --volume-multiplier=<n> Volume multiplier (1.0 default)
  --full-screen           Start in full screen mode
  --window                Start in windowed mode
  --gore-check            Enable original censorship/gore check
  --sound-options         Enable "Sound Options" menu screen
  --opengl                Enable 3DFX mode via OpenGL
  --game-completed        Mark game as completed
  --no-bind               Skip network socket binding

AROS-specific double-dash options:
  --audiofreq=<n>     Audio sample rate (8000, 11025, 22050, 44100, 48000)
  --audiobuf=<n>      Audio buffer size in frames (1024, 2048, ..., 8192)
  --audiochan=<n>     Audio channels (1 to 8)
  --preload-audio     Pre-load smacker video audio into memory (recommended on
slower I/O setup, use lot of memory)

Example:
    dethrace --dir c1 --fps=60 --window --audiofreq=22050 --preload-audio


ICON TOOLTYPES (AROS only)
--------------------------

Add these to the dethrace icon's ToolTypes:

  USE_TOOLTYPES       Must be present and enabled to enable reading other
ToolTypes (disabled by default)
  AUDIO_RATE=<n>      Audio sample rate (default 22050)
  AUDIO_BUFFER=<n>    Audio buffer size in frames (default 4096)
  AUDIO_CHANNELS=<n>  Audio channels (default 2)
  NO_CUTSCENES=<0|1>  1 = skip cutscenes
  FULLSCREEN=<0|1>    1 = full screen mode
  BORINGMODE=<0|1>    1 = boring/robots mode
  HIRES=<0|1>         1 = force 640x480
  3DFX                Enable OpenGL/3DFX mode
  LOWMEM_MODE         Enable low memory mode
  PRELOAD_AUDIO       Pre-load smacker video audio into memory (recommended on
slower I/O setup, use lot of memory)
  GAME=<name>         Game selection: c1, c1demo, spdemo, spxmasdemo
(dethrace.ini need to be present and correctly configured)
  DIR=<path>          Custom game directory (will use PROGDIR: by default)


INI FILE (dethrace.ini)
-----------------------

The GUI launcher reads and writes dethrace.ini from PROGDIR:.
You can also create and edit it manually. Example:

  [General]
  ; Enable original CD check
  CdCheck = 0
  
  ; Enable original censorship check
  GoreCheck = 0
  
  ; set to 0 to disable
  FPSLimit = 60
  
  ; Full screen or window
  Windowed = 1
  
  ; 3dfx mode (via OpenGL)
  Emulate3DFX = 0
  
  ; Censored zombie/robots mode
  BoringMode = 0
  
  ; Play cut scenes on startup and between races
  Cutscenes = 0
  
  ; "hires" mode is 640x480, otherwise default 320x200
  Hires = 1
  
  ; Only used in 'demo' mode. Default demo time out is 240s (4 mins)
  DemoTimeout = 240
  
  ; Which directory in the [Games] section to run
  DefaultGame = c1

  [Games]
  c1 = PROGDIR:c1
  c1demo = PROGDIR:c1demo
  spdemo = PROGDIR:spdemo
  spxmasdemo = PROGDIR:spxmasdemo

  [Sound]
  Enabled = 1

  [Gui]
  AudioRate = 22050
  AudioBuffer = 4096
  AudioChannels = 2
  LowMem = 0
  SpamFritter = 0

NOTES
-----

- You can switch from/to fullscreen any time using ALT+ENTER
- Mixing TOOLTYPES and .ini file can cause options collision as .ini file
  take precedence in most common options.
- For some versions of the game (like the rare demo included) "boring mode" 
  is enabled by default so enabling it will prevent game from starting.
- To have a quicker game start just disable cutscenes.
- For high-res mode (-hires), ensure DATA/64X48X8/ subdirectory exists.
- For 3DFX mode you need a game patched with 3DFX Patch. High Octane or
  Max Pack have it by default.
- Do not use GL/3DFX mode with software rendering, it will be unplayable.
- The GUI launcher (dethrace_gui) provides a user-friendly interface
  for configuring common options and use dethrace.ini to read/write them.
- The --preload-audio flag/TOOLTYPE loads all smacker video audio into 
  memory before playback, avoiding audio starvation during cutscenes. This
  is recommended on AROS where video decoding is slower due to slow I/O.
- On most recent non "GOG" versions (eg. High Octane, C1 + Splat Pack) you can 
  convert CD tracks to OGG and create a MUSIC drawer alongside DATA, dethrace 
  will use these files to play music tracks.