# zaxx.mods: Player Guide

Everything you need to use this setup: a 5-minute quick start, then a section for each mod. Keybinds listed are the defaults; change any of them in **Options → Controls → Key Binds** (search by mod name).

---

## Quick start (5 minutes)

1. **Install.** Run `powershell -ExecutionPolicy Bypass -File install.ps1` from the repo folder, or skip this if you already have the mods.
2. **Launch.** In the Minecraft Launcher, choose the **fabric-loader-26.3** profile and press Play.
3. **Turn on textures.** Go to Options → Resource Packs and move these to the right-hand side in this order, top to bottom:
   1. Fresh Animations
   2. Faithful 32x
   3. Default Connected Textures (built into Continuity)
4. **Turn on a shader.** Press **O**, or go to Options → Video Settings → Shader Packs, and pick **Complementary Reimagined**. Apply, then Done.
5. **Check FPS.** Press **F3**. If you're under ~60 FPS, lower Render Distance in Video Settings or pick a lighter shader preset.
6. **Learn the 5 keys you'll actually use:**

| Key | Does |
|---|---|
| `C` (hold) | Zoom; scroll while holding to zoom further |
| `M` | Full-screen world map |
| `B` | Drop a waypoint where you stand |
| `J` | Show / hide your Trailblazer trail |
| `K` | Toggle shaders on and off instantly |
| Right-click drag | Spread one item into each slot you drag over |

---

## Engine

### Sodium: performance
Rewrites Minecraft's renderer, which usually doubles or triples your FPS. There's nothing to learn: it just runs.
- **Settings:** Options → Video Settings has a new tabbed menu (General / Quality / Performance / Advanced).
- **Tips:** Leave *Use Block Face Culling* and *Use Fog Occlusion* on. If you get stutter, set *Chunk Update Threads* to match about half your CPU cores.

### Iris: shader loader
Loads shader packs and works together with Sodium.
| Key | Action |
|---|---|
| `O` | Open the shader pack picker |
| `K` | Toggle shaders on and off |
| `R` | Reload the current shader, after changing its files |
- **Per-shader settings:** in the picker, select a pack and click **Shader Pack Settings**. Every pack has presets (Low → Ultra).
- **Adding packs:** drop a `.zip` into `.minecraft\shaderpacks`, or click *Open Shader Pack Folder* in the picker.

### Libraries (no action needed)
**Fabric API**, **Fabric Language Kotlin** and **YACL** are code libraries other mods need. Don't remove them. Zoomify won't start without Kotlin and YACL.

---

## Utility

### Mouse Tweaks: inventory dragging
Makes moving items in any chest or inventory much faster.
| Gesture | Result |
|---|---|
| **Right-click + drag** with a stack | Drops **one** item into each slot you drag over |
| **Left-click + drag** with an item held | Pulls every matching item you drag over into your held stack |
| **Shift + left-click + drag** (empty hand) | Shift-moves every slot you drag over to the other inventory |
| **Scroll wheel** over an item | Scroll down moves it into the other inventory; scroll up pulls it back |
- **Typical use:** open a chest, hold Shift, and sweep your mouse across your inventory to dump everything in one motion.
- **Settings:** Mod Menu → Mouse Tweaks (for example, invert scroll direction).

### Zoomify: zoom
| Input | Action |
|---|---|
| Hold `C` | Zoom in |
| Scroll while holding `C` | Zoom in or out further |
| Release `C` | Smoothly zoom back out |
- **Settings:** Mod Menu → Zoomify. Useful ones: *Zoom Transition* (smoothness), *Scroll Zoom* on or off, *Relative Sensitivity* (slower mouse while zoomed), and *Cinematic Camera* for smooth shots.
- **Tip:** switch it to toggle mode in its settings if holding a key gets tiring.

### Xaero's Minimap: corner map and waypoints
A live map in the top corner showing terrain, mobs and players, plus waypoints.
| Key | Action |
|---|---|
| `Y` | Minimap settings (size, position, zoom, cave mode) |
| `B` | Create a waypoint at your position |
| `U` | Open the waypoint list (edit, teleport if allowed, share) |
| `Z` | Enlarge the minimap temporarily |
| `]` / `[` | Zoom the minimap in / out |
- **Waypoints** appear in the world as beacons with a distance readout. Deleted ones go to the list's trash, so they're recoverable.
- **Death waypoint:** a waypoint marking where you died is created automatically.
- **Cave mode** turns on underground automatically. Toggle it in `Y` settings if it's distracting.

