import sources from scattered branches

content/interference-causes.typ

@@ -0,0 +1,118 @@
+#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, ???]
+
+#todo[think about lazy conditions by cases]
+
+
+#todo[wip comment on discord][
+  The problem with unloaded chunks is that when the chunk reloads, all items are recreated with new
+  entity ids and the transmission information is destroyed. There is no hope for recovery, so the
+  only solution is to discard the first cycle.
+
+  The problem with lazy chunks is that it's impossible (or at least very hard) to synchronize entity
+  movement. The redstone, droppers, and hoppers all continue to tick in lazy chunks. If you have
+  multiple items in each slice, then every cycle in lazy chunks spaws an item. When you the chunk
+  ticks again, the hopper can onl pick up one of the items, and the rest sit there. You can't
+  control when in the cycle the chunk ticks again either, so it may tick with the trapdoor already
+  open, or just about to close.
+
+  Quite often, things will be desynchronized such that the trapdoor closes clipped into an item
+  while the hopper is on cooldown. In that case, the collision flings the item out of the
+  measurement chamber. If you only have one item, then the hopper can never be on cooldown while the
+  item would collide with the trapdoor, so it always gets recycled and can never be flung out.
+
+  However because you can't control the timings, you can't guarantee the mod 4 optimization was
+  actually applied or if the items are just falling through the already-open trapdoor. So you still
+  have to discard the message.
+
+  If you have a lazy chunk detector, you can stop the clock while in lazy chunks, then simply resume
+  the clock on the next cycle after ticking again.
+
+  But since you also need to lock the output for reloaded chunks, it's just easier to do that every
+  time.
+]
+