GRAND PRIX 2D - DOCUMENTATION (EN)
==================================

This documentation is written in plain ASCII so it can be read comfortably in MS-DOS / DOSBox without special character encoding setup.

CONTENTS
--------
1. What is Grand Prix 2D
2. Running the game
3. Controls
4. GPSETUP - game settings
5. Game files
6. Custom tracks and MAPEDIT
7. Map tile rules
8. AI waypoints and checkpoints
9. Car sprites
10. Sound files
11. Splash screen
12. Best time files
13. Tools
14. Recommended directory structure
15. Troubleshooting
16. Version notes


1. WHAT IS GRAND PRIX 2D
------------------------
Grand Prix 2D is a small retro racing game for MS-DOS / DOSBox.
The game is written in x86 assembly for TASM/TLINK and uses VGA mode 13h,
320x200 pixels with 256 colors.

The game supports:
- custom tracks through MAPEDIT,
- 1 to 3 AI opponents,
- separate sprites for the player and AI cars,
- configurable number of laps,
- configurable difficulty,
- sound ON/OFF,
- splash screen,
- 3-2-1-GO countdown,
- best time per track,
- WIN/LOSE race result.


2. RUNNING THE GAME
-------------------
Default run:

    GP2D.COM

Run a specific track:

    GP2D TRACK1.MAP
    GP2D TRACK2.MAP
    GP2D CITY.MAP

If no track name is given, the game uses:

    TRACK1.MAP

Before the first run, it is recommended to start the setup program:

    GPSETUP.COM


3. CONTROLS
-----------
W = accelerate
S = decelerate
A = turn left
D = turn right
Q = quit game

On the splash screen, intro screen, and result screen, press any key to continue.


4. GPSETUP - GAME SETTINGS
--------------------------
GPSETUP.COM creates and modifies:

    GP2D.CFG

Current options:

1 = number of laps: 1 to 9
2 = sound: ON / OFF
3 = AI opponents: 1 to 3
4 = difficulty: EASY / NORMAL / HARD
S = save settings
Q = quit setup

If GP2D.CFG does not exist or is invalid, the game uses default settings.

Recommended defaults:
- LAPS = 3
- SOUND = ON
- AI COUNT = 3
- DIFFICULTY = NORMAL

The countdown is always enabled and is not part of the setup menu.


5. GAME FILES
-------------
Main programs:

GP2D.COM       - main game
GPSETUP.COM    - game setup
MAPEDIT.COM    - track editor
PIXSPR.COM     - sprite editor

Main data:

TRACK1.MAP     - default track
TRTILES.TIL    - track tileset
GP2D.CFG       - game configuration
SPLASH.RAW     - 320x200 RAW splash screen image
SPLASH.PAL     - splash screen palette

Player car:

PCAR0.SPR      - player up
PCAR2.SPR      - player right
PCAR4.SPR      - player down
PCAR6.SPR      - player left

AI car 1:

CAR10.SPR      - AI1 up
CAR12.SPR      - AI1 right
CAR14.SPR      - AI1 down
CAR16.SPR      - AI1 left

AI car 2:

CAR20.SPR      - AI2 up
CAR22.SPR      - AI2 right
CAR24.SPR      - AI2 down
CAR26.SPR      - AI2 left

AI car 3:

CAR30.SPR      - AI3 up
CAR32.SPR      - AI3 right
CAR34.SPR      - AI3 down
CAR36.SPR      - AI3 left

Sound files:

ENIDLE.SND     - idle / low-speed engine
ENTHRTLL.SND   - driving engine sound
START.SND      - start / GO sound
CRASH.SND      - crash sound

Best time:

TRACK1.BST     - best time for TRACK1.MAP
TRACK2.BST     - best time for TRACK2.MAP

A BST file is created automatically for each track.


6. CUSTOM TRACKS AND MAPEDIT
----------------------------
Map format:

    40 x 25 tiles = 1000 bytes
    1 byte = tile value 0 to 15

Run the editor:

    MAPEDIT TRACK1.MAP
    MAPEDIT TRACK2.MAP

In the editor, tile values 10 to 15 are shown as hexadecimal characters:

    10 = A
    11 = B
    12 = C
    13 = D
    14 = E
    15 = F

When creating tracks, pay special attention to AI waypoints. AI cars follow the fixed route order.


7. MAP TILE RULES
-----------------
0  = grass / off-road, slows the player down
1  = asphalt / road
2  = curb / decoration or track edge
3  = wall / barrier, blocks player and AI
4  = player start / finish
5  = AI car start position
6  = checkpoint 1
7  = checkpoint 2
8  = checkpoint 3
9  = AI waypoint 1
10 = AI waypoint 2, shown as A
11 = AI waypoint 3, shown as B
12 = AI waypoint 4, shown as C
13 = AI waypoint 5, shown as D
14 = AI waypoint 6, shown as E
15 = AI waypoint 7, shown as F

