Skip to content

For Modpack Devloper

Jump to bottom
IceCubeSoda edited this page Sep 3, 2026 · 18 revisions

🛠️ Lumina Compatibility & Performance Integration Guide

If you are using Lumina as the core engine for your custom modpack, refer to the configuration guidelines and known compatibility workarounds below to maintain maximum stability and rendering throughput when adding external mods.

Note on Configuration Strategy: Lumina intentionally ships with a minimal config/ directory. All unlisted performance mods run on auto-generated engine defaults. Only the files listed below contain tailored overrides.

⚙️ Modpack Expansion & Overhauls

Lumina is configured out of the box for client-side performance and strict vanilla gameplay parity. If you are building a larger modpack project with content, tech, or utility mods, consider these recommended engine adjustments:

  • Quick Pack (Add): Optimizes ZIP archive reading for datapacks and resource packs, significantly cutting main-menu loading and asset reload times.
  • Gnetum (Add): Recommended if your pack introduces heavy HUD overlays (e.g., RPG stats, mini-maps, thirst meters, or item viewer GUIs). It distributes overlay rendering calls across multiple frames to protect FPS and 1% lows.

⚠️ Configuration Toggles & Conflict Resolution

Before removing a performance mod due to a visual artifact or crash, inspect its respective configuration file. Core Lumina mods include targeted compatibility flags designed to resolve external mod overlaps.

1. ModernFix Optimization Mixins (config/modernfix-mixins.properties)

Lumina enables aggressive memory and rendering optimizations in ModernFix. When adding large content mods, custom entities, or custom item renderers, adjust these toggles under user overrides:

# Disable if custom modded items appear invisible or glitch in hand
mixin.perf.faster_item_rendering=false

# Disable if custom mob models, bosses, or armor stands flicker
mixin.perf.compact_entity_models=false

# Disable if custom dimension or structure mods crash during chunk loading
mixin.perf.compact_imposterprotochunks=false

# Disable if custom mod GUIs display raw translation keys (e.g., gui.mod.title)
mixin.perf.dynamic_languages=false

# Leave disabled to allow BadOptimizations to handle model caching cleanly
mixin.perf.model_optimizations=false

2. Worldgen & Biome API Mods (config/zfastnoise.mixin.toml)

If adding Biolith or complex custom terrain/biome generation APIs, disable Fast Noise's biome and surface hooks to prevent worldgen crashes:

[mixin.perf]
surface = false
biome = false

[perf.biomes]
tree = false
end = false

3. Custom Fluid & Pipe Rendering (config/sodium-options.json)

If adding mods that introduce non-vanilla liquid geometry, custom animated fluids, or transparent transport pipes, disable fluid vertex shaping to avoid texture-tiling glitches:

{
  "quality": {
    "improved_fluid_shaping": false
  }
}

4. Custom Tree & Foliage Mods (config/moreculling.toml)

If adding content mods with oversized or non-standard leaf geometry (e.g., The Twilight Forest) that exhibit see-through texture gaps under depth culling, change the leaf culling algorithm:

leavesCullingMode = "CHECK SURROUNDING"

8. Storage & Entity Rendering Cache (config/badoptimizations.txt)

  • Entity Renderer Conflicts: If custom entities from large content mods cause crashes on spawn, set enable_entity_renderer_caching: false.

Clone this wiki locally