Add User Documentation for Item and Fluid Logistics (#3845)

Co-authored-by: Jurre Groenendijk <jurre@jilles.com>

Author: DilithiumThoride

docs/content/Gameplay/Logistics/Covers.md

@@ -0,0 +1,100 @@
+# Covers
+**All** GregTech Modern blocks which contain a BlockEntity can have Covers attached to them to add additional functionality
+or alter their normal functions. Some of these covers affect item and fluid transfer.
+
+Covers can be attached, configured, or removed, through the machine side configuration UI found in all GregTech Modern
+machines and hatches. They can also be:
+
+* Attached by right-clicking the machine while holding the cover
+* Configured by right-clicking their side with a Screwdriver or shift- right-clicking with an empty hand
+* Removed by right-clicking with a Crowbar.
+
+Logistics are available at all voltage tiers starting at LV, and the maximum rate at which they transfer items and fluids 
+is based on their voltage tier. (There is an add-on mod which also adds ULV covers however those are not included in base 
+GregTech Modern.)
+
+## Conveyor Modules and Electric Pumps
+Conveyor Modules and Electric Pumps are the standard set of logistics covers. They can be placed on blocks with inventories
+or tanks, or on item or fluid pipes (respectively). On placement, they default to Export mode, extracting items or fluids
+from their attached block and pushing them into the block they face. By using a Screwdriver, they can be toggled to 
+Import mode, and their transfer rate per-second or per-tick can also be configured.
+
+When connected to a Fluid Pipe, Electric Pumps will override the normal fluid transfer rate of the pipe on that side,
+and fluid will transfer according to the Pump's settings.
+
+When transporting items into an Item Pipe (either by being placed adjacent to a pipe and set to export, or placed on a
+pipe and set to import), Conveyor Modules have an additional feature: Distribution Mode. There are three options for this:
+
+* Priority: Items are sent to the closest available inventory first
+* Round Robin: Items are distributed approximately equally across all available inventories
+* Round Robin with Restriction: Items are distributed across all available inventories, but the distribution will ignore
+any destinations that have Restrictive Item Pipes along the route to them, unless there are no other destinations it can
+send to.
+
+## Robot Arms and Fluid Regulators
+Robot Arms and Fluid Regulators are more advanced versions of the Conveyor and Pump. They have the same features, but 
+with an additional Transfer Mode toggle:
+
+* Transfer Any: always transfer as many items/fluid as are available
+* Transfer Exact: Only transfer items/fluid if an **exact** amount is available for transport (e.g. only transport 
+exactly 13 items at once, or exactly 144mB of a fluid). The cover will not transfer any if it has less than the target, 
+and will only transfer the exact amount even if more is available. This is useful for preventing machines being jammed
+from a full inventory but each stack has only half the items needed to run a recipe.
+* Keep Exact: Check the contents of the target inventory. Only transfer items/fluids if the amount of each available 
+item/fluid in the target is less than the set amount, and only transfer enough to raise the target's inventory to the
+set amount. This is useful to prevent a machine from getting completely filled with one item and having no space for a
+second required item.
+
+When attached to a Pipe, Robot Arms can export into the pipe using Transfer Exact mode, but they are unable to export using
+Keep Exact mode. However, Robot Arms *can* be attached to pipe output ends, and they will enforce the Keep Exact quantity
+for the inventory they are exporting to.
+
+## Filters
+Logistics covers can have Filters installed in them, to specifically allow (whitelist) or disallow (blacklist) chosen 
+items or fluids to pass through those covers. Filters can be configured by right-clicking them against the air, and
+items and fluids can be added to the filter either by placing them in from inventory (not consumed), or by dragging them
+in from NEI/JEI/EMI.
+
+There are five types of filters:
+
+* Item Filter, Fluid Filter - filters by specific items/fluids. Can be set to filter by, or ignore, item NBT data.
+* Item Tag Filter, Fluid Tag Filter - Filters using a Regular Expression string, searching by one or more Item Tags. 
+Multiple tags can be included or excluded from a single filter using logical operators.
+* Smart Item Filter - Filters items by searching recipe logic for valid ingredients. Supports the Centrifuge, Electrolyzer,
+and Sifter recipe lists.
+
+Filters can also be attached as covers to Machine faces set to auto-export or receiving inputs, to apply their filter 
+to the items or fluids traveling through that face.
+
+Fluid Filter Covers can also be attached to Fluid Pipes to isolate individual pipe directions and ensure only a single 
+fluid can travel down that pipe (if, for example, there was a Quadruple Fluid Pipe carrying four fluids, and one fluid
+needed to be separated out).
+
+## Ender Links
+Independent from all these other devices, there are also another set of covers: the Ender Link Covers. These come in 
+three types: Item, Fluid, and Redstone. These covers must be configured with a screwdriver on placement, but once configured
+they become part of a Network of interdimensionally wirelessly connected Ender Links.
+
+Ender Links are assigned a network using a Channel, using an 8-digit hexadecimal color code (RBGA format) and optionally
+a Description (as a text string). Every Channel has two forms: a Public form (accessible to everyone on the server), and
+a Private form (accessible only to the player who placed the Link cover). All Links of the same type on the same channel
+then become linked, allowing items, fluids, or redstone signals to be imported or exported between them.
+
+After being assigned a channel, Ender Links have the same input/output and filter controls as a Conveyor or Pump. A single
+Ender Link cover is only one-directional though, only allowing its attached machine to export to the ender network, or
+import from it. 
+
+Each Ender Link channel contains a single storage slot: either a single redstone value, a 160,000mB fluid tank, or a 1-
+slot inventory. Each Ender Fluid Link cover can transfer up to 160,000mB of fluid per second in or out, and each Ender
+Item Link can transfer up to 160 items per second in or out, attempting transfer every tick. Because Link Covers contain
+only a single slot, they are most efficient at teleporting only a single type of item or fluid.
+
+## Void Covers
+Sometimes items or fluids are unneeded or unwanted. Void Covers answer that. Any items or fluids which are exported into
+a Voiding Cover are simply deleted.
+
+Void Covers have two versions:
+
+* Simple: Voids all items/fluids that enter it. No further configuration.
+* Advanced: Allows for Filter configuration to only void specific items/fluids. Also has a Keep Exact mode, causing the
+cover to only void contents if the attached inventory contains more than the configured amount.

docs/content/Gameplay/Logistics/Machines.md

@@ -0,0 +1,59 @@
+# Machine Logistics
+## Steam Machines
+Steam Machines do not have any form of built-in logistics capability, with three exceptions:
+
+* The Primitive Water Pump is a Multiblock Machine and contains an Output Hatch. This hatch will automatically push water
+  out into any connected pipe or tank.
+* The Coke Oven is also a Multiblock machine, but unlike other multiblocks its controller does contain its inventory.
+  To aid in Coke Oven automation, a unique block called the Coke Oven Hatch can be placed in its structure, which will
+  accept item input and automatically push items and fluids out.
+* All Boilers which contain Steam will attempt to push Steam out into any fluid pipes or machines adjacent to them, on
+  all sides _except below_. This means that water can be safely input from below with no risk of steam entering your water
+  pipes.
+
+Additionally, Steam machines have a unique design challenge feature: all Steam machines have an Exhaust face, which must
+be facing open air, and will emit a blast of Steam every time the machine finishes a recipe. If the Exhaust face is
+blocked, the machine cannot complete its recipes; and the blast of Steam released will heavily injure any player
+standing in it.
+
+## Electric Machines
+All Electric machines have the ability to automatically output their produced items, fluids, or both, into any adjacent
+machine, inventory, tank, or pipe. This can be done with a Wrench, or via the Side Configuration tab in the machine's UI.
+
+* To change auto output from outside a machine, shift-right-click on air with the wrench to choose whether to configure
+  for Items, Fluids, or Both, then right click with a Wrench on the side of the machine to rotate its output face.
+  * To then enable automated output, right-click the machine face with a Screwdriver.
+* To change auto output from inside a machine, open the Side Configuration tab, and click the side you want to set as
+  output.
+  * One click will select the side, a second left click will set the side to item output, and a third left click will
+    toggle auto output. Right clicks will set and toggle fluid output.
+  * The main machine UI also contains two toggle buttons to enable or disable auto output for items or fluids, without
+    needing to open the configuration panel.
+
+Additionally, all electric machines will also **block** automated item or fluid input from their output sides. To
+override this and allow input from output side, there is an additional toggle button in the Side Configuration tab, or
+shift-right-click on the machine with a Screwdriver.
+
+## Multiblock Machines
+Multiblock machines do not contain items within their controller blocks, and instead all I/O is handled by Buses and
+Hatches. Buses and Hatches will, by default, **auto-import** from any inventories, tanks, or pipes they face, and
+**auto-export** to any inventories, tanks, or pipes. This behavior can be toggled by Disabling the hatch, either through
+the power button in its UI or by right-clicking it with a Soft Mallet.
+
+Buses and Hatches can accept automated import or export from other sides, so long as something else is causing it.
+
+## Passthrough Hatches and the Cleanroom
+The Cleanroom is a unique multiblock with unique restrictions. Because the Cleanroom must have solid walls, pipes, cables,
+and inventories outside cannot directly connect to machines inside. For this purpose, Passthrough Hatches exist.
+Passthrough Hatches (by default, only the HV Passthrough Hatches can be crafted) are solid blocks which can be placed in
+the walls or floor of a cleanroom. These hatches act as Input and Output at the same time, and will auto-Import from
+their green face, and auto-Export to their red face, in the same tick. This allows items and fluids to be pulled through
+the cleanroom walls, in or out.
+
+Furthermore, as Generators cannot be placed inside the Cleanroom, to transfer power in, Diodes can be used. Diodes can
+also be placed in the Walls or Floor, and if right-clicked with a Soft Mallet will limit how many Amps will travel through,
+cycling through 1/2/4/8/16A.
+
+Finally, Machine Hulls have a unique feature. On one hand, they can be used as a 1A Diode and transfer a single amp
+of power. On the other hand, they are also considered valid cables for an Applied Energistics ME Network, and thus
+ME Cables will connect to Hulls and allow an ME Network to extend into a Cleanroom.

docs/content/Gameplay/Logistics/Pipes.md

@@ -0,0 +1,96 @@
+# Pipes
+GregTech Modern offers both Item and Fluid pipes, made out of a wide range of materials in a wide range of capacities.
+
+## Pipe Placement
+Pipes and Cables use a shared, unique system for placement in world.
+
+A pipe or cable which is placed in world will, by default, not connect to any other adjacent blocks. However, if the
+pipe was shift-right-click placed against a machine or another pipe, the pipe will be placed connected to that machine.
+
+Once one pipe has been placed, looking at that pipe with another pipe will display the same sided overlay as when
+looking at a machine with a wrench or other tool. Right-clicking with a pipe within one of the sided regions will place
+a new pipe *on that side of the existing pipe*, connected to the pipe. This allows for placing lines of pipe without
+needing to stand in the path being placed along.
+
+### Frame Boxes
+Pipes can be placed inside of Frame Boxes, and Frame Boxes can be placed over Pipes. This is primarily an aesthetic
+choice, however it also forces the pipe's collision box to take up a full block of space, and thus also provides some 
+protection from the hazards of touching a fluid pipe carrying very hot or cold fluids (see below).
+
+## Pipe Connections
+Pipes can be right-clicked with a wrench to Connect or Disconnect the pipe from that side. This can be used to
+preemptively set pipe connections in preparation for a machine to be placed there, or to connect or disconnect pipe
+segments that need to branch off of others.
+
+Additionally, pipes can be shift-right-clicked in order to "Shutter" a given side of them. Shuttered pipe sides become
+**output-only**, allowing pipes to be made one-way. Shuttered pipe sides are visible via a small black arrow drawn in the
+allowed direction of transfer.
+
+Pipes have default logic for how they distribute their contents across their connections, however these behaviors can be
+modified by using [Covers](./Covers.md)
+
+## Pipe Materials and Sizes
+Pipes come in four sizes: Small, Normal, Large, and Huge. Fluid pipes also come in a Tiny size. Each larger size is more
+expensive but has greater throughput. The throughput of a pipe is determined by its Material (and in general, materials
+that require higher voltage tiers to produce have higher throughput) and multiplied by its size.
+
+## Item Pipes
+Item Pipes effectively act as teleportation tunnels between their sources and destinations: any items which are pushed
+into a pipe, are instantly pushed out the other end(s). Item pipes can be 1-to-1, 1-to-many, many-to-1, or many-to-many.
+Item pipes have a limit on how many items can be pushed through them every second. The limit of a full pipe is the limit
+of the smallest segment through (as even though the items are teleported rather than moving from pipe block to pipe block,
+they do still follow a path through the pipes and check every pipe along the path). There is no limit to the amount of
+different items that can move through a pipe at once, only the total count per second.
+
+When items are pushed into a pipe, by default they are pushed to the "closest" inventory to the source. However, the
+"closest" inventory is not directly determined by the distance in blocks between source and destination. Instead, it is
+determined by the "Priority" value of the pipe. Larger pipes have lower priorities, smaller pipes have higher priorities,
+and items will take the path which has the smallest total priority value.
+
+### Restrictive Item Pipes
+Item Pipes have a special variant called Restrictive Item Pipes. Restrictive pipes have 100x the priority value of
+equivalent non-restrictive pipes, allowing a pipe path to be forcibly made into the "longest" path and thus the final 
+path items can choose to go down.
+
+## Fluid Pipes
+Fluid Pipes function completely differently from item pipes. Each fluid pipe block is a small fluid tank, with a size
+equal to 20x the pipe's listed Transfer Rate.
+
+Every 5 ticks (4 times per second), fluid pipes will check for their adjacent connections, and try to export up to
+Half of their maximum storage capacity, distributed among all adjacent connections that the pipe did *not* receive input
+from since it last exported, based on the fullness percentage of those connections.
+
+As a result, while fluid pipes list their throughput as mB/t, they do not transfer on every tick; they transfer a large
+amount of fluid several times per second.
+
+As a further result however, a line or network of fluid pipes which are not completely filled can experience the fluid
+in the pipes sloshing around, becoming more full in some places and more empty in others. This can be mitigated by
+Shuttering pipes to prevent backflow.
+
+## Multi Pipes
+While Item Pipes can transfer an unlimited number of item types at once, Fluid Pipes cannot and trying to move multiple
+fluids through one pipe is liable to get a fluid stuck somewhere. To combat this, 4 Small Pipes or 9 Tiny Pipes can be
+crafted together into a Quadruple or Nonuple Fluid Pipe. These pipes act as 4 or 9 separate piped all in a single block. 
+Each of these pipes calculates its I/O independently, but **cannot contain duplicate fluids**, allowing 4 or 9 fluids 
+to be transferred through a single block with no risk of jams.
+
+## Hazards
+Fluid Pipes have an additional set of properties on them: Max Temperature, and Fluid Containment.
+
+All fluids in GregTech Modern have a Temperature, and some of them also have further properties:
+* Acids
+* Gases
+* Cryogenics
+* Plasmas
+
+If a Pipe's max temperature is less than the temperature of the fluid traveling through it, the pipe will intermittently
+void some of its contents, severely injuring nearby players and spreading fires, and quickly be destroyed.
+The exception to this is that if the fluid a pipe is carrying is a Plasma, and the pipe is marked as being able to contain
+Plasmas, the temperature limit is ignored.
+
+For other properties, if improperly contained, the effects are similarly hazardous. Acids and Cryogenics will harm their
+surroundings, then explode. Gases within pipes that cannot carry them will not destroy the pipe, but the gasses will
+quickly escape and cause small explosions.
+
+Finally, pipes carrying very hot or cold fluids (above 320K or below 260K) will injure entities that touch them, twice
+per second, damage scaling with how extreme the heat or cold is.

docs/content/Gameplay/Logistics/index.md

@@ -0,0 +1,11 @@
+# Logistics: Automated Item and Fluid Transport
+GregTech Modern contains several options for how items and fluids can be transferred between machines, at varying speeds
+and technology levels.
+
+Automated item and fluid transport is managed by three separate systems:
+
+* [**Machines**](./Machines.md)
+* [**Pipes**](./Pipes.md)
+* [**Covers**](./Covers.md)
+
+These systems are commonly manipulated using Tools such as a Wrench, Screwdriver, or Soft Mallet.