Licar/media/manual.txt

WORK IN PROGRESS

-._.-'"'-._.-'"'- LICAR MANUAL -'"'-._.-'"'-._.-

by drummyfish, released under CC0 1.0, public domain

~~~ GENERAL ~~~

Licar is a relatively simple 3D stunt racing game inspired by other popular
games of this genre. Unlike most games in existence, Licar is completely free
as in freedom (meaning its source code is available for any use), gratis, and
its focus lies on being well programmed by employing minimalism and rejecting
harmful "modern" programming practice. The game aims to seflessly bring
happiness to all people, even those who have no money, own only very old and
weak computers etc. It is not a commercial product and has been made purely out
of love by a single man.

The game runs on many platforms and comes in different versions depending on
what the platforms allow. Some versions may have more features or visual
"richness" than others. If anything mentioned in this manual is missing in your
game, it's probably because of limitations of your platform. On PCs and laptops
however everything should be supported.

~~~ RUNNING ~~~

There are compiled versions of Licar for many different platforms. If yours
is among them, running the game should be as simple as running any other
program.

If there isn't a version for your system or for some other reason you can't
run the game, you may try to compile the game yourself from the source code.
This is very easy (unlike with most "modern" software), it usually involves
typing a command in command line. For more detail check out the README.

Note that it's also possible to play the game in a web browser or through some
kind of compatibility layer or emulator if there is no native executable for
your system.

If you know what command line arguments are, you may also check them out by
running the game with -h argument. This will allow you to for example start the
game and immediately load a map, which is handy when creating new maps.

~~~ GAMEPLAY ~~~

In Licar, unlike in most other racing games, you only race against time, i.e.
you are alone on the track. There is an option to race against a replay ghost,
but the ghost still cannot collide with your car, so the point remains that your
final time depends purely on how well you drive, opponents cannot spoil your
results by crashing with you or blocking your path.

The objective of every map is to drive from start to finish (red octahedron) as
fast as possible while collecting all the checkpoints (CP, green octahedron)
along the way (in any order). There is always a target time which you're trying
to beat in the bottom left of the screen. If you beat the time, you have
achieved the goal, your replay is automatically saved and your new time becomes
the next target time.

On the map there can be several different kinds of surfaces with different
physics properties: concrete, grass, dirt and ice. Furthermore there are two
special kind of sufaces: an accelerator (a bright yellow/orange one), which
boosts the car's speed, and a fan, which propels the car upwards.

Your run can be restarted at any time. Typically you will need hundreds of
attempts to achieve a good time on a map.

During the run the game also displays additional info such as your current
speed, times at checkpoints etc.

~~~ CONTROLS ~~~

Controls are extremely simple. The car is only controlled by 4 directional
keys: up (accelerate), down (deccelerate, reverse), left (steer left) and
right (steer right). There are two additional keys, A and B (depending on your
platform these may be e.g. the K and L letter or RETURN and SPACE keys), for
restarting runs and handling menu.

PRO TIP: pressing brake while in air stops the car's horizontal rotation!

~~~ DATA FILE ~~~

The game uses so called data file to store data such as maps and replays (if the
platform allows it). The file is usually located in the same directory as the
game and is called just "data". It's a single text file, so it can be opened in
any plain text editor. If you just want to casually play the game, you may
safely ignore the file. You will need to edit the file if you want to add new
maps and replays, or if you want to share your replays and maps with others.

The file consists of data items -- an item represents a map, replay, and
possibly other types of data. The items are separated by the '#' (hash)
character. Each item is stored in plaintext format, there are no binary data.
Each item starts with a magic number, which is a single character ('M' for a
map, 'R' for a replay), then its name follows immediately, terminated by the
';' (semicolon) character, and then the item's data follow. Format of this data
depends on what data it is, so map data of course have a different format than
replay data. For example a map named "mymap" will start with "Mmymap;".

~~~ CONFIGURATION ~~~

The game offers a very high level of configuration and customization. Very basic
settings (such as turning the music off or switching between windowed and
fullscreen mode) are accessible either in the game menu, or as a commandline
flag (run the game with -h flag to see the options). All other settings,
however, are kept at the source code level and so changing them requires
recompiling the whole game from source code (which is nonetheless very simple).
All user settings, along with their descriptions, are located in the settings.h
source file. The game also comes in several precompiled versions with different
settings.

~~~ REPLAYS ~~~

If your platform supports it, Licar can save and play back recorded runs as
"replays" (sometimes also called "demos"), which are just exact records of game
inputs (so that replays, unlike videos, take very little space). Replays can
also be used to spawn a ghost car to race against.

Replays are saved in the data file.

Whenever a map's target time is beaten, replay is automatically saved. It's also
possible to save a replay manually by opening the menu and selecting
"save replay".

~~~ GHOSTS ~~~

The game supports ghost cars to race against (note that this may be unsupported
on some weaker platforms). A ghost car is created from a replay and will race
in real time against the player, without being able to collide with him. This is
very useful when attacking someone else's (or one's own) achieved time, to see
where exactly time losses against the opponent occur.

~~~ MAKING CUSTOM MAPS ~~~

Maps are stored in the data file. For its simplicity the original game doesn't
come with a user-friendly map editor, the maps are hand-written directly in the
text format that's stored in the data file, however there is a helper file for
Blender that facilitates this process.

The map is a 64x64x64 grid, with each cell one unit in width, one unit in depth
and half a unit in height. In the cell blocks can be placed. There are several
types of blocks such as ramps, walls, corners etc. Each block can be rotated
and/or flipped. Additionally each block also has a material (concrete, grass,
...). The finish, checkpoints and car start position can also be seen as block.

The format of the map data string is described in the map.h file, refer to it
for further detail. In short: TODO



Under the asset directory there is a helper file for Blender (a FOSS 3D editor)
with which a map layout can be comfortably created. But Blender is not required
for map making, you can easily draw the map layout on a grid paper for example,
or -- for simpler maps -- it may be possible to just imagine them in one's head.

The "workflow" for making maps is roughly the following:

1. Drawing the map (in Blender, on paper, ...).
2. Rewriting this to the map text format in the data file. The edited map should
   be the very last item in the data file so that it can be quickly loaded with
   the -M command line argument.
3. Testing the map in game. This is easily done by running the game with -M
   argument (and possibly also other arguments, e.g. to start with free camera)
   to instantly load the edited map. If something needs changing, we return to
   1. or 2.

~~~ FAQ ~~~

Q: Why is the physics so buggy?

A: You are right in the observation that Licar physics is not perfect. This is
firstly because of the game's aim for simplicity (e.g. avoiding use of floating
point) combined with the fact that even without such constraints it's one of the
most difficult tasks to create a flawless physics engine. We apologize for any
frustration but unless you want to fix this yourself, you'll have to just accept
it, the game is meant to be a simple entertainment. In other words this is a
feature :)