[WIP] XRacer - a racing gamexracer

Plan:
-----

A simple racing game like Pole Position or Enduro.

Status:
-------
 - Currently generates a random road and scrolls through it
 - Random road generation (curves and hills)
 - Supports loading of maps from a file ("/output.xrm")
 - Sample map at http://a.pomf.se/ynhlwq.xrm

Todo:
-----
 - Convert to fixed-point math in all places (only one place left!)
 - Improve/fix track looping
 - Improve random road generation to start and end at the same height
 - Finish sprite code
 - Make sprites
 - Game-ify!

What's new:
-----------
 - NEW: uses greylib on low-depth targets!
 - Loadable maps implemented, UNTESTED!
 - Sprites in progress (see render() in graphics.c)

Change-Id: Ia2ff60b3c43d9f2e3a4f63e0ad90d2cb571c605e

1 files changed, 79 insertions, 0 deletions

diff --git a/apps/plugins/xracer/README b/apps/plugins/xracer/README
new file mode 100644
index 0000000..8b6312c
--- /dev/null
+++ b/apps/plugins/xracer/README
@@ -0,0 +1,79 @@
+This file contains some quick notes about this plugin.
+======================================================
+
+Some useful links:
+------------------
+
+<http://codeincomplete.com/projects/racer/> - a very good tutorial on building a similar game in Javascript
+
+<http://www.extentofthejam.com/pseudo/> - excellent page on pseudo-3d
+
+Terminology:
+------------
+
+In the code, a "fixed-point" number is one that has a nonzero number of fractional bits.
+When dealing with these numbers, you must be careful to convert all operands to fixed-point, and use the correct function/macro to replace the operators.
+In the code, I've tried to make all fixed-point numbers of type 'long.'
+An "integer" is a number with zero fractional bits.
+
+(NOTE: I'm not sure if this "proper" terminology)
+
+Code structure:
+---------------
+
+generator.c: random map generator
+
+graphics.c: this is where almost all of the rendering takes place
+
+main.c: main loop
+
+sprite.c: static sprite data (offsets, dimensions)
+
+util.c miscellaneous functions, also contains FOV calculation code
+
+Proposed map formats:
+---------------------
+
+There will be two map formats: one that can be compiled into the executable ("Internal format"), and one that can be loaded from a file ("Interchange format").
+
+Internal format:
+----------------
+
+This format is represented as a series of struct road_section's.
+
+struct road_section {
+    uchar type;
+    uint32 len;
+    int slope;
+    long curve; // <<< this is fixed-point with 8 fracbits
+};
+
+'type' can be any of the following:
+ 0: constant segment - all 3 parameters used
+ 1: up-hill - an up hill is added. actual length is len + 2*slope due to enters and exits
+ 2: down-hill - a down hill is added. actual length is len + 2*slope due to enters and exits
+
+Endianness is platform-dependent in the Internal format.
+
+Interchange format:
+-------------------
+
+NOTE: all numbers are BIG-ENDIAN unless otherwise specified!
+
+This format is essentially the Internal format serialized into a file, but with some minor differences.
+
+File extension: .xrm
+
+Current format version number: 0x0000
+
+- File header - 8 bytes
+  - 0x00-0x04: 'XMaP'
+  - 0x05-0x06: version number (see above)
+  - 0x07-0x08: 0xFF padding
+- Data blocks - 15 bytes each (corresponds to the "sections" of the Internal format)
+  - 0x00     : type
+  - 0x01-0x04: length
+  - 0x05-0x08: slope (signed two's complement)
+  - 0x09-0x0C: curve (signed two's complement, fixed-point with 8 fractional bits)
+  - 0x0D-0x0E: CRC16-CCITT of data from 0x0-0xC
+  - 0x0F     : CRC high byte XOR CRC low byte