==--------------------------------------------------------------------------==
                               OUTRUN: AMIGA EDITION

                       Program Code: Reassembler [2023-2025]
                             reassembler68k@gmail.com

                  YouTube: https://www.youtube.com/@reassembler68k
                  Discord: https://discord.com/invite/u94mmuCzgB
==--------------------------------------------------------------------------==

 OutRun is a trademark of the SEGA Corporation. This project is not affiliated
 with SEGA in any way.

 Redistributions may not be sold, nor may they be used in a commercial product
 or activity.

 Audio tracks may be reused in non-commercial projects, if credit is provided.

 There is no warranty for the software. It is delivered with the best
 intentions, but as always with software obtained from the internet, please
 be cautious.

 Amiga Port (c) Copyright Chris White. All Rights Reserved.


=----------------------------------------------------------------------------=
 > What is this?
=----------------------------------------------------------------------------=

 This is an optimized port of SEGA's 1986 arcade game OutRun, utilizing the
 original 68000 assembly code, to mid-spec Commodore Amiga computers.

 Whilst small compromises have been made to accommodate differences between
 the arcade hardware and the Amiga - this looks and plays almost identical
 to the original.

 It is not based on Cannonball, MAME or any previous project. It is a
 ground up rewrite in assembler, with a focus on performance.

 I hope you enjoy speeding down Coconut Beach with Magical Sound Shower
 booming away, as much as I have over the years.

 If you're interested in how this works under the hood, please subscribe to
 my YouTube channel, where I'll be releasing a 'Making Of' series of videos
 and releasing accompanying source code later in the year, so you can code
 along at home. Link: https://www.youtube.com/@reassembler68k


=----------------------------------------------------------------------------=
 > Hardware Requirements
=----------------------------------------------------------------------------=

 Minimum:
   * 68030 Processor @ 50 Mhz
   * PAL Machine
   * AGA Chipset
   * 2MB Chip RAM
   * 8MB Fast RAM
   * Hard drive

 Optional:
   * 2 Button Joystick/Pad
   * CD32 Compatible Gamepad

 Recommended:
   * 68040 Processor @ 25 Mhz
   * Fast RAM capable of 25 MB/s or better (+)

 The hardware requirements are relatively beefy to compensate for the power
 of the custom graphics hardware in the original arcade boardset. Much of
 this hardware, including the sprite scaling, is replicated in software
 due to differences in the Amiga's graphics architecture. As a point of
 comparison, the arcade sprite hardware had a framebuffer fill-rate of
 92 MB/s (!)

 (+) In testing, performance can be bottlenecked by poor RAM speeds. If your
 'Fast' RAM is slower than 25 MB/s in transfer speed, this will hinder
 performance. The latest version of Sysinfo can verify your RAM speed:
 https://sysinfo.d0.se/ [4.5 Beta 12]

 In short, a 25Mhz 040, with adequate Fast RAM will run at a full 25fps.


=----------------------------------------------------------------------------=
 > Installation
=----------------------------------------------------------------------------=

 This port uses the original graphics and audio data from the arcade ROMs.
 The data is identical between different revisions of the ROMs, so any
 version should suffice.

 The copyright for these resides with SEGA, so you'll have to source them
 yourself. They are not included.


 -> Step 1. Obtain the ROMs <-
 -----------------------------

 The following files should be copied to the 'in' subdirectory of this
 package. All files will be CRC checked for correctness:

 opr-10268.99    - Tile ROMs   [Background graphics]
 opr-10232.102
 opr-10267.100
 opr-10231.103
 opr-10266.101
 opr-10230.104

 opr-10185.11    - Road ROM    [Road graphics]

 mpr-10371.9     - Sprite ROMs [Scenery & cars]
 mpr-10373.10
 mpr-10375.11
 mpr-10377.12
 mpr-10372.13
 mpr-10374.14
 mpr-10376.15
 mpr-10378.16

 opr-10193.66    - Sample ROMs [Sound Effects]
 opr-10192.67
 opr-10191.68
 opr-10190.69


 -> Step 2. Convert the ROMs <-
 ------------------------------

 The ROMs must be converted to a format suitable for the Amiga port with the
 included Python script.

 a. Install Python:  https://www.python.org/downloads/
 b. Ensure Python is in your system path by typing 'python -h' from the
    command line.
 c. Install Numpy:   'pip install numpy'
 d. Install Librosa: 'pip install librosa'
    (The above two libraries are used in the audio conversion process)
 e. Run the included script:  'python amiga_rom_exporter.py'
 f. If all is successful, you will have newly created files in the 'gfx' and
    'audio' subdirectories.
 g. The original ROMs can now be disregarded. They are not needed.
 
 Mac users: I'm informed that you might need to type 'python3' instead of
 'python'.


 -> Step 3. Copy the Files! <-
 -----------------------------

 Transfer the folder structure, excluding the ROMs, to a folder on your Amiga.

 I'd recommend running the game from the Workbench Shell the first time.
 This will ensure useful error messages are visible, if there's a problem.

 * If you have problems with the game freezing when run from the OS, reboot
   without startup-sequence, run SetPatch, then launch the game.

 * Shutdown your network drivers (Roadshow, Envoy etc.)

 * Some, but not all, network cards have also caused crashes and issues.

 IN SHORT, IF YOU HAVE PROBLEMS - ENSURE YOU ARE RUNNING A MINIMAL SETUP!


