Item Frame Cache

Item Frame Cache is a lightweight, client-side Minecraft mod that keeps previously seen item frames and wall paintings visible beyond the server's normal entity-tracking distance.

Originally created for huge map walls and map floors, Item Frame Cache has grown into a general-purpose decoration cache supporting:

• 🗺️ Filled maps in item frames
• 📦 Regular items displayed in item frames
• ⬜ Empty item frames, optionally
• 🖼️ Wall paintings, including large multi-block paintings

This makes it especially useful for:

• Huge map walls and map floors
• Decorative builds
• Museums and galleries
• Storage rooms using item frames as labels
• Shops and item showcases
• Large bases containing hundreds or thousands of decorations

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

---

✨ What Item Frame Cache does

Minecraft servers stop sending many entities to the client once they move beyond their normal tracking distance.

This can cause item frames, their contents and paintings to disappear even while the surrounding terrain is still visible.

Item Frame Cache remembers decorations that you have already seen and can continue rendering them after the server stops tracking them.

Version 2.1 can cache:

• Filled maps
• Regular items
• Empty item frames
• Wall paintings

Each major category can be enabled or disabled independently.

---

🖼️ Wall painting cache

New in 2.1

Item Frame Cache can now retain normal Minecraft paintings placed directly on walls.

Once a painting has been seen, it can remain visible beyond the server's entity-tracking distance just like cached item frames.

The painting cache supports:

• Small and large paintings
• Multi-block paintings
• Chunk unload and reload
• Long-distance rendering
• Frustum culling
• Configurable render distance
• Correct removal when the painting is destroyed
• Correct removal when one of its required supporting blocks is broken

Cached paintings remain available when their area unloads, avoiding the gradual painting pop-in that normally occurs while returning to an area and waiting for the server to resend each painting entity.

Painting caching is enabled by default and can be 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, regular displayed items and paintings are session-only and are not permanently stored.

---

📦 Regular items in item frames

Item Frame Cache is not 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:

• 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 screen or JSON configuration file.

---

📏 Configurable render distance

Item Frame Cache supports two render-distance modes.

Fixed distance

Uses a specific distance in blocks.

For example, cached item frames and paintings 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 decoration cache 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 lets cached decorations stay within approximately the same visual range as the world around them.

---

👁️ Frustum culling

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

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

Frustum culling is enabled by default.

---

🧠 Cache limits

Large servers and builds can contain enormous numbers of item frames and paintings.

Item Frame Cache therefore includes a configurable maximum cache size.

The default limit is:

10,000 cached decorations

The limit is shared between cached item frames and paintings.

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 and painting cache.

---

⚙️ Configuration

Item Frame Cache uses:

config/itemframecache.json

The configuration controls:

• Map caching
• Regular-item caching
• Empty-frame caching
• Painting caching
• Render-distance mode
• Fixed render distance
• Minecraft render-distance multiplier
• Frustum culling
• Maximum cached decorations
• 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.

---

🖥️ In-game configuration

Item Frame Cache includes an in-game configuration screen.

On Fabric and Quilt, it integrates with Mod Menu when Mod Menu is installed.

On NeoForge and Forge, the configuration screen is available through the loader's Mods interface.

The configuration screen includes controls for the major cache settings, with tooltips explaining each option.

Changes are saved to the same JSON configuration file.

---

🔄 Upgrading from older versions

Existing users can upgrade directly from previous Item Frame Cache versions.

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.

Version 2.1 adds painting caching as a new option, enabled by default.

Players who only want the original map-focused behavior can disable regular items, empty frames and paintings.

Example:

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

---

🧩 Supported loaders

Item Frame Cache 2.1 is available for:

• Fabric
• Quilt
• NeoForge
• Forge

Loader availability may depend on the Minecraft version.

---

💻 Requirements

• Client-side only
• No server installation required
• Java 25 for Minecraft 26.3