Item Frame Cache 2.0.0

Item Frame Cache 2.0.0 is a major update that expands the mod beyond map walls. The cache can now preserve regular items and optionally empty item frames, adds a completely new configuration system, optional ModMenu integration, configurable cache limits, and new render-distance behavior.

✨ Major new features

Support for regular items in item frames

Item Frame Cache is no longer limited to filled maps.

Version 2.0.0 can now cache and keep visible:

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

This means large storage rooms, museums, shops, decorative builds, item displays and other areas using item frames can now benefit from the same client-side caching system previously available mainly for map walls.

Maps and regular items can be enabled or disabled independently.

Optional empty item frame caching

A new setting allows empty item frames to remain cached as well.

This is disabled by default because worlds containing very large numbers of empty frames may increase memory usage unnecessarily.

🖥️ New ModMenu configuration screen

Item Frame Cache can now be configured directly from Minecraft when ModMenu is installed.

ModMenu remains completely optional.

The configuration screen provides controls for:

• Cache maps
• Cache regular items
• Cache empty item frames
• Frustum culling
• Render distance mode
• Fixed render distance
• Minecraft render-distance multiplier
• Maximum number of cached frames
• Persistent map cache
• Number of map states retained in RAM
• Maximum persistent map cache age
• Cache statistics logging

New option tooltips

Every ModMenu setting now includes a short explanation describing what the option does and, where relevant, its effect on memory or rendering.

This should make it considerably easier to configure Item Frame Cache without needing to consult external documentation.

⚙️ New JSON configuration system

The old properties-based configuration has been replaced by:

config/itemframecache.json

The JSON file allows more precise control than the ModMenu presets and can be edited manually.

Existing users are not forced to recreate their configuration from scratch:

Item Frame Cache automatically imports the old itemframecache.properties configuration when the new JSON file does not yet exist.

The old properties file is left untouched.

📏 New render distance modes

Item Frame Cache 2.0.0 introduces two different ways to determine how far cached frames remain visible.

Fixed mode

Uses an explicit distance in blocks.

Example:

"renderDistanceMode": "FIXED",
"renderDistanceBlocks": 512

This behaves similarly to previous Item Frame Cache versions.

Minecraft mode

The cache distance automatically follows Minecraft's configured render distance.

Example:

"renderDistanceMode": "MINECRAFT",
"renderDistanceMultiplier": 1.0

A multiplier can be applied to increase or reduce that distance.

For example:

• 0.5 = half Minecraft's render distance
• 1.0 = match Minecraft's render distance
• 1.5 = 150%
• 2.0 = twice Minecraft's render distance

This is particularly useful for players using mods such as distant terrain renderers, because cached item frames no longer need to remain visible far beyond the area where normal Minecraft terrain is being rendered.

🧠 Configurable cache size

A new setting limits how many item frames Item Frame Cache may keep in memory:

"maxCachedFrames": 10000

This provides a predictable memory ceiling for extremely large worlds or servers.

Setting the value to:

0

disables the limit.

The default limit is 10,000 cached item frames.

🚀 Improved cache architecture

The runtime cache has been redesigned to support different kinds of item frames while keeping their required render information.

The cache now distinguishes between:

• Map frames
• Regular item frames
• Empty frames

On the Minecraft 26.x rendering pipeline, cached states are optimized according to their contents so unnecessary render information can be discarded wherever possible.

Map frames continue to receive the most aggressive optimization because the map itself is the important visual content.

Regular item frames preserve the information necessary to render both the frame and its displayed item.

👁️ Frustum culling

Cached item frames outside the current camera view can continue to be excluded from rendering.

This avoids unnecessary processing for cached frames that cannot currently be seen.

Frustum culling remains enabled by default.

💾 Persistent map cache retained and integrated

The persistent filled-map cache introduced in Item Frame Cache 1.5 remains fully supported.

Previously seen multiplayer map pixel data can still be stored locally and restored when the server is no longer providing that map data.

Persistent map data remains separate from the runtime item-frame cache.

Only map image data is stored between sessions.

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

The persistent map cache continues to include:

• Per-server cache separation
• Corruption detection
• CRC validation
• Asynchronous disk I/O
• Atomic file replacement when supported
• Memory caching
• Automatic age cleanup
• Configurable memory limits

🔄 Live configuration changes

Changes made through ModMenu are applied immediately.

The active runtime frame cache is refreshed when configuration changes are saved, preventing frames belonging to a newly disabled cache category from remaining visible from an older cache state.

This also fixes a configuration-state issue found during development of the Minecraft 1.21.x builds.

📊 Cache diagnostics

Optional cache statistics can still be written to the Minecraft log for troubleshooting and performance analysis.

This remains disabled by default.

🧪 Performance

The 2.0 architecture was tested with very large item-frame installations, including a test area containing 3,477 item frames.

Testing showed that the expanded cache architecture remains lightweight even with thousands of cached frames.

Map-heavy testing showed performance comparable to or slightly better than Item Frame Cache 1.5.0, while testing regular displayed items showed only a small additional rendering cost and no significant increase in average memory consumption.

Because of those results, 2.0.0 does not introduce unnecessary additional state-deduplication complexity.

🛠️ Configuration defaults

The default 2.0.0 configuration is approximately:

{
  "cacheMaps": true,
  "cacheItems": true,
  "cacheEmptyFrames": false,

  "renderDistanceMode": "FIXED",
  "renderDistanceBlocks": 512,
  "renderDistanceMultiplier": 1.0,

  "frustumCulling": true,
  "maxCachedFrames": 10000,

  "persistentMapCache": true,
  "mapCacheMemoryEntries": 512,
  "mapCacheMaxAgeDays": 180,

  "logCacheStats": false
}

Manual JSON values are validated and constrained to safe ranges.

🎮 Minecraft compatibility

Minecraft 26.x

One universal Fabric build supports:

• Minecraft 26.1
• Minecraft 26.1.1
• Minecraft 26.1.2
• Minecraft 26.2

Requires Java 25.

Minecraft 1.21.x

Three optimized compatibility builds cover:

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

Requires Java 21.

All supported 1.21.x versions are compiled and validated separately in CI.

📦 Dependencies

• Fabric Loader required
• Fabric API is not required
• ModMenu is optional

Without ModMenu, Item Frame Cache works normally and can be configured through itemframecache.json.

🔁 Upgrading from 1.5.0

Existing users can replace Item Frame Cache 1.5.0 directly with 2.0.0.

The persistent map cache remains compatible with the new version.

If an old itemframecache.properties file exists and no JSON configuration has yet been created, Item Frame Cache will migrate those settings automatically.

The biggest behavioral change is that regular item frames are now cached by default.

Players who only want the old map-focused behavior can simply set:

"cacheItems": false,
"cacheEmptyFrames": false

Summary

Item Frame Cache 2.0.0 turns the original map-wall cache into a general-purpose item-frame caching system while retaining the lightweight client-side philosophy of previous releases.

Large map walls, item displays, museums, storage systems and decorative builds can now remain visually complete even after the Minecraft server stops tracking their item-frame entities.