Item Frame Cache

Item Frame Cache is a lightweight, client-side Fabric mod that keeps previously seen item frames visible after the server stops tracking them.

It was originally created for huge map walls and map floors, but version 2.0 expands the cache to support regular items and optionally empty item frames too.

This makes it useful for:

• 🗺️ Huge map walls and map floors
• 🖼️ Decorative item frame builds
• 📦 Storage rooms using item frames as labels
• 🏛️ Museums and display halls
• 🛒 Shops and item showcases
• 🧱 Large builds containing thousands of item frames

Everything runs client-side. No server installation is required.

---

✨ What Item Frame Cache does

Minecraft servers stop sending item-frame entities to the client after a certain tracking distance.

When that happens, the item frame and its contents normally disappear even if the surrounding terrain is still being rendered.

Item Frame Cache remembers previously seen item frames and can continue rendering them after the server stops tracking them.

Version 2.0 can cache:

• Filled maps
• Regular items
• Empty item frames, optionally

Each category can be enabled or disabled independently.

---

🗺️ Large map displays

Item Frame Cache is especially useful for very large map walls and map floors.

Once a map frame has been seen, the mod can keep its cached render state available even after the server stops sending that item frame to your client.

The persistent map cache can also store previously received map pixel data locally, allowing known multiplayer maps to be restored when the server is no longer providing that data.

Only the map image data is stored persistently.

Item-frame positions and normal displayed items are session-only and are not permanently stored.

---

🖼️ Regular items in item frames

Item Frame Cache 2.0 is no longer limited to filled maps.

Regular items displayed in item frames can also remain visible beyond the server's normal entity tracking distance.

This is useful for builds such as:

• Storage systems
• Item displays
• Museums
• Shops
• Decorative interiors
• Large technical or themed builds

Regular-item caching is enabled by default and can be disabled independently from map caching.

---

⬜ Empty item frames

Empty item frames can also be cached.

This option is disabled by default because keeping very large numbers of empty frames in memory may not be useful for every player.

It can be enabled from the configuration file or ModMenu.

---

📏 Configurable render distance

Item Frame Cache supports two render-distance modes.

Fixed distance

Uses a specific distance in blocks.

For example, cached item frames can remain visible up to 512 blocks away regardless of Minecraft's current render-distance setting.

Minecraft distance

Automatically follows Minecraft's current render distance.

A multiplier can be applied to make the cached-frame distance shorter or longer.

Examples:

• 0.5x — half Minecraft's render distance
• 1.0x — match Minecraft's render distance
• 1.5x — 150% of Minecraft's render distance
• 2.0x — twice Minecraft's render distance

This mode is useful if you want cached item frames to stay within roughly the same visual range as the world around them.

---

👁️ Frustum culling

Cached item frames outside the camera view can be skipped automatically.

This reduces unnecessary rendering work for cached frames that cannot currently be seen.

Frustum culling is enabled by default.

---

🧠 Cache limits

Large servers can contain enormous numbers of item frames, so Item Frame Cache includes a configurable maximum cache size.

The default limit is:

10,000 cached item frames

Setting the limit to 0 disables the cap.

This allows players to balance maximum retained visibility against memory usage.

---

💾 Persistent map cache

Previously seen multiplayer map pixel data can be stored locally.

The persistent map cache includes:

• Per-server cache separation
• CRC validation
• Corruption detection
• Asynchronous disk I/O
• Atomic file replacement where supported
• Configurable in-memory map cache
• Automatic cache age cleanup

The persistent map cache is independent from the runtime item-frame cache.

---

⚙️ Configuration

Item Frame Cache 2.0 uses:

config/itemframecache.json

The configuration file controls:

• Map caching
• Regular-item caching
• Empty-frame caching
• Render-distance mode
• Fixed render distance
• Minecraft render-distance multiplier
• Frustum culling
• Maximum cached frames
• Persistent map cache
• Map states kept in RAM
• Maximum persistent map cache age
• Diagnostic cache logging

Manual JSON values are validated and constrained to safe ranges.

---

🖥️ Optional ModMenu support

If ModMenu is installed, Item Frame Cache can be configured directly from Minecraft.

ModMenu is completely optional.

The configuration screen includes controls for all major settings, and every option includes a short tooltip explaining what it does.

Changes made through ModMenu are saved to the same JSON configuration file.

---

🔄 Upgrading from older versions

Existing users can upgrade directly from Item Frame Cache 1.5.x.

If the old:

config/itemframecache.properties

file exists and no JSON configuration has been created yet, Item Frame Cache automatically imports the old settings.

The original properties file is left untouched.

The persistent map cache remains compatible.

Players who only want the previous map-focused behavior can disable regular items and empty frames:

{
  "cacheItems": false,
  "cacheEmptyFrames": false
}