Licar/media/manual.txt

WORK IN PROGRESS

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

  libre racing video game 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 the genre such as Trackmania and Stunts. Unlike mainstream video games,
Licar is completely libre, i.e. free as in freedom (meaning its source code is
available for any use whatsoever), gratis (free of cost) and its focus lies on
being well programmed by utilizing minimalism and rejecting harmful "modern"
programming practice. The game aims to seflessly bring joy and entertainment to
all people who might enjoy it, even those who have no money, own only very old
and weak computers and so on. It is not a commercial product and has been made
purely out of love by a single man. Licar is also more than a game, for example
it can be used for educational purposes or as a basis for new projects.

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, the player always only attempts
time attacks, i.e. you only race against time with no physical opponents on the
track with you. There is an option to race against a replay ghost, but that
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 ESCAPE keys), for
restarting runs and handling menu.

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

~~~~~ DATA FILE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Where supported, the game uses a so called data file to store data such as maps,
replays, information about map completion etc. On platforms that don't support
the feature the game still has its own internal data file with very basic maps,
so that there is still "content" to play, but it won't be possible to add new
maps or save replays. If the feature IS supported, the game will use a file
that's usually located in the same directory as the game's executable and which
is called just "data". It's a single text file, and so it's possible to open it
with 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, and those
with at least basic programming skill will be able to implement any changes
imaginable. 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.

In the game a map is represented as 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. The
map will be made of these blocks.

Each placed block can additionally be transformed: rotated by multiples of 90
degrees along vertical axis and/or flipped horizontally/vertically. Additionally
each block also has a material (concrete, grass, ...). Special kinds of blocks
are accelerators and fans. The finish, checkpoints and car start position can
also be seen as a special kind of block. And still, there are yet "more special"
kinds of (pseudo)blocks that are not real blocks but rather "commands" that do
something with the blocks (such as duplicating given block certain number of
times in a row) -- these only appear in the map's text format; they are not
necessary, but greatly help making maps faster and also keep their code smaller.

The text format of the map is described in the map.h file, refer to it for
details you won't find here. In summary:

First, if the map is preceded by another data string in the data file, remember
to start it with the `#` character (to separate it from the previous string).
Then there must be the letter `M` (for map), and the immediately the map's name
terminated with `;`. For example a map named "mymap" will in the data file
start with "#Mmymap;". Then the map string itself follows.

This string starts with a decimal number saying the target time in physics
ticks, then a space (` `) follows, then a single digit saying the map
environment (`0`, `1` or `2`), and then the string of map blocks follows.

Each map block starts with `:`, then immediately follows the type of the block
(these types are documented in map.h file), then exactly 3 coordinate characters
follow. Each coordinate is a number 0 to 63 encoded by a single character like
this:

0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ$@

I.e. number 11 will be encoded as `b` etc. After the coordinates an optional
decimal digit MAY follow, which defines the block material (`0`, `1`, `2` or
`3`, `0` being default). Finally there MAY follow the transformation string,
which may consists of characters `|` (flip horizontally), `-` (flip vertically),
`L` (rotate by 90 degrees), `I` (rotate by 180 degrees and `J` (rotate by 270
degrees). For example ":^5dA1-L" represents a ramp (`^`) placed on coordinates
5, 13, 36, having material 1 (grass), flipped vertically (`-`) and rotated by
180 degrees (`I`).

Note that the blocks may be separated by any characters that aren't `:` so that
it's possible to format and comment the map code.

Very important is the special "cuboid fill" pseudoblock that's identified by
type `f`. This will take the previously defined block B (which however MUST be a
"normal" block) and will create a filled cuboid of blocks B, starting at B's
position, with the size given by the `f` block's coordinates. For example
":=123 :f456" will create a 4x5x6 cuboid of full blocks (`=`) whose
bottom-left-front edge lies at coordinates 1, 2, 3. There are more special block
blocks like this (see map.h). This is mostly how floors, walls and ceilings are
made.

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, with Lego, ...).
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 ones, e.g. -c3 to start with free camera)
   to instantly load the edited map. If something needs changing, we return to
   1. or 2.

A few tips for making maps:

- Placing "none" blocks deletes previously placed blocks, which can come in
  handy for making holes etc. Sometimes it's much easier to created by
  subtracting than adding up smaller parts.
- The special "end" block can be used to exclude anything written after it. This
  is useful for temporarily hiding already finished parts of the map to make it
  load faster while working on other parts.
- Another way of temporarily disabling blocks is "commenting" them, i.e.
  replacing the starting `:` character with let's say `_`. Replacing `_` to `:`
  back again will reenable these blocks.
- It's very good to format and comment the map code. Group related structures
  together, separate the groups by empty newlines etc.
- Mind performance, too many too complex blocks will likely make the map load
  very slowly and/or decrease FPS and/or even make it not load due to memory
  constraints. Remember the game is using a simple software renderer (no GPU),
  so it won't be able to smoothly render 100 thousand triangles. Be especially
  careful about large structures created with the cuboid fill blocks, as the the
  volume of such structure grows with the cube of the side length. When a map is
  loading, the game removes (culls) invisible triangles, but for this it
  basically has to check every triangle against every other triangle, i.e. the
  time needed to load the map slows down quadratically with the number of
  triangles.
- Triangles can be saved by cleverly using simpler types of blocks where
  possible, for example walls can be made with rotated ramps rather than full
  blocks, which for a long wall may reduce triangle count considerably while
  not even being noticed by the player.
- There is a special "mirror" block that's very useful for creating
  8-symmetrical structures.

~~~~~ COMPILING AND MODIFYING ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Mods are highly recommended to be distributed as diff files that will apply
changes to the source code. This is inspired by suckless programs.

TODO

~~~~~ FAQ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Q: Is this game really free? Do I have to pay for it? What can I legally do with
it? Can I use it commercially? What's the catch?

A: This game is public domain, free as in freedom and free as in beer, i.e. it
is free software (some would say "open source", which is however a very bad
term), you have its source code and you can do anything with it, without
having to pay anything. You can play it, study it, modify it, share it, even
sell it, all without any conditions whatsoever. You don't even have to give
credit to the original author, although it's always appreciated. This is all
granted by the CC0 waiver under which the game is released. Practically the only
thing you "cannot" do is to claim that you made it and that you hold copyright
on it, preventing others from using it freely. If you liked the game, you may
thank the author, send him a donation or do whatever you like, but none of can
be "enforced" legally, and neither are you pressured to it morally. There is no
catch to this, the project wasn't made as a capitalist product, it's something
that's meant to help the people.

Q: Can I still voluntarily donate money?

A: Currently it is possible, donation info is on my website (www.tastyfish.cz),
but I am not dependant on donations and don't even encourage them too much, but
if you still insist, I'll be very grateful, thank you very much.

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 :)

Q: I have some other question (such as "Why is this not written in a modern
language?" or "What inspired you to make the game?" etc.)

A: Many questions I often get asked about my life philosophy and opinions can't
now be answered shortly. I have a website at http://www.tastyfish.cz. If you
don't find the answer there, my email is currently drummyfish@disroot.org, feel
free to ask me anything, but please remember I am not very social and don't
enjoy too much engaging in smalltalk or lengthy discussions about worldviews
etcetc.