Recommended rules:
- tile 4 should appear only once,
- tile 6, 7, and 8 should each appear only once,
- tiles 9 to 15 should each appear only once,
- tile 5 may appear one to three times depending on the number of AI opponents.


8. AI WAYPOINTS AND CHECKPOINTS
-------------------------------
The AI route is fixed:

    4 -> 9 -> A -> 6 -> B -> C -> 7 -> D -> E -> 8 -> F -> 4

Meaning:

4 = start / finish
9 = first AI point after start
A = second AI point before CP1
6 = CP1
B = point after CP1
C = point before CP2
7 = CP2
D = point after CP2
E = point before CP3
8 = CP3
F = point between CP3 and finish
4 = finish

AI does not perform real pathfinding. It moves from one target point to the next. Therefore, place waypoints so that there is a clear drivable route between neighboring points.

If an AI car hits a wall repeatedly, the most common reason is a badly placed waypoint or checkpoint.


9. CAR SPRITES
--------------
Sprites are 16x16 pixels.

Directions:

0 = up
2 = right
4 = down
6 = left

Transparent color index is 0.

Player car:
PCAR0.SPR, PCAR2.SPR, PCAR4.SPR, PCAR6.SPR

AI1:
CAR10.SPR, CAR12.SPR, CAR14.SPR, CAR16.SPR

AI2:
CAR20.SPR, CAR22.SPR, CAR24.SPR, CAR26.SPR

AI3:
CAR30.SPR, CAR32.SPR, CAR34.SPR, CAR36.SPR


10. SOUND FILES
---------------
The game uses simple SND files played through the PC speaker.

Used files:

ENIDLE.SND
ENTHRTLL.SND
START.SND
CRASH.SND

If SOUND = OFF in GPSETUP, the game does not use sound and the SND files are not required.

If SOUND = ON, these files must be present in the game directory.


11. SPLASH SCREEN
-----------------
The splash screen uses two files:

SPLASH.RAW = 320x200 image, 64000 bytes
SPLASH.PAL = 256-color palette, 768 bytes

At startup the game:

1. loads SPLASH.PAL,
2. sets the VGA palette,
3. loads SPLASH.RAW into video memory,
4. displays PRESS ANY KEY TO START,
5. waits for a keypress.

If SPLASH.RAW or SPLASH.PAL is missing, the game continues without the splash screen.



12. BEST TIME FILES
-------------------
The game creates a separate best time file for each map.

Examples:

TRACK1.MAP -> TRACK1.BST
TRACK2.MAP -> TRACK2.BST
CITY.MAP   -> CITY.BST

Best time is updated only when the player finishes the race.


13. TOOLS
---------
Recommended tool package:

MAPEDIT.COM  - track creation and editing
PIXSPR.COM   - sprite creation and editing
GPSETUP.COM  - game settings


14. RECOMMENDED DIRECTORY STRUCTURE
-----------------------------------
GP2D\
  GP2D.COM
  GPSETUP.COM
  MAPEDIT.COM
  PIXSPR.COM
  GP2D.CFG
  TRACK1.MAP
  TRTILES.TIL
  SPLASH.RAW
  SPLASH.PAL
  PCAR0.SPR
  PCAR2.SPR
  PCAR4.SPR
  PCAR6.SPR
  CAR10.SPR
  CAR12.SPR
  CAR14.SPR
  CAR16.SPR
  CAR20.SPR
  CAR22.SPR
  CAR24.SPR
  CAR26.SPR
  CAR30.SPR
  CAR32.SPR
  CAR34.SPR
  CAR36.SPR
  ENIDLE.SND
  ENTHRTLL.SND
  START.SND
  CRASH.SND
  README_SK.TXT
  README_EN.TXT


15. TROUBLESHOOTING
-------------------
Game shows file loading error:
- check that all required SPR, SND, MAP, and TIL files exist,
- if SOUND = ON, all SND files must exist,
- if using 3 AI cars, CAR30/32/34/36.SPR must exist.

Splash screen colors look wrong:
- SPLASH.PAL is missing,
- or RAW was created with a different palette than PAL.

AI drives into a wall or wrong direction:
- check waypoint order,
- there must be no wall between neighboring route points,
- CP1, CP2, and CP3 must be placed on the real driving route,
- tiles 9,A,B,C,D,E,F should each appear only once.

Game colors look wrong after splash screen:
- the game should reset VGA mode after the splash screen, but if this happens, check the palette restore / mode reset code.


16. VERSION NOTES
-----------------
Recommended current final branch:

GP2D v1.0
GPSETUP v1.3

Created by Martin Bela (FANTASY FOUNDRY) and with help of Artificial Inteligence.

