diff --git a/README b/README
deleted file mode 100644
index 6dde1ae..0000000
--- a/README
+++ /dev/null
@@ -1,3 +0,0 @@
-WIP Pokitto raycasting demo
-
-raycastinglib is needed (can be found among my repos) - simply drop the .h file in the same directory as the program and compile.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5dec3fb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,41 @@
+# Pokitto Ray Casting Demos
+
+These are demos showing ray casting (pseudo) 3D rendering technique using
+raycastlib (a Pokitto-independent C library I made along with this project) on
+a small gaming console Pokitto.
+
+There are these demos:
+
+- helloRay: Hello world program showing the very basic usage of raycastlib
+  on Pokitto. If you want to learn about the code, start here.
+- demo1: Showoff RPG-like program demonstrating most raycastlib features.
+- demo2: Classic "flat/1D" ray casting program in a sci-fi mood.
+- demo3: Minecraft-like demo with procedurally generated editable world.
+
+Included are also other tools I created, such as Python scripts for image
+conversion to the format I use. Everything should be sufficiently commented.
+
+The last three demos use common definitions from the general.hpp file. This
+file contains some useful resources that you can use in your own game. You can
+of course as well create a game by expanding any of the demos.
+
+There are a lot of compile-time options you can try out, like turning various
+effects on/off, setting the rendering quality etc. Check out the defines at
+the beginning of each source code file.
+
+This repository contains the version of raycastlib that I tested the demos
+with, but you can find the most recent version of the library among my other
+repositories.
+
+The demos use display Mode13, i.e. 110x88 with 256 colors. I recommend you use
+this mode for your games, but the other ones are an option too. I created a
+custom general 256-color HSV-based palette that allows for fast brigtness
+manipulation of colors, which is important for fog/dimming. Reusing this
+palette (or modifying it) will most likely be the best option for your project.
+
+# License
+
+Everything is under CC0 1.0, including all the assets (they are mostly based on
+CC0 images I found at OpenGameArt). I always appreciate credit, but it's not
+required. More than credit I appreciate if you share your own software as free
+and open-source. With that said, use this in any way you want.