docs: rewrite reference, containers, crafting, effects, enchantments, networking, storage, tile-entities in casual tone

Author: coah80

src/content/docs/reference/entity-types.md

@@ -8,7 +8,7 @@ Entity types are registered in `EntityIO::staticCtor()` in
 `EntityIO::setId()` maps a factory function, an internal enum value (`eINSTANCEOF`),
 a string identifier, and a numeric ID.
 
-Entities that are spawnable in Creative mode via the Monster Placer (Spawn Egg) also
+Entities that can be spawned in Creative mode through the Monster Placer (Spawn Egg) also
 include egg colors and a name string ID.
 
 ## Entity ID Table
@@ -63,14 +63,14 @@ include egg colors and a name string ID.
 
 :::note
 IDs 3-8, 19, 22-39, 42-47, 64-89, 100-119, 121-199, 201-999 are unassigned.
-The base types `Mob` (48) and `Monster` (49) are registered but serve as generic
+The base types `Mob` (48) and `Monster` (49) are registered but act as generic
 fallbacks; specific mob types override them.
 :::
 
 ## Spawnable Entities (Spawn Eggs)
 
-The following entities can be spawned via the Monster Placer item (ID 383) using the
-entity ID as the data value. These are the entities registered with the
+These entities can be spawned with the Monster Placer item (ID 383) using the
+entity ID as the data value. They're the entities registered with the
 `SpawnableMobInfo` overload of `setId()`:
 
 | Entity ID | Name | Egg Colors |

src/content/docs/reference/file-index.md

@@ -3,15 +3,15 @@ title: Complete File Index
 description: Index of all source files in both LCEMP modules.
 ---
 
-LCEMP consists of two modules: **Minecraft.World** (game logic, networking, world simulation) and **Minecraft.Client** (rendering, UI, platform integration, server hosting). This page indexes every `.cpp` and `.h` source file in both.
+LCEMP has two modules: **Minecraft.World** (game logic, networking, world simulation) and **Minecraft.Client** (rendering, UI, platform integration, server hosting). This page lists every `.cpp` and `.h` source file in both.
 
-**Totals: 1,567 files in Minecraft.World -- 1,392 files in Minecraft.Client -- 2,959 files overall.**
+**Totals: 1,567 files in Minecraft.World, 1,392 files in Minecraft.Client, 2,959 files overall.**
 
 ---
 
 ## Minecraft.World (1,567 files)
 
-All files reside in a flat directory (`Minecraft.World/`) except for 7 headers in `x64headers/`.
+All files live in a flat directory (`Minecraft.World/`) except for 7 headers in `x64headers/`.
 
 ### Tiles / Blocks (200 files)
 
@@ -207,7 +207,7 @@ Platform-specific headers for Xbox 360 / x64: `extraX64.h`, `qnet.h`, `xmcore.h`
 
 The Client module has a deeper directory structure with platform-specific subdirectories.
 
-### Root Directory -- Rendering (174 files)
+### Root Directory: Rendering (174 files)
 
 Core rendering, models, entity renderers, and particle effects at the top level.
 
@@ -232,7 +232,7 @@ BreakingItemParticle, BubbleParticle, CritParticle, CritParticle2, DragonBreathP
 
 </details>
 
-### Root Directory -- Screens / UI (82 files)
+### Root Directory: Screens / UI (82 files)
 
 <details>
 <summary>Screen classes</summary>
@@ -241,7 +241,7 @@ AbstractContainerScreen, AchievementPopup, AchievementScreen, Button, ChatScreen
 
 </details>
 
-### Root Directory -- Core Engine (90 files)
+### Root Directory: Core Engine (90 files)
 
 <details>
 <summary>Core client classes</summary>
@@ -250,7 +250,7 @@ AllowAllCuller, Camera, Chunk, ClientConnection, ClientConstants, ClockTexture,
 
 </details>
 
-### Root Directory -- Textures (38 files)
+### Root Directory: Textures (38 files)
 
 <details>
 <summary>Texture system</summary>
@@ -259,7 +259,7 @@ AbstractTexturePack, ArchiveFile, BufferedImage, DefaultTexturePack, DLCTextureP
 
 </details>
 
-### Root Directory -- Server (18 files)
+### Root Directory: Server (18 files)
 
 <details>
 <summary>Server-side classes at root</summary>

