Continue manual

TODO.txt

@@ -40,14 +40,11 @@
     - U-ramp to build speed and jump up to catch a CP (done)
     - jump through air ring with CP
 - try to speed up the slow culling
-- make a small txt game manual
 - test:
   - long replay
   - replay stretching works
   - replay with input not occuring for more that LCR_SETTING_GHOST_STEP
 - replay validation
-- maybe each map could have a target time embedded: when beaten, the map would
-  be marked as such
 - make the racing module usable by itself, e.g. to allow making tools for
   verifying replays etc., i.e. make the module measure time, count checkpoints
   etc.
@@ -67,6 +64,9 @@
 
 - sometimes getting a SLIGHTLY slower time counts as beating it (prolly
   conversion fail) (SEEMS FIXED NOW)
+- make a small txt game manual
+- maybe each map could have a target time embedded: when beaten, the map would
+  be marked as such
 - on tiny map 1 maybe add a few block below the first sharp ramp to prevent
   those nasty piercing bugs
 - replays are bugged, seem to not steer

map.h

@@ -16,7 +16,7 @@
   The TEXT format serves for editing maps in human readable format, it more or
   less corresponds to the binary storage format (below) with some exceptions.
   It has the following structure:
-    - Target time as a decimal number of milliseconds.
+    - Target time as a decimal number of physics ticks.
     - Non-decimal character.
     - Number of environment (0, 1, 2, ...)
     - A series of block strings. Blocks may be preceded/followed by characters
@@ -729,8 +729,9 @@ uint8_t LCR_mapLoadFromStr(char (*getNextCharFunc)(void), const char *name)
 
   _LCR_mapComputeHash();
 
-  LCR_LOG1("map loaded, block count:")
+  LCR_LOG1("map loaded, block count/hash:")
   LCR_LOG1_NUM(LCR_currentMap.blockCount)
+  LCR_LOG1_NUM(LCR_currentMap.hash)
 
   LCR_mapReset();
 

media/manual.txt

@@ -8,13 +8,13 @@ by drummyfish, released under CC0 1.0, public domain
 
 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 libre,
-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 employing
-minimalism and rejecting harmful "modern" programming practice. The game aims to
-seflessly bring happiness to all people who might enjoy it, 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. It is also more
-than a game, for example it can be used for educational purposes.
+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 employing minimalism and rejecting harmful "modern" programming practice. The
+game aims to seflessly bring happiness to all people who might enjoy it, 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. It is
+also more than a game, for example it can be used for educational purposes.
 
 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
@@ -137,14 +137,61 @@ 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.
+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.
 
-The format of the map data string is described in the map.h file, refer to it
-for details. In short: TODO (also small example)
+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
@@ -162,8 +209,49 @@ The "workflow" for making maps is roughly the following:
    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.
+
 ~~~ FAQ ~~~
 
+Q: This game is 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: Why is the physics so buggy?
 
 A: You are right in the observation that Licar physics is not perfect. This is
@@ -174,9 +262,13 @@ 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.
+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: 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.
+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.