Documentation: Create texture_packs.txt

Combine texture_overrides.txt and sections of lua_api.txt

1 files changed, 77 insertions, 0 deletions

diff --git a/doc/texture_packs.txt b/doc/texture_packs.txt
new file mode 100644
index 000000000..44871ebba
--- /dev/null
+++ b/doc/texture_packs.txt
@@ -0,0 +1,77 @@
+Minetest Texture Pack Reference
+===============================
+
+Texture packs allow you to replace textures provided by a mod with your own
+textures.
+
+Texture pack directory structure
+--------------------------------
+
+    textures
+    |-- Texture Pack
+    |   |-- screenshot.png
+    |   |-- description.txt
+    |   |-- override.txt
+    |   |-- your_texture_1.png
+    |   |-- your_texture_2.png
+    `-- Another Texture Pack
+
+### Texture Pack
+This is a directory containing the entire contents of a single texture pack.
+It can be chosen more or less freely and will also become the name of the
+texture pack. The name must not be “base”.
+
+### `description.txt`
+A file containing a short description of the texture pack to be shown in the
+texture packs tab.
+
+### `screenshot.png`
+A preview image showing an in-game screenshot of this texture pack; it will be
+shown in the texture packs tab. It should have an aspect ratio of 3:2 and a
+minimum size of 300×200 pixels.
+
+### `your_texture_1.png`, `your_texture_2.png`, etc.
+Any other PNG files will be interpreted as textures. They must have the same
+names as the textures they are supposed to override. For example, to override
+the apple texture of Minetest Game, add a PNG file named `default_apple.png`.
+
+The custom textures do not necceessarily require the same size as their
+originals, but this might be required for a few particular textures. When
+unsure, just test your texture pack in-game.
+
+Texture modifiers
+-----------------
+
+See lua_api.txt for texture modifiers
+
+Texture Overrides
+-----------------
+
+You can override the textures of a node from a texture pack using
+texture overrides. To do this, create a file in a texture pack
+called override.txt
+
+Each line in an override.txt file is a rule. It consists of
+
+	nodename face-selector texture
+
+For example,
+
+	default:dirt_with_grass sides default_stone.png
+
+You can use ^ operators as usual:
+
+	default:dirt_with_grass sides default_stone.png^[brighten
+
+Here are face selectors you can choose from:
+
+| face-selector | behavior                                          |
+|---------------|---------------------------------------------------|
+| left          | x-                                                |
+| right         | x+                                                |
+| front         | z-                                                |
+| back          | z+                                                |
+| top           | y+                                                |
+| bottom        | y-                                                |
+| sides         | x-, x+, z-, z+                                    |
+| all           | All faces. You can also use '*' instead of 'all'. |