shuffle and reorganize documentation

README.md

@@ -6,9 +6,75 @@ A mod for [minetest](http://www.minetest.net)
 
 ![](https://github.com/mt-mods/technic/workflows/integration-test/badge.svg)
 
-
 # Overview
 
+The technic modpack extends the Minetest game with many new elements,
+mainly constructable machines and tools.  It is a large modpack, and
+tends to dominate gameplay when it is used.  This manual describes how
+to use the technic modpack, mainly from a player's perspective.
+
+The technic modpack depends on some other modpacks:
+
+*   the basic Minetest game
+*   mesecons, which supports the construction of logic systems based on
+    signalling elements
+*   pipeworks, which supports the automation of item transport
+*   moreores, which provides some additional ore types
+*   basic_materials, which provides some basic craft items
+
+This manual doesn't explain how to use these other modpacks, which have
+their own manuals:
+
+*   [Minetest Game Documentation](https://wiki.minetest.net/Main_Page)
+*   [Mesecons Documentation](http://mesecons.net/items.html)
+*   [Pipeworks Documentation](https://gitlab.com/VanessaE/pipeworks/-/wikis/home)
+*   [Moreores Forum Post](https://forum.minetest.net/viewtopic.php?t=549)
+*   [Basic materials Repository](https://gitlab.com/VanessaE/basic_materials)
+
+Recipes for constructable items in technic are generally not guessable,
+and are also not specifically documented here.  You should use a
+craft guide mod to look up the recipes in-game.  For the best possible
+guidance, use the unified\_inventory mod, with which technic registers
+its specialised recipe types.
+
+# Documentation
+
+Ingame:
+* [Substances](./technic/doc/substances.md)
+* [Processes](./technic/doc/processes.md)
+* [Chests](./technic/doc/chests.md)
+* [Radioactivity](./technic/doc/radioactivity.md)
+* [Electrical power](./technic/doc/power.md)
+* [Powered machines](./technic/doc/machines.md)
+* [Generators](./technic/doc/generators.md)
+* [Forceload anchor](./technic/doc/anchor.md)
+
+Mod development:
+* [Api](./technic/doc/api.md)
+
+subjects missing from this manual:
+* powered tools
+  * tool charging
+  * battery and energy crystals
+  * chainsaw
+  * flashlight
+  * mining lasers
+  * mining drills
+  * prospector
+  * sonic screwdriver
+* liquid cans
+* wrench
+* frames
+* templates
+
+
+## FAQ
+
+1. My technic circuit doesn't work.  No power is distributed.
+  * A: Make sure you have a switching station connected.
+
+# Notes
+
 This is a maintained fork of https://github.com/minetest-mods/technic with various enhancements.
 Suitable for multiplayer environments.
 
@@ -58,13 +124,6 @@ Recommended mods that build on the `technic mod`:
 * @S-S-X
 * And many others...
 
-# FAQ
-
-* [Manual](./manual.md)
-
-1. My technic circuit doesn't work.  No power is distributed.
-  * A: Make sure you have a switching station connected.
-
 # License
 
 Unless otherwise stated, all components of this modpack are licensed under the

technic/doc/anchor.md

@@ -0,0 +1,57 @@
+
+
+administrative world anchor
+---------------------------
+
+A world anchor is an object in the Minetest world that causes the server
+to keep surrounding parts of the world running even when no players
+are nearby.  It is mainly used to allow machines to run unattended:
+normally machines are suspended when not near a player.  The technic
+mod supplies a form of world anchor, as a placable block, but it is not
+straightforwardly available to players.  There is no recipe for it, so it
+is only available if explicitly spawned into existence by someone with
+administrative privileges.  In a single-player world, the single player
+normally has administrative privileges, and can obtain a world anchor
+by entering the chat command "/give singleplayer technic:admin\_anchor".
+
+The world anchor tries to force a cubical area, centered upon the anchor,
+to stay loaded.  The distance from the anchor to the most distant map
+nodes that it will keep loaded is referred to as the "radius", and can be
+set in the world anchor's interaction form.  The radius can be set as low
+as 0, meaning that the anchor only tries to keep itself loaded, or as high
+as 255, meaning that it will operate on a 511×511×511 cube.
+Larger radii are forbidden, to avoid typos causing the server excessive
+work; to keep a larger area loaded, use multiple anchors.  Also use
+multiple anchors if the area to be kept loaded is not well approximated
+by a cube.
+
+The world is always kept loaded in units of 16×16×16 cubes,
+confusingly known as "map blocks".  The anchor's configured radius takes
+no account of map block boundaries, but the anchor's effect is actually to
+keep loaded each map block that contains any part of the configured cube.
+The anchor's interaction form includes a status note showing how many map
+blocks this is, and how many of those it is successfully keeping loaded.
+When the anchor is disabled, as it is upon placement, it will always
+show that it is keeping no map blocks loaded; this does not indicate
+any kind of failure.
+
+The world anchor can optionally be locked.  When it is locked, only
+the anchor's owner, the player who placed it, can reconfigure it or
+remove it.  Only the owner can lock it.  Locking an anchor is useful
+if the use of anchors is being tightly controlled by administrators:
+an administrator can set up a locked anchor and be sure that it will
+not be set by ordinary players to an unapproved configuration.
+
+The server limits the ability of world anchors to keep parts of the world
+loaded, to avoid overloading the server.  The total number of map blocks
+that can be kept loaded in this way is set by the server configuration
+item "max\_forceloaded\_blocks" (in minetest.conf), which defaults to
+only 16.  For comparison, each player normally keeps 125 map blocks loaded
+(a radius of 32).  If an enabled world anchor shows that it is failing to
+keep all the map blocks loaded that it would like to, this can be fixed
+by increasing max\_forceloaded\_blocks by the amount of the shortfall.
+
+The tight limit on force-loading is the reason why the world anchor is
+not directly available to players.  With the limit so low both by default
+and in common practice, the only feasible way to determine where world
+anchors should be used is for administrators to decide it directly.

technic/doc/chests.md

@@ -0,0 +1,52 @@
+
+chests
+------
+
+The technic mod replaces the basic Minetest game's single type of
+chest with a range of chests that have different sizes and features.
+The chest types are identified by the materials from which they are made;
+the better chests are made from more exotic materials.  The chest types
+form a linear sequence, each being (with one exception noted below)
+strictly more powerful than the preceding one.  The sequence begins with
+the wooden chest from the basic game, and each later chest type is built
+by upgrading a chest of the preceding type.  The chest types are:
+
+1.  wooden chest: 8×4 (32) slots
+2.  iron chest: 9×5 (45) slots
+3.  copper chest: 12×5 (60) slots
+4.  silver chest: 12×6 (72) slots
+5.  gold chest: 15×6 (90) slots
+6.  mithril chest: 15×6 (90) slots
+
+The iron and later chests have the ability to sort their contents,
+when commanded by a button in their interaction forms.  Item types are
+sorted in the same order used in the unified\_inventory craft guide.
+The copper and later chests also have an auto-sorting facility that can
+be enabled from the interaction form.  An auto-sorting chest automatically
+sorts its contents whenever a player closes the chest.  The contents will
+then usually be in a sorted state when the chest is opened, but may not
+be if pneumatic tubes have operated on the chest while it was closed,
+or if two players have the chest open simultaneously.
+
+The silver and gold chests, but not the mithril chest, have a built-in
+sign-like capability.  They can be given a textual label, which will
+be visible when hovering over the chest.  The gold chest, but again not
+the mithril chest, can be further labelled with a colored patch that is
+visible from a moderate distance.
+
+The mithril chest is currently an exception to the upgrading system.
+It has only as many inventory slots as the preceding (gold) type, and has
+fewer of the features.  It has no feature that other chests don't have:
+it is strictly weaker than the gold chest.  It is planned that in the
+future it will acquire some unique features, but for now the only reason
+to use it is aesthetic.
+
+The size of the largest chests is dictated by the maximum size
+of interaction form that the game engine can successfully display.
+If in the future the engine becomes capable of handling larger forms,
+by scaling them to fit the screen, the sequence of chest sizes will
+likely be revised.
+
+As with the chest of the basic Minetest game, each chest type comes
+in both locked and unlocked flavors.  All of the chests work with the
+pneumatic tubes of the pipeworks mod.