wip content

content/interference-causes.typ

@@ -0,0 +1,81 @@
+#import "/lib.typ": note, tip, todo
+
+= Causes of Interference
+
+We need precise control over the entity age and ID for this to work, so sources of interference are
+generally unexpected entity spawns that mess up the ID.
+
+== Other Entities
+
+Recall that *any* entity spawning will increment the ID counter, and the full list of entities is
+surprising. An exhaustive list is available at
+#link("https://minecraft.wiki/w/Entity#Types_of_entities")[The Minecraft Wiki].
+
+In general, the solution is to spawn our item entities at nearly the same time, so there is no
+chance for other entities to spawn in-between. For example, by spawning all items with droppers in
+the same game tick, all the items are created in the same tick phase, so player inputs and world
+events cannot affect it. See @timing for details.
+
+== Singleplayer (before 26.2) <singleplayer>
+
+In singleplayer worlds, there are separate execution threads for the renderer and game world. The
+game world ("server thread") contains the item entities we care about for the purposes of EID
+Wireless, as these are the entities we can detect with redstone. However, the renderer ("client
+thread") *also* tracks some entities.
+
+In versions before 26.2, there was a bug that caused the client thread and server thread to use the
+*same* global ID counter. Therefore every entity might increment the counter twice: once when it
+spawns in the server, and once when the client begins to track it. Because this depends on the
+position and orientation of the player, and also on the unpredictable scheduling of the two
+execution threads, it is impossible to truly compensate for these effects.
+
+The solution is to either use a dedicated minecraft server, so that the client and servers run in
+separate processes, or install a mod which patches the game to use a separate counter for the
+client.
+
+#todo[Singleplayer patch links][Grab links for these mods and figure out exactly which versions
+  they're good for.]
+
+== Paper Servers <paper>
+
+#todo[Paper compatibility list][Figure out which versions of Paper broke the thing.]
+
+Most recent versions of Paper server are compatible with EID Wireless. However, there are old
+versions of Spigot which include a *different* stationary item optimization which corrupts this. A
+few versions of Paper erroneously included this old optimization (on top of the mod 4 optimization)
+which breaks EID Wireless.
+
+#todo[Broken Paper/Spigot code][Show the patch with the busted optimization.]
+
+== Unloaded Chunks
+
+When a chunk unloads and reloads, all entities contained within it are destroyed and recreated with
+new entity IDs. Therefore any information encoded in the ID group offsets is destroyed.
+
+#tip[ When a chunk containing an EID Wireless receiver is reloaded, every in-progress transmission
+  *MUST* be discarded. ]
+
+The best thing to do is to use a reload detector and lock the receiver output for one full cycle
+after a reload.
+
+#todo[Reload detector designs][frost walker, sculk sensor, ???]
+
+== Lazy Chunks
+
+Entities in lazy chunks do not age or move, and their IDs are preserved. However, the redstone
+circuitry will continue to function. If a chunk becomes lazy while a transmission is being
+processed, the detection circuits will not observe the right drop delays and so the transmission is
+corrupted.
+
+#tip[ When a chunk containing an EID Wireless receiver becomes lazy, every in-progress transmission
+  *MUST* be discarded. ]
+
+Further, depending on the receiver design, there is a small chance the items become clipped into
+blocks. When the chunk becomes entity-processing again, the clipped items will fly out of the
+machine instead of being recycled.
+
+The best thing to do is to use a chunkloader to prevent the receiver ever being lazy-loaded. If
+chunkloaders cannot be used, a lazy-chunk detector can be used to lock the outputs while the chunk
+is lazy-loaded and for one full cycle after it becomes entity-processing.
+
+#todo[Lazy chunk detector designs][falling entity, ???]