FTB Pregen Map Bridge

By
K9_pos_ela

Progressively fills FTB Chunks maps from saved local terrain or LSS-delivered chunks, with configurable work limits.

# FTB Pregen Map Bridge

Fill missing terrain on your FTB Chunks map from chunks that already exist, without revisiting every area yourself.

This is an **independent client-side addon** developed for Voxy Enhanced on **Minecraft 1.21.11 / Fabric**. It uses FTB Chunks' native map drawing and the LOD Server Support API. It is not an official FTB or LSS project and does not bundle their original classes or assets.

## What it does

- In singleplayer or on the client hosting a local world, reads saved `.mca` terrain in the current dimension and fills missing FTB map tiles, prioritizing nearby regions when scanning.

- Can use saved terrain created by a pregenerator such as Chunky, or terrain previously generated during ordinary play. Chunky is not a direct requirement of this addon.

- On a remote multiplayer client, accepts terrain columns delivered by **LOD Server Support 0.20.0**. The addon does not read files from someone else's computer or independently request their entire world.

- Retains already-complete FTB tiles. FTB's normal nearby updates continue to handle changes to explored terrain.

- Saves map data through FTB and records completed local-region fingerprints so unchanged regions can be skipped on a later pass.

It **does not generate Minecraft terrain, load entities, increase simulation/render distance or edit world-region files**. It does write map/cache and progress data on the client, so the FTB map's disk usage grows as more terrain is mapped. It does not add claims or change their permissions.

## Controlled background work

- One low-priority reading/decoding thread, with bounded queues.

- Up to 12 prepared chunk snapshots and 32 queued network columns.

- A default cap of **64 chunks per second**, drawn in 64-pixel slices with a **2 ms target per client update**.

- Yields an update after a long game tick and provides pause/resume commands.

These are work limits, not guaranteed throughput or a hard maximum for every operation. Huge pregenerated areas can take hours. **No FPS improvement or zero-stutter guarantee is claimed.** The native FTB map still performs its own loading, saving and memory management.

## Requirements

- **Minecraft 1.21.11**, **Fabric Loader 0.20.1+**, Java **21+**.

- **Fabric API** for Minecraft 1.21.11; the source setup uses 0.141.6+1.21.11.

- **FTB Chunks (Fabric) 2111.1.1**, with its normal dependencies, including FTB Library, FTB Teams and Architectury.

- **LOD Server Support / Voxy Server Side 0.20.0**, Fabric build for Minecraft 1.21.11.

Both FTB Chunks and LSS are hard dependencies in this beta, **including singleplayer**. This build is pinned to those API versions and is not advertised for other Minecraft versions or different FTB/LSS releases.

Install the main JAR in each **client** that should fill its own map. Do not install it as a standalone dedicated-server mapper: the addon is client-only. Remote mapping needs LSS on the server and client so terrain can actually be delivered, subject to that connection's available data and configured range. Follow the original dependency projects' setup instructions.

## Commands and configuration

- `/ftbmapfill` — status and counts of mapped/skipped chunks, queued work and errors.

- `/ftbmapfill pause` — pauses this session's mapping work.

- `/ftbmapfill resume` — resumes it.

Status messages in this first beta use Portuguese. Mapping starts automatically after entering a world when enabled.

The configuration is `config/ftb_pregen_map_bridge.json`; restart after editing:

```json

{"enabled": true, "maxChunksPerSecond": 64, "frameBudgetMillis": 2.0}

```

Accepted limits are 4–256 chunks/s and a 0.5–4 ms drawing target. A lower cap, such as 16 chunks/s and 1 ms, trades filling speed for a smaller work budget.

## Current beta limitations

- Only existing, fully generated local chunks are read. Supported Anvil compression formats are gzip, zlib and uncompressed records, including external `.mcc` chunks. Unsupported compression or unreadable records are skipped/reported; the world is not converted.

- The remote LSS path maps newly delivered data. Terrain LSS already considers delivered may not be resent automatically; this cache/reconnect scenario has not been fully validated. The addon does not silently erase or reset LSS/Voxy caches.

- If you deliberately clear the FTB map cache, also clear the matching bridge progress record under `local/ftb-pregen-map-bridge/`; otherwise completed local regions may remain marked as processed.

- This does not replace nearby map updates or forcibly refresh every already-complete distant tile.

## Validation and credits

Isolated native checks passed for Anvil reads, negative coordinates, palettes, heights, biomes, LSS column snapshots, real FTB drawing, map saving/reloading, queue limits, pause and disconnect. The synthetic fixtures did not open a personal world. **Visual gameplay, a full multiplayer connection and real-world FPS remain to be confirmed.**

Original addon: **K9 / Chris Heverton**, for Voxy Enhanced.

- [FTB Chunks (Fabric)](https://www.curseforge.com/minecraft/mc-mods/ftb-chunks-fabric) — FTB.

- [LOD Server Support](https://www.curseforge.com/minecraft/mc-mods/lod-server-support) — bitvox / VoX and contributors; the tested release is also named Voxy Server Side 0.20.0.

- Fabric and Minecraft retain their own authorship and licenses.

The original integration code uses the **Custom License / All Rights Reserved** included as `LICENSE.txt`. Dependency licenses are not replaced by it. No upstream class, map texture or other asset is redistributed in this addon.

Not affiliated with or endorsed by FTB, the LSS developers, Mojang or Microsoft.

**Artwork disclosure:** the project avatar is an original AI-generated branding illustration. It is not a game screenshot or a replica of FTB's map interface.