Item Frame Cache

Item Frame Cache is a lightweight client-side Fabric mod designed for very large map walls, map floors and other displays made from filled maps placed in item frames.

In vanilla Minecraft, item frames are entities. When you move beyond the server's entity tracking distance, those frames can disappear even though the surrounding terrain is still visible.

Item Frame Cache solves this by remembering filled-map item frames after they have been rendered once and keeping them visible when the server stops tracking those entities.

Starting with version 1.5.0, Item Frame Cache also includes a persistent map data cache, allowing map pixel data received from multiplayer servers to be stored locally and reused when the server no longer provides it.

Features

• Keeps filled maps visible beyond the server's item frame tracking distance.
• Designed for huge map walls and map floors containing hundreds or thousands of maps.
• Persistent map data cache for multiplayer servers.
• Cached map data can survive disconnects and game restarts.
• Server-provided map data always takes priority over cached data.
• Item frame positions remain session-only, preventing stale or ghost maps after reconnecting.
• Optimized RAM usage for very large map displays.
• LRU + soft-reference memory management for cached map data.
• Asynchronous disk reading and writing to minimize impact on game performance.
• Automatic detection and removal of corrupted cache files.
• Automatic cleanup of old cached map data.
• Configurable render distance.
• Optional frustum culling.
• Fully client-side.
• Compatible with vanilla servers.
• No server installation required.
• No Fabric API required.

How it works

When a filled map in an item frame is rendered normally by Minecraft, Item Frame Cache remembers the required render information.

If the server later stops sending that item frame because you have moved outside its tracking range, the cached version can continue to be displayed by the client.

Map pixel data received from multiplayer servers is also stored locally. If Minecraft later needs that map data and the server is no longer providing it, Item Frame Cache can restore it from the local cache.

Vanilla server data always has priority. When updated map information is received from the server, the local cached data is replaced.

If a map is removed from an item frame while the client can see that change, the cached frame is immediately invalidated and the map disappears normally.

Memory optimization

Item Frame Cache is designed with very large displays in mind.

Persistent map data uses a limited in-memory cache. By default, only a configurable number of map states are strongly retained in RAM, while additional cached maps can be released by Java when memory is required and loaded again from disk when needed.

Cached item frame render states are also stripped of unnecessary rendering information whenever possible, reducing memory usage when thousands of maps are retained.

Configuration

The mod creates:

config/itemframecache.properties

Default settings:

render_distance_blocks=512
frustum_culling=true
persistent_map_cache=true
map_cache_memory_entries=512
map_cache_max_age_days=180
log_cache_stats=false

render_distance_blocks

Maximum distance at which cached item frame maps can remain visible.

frustum_culling

Skips cached maps that are outside the camera view.

persistent_map_cache

Enables persistent storage of multiplayer map pixel data.

map_cache_memory_entries

Maximum number of fallback map states strongly retained in RAM. Additional cached maps can be released from memory and restored from disk when needed.

map_cache_max_age_days

Automatically removes persistent map cache files older than the specified number of days.

Set to 0 to disable automatic cleanup.

log_cache_stats

Outputs persistent cache statistics to the Minecraft log when changing server sessions.

Compatibility

Current releases support:

• Minecraft 1.21–1.21.1
• Minecraft 1.21.2–1.21.8
• Minecraft 1.21.9–1.21.11
• Minecraft 26.1–26.2

Separate builds are provided where Minecraft rendering internals require different implementations.

Important

Item Frame Cache does not increase the server's entity tracking distance and does not generate map data that the client has never received.

A map or item frame must first have been received and rendered normally before it can be cached.

Persistent storage applies to map data, not item frame positions. Frame positions are deliberately kept session-only so that changes made to the world while you are disconnected do not create permanently cached or outdated item frames.

Requirements

• Fabric Loader
• A supported Minecraft version

Fabric API is not required.

License

Item Frame Cache is distributed under the Item Frame Cache License 1.0.

Official license:

https://thewicked.tv/mods/ifc/license-ifc.txt

Unauthorized redistribution, reuploads, mirrors, modified versions and derivative distributions are not permitted without prior written authorization from the copyright holder.