### Xaero's World Map: full map
| Key / Input | Action |
|---|---|
| `M` | Open the full-screen map |
| Scroll | Zoom |
| Drag | Pan |
| Right-click on the map | Create a waypoint there, or teleport (creative / op) |
| `H` (in map) | Center on yourself |
- The map fills in as you explore and is saved per world and server.
- It shares waypoints with the Minimap.

### Distant Horizons: see for miles
Renders simplified versions of far-away terrain (called LODs, for "level of detail") way past your normal render distance, so mountains and coastlines stay visible on the horizon.
- **Settings:** Options → Video Settings → the **Distant Horizons** button, or Mod Menu → Distant Horizons. Start with the **Quick** tab. Set *LOD Render Distance* to 128–256 chunks, and keep *Quality* on Medium at first.
- **First load:** DH builds the distant terrain in the background, so the horizon fills in over the first few minutes in a new area. You'll see CPU use jump while this happens.
- **Normal render distance:** you can drop vanilla Render Distance to 8–12 chunks. DH covers everything beyond that, so FPS often goes *up*.
- **Shaders:** Complementary Reimagined and Photon support DH natively, with fog and lighting matched to the far terrain. Rethinking Voxels and older packs may show a visible seam or no DH terrain at all.
- **Storage:** LOD data is saved per world in that world's `data` folder, and it can grow to a few GB for large explored areas.
- **Servers:** it works client-side anywhere. Servers that also run DH can send you LODs of chunks you haven't visited.

### Falling Leaves: ambient leaves
Leaf particles drift down from leaf blocks, with colours that match the tree and biome.
- No keys needed. It just works.
- **Settings:** Mod Menu → Falling Leaves. *Leaf Size*, *Leaf Spawn Rate* (lower it in dense jungles if FPS dips) and per-tree-type overrides.
- Settings screens use **Cloth Config** (a library, installed).

### Sound Physics Remastered: 3D cave audio
Adds real reverb, echo and occlusion. Caves boom, sounds behind walls get muffled, and big rooms ring.
- No keys needed.
- **Settings:** Mod Menu → Sound Physics Remastered. *Reverb Gain* sets how strong the echo is, *Attenuation Factor* sets how fast sound fades, and *Simple Reverb* is a lighter mode for slower CPUs.
- **It's a beta** for 26.3. If audio crackles or cuts out, turn on *Simple Reverb* or lower *Ray Count*.
- Works with every shader. It's all CPU, so expect a small FPS cost in huge caves.

### Trailblazer: guide lines and dig-out planner (our own mod)
Draws a glowing trail to where you want to go, and can outline exactly which blocks to mine for a tunnel or staircase. It reads your Xaero waypoints, so any waypoint you've made on the map can be a destination.

**Quick start**
1. Press **`G`** to open the marker menu.
2. Click **Go** next to any destination. The menu lists:
   - **Built-in:** Origin (0, 0), your respawn point (your bed or anchor in singleplayer; world spawn on servers, which never tell the client your bed), world spawn, and your last death.
   - **My markers:** your own. Type a name at the top and click **+ Add here** to save where you're standing, or use `/trail mark <name>`. Click **✕** to delete one. They're saved per world in `config/trailblazer/markers.json`.
   - **Xaero waypoints:** everything from your minimap, read-only.
   Markers in other dimensions are greyed out. Use the buttons at the bottom to switch Path (line or walk) and Dig mode.
3. Follow the **ice-blue** line. A **white beacon** marks the target, and the action bar counts down the distance.
4. When you arrive (within 3 blocks), the trail clears itself.