src/content/docs/reference/item-ids.md

@@ -5,8 +5,8 @@ description: Complete table of all item IDs in LCEMP.
 
 Items are registered in `Item::staticCtor()` in
 [`Minecraft.World/Item.cpp`](/lcemp-docs/reference/file-index/). Block IDs 0-255 also
-occupy the item ID space (blocks are automatically wrapped in `TileItem`). True item IDs
-start at 256.
+take up space in the item ID range (blocks are automatically wrapped in `TileItem`). True
+item IDs start at 256.
 
 The constructor argument (e.g., `new Item(9)`) is an **internal slot index**. The actual
 item ID is `256 + slot`, declared as `*_Id` constants in `Item.h`.
@@ -195,14 +195,14 @@ IDs 0-255 are reserved for block items (see the [Block ID Registry](/lcemp-docs/
 | 2267 | `record_08` | where are we now |
 
 :::note
-The field names `record_08` through `record_12` do not correspond 1:1 with their IDs
-due to records being added across different title updates. The table above reflects the
+The field names `record_08` through `record_12` don't match up 1:1 with their IDs
+because records were added across different title updates. The table above shows the
 actual assignments in the source.
 :::
 
 ## Tool Tiers
 
-Tools are constructed with a `Tier` that determines durability, speed, damage, and
+Tools are built with a `Tier` that sets durability, speed, damage, and
 enchantability:
 
 | Tier | Level | Durability | Speed | Damage Bonus | Enchantability |

src/content/docs/reference/packet-ids.md

@@ -3,17 +3,17 @@ title: Packet ID Registry
 description: Complete table of all network packet IDs in LCEMP.
 ---
 
-Every packet in LCEMP is registered in `Packet::staticCtor()` inside `Minecraft.World/Packet.cpp`. The `map()` call signature is:
+Every packet in LCEMP is registered in `Packet::staticCtor()` inside `Minecraft.World/Packet.cpp`. The `map()` call signature looks like this:
 
 ```cpp
 map(id, receiveOnClient, receiveOnServer, sendToAnyClient, renderStats, typeid, createFn)
 ```
 
 **Direction key:**
 
-- **S->C** -- Server sends to client (`receiveOnClient = true`, `receiveOnServer = false`)
-- **C->S** -- Client sends to server (`receiveOnClient = false`, `receiveOnServer = true`)
-- **Both** -- Either direction (`receiveOnClient = true`, `receiveOnServer = true`)
+- **S->C** means the server sends it to the client (`receiveOnClient = true`, `receiveOnServer = false`)
+- **C->S** means the client sends it to the server (`receiveOnClient = false`, `receiveOnServer = true`)
+- **Both** means either direction (`receiveOnClient = true`, `receiveOnServer = true`)
 
 ## Packet Table
 
@@ -108,11 +108,11 @@ map(id, receiveOnClient, receiveOnServer, sendToAnyClient, renderStats, typeid,
 | 254 | `GetInfoPacket` | C->S | no | Server list ping (added 1.8.2) |
 | 255 | `DisconnectPacket` | Both | yes | Disconnect / kick reason |
 
-**Total registered packets: 88** (IDs 0--255, with gaps)
+**Total registered packets: 88** (IDs 0 to 255, with gaps)
 
 ## Unused / Commented-Out IDs
 
-The following IDs appear in comments but are not registered:
+These IDs show up in comments but aren't registered:
 
 | ID | Class Name | Notes |
 |----|-----------|-------|
@@ -125,9 +125,9 @@ The following IDs appear in comments but are not registered:
 
 ## Notes
 
-- The **Broadcast** column corresponds to the `sendToAnyClient` parameter. When `yes`, the packet is sent to all connected clients. When `no`, it is sent per-dimension per-machine (a 4J splitscreen optimization).
-- Packets marked **(4J added)** are custom additions by 4J Studios for the Legacy Console Edition and do not exist in vanilla Java Edition.
-- `MoveEntityPacketSmall` (162--165) is an optimized variant of `MoveEntityPacket` (30--33) for smaller position deltas.
+- The **Broadcast** column matches the `sendToAnyClient` parameter. When `yes`, the packet goes to all connected clients. When `no`, it's sent per-dimension per-machine (a 4J splitscreen optimization).
+- Packets marked **(4J added)** are custom additions by 4J Studios for the Legacy Console Edition and don't exist in vanilla Java Edition.
+- `MoveEntityPacketSmall` (162 to 165) is an optimized version of `MoveEntityPacket` (30 to 33) for smaller position changes.
 - `ContainerSetSlotPacket` (103) has conditional direction: in non-content-package builds it can also be sent C->S for debug purposes.
 
 **Source file:** `Minecraft.World/Packet.cpp`

src/content/docs/reference/tile-classes.md

@@ -3,7 +3,7 @@ title: Tile Class Index
 description: Index of all Tile (block) subclasses in LCEMP.
 ---
 
-In LCEMP, blocks are called "Tiles." Every block type is a subclass of `Tile` (defined in `Minecraft.World/Tile.h`). Some tiles inherit from intermediate base classes that provide shared behavior.
+In LCEMP, blocks are called "Tiles." Every block type is a subclass of `Tile` (defined in `Minecraft.World/Tile.h`). Some tiles inherit from intermediate base classes that share common behavior.
 
 ## Inheritance Hierarchy
 
@@ -164,10 +164,10 @@ Tile
 
 ## Notes
 
-- `Bush` is declared in `Bush.h` / `Bush.cpp` and is a Tile subclass for plant-type blocks. It does not follow the `*Tile.h` naming convention.
-- `LiquidTile` has two concrete subclasses -- `LiquidTileDynamic` and `LiquidTileStatic` -- defined in their own files, but they are not separate `*Tile.h` headers.
-- `FallingTile` (in `FallingTile.h`) extends `Entity`, not `Tile`. It is the falling-block entity (sand, gravel in motion), not a block type.
+- `Bush` is declared in `Bush.h` / `Bush.cpp` and is a Tile subclass for plant-type blocks. It doesn't follow the `*Tile.h` naming convention.
+- `LiquidTile` has two concrete subclasses (`LiquidTileDynamic` and `LiquidTileStatic`) defined in their own files, but they don't have separate `*Tile.h` headers.
+- `FallingTile` (in `FallingTile.h`) extends `Entity`, not `Tile`. It's the falling-block entity (sand, gravel in motion), not a block type.
 - The `Tile` base class itself is defined in `Tile.h` / `Tile.cpp` and holds the static tile registry (all block IDs are registered there).
-- Related tile items (e.g., `ClothTileItem`, `StoneSlabTileItem`, `TreeTileItem`) handle aux-data variants and are in separate files.
+- Related tile items (like `ClothTileItem`, `StoneSlabTileItem`, `TreeTileItem`) handle aux-data variants and live in separate files.
 
 **Source directory:** `Minecraft.World/`

src/content/docs/world/containers.md

@@ -3,11 +3,11 @@ title: Container Menus
 description: Inventory management and container menu system in LCEMP.
 ---
 
-LCEMP uses a two-layer container system: **Container** objects hold raw item data, and **AbstractContainerMenu** subclasses manage the GUI logic, slot layout, click handling, and synchronization between server and client.
+LCEMP uses a two-layer container system: **Container** objects hold the raw item data, and **AbstractContainerMenu** subclasses manage the GUI logic, slot layout, click handling, and sync between server and client.
 
 ## Container (data layer)
 
-`Container` is the pure-virtual interface every item-holding object implements. It defines the fundamental storage contract.
+`Container` is the pure-virtual interface that every item-holding object implements. It defines the basic storage contract.
 
 **Key constants and methods:**
 
@@ -34,7 +34,7 @@ LCEMP uses a two-layer container system: **Container** objects hold raw item dat
 | `MerchantContainer` | Villager trade slots | 3 slots: two payment, one result. Calls `updateSellItem()` on changes. Tracks `activeRecipe` and `selectionHint`. |
 | `EnchantmentContainer` | Enchanting table input | Extends `SimpleContainer` with a max stack size of 1 and menu callbacks. |
 | `RepairContainer` | Anvil input slots | Extends `SimpleContainer`. Triggers `RepairMenu::createResult()` on changes. |
-| `PlayerEnderChestContainer` | Per-player ender chest | Extends `SimpleContainer`. Persists via NBT through `setItemsByTag()` / `createTag()`. Tracks the currently active `EnderChestTileEntity`. |
+| `PlayerEnderChestContainer` | Per-player ender chest | Extends `SimpleContainer`. Persists through NBT with `setItemsByTag()` / `createTag()`. Tracks the currently active `EnderChestTileEntity`. |
 
 ## AbstractContainerMenu (GUI layer)
 
@@ -60,18 +60,18 @@ LCEMP uses a two-layer container system: **Container** objects hold raw item dat
 
 ### Core methods
 
-- **`addSlot(Slot*)`** -- Registers a slot, assigning it a sequential index.
-- **`broadcastChanges()`** -- Compares each slot against `lastSlots` and fires `ContainerListener::slotChanged()` on differences.
-- **`clicked(slotIndex, buttonNum, clickType, player)`** -- The central click dispatcher. Handles pickup, quick-move, swap, and clone logic. Manages carried items via the player's `Inventory`.
-- **`quickMoveStack(player, slotIndex)`** -- Virtual. Subclasses override to define shift-click transfer rules between slot regions.
-- **`moveItemStackTo(itemStack, start, end, backwards)`** -- Helper that moves items into a slot range, first trying to stack with existing items, then filling empty slots.
-- **`removed(player)`** -- Drops any carried item when the menu closes.
-- **`stillValid(player)`** -- Pure virtual. Each subclass defines the distance/validity check.
-- **`mayCombine(slot, item)`** -- Hook for dyeable armor and damaged item combination (4J addition).
+- **`addSlot(Slot*)`**: Registers a slot, giving it a sequential index.
+- **`broadcastChanges()`**: Compares each slot against `lastSlots` and fires `ContainerListener::slotChanged()` when things differ.
+- **`clicked(slotIndex, buttonNum, clickType, player)`**: The main click dispatcher. Handles pickup, quick-move, swap, and clone logic. Manages carried items through the player's `Inventory`.
+- **`quickMoveStack(player, slotIndex)`**: Virtual. Subclasses override this to define shift-click transfer rules between slot regions.
+- **`moveItemStackTo(itemStack, start, end, backwards)`**: Helper that moves items into a slot range, first trying to stack with existing items, then filling empty slots.
+- **`removed(player)`**: Drops any carried item when the menu closes.
+- **`stillValid(player)`**: Pure virtual. Each subclass defines the distance/validity check.
+- **`mayCombine(slot, item)`**: Hook for dyeable armor and damaged item combination (4J addition).
 
 ### Synchronization
 
-The menu tracks `unSynchedPlayers` -- a set of players whose client state is out of date. `isSynched()` and `setSynched()` control this flag. Change detection uses `ItemInstance::matches()` to compare current slot contents against `lastSlots` snapshots.
+The menu tracks `unSynchedPlayers`, a set of players whose client state is out of date. `isSynched()` and `setSynched()` control this flag. Change detection uses `ItemInstance::matches()` to compare current slot contents against `lastSlots` snapshots.
 
 `MenuBackup` provides transactional rollback support, storing snapshots keyed by `changeUid`. It supports `save()`, `rollback()`, and `deleteBackup()`.
 
@@ -83,38 +83,38 @@ The menu tracks `unSynchedPlayers` -- a set of players whose client state is out
 
 | Method | Purpose |
 |---|---|
-| `mayPlace(item)` | Whether the item can be placed here (overridden for type-restricted slots) |
+| `mayPlace(item)` | Whether the item can go here (overridden for type-restricted slots) |
 | `mayPickup(player)` | Whether the player can take the item out |
 | `getMaxStackSize()` | Stack limit for this slot (delegates to container by default) |
 | `set(item)` / `getItem()` | Read/write the slot contents |
 | `remove(count)` | Split items off the slot |
 | `onTake(player, item)` | Callback after a player takes items (used for achievements, XP) |
 | `swap(other)` | Swap contents with another slot |
 | `mayCombine(item)` | 4J addition for item combination support |
-| `combine(item)` | 4J addition that performs the combination |
+| `combine(item)` | 4J addition that does the combination |
 | `isAt(container, index)` | Identity check for finding a slot by its backing container and index |
 
-Specialized slot subclasses exist within menus. For example, `BrewingStandMenu::PotionSlot` restricts placement to bottles and caps stack size at 1, while `BrewingStandMenu::IngredientsSlot` only accepts valid brewing ingredients.
+Specialized slot subclasses exist within menus. For example, `BrewingStandMenu::PotionSlot` only allows bottles and caps stack size at 1, while `BrewingStandMenu::IngredientsSlot` only accepts valid brewing ingredients.
 
 ## Menu subclasses
 
 ### InventoryMenu
 
-The player's own inventory screen. Contains a 2x2 crafting grid, 4 armor slots, 27 main inventory slots, and 9 hotbar slots.
+The player's own inventory screen. Has a 2x2 crafting grid, 4 armor slots, 27 main inventory slots, and 9 hotbar slots.
 
 | Region | Constant | Range |
 |---|---|---|
 | Result | `RESULT_SLOT` | 0 |
-| Crafting grid | `CRAFT_SLOT_START` .. `CRAFT_SLOT_END` | 1--4 |
-| Armor | `ARMOR_SLOT_START` .. `ARMOR_SLOT_END` | 5--8 |
-| Main inventory | `INV_SLOT_START` .. `INV_SLOT_END` | 9--35 |
-| Hotbar | `USE_ROW_SLOT_START` .. `USE_ROW_SLOT_END` | 36--44 |
+| Crafting grid | `CRAFT_SLOT_START` .. `CRAFT_SLOT_END` | 1-4 |
+| Armor | `ARMOR_SLOT_START` .. `ARMOR_SLOT_END` | 5-8 |
+| Main inventory | `INV_SLOT_START` .. `INV_SLOT_END` | 9-35 |
+| Hotbar | `USE_ROW_SLOT_START` .. `USE_ROW_SLOT_END` | 36-44 |
 
 Overrides `slotsChanged()` to re-check crafting recipes. Supports `mayCombine` for dyeable armor.
 
 ### CraftingMenu
 
-The 3x3 crafting table screen. Tied to a world position for the `stillValid()` distance check. Drops crafting grid contents on close via `removed()`.
+The 3x3 crafting table screen. Tied to a world position for the `stillValid()` distance check. Drops crafting grid contents on close through `removed()`.
 
 ### FurnaceMenu
 
@@ -132,27 +132,27 @@ Shift-click logic routes fuel items to the fuel slot, smeltable items to the ing
 
 Wraps a `BrewingStandTileEntity`. Uses custom slot classes:
 
-- **`PotionSlot`** -- Restricts to potion bottles, max stack 1. Fires an achievement on take.
-- **`IngredientsSlot`** -- Restricts to valid brewing ingredients, max stack 1.
+- **`PotionSlot`**: Only takes potion bottles, max stack 1. Fires an achievement on take.
+- **`IngredientsSlot`**: Only takes valid brewing ingredients, max stack 1.
 
 Broadcasts `brewTime` as data ID 0.
 
 ### EnchantmentMenu
 
-Single input slot (max stack 1). Generates three random enchantment `costs[]` based on nearby bookshelves. `clickMenuButton()` applies the chosen enchantment, consuming player XP. Uses a `Random` seeded by `nameSeed`.
+Single input slot (max stack 1). Generates three random enchantment `costs[]` based on nearby bookshelves. `clickMenuButton()` applies the chosen enchantment, spending player XP. Uses a `Random` seeded by `nameSeed`.
 
 ### MerchantMenu
 
 Three slots: two payment inputs and one result output. Wraps a `Merchant` (villager) and a `MerchantContainer`. The `setSelectionHint()` method syncs the selected trade recipe from the trade list GUI.
 
 ### RepairMenu (Anvil)
 
-Two input slots and one result slot. Computes `cost` (XP levels) via `createResult()`. Supports item renaming through `setItemName()`. The `DATA_TOTAL_COST` (0) data ID broadcasts the repair cost to listeners.
+Two input slots and one result slot. Computes `cost` (XP levels) through `createResult()`. Supports item renaming with `setItemName()`. The `DATA_TOTAL_COST` (0) data ID broadcasts the repair cost to listeners.
 
 ### TrapMenu (Dispenser/Dropper)
 
 Simple 9-slot grid wrapping a `DispenserTileEntity`. No special slot logic beyond standard quick-move between dispenser and inventory.
 
 ### ContainerMenu (Generic chest)
 
-Used for single and double chests. Calculates `containerRows` from the container size and creates the appropriate slot grid. Calls `startOpen()` / `stopOpen()` for chest animations.
+Used for single and double chests. Calculates `containerRows` from the container size and creates the right slot grid. Calls `startOpen()` / `stopOpen()` for chest animations.