=----------------------------------------------------------------------------=
 > Controls
=----------------------------------------------------------------------------=

 The game can be played on a Keyboard or a Joystick/Pad, or even a combination
 of the two.

 Controls can be configured from the SETTINGS -> CONTROLS menu.

 The menu includes:
 - A control test utility to ensure your input devices are working.
 - Joypad Port Selection
   (usually port 2, but port 1 can be configured instead).
 - The number of buttons your pad has, mostly to avoid mapping the gear change
   to 'down' on 3+ button pads.
 - The ability to disable joypads in-game (for either a minor speed increase,
   or to avoid reading the ports if you have other peripherals connected).
 - Automatic Gear Shift / Manual Gear Shift selection.


 Option 1 - Keyboard        [Always enabled]
 ------------------------------------------------------------------
   * Arrow Keys: Steering & Menu navigation
   * Z         : Accelerate / Select / Start
   * X         : Brake
   * Space     : Gear Shift
   * Left Shift: Gear Shift (Alternate)
   * F1        : Enable AI / Autoplay
   * F2        : FPS Counter Toggle
   * P         : Pause Game
   * Escape    : Return To Menu

   Left Shift is also supported as a gear shift, due to hardware
   issues with simultaneous keypresses on the A1200 keyboard.

 Option 2 - 3+ Button Pad   [e.g. CD32 Compatible pad]
 ------------------------------------------------------------------
   * Left/Right: Steering
   * Up/Down   : Menu navigation
   * Red       : Accelerate / Select / Start
   * Blue      : Brake
   * Green     : Gear Shift

  On CD32 pads, the shoulder buttons are also mapped to accelerate/brake as
  an alternate control scheme.

 Option 3 - 2 Button Pad    [e.g. Megadrive / Master System pad]
 ------------------------------------------------------------------
   * Left/Right: Steering
   * Up/Down   : Menu navigation
   * Fire 1    : Accelerate / Select / Start
   * Fire 2    : Brake
   * Down      : Gear Shift

 Option 4 - 1 Button Pad    [e.g. Original Amiga joystick]
  ------------------------------------------------------------------
   * Left/Right: Steering
   * Up/Down   : Menu navigation
   * Fire 1    : Accelerate / Select / Start
   * Up        : Gear Shift
   * Down      : Brake

 Note: if you physically change controllers after the game has booted, it's
 best to enter the SETTINGS -> CONTROLS -> JOYPAD TEST menu to ensure they
 are redetected.


=----------------------------------------------------------------------------=
 > Gameplay Options
=----------------------------------------------------------------------------=

 The original arcade game predominantly runs at 30fps, with the exception of
 the background tilemaps, which scroll at 60fps.

 This version is capped at 25fps, as dictated by the 50Hz PAL video standard.

 There is a menu option to run at 30fps, but this requires a much faster CPU
 to perform well - as it effectively relies on being able to generate frames
 twice as quickly for that small increase in frame-rate.

 Therefore, leave the FPS setting at 25, unless you're playing on modern
 hardware (A600GS / A500 Mini / PiStorm etc.)
 
 There are some new gameplay options in this version, not present in the
 arcade. These are disabled by default:
 
 1/ Rolling Stop  : Gradually come to a stop when the timer expires...
 2/ Turbo Speed   : Top speed is boosted by around 50km/h!
 3/ Offroad Tyres : Drive off-road with no slowdown!
 4/ Grippy Tyres  : Very easy cornering!
 5/ Bumper Cars   : Smash into other traffic with less impact!


=----------------------------------------------------------------------------=
 > Audio
=----------------------------------------------------------------------------=

 Music can be selected, as per the arcade, at game start by steering. The game
 plays with music and a limited selection of sound effects. The music is newly
 composed specifically for this project.

 However, if you press up during the music select, you'll invoke a sound
 effects only mode, which provides a full suite of effects.

 The included MOD files are in standard 4 channel ProTracker format. They can
 be replaced with MODs of your choosing, should you wish.


=----------------------------------------------------------------------------=
 > Feature Set
=----------------------------------------------------------------------------=

 Sprite Hardware:
 * Realtime Sprite Scaling (both shrinking and expanding)
 * Horizontal Flipping
 * Translucent Shadows

 Road Hardware:
 * Dual Road Layer with variable road width and undulation
 * Palette Fade Support Between Levels

 Tile Hardware:
 * 2 x independently scrolling tile layers

 Many small bugs fixed from the original arcade codebase:
 * Timing fixes to the player facing lap timers, on checkpoint and in general
   (these are also fixed in the recent Nintendo Switch/3DS ports)
 * Fixes to sprite zooming
 * Incorrect palette usage on some end sequences
 * Visual defects on music select and course map screens


=----------------------------------------------------------------------------=
 > Known Limitations & Compromises
=----------------------------------------------------------------------------=

 AGA supports 256 simultaneous colours, excluding Copper driven manipulation,
 whereas the original hardware supports many thousands. Some palettes have
 been changed as a result.

 Some stages have had subtle reductions in scenery to compensate for software
 sprite scaling.

 The visible play area has been vertically reduced to offload Chunky to
 Planar conversion time, which is incredibly expensive from a computational
 standpoint.

 Traffic density can't be set as high as the arcade version.

 The Amiga's audio hardware is obviously very different, but that probably
 doesn't need to be called out!


=----------------------------------------------------------------------------=
 > Compatibility
=----------------------------------------------------------------------------=

 Successfully tested on the following hardware:

 Hardware    | Accelerator Card            | Notes
 ------------+-----------------------------+-------------------------------
 * A1200     | TerribleFire TF1230         | Minimum Playable Spec
 * A1200     | Blizzard 1230 III w/ FPU    | ~25% faster than the TF1230
 * CD32      | TerribleFire TF030          | ~2fps faster than A1200/TF1230
 * A4000     | Default Commodore 040 Card  | Slow due to Fast RAM access
 * A4000     | Cyberstorm MK2 060          | Full speed @ 25 fps
 * A500 Mini | n/a                         | Full speed @ 30 fps
 * A600GS    | n/a                         | Full speed @ 30 fps
 * A1200     | PiStorm32 Lite Model 4      | Full speed @ 30 fps
 * A1200     | Vampire 1200 V2             | Full speed @ 30 fps
 * MIST      | n/a                         |
 * MiSTer    | Minimig Core                | config.txt - Set force_akiko=1

 Successfully tested with the following Kickstart versions:

 * Kickstart 3.0 rev-39.106
 * Kickstart 3.1 rev-40.68
 * Kickstart 3.1 rev 40.70
 * Kickstart 3.1.4 (Hyperion)
 * Kickstart 3.2.1 (Hyperion)
 * Kickstart 3.2.2 (Hyperion)
 * Kickstart 3.2.3 (Hyperion)
 * Kickstart 3.9 (Homebrew)

 A note on CD32 hardware:

 As of v0.9.1, there is support for the Akiko chip contained in the CD32.

 If the chip is detected, there will be an additional AKIKO option in the
 SETTINGS menu. By default, this will be set to the optimal mode at startup,
 which is ON for 030 or slower CPUs, and OFF for faster CPUs.

 From testing, the Akiko provides a small performance boost for 030 CPUs, but
 becomes a hinderance once you have an 040 or faster CPU.

 The default setting should be the best one, so if you're unsure leave things
 as-is.


=----------------------------------------------------------------------------=
 > Credits & Thanks
=----------------------------------------------------------------------------=

* Frank Wille (VASM & PTPlayer)
* Jeroen Knoester (AudioMixer)
* Olav Sorensen (PT2 Clone)
* JOTD (Joypad Code)
* Michael "TAWS" Rupp & Ola "4pLaY" Stokka (Testing & Feedback)


=----------------------------------------------------------------------------=
 >  ¯\_(ツ)_/¯
=----------------------------------------------------------------------------=

Q/ What's the point of this? I can just play OutRun in MAME! You suck!

A/ Us old men need our silly hobbies. Hobbies aren't supposed to make any
   rational sense. Just be pleased I'm happy and not drooling on you.


Q/ This is cheating! It doesn't run on an A500 in 512K of Chip RAM!
   You suck and I will be letting the entire Internet and possibly Commodore
   law enforcement know!

A/ The goal is arcade perfection, not an interpretation. The arcade hardware
   is substantially more powerful than a stock A500, and there's no way the
   original game would run without serious compromises. There's an A500
   version waiting to be made, but it will surely be quite different...


Q/ Yeah, but I've seen demos where the Amiga handles 5 million colours,
   realtime raytraces a terrapin, plays 32 simultaneous channels of audio and
   rides a unicycle. You suck!

A/ Many demos do one or two things exceptionally well, but in isolation.
   A game engine has to perform many tasks simultaneously, so some of those
   techniques become very hard or impossible to utilise successfully. Also,
   these are no longer really questions!


=----------------------------------------------------------------------------=