**Auto-walk** (`X`, the menu's top-right button, or `/trail autowalk`)
- Walks the route for you: it steers along smooth curves (aiming a few blocks ahead), turns the camera gently every frame, jumps up blocks, swims, and sprints on straight stretches.
- Slows down and turns in place on sharp corners rather than walking off edges.
- **Stops when:** you press S, A or D, you take damage, it makes no progress for about 8 seconds, the target is in another dimension, or you arrive. Opening a menu pauses it.
- Built for private worlds. Some servers treat automated movement as cheating.

**Settings** (G → **⚙ Settings**, saved automatically)
| Setting | What it does |
|---|---|
| Turn speed | Fastest the camera can turn (default 120°/s). Lower = calmer. |
| Turn smoothing | Floaty ↔ snappy easing onto the route |
| Look-ahead | How far ahead it aims. Higher = wider, smoother corners. |
| Sprint / Sprint-jump | Sprint on straights; parkour-style hops on long flat runs (off by default) |
| Level camera | Settles your view to a relaxed, slightly-down angle |
| Auto-trail temp waypoints | Start a trail as soon as you drop a Xaero temporary waypoint (on by default) |
| Particle density | Thickness of trail lines |
| Path budget / Search size | Route-search performance. Lower budget = smoother FPS. |
| Debug overlay | Top-left timings: tick cost (avg/max), route search, particles, auto-walk state |

**Xaero temporary waypoints:** right-click Xaero's world map → *Create temporary waypoint* (or use Xaero's temp-waypoint key) and the trail starts heading there automatically. Press `X` to auto-walk. Temporary waypoints also show in the G menu, marked *(temp)*. Trailblazer now reads waypoints live from Xaero, so new ones appear instantly without waiting for Xaero to save.

**Direction arrow:** while a trail is active, the bar above your hotbar shows an arrow pointing to the target relative to where you're looking, plus the distance (for example `↗ Base · 142 m`).

**Death return:** after you respawn, a clickable **[Trail back to your death]** shows in chat. One click sets the trail.

**Line or walking route**
- `/trail mode line`: a straight line that ignores terrain. Best for tunnelling, flying or the Nether roof.
- `/trail mode walk`: a **mint** route that goes around walls and drops and avoids lava. It can only plan through chunks you have loaded, so on long trips it plans about 160 blocks at a time and updates every 2 seconds as you move.

**Dig-out previews** (amber outlines = blocks to mine)
| Command | Result |
|---|---|
| `/trail dig tunnel` | A 1×2 tunnel straight to your target |
| `/trail dig tunnel 3 3` | A 3×3 tunnel (width 1–5, height 2–5) |
| `/trail dig stairs -58` | A staircase down (or up) to Y -58, heading towards your target, or the way you face if there's no target |
| `/trail dig off` | Hide the dig preview |
- The outline only shows the next ~32 blocks and updates as you mine, so mined blocks disappear from it.
- It skips air, water, lava, bedrock, and things you walk through like grass or torches.

**Keys:**
| Key | Action |
|---|---|
| `G` | Open the marker menu |
| `X` | Auto-walk to the target (again to stop) |
| `J` | Show / hide the trail |
| `N` | Switch straight line ↔ walking route |
| `V` | Cycle dig preview: off → tunnel → stairs |

None of these clash with vanilla, Xaero, Iris or Zoomify. Rebind them under Controls → Key Binds → Trailblazer if you want.

**Other:** `/trail waypoints` lists the waypoints it can see, `/trail status` shows your current settings, and `/trail clear` removes the trail.

**Fair play:** it only draws particles. It never mines, moves you, sees through blocks or talks to the server.

### Jarvis: ECHO, the AI companion (our own mod)

ECHO talks to you over voice, points things out and can do work in the world for you. Needs Trailblazer and the Jarvis Worker connection (`config/jarvis/connection.json`).

- **Keys:** hold **V** and talk (push-to-talk), **K** = pause/resume ECHO (stops what she's doing and goes quiet; asking anything also brings her back), **I** = ask, **J** = menu (chat log on the left and settings on the right, both scroll with the mouse wheel), **H** = take me there.
- **Ask about things:** "show me some chests", "more", "what's the move", "is this worth taking?"
- **Get ECHO to do things:** "dig a staircase to the nearest marker", "tunnel 40 blocks west and light it up", "mine 5 iron", "dig down to y -50". ECHO plans the steps, then digs and walks for you. Torches go down in the dark if they're in your hotbar.
- **Stopping:** say "stop", press **X**, or press S/A/D. A step that fails is re-planned up to twice. Lava, water and drops into caves stop a dig straight away.
- **Building:** "build me a 9x7 room", "make a little house here", "a 20-long wall with battlements", "bridge across this". ECHO designs 1–3 options from what you're holding, what's in your pack and what you've built nearby. It shows them as see-through ghost blocks in front of you, and a clickable line in chat lets you pick, build, rotate or cancel.
  - **Change it by talking:** "make the second one taller", "pointy roof", "use spruce for the corners", "move it left 2", "put it here", "rotate".
  - **"Build it":** ECHO clears natural blocks out of the way (never anything you built), then places bottom-up with what you carry. If something runs out, it builds what it can, then tells you what's missing; say "continue" once you have more. "stop" or any movement key pauses it.
  - **"Guide me":** the ghost stays up as a template. The layer to place next is highlighted and blocks disappear as you place the right ones.
  - Shapes: room, house (gable roof), tower, wall, platform, bridge, pillar.
- **Getting things from chests:** "collect all the seeds from the chests in this room", "grab all the gold", "get me the low-durability weapons out of these chests", "grab 32 oak logs from storage". ECHO walks to each chest, barrel and shulker box nearby (about 10 blocks for "this room", 16 for "nearby"), opens it, and shift-clicks out what matches. It stops when it has enough, runs out of chests, or your inventory fills up.
  - **During a paused build:** "get what you need from the chests" pulls exactly what the build is short of, then ECHO carries on building.
- **Farms:** "build me an automated sugarcane farm" offers real variants: observers (fully automatic) or a button (no quartz), 1 or 2 rows, any length, with or without a hopper line into a chest. Every option is weighed against your pack, your **base chests** (remembered whenever they're opened) and what ECHO can craft.
- **Design panel:** the bottom-right panel shows every option ECHO is considering, a picture of the selected one and its materials (have / in chests / craft / short). **J › Designs** opens all options side by side.
- **Crafting & smelting:** "make me 40 cobblestone stairs", "smelt my raw iron". Crafting uses your recipe book (2x2 grid, or a crafting table nearby). A build that's short offers **[Get it from the chests]** / **[Craft what's missing]**.
- **Long jobs:** "fill my inventory with sand" (mines everything in reach, sweeps up the drops, moves on), "enchant my hoe with fortune, sword with sharpness, unbreaking on all" (uses a matching book on an anvil, or the enchanting table only when it actually offers that enchantment; otherwise it tells you what's on offer instead of spending your levels).
- **Chores:** "harvest and replant" (wheat, carrots, potatoes, beetroot, each spot replanted with the same crop), "breed the cows".
- **Companion:** a welcome-back recap, goals ("my goal is full netherite"), warnings (lava ahead, a big drop, a tool about to break, night far from base, low health), and offers that only act on a yes: eat, wear better armour, toss junk, light a dark spot. **J › Journal** shows a map of places and trips, your goals, and what ECHO has learned about you.
- **More farms:** automatic bamboo farms (no water needed). "Build all the automated farms you can" builds every farm type you don't have yet, sized to what's in your pack and chests, on flat free ground nearby. ECHO recognises farms you've already built ("what farms do I have?").
- **Vein mining:** "mine out this vein" (look at the ore) mines every connected block of it, tunnelling in as needed, then picks up the drops.
- **Loadouts:** "get me ready for a mining trip" (or exploring / nether / farming / fighting) takes only what's missing from your chests.
- **Villagers:** "find me a Mending librarian" checks the trades ECHO remembers, otherwise opens nearby villagers' trades, then marks the right one.
- **Nether:** portals are remembered when you use them. "Take me home through the nether" goes via the portals, and ECHO knows nether ↔ overworld coordinates for your places.
- **Your places:** "take me home" uses your own markers and Xaero waypoints (then base / house / bed / respawn). Saying "after that, take me home" while she's busy queues it.
- **Compass:** a slim strip in the bottom-right. Say "hide the compass" / "show the compass", or move it in G › Settings.
- **Voice:** MeloTTS by default (about 100x cheaper); Aura voices in J › Engine.
- **Can't do (yet):** fighting, scaffolding (very tall builds may pause), multi-storey houses, copying a build.
- **Servers:** add the world seed in the J menu (or `/jarvis seed <seed>`) so ECHO can look up structures. Real blocks in loaded chunks (trial spawners, vaults, chests) are always checked first.

### Cave Dust: atmospheric dust (our 26.3 port)
Floating dust particles underground that get thicker the deeper you go.
| Key | Action |
|---|---|
| `Numpad +` | Toggle dust on and off |
| `Numpad Enter` | Reload its config |
- **Settings:** Mod Menu → Cave Dust (particle amount, depth scaling, colour).
- **Our build:** the original mod stops at 26.1.2, so we ported it in [Krovikan-Vamp/cave_dust](https://github.com/Krovikan-Vamp/cave_dust/tree/26.3_fabric), branch `26.3_fabric`. The changes are version bumps and renamed game methods only. To rebuild: `git clone` that branch, run `gradlew build`, then copy `build/libs/cave_dust-*.jar` (not the `-sources` one) into `mods`.
- License: MPL-2.0, credit to LizIsTired.

### AppleSkin: hunger info
- Hover over a food item to see how much hunger and saturation it restores.
- While holding food, the hunger bar flashes the amount it will refill.
- Saturation shows as a yellow outline on the hunger bar, and exhaustion as a faint underlay.
- No keys. Settings are in Mod Menu.

### Continuity: connected textures
Glass, bookshelves, sandstone and other blocks join up seamlessly.
- **It only works if** *Default Connected Textures* (and optionally *Glass Pane Culling Fix*) is enabled under Options → Resource Packs.
- Faithful 32x and other packs with connected-texture support use it automatically.

### Mod Menu: mod list
- Click **Mods** on the title screen or the pause menu.
- Click any mod to read about it. The gear icon opens its settings, which is where most of the settings mentioned in this guide live.

### Performance pack (no action needed)
**Lithium**, **FerriteCore**, **Entity Culling**, **ImmediatelyFast**, **More Culling** and **C2ME** run in the background and have nothing to learn.
- **C2ME is an alpha build.** If the game crashes or chunks look wrong, remove `c2me-fabric-*.jar` from `mods` first.
- **Dynamic FPS** drops the frame rate when the window is in the background or you're idle. Settings: Mod Menu → Dynamic FPS.
- **Sodium Extra** and **Reese's Sodium Options** change Options → Video Settings: a sidebar layout with extra pages for particles, animations, fog and details.
- **LambDynamicLights:** held torches, lanterns and glowing items light the area around you with shaders off. Settings: Mod Menu → LambDynamicLights.

### Atmosphere pack
No keys for any of these. Each has settings in Mod Menu.
- **Visuality:** ore sparkles, slime blobs, ripples on water in rain.
- **Particle Rain:** rain, snow, sandstorms and fog as particles.
- **Subtle Effects:** campfire sparks, fireflies, breath in cold biomes and many more. Uses **Fzzy Config** (library, installed).
- **Wakes:** wakes behind boats and swimmers. **Explosive Enhancement:** bigger explosion effects.
- **AmbientSounds:** biome soundscapes. Uses **CreativeCore** (library, installed). **Presence Footsteps:** footsteps that match the block you walk on. Both work with Sound Physics.
- **Not Enough Animations:** your character visibly eats, holds maps and climbs in third person.
- **First-person Model:** look down to see your own body. Its on/off key is under Controls → Key Binds → First-person Model.
- **If FPS dips** in heavy weather or dense forest, lower the particle amounts in Particle Rain and Subtle Effects first.

### Jade: what am I looking at
A small box at the top of the screen names the block or mob under your crosshair, with extras like crop growth, chest contents and mob health.
| Key | Action |
|---|---|
| `Numpad 1` | Show / hide the box |
| `Numpad 0` | Jade settings |

### Roughly Enough Items (REI): recipes
Opens as an item list on the right side of your inventory.
| Input | Action |
|---|---|
| Hover an item + `R` | Show how to craft it |
| Hover an item + `U` | Show what it's used in |
| `Ctrl` + `O` | Hide / show the item list |
- Type in the search box at the bottom to filter. Uses **Architectury API** (library, installed).

### Inventory Profiles Next: sorting
Adds small sort and move-all buttons to your inventory and every chest screen, and refills your hotbar slot when a stack or tool runs out.
- **Settings and keys:** Mod Menu → Inventory Profiles Next. Uses **libIPN** (library, installed).

### Small helpers
- **Shulker Box Tooltip:** hold `Shift` while hovering a shulker box to see its contents.
- **BetterF3:** `F3` shows a colour-coded debug screen. `F3` + `M` edits its layout.
- **Controlling:** Options → Controls → Key Binds now has a search bar and a button to show only conflicts. Uses **Searchables** (library, installed).
- **Status Effect Bars:** potion icons get a bar showing time left.
- **Dynamic Crosshair:** the crosshair changes shape when you can mine, use or hit what you're aiming at.
- **Held Item Info:** switching hotbar slot shows the item's enchantments under its name.
- **Better Advancements:** the advancements screen fills the window and can be dragged around.
- **Chat Heads:** player faces next to chat lines on servers.

### Flashback: replays
Records your session so you can fly a camera through it afterwards and export video.
- **Record:** use the Flashback buttons on the pause menu to start and finish a recording.
- **Watch and edit:** open saved replays from the Flashback button on the title screen. The editor has a timeline with camera keyframes and an export option.
- Replays are saved in `.minecraft\flashback` and can get large on long sessions.

---

## Shaders

Switch with `O`. Toggle with `K`. Each pack has a settings menu with quality presets.

| Pack | Look | Performance | Best for |
|---|---|---|---|
| **Complementary Reimagined** | Rich, balanced, vanilla-friendly | ★★★★☆ | Daily play (start here) |
| **Rethinking Voxels** | Ray-traced, coloured light that bounces off torches, lava and glowstone | ★★☆☆☆ (beta) | Caves, bases, night builds |
| **Photon** | Semi-realistic, cinematic sky and clouds | ★★☆☆☆ | Screenshots and scenery |
| **BSL** | Bright, vivid, saturated | ★★★☆☆ | Sunny survival worlds |
| **Super Duper Vanilla** | Stylised Super Duper Graphics tribute | ★★★★☆ | A softer, nostalgic look |

**Tuning for an RTX 3070:** Complementary and BSL on High at 16+ chunks. Photon on Medium/High at 12–16 chunks. Rethinking Voxels on its default preset at 8–12 chunks, raising it if FPS allows.

**Shader troubleshooting:**
- **Black or pink screen:** press `K` to turn shaders off, then try another pack.
- **Low FPS:** lower the shader preset first, then render distance. Turn off *Shadows* in shader settings for the biggest gain.

---

## Resource packs

| Pack | What it does | Notes |
|---|---|---|
| **Fresh Animations** | Mobs blink, breathe, look around and move naturally | Needs EMF and ETF (installed). Keep it **at the top**. |
| **Faithful 32x** | Vanilla textures at double resolution | Works with Continuity's connected textures |
| **Roundista** | Rounded, hand-painted 128x textures with LabPBR | Pairs with shaders that support LabPBR (Complementary, BSL, Photon). Use *instead of* Faithful, not with it. |
| **Fresh Textures** | Older local pack | May show odd textures on 26.3. Disable it if it does. |

**Entity Model Features / Entity Texture Features** run Fresh Animations' custom mob models and emissive textures (glowing spider eyes, for example). Settings are in Mod Menu, though the defaults are fine.

---

## Troubleshooting

| Problem | Fix |
|---|---|
| Game crashes on launch | Open `.minecraft\logs\latest.log` and look for `Caused by:`. A missing dependency names the mod it needs. Reinstall it with `install.ps1`. |
| A mod's key doesn't work | Options → Controls → Key Binds. Check for conflicts, which show in red. |
| Mobs look vanilla | Fresh Animations isn't enabled, or isn't at the top of the resource pack list. |
| Glass isn't connecting | Enable *Default Connected Textures* in Resource Packs. |
| Lost waypoints after updating | They're stored in `.minecraft\xaero`, so keep that folder when reinstalling. |
| Want the old 1.21.4 setup | Copy `backups\mods-1.21.4\*` into `.minecraft\mods` and launch the 1.21.4 Fabric profile. |