NeuroLux

Replace Minecraft's BFS light propagation with single-pass 3D CNN inference
GPU Accelerated  |  Trainable Custom Models  |  Automatic Vanilla BFS Fallback

_{中文 | English}

---

Status: Experimental / Research Prototype. This is a research project exploring whether neural networks can predict Minecraft lighting. Not production-ready. See Limitations before use.

Table of Contents

• Why?
• Features
• Demo
• Requirements
• Installation
• Quick Start
• Commands
• Architecture
• Model Evaluation
• Training
• Limitations
• Project Structure
• Contributing
• Citation
• License
• Acknowledgments

Why?

Minecraft's lighting engine uses Breadth-First Search (BFS) to iteratively propagate light. On every block update:

1. Scan the 16x16x16 subchunk
2. Propagate light values to 6 neighbors
3. Repeat until convergence
4. Recursively trigger adjacent subchunks

On complex redstone machinery, large TNT explosions, or chunk loading, this causes significant TPS lag.

NeuroLux replaces this with a hybrid approach: vanilla BFS handles cross-subchunk propagation and rendering state, then a 3D CNN performs single-pass inference on subchunks containing light sources, directly predicting final light values.

This is not a drop-in replacement. The model is trained on synthetic BFS data and has not been fully validated against real Minecraft gameplay complexity.

Features

• 3D CNN Inference — U-Net encoder-decoder, predicts lighting for 4,096 blocks in a single forward pass
• Hybrid Architecture — Neural network handles light-source subchunks; vanilla BFS handles the rest
• GPU Acceleration — CUDA support with automatic CPU fallback
• Safe Fallback — Auto-reverts to vanilla BFS after 10 consecutive inference failures
• Complete Training Pipeline — Synthetic data generation + PyTorch training + ONNX export, no Minecraft instance needed
• In-Game Commands — Hot-switch between neural / analysis / vanilla modes, real-time stats

Demo

Vanilla BFS (Iterative Propagation)	Neural Engine (BFS + CNN Post-processing)
Place light → scan → propagate neighbors → re-scan → ... → converge	Place light → BFS propagation → CNN predicts final values → done

Requirements

Dependency	Version	Notes
Minecraft	26.2
NeoForge	26.2.0.25-beta
Java	25+	Microsoft OpenJDK
GPU (optional)	CUDA-capable	CPU fallback available, may be slower than vanilla BFS

Note: This mod uses ONNX Runtime for inference. Without a CUDA GPU it falls back to CPU, which may be slower than vanilla BFS. A dedicated GPU is recommended.

Installation

Download Pre-built

1. Install NeoForge for Minecraft 26.2
2. Download the latest .jar from Releases
3. Place in .minecraft/mods/
4. Launch the game

Build from Source

git clone https://github.com/Fengrru/neuro-lux.git
cd neuro-lux

# Windows
gradlew.bat build

# Linux / macOS
chmod +x gradlew
./gradlew build

Output: build/libs/neuro-lux-1.0.0.jar

Quick Start

1. Launch the game and type:

/neural

Verify that the output shows Engine: ENABLED and Model: Loaded.

2. Switch modes:

/neural mode neural       # Neural network lighting (default)
/neural mode analysis     # Vanilla + data collection
/neural mode vanilla      # Fully disable mod

3. View inference statistics:

/neural stats

Commands

/neural                                  # Display engine status
/neural mode <neural|analysis|vanilla>   # Switch mode
/neural enable                           # Enable neural engine
/neural disable                          # Disable neural engine
/neural stats                            # Show inference statistics
/neural collect <on|off>                 # Toggle data collection
/neural reset                            # Reset statistics

Mode	Description	Use Case
neural	BFS + CNN inference (default)	General gameplay
analysis	Vanilla BFS + data collection	Preparing custom models
vanilla	Fully disable mod, use vanilla BFS	Benchmarking / troubleshooting

Architecture

Inference Pipeline

Block change → checkBlock()
    │
    ▼
NeuroLuxTriggerMixin → enqueueSection(sectionPos)
    │
    ▼
Vanilla BFS (runLightUpdates) ─── cross-subchunk propagation ───┐
    │                                                             │
    ▼ (RETURN)                                                    │
processPendingInferences()                                        │
    │                                                             │
    ├── extractBlockStates()   [16³ × 5 → float[4096×5]]
    ├── runInference()         [ONNX 3D CNN → float[4096×2]]
    └── applyToDataLayer()     [write block_light + sky_light]

Input Features (5 channels per block)

Input: [B, 5, 16, 16, 16]
  ├── Ch 0: light_emission    [0, 15] → [0, 1]
  ├── Ch 1: light_opacity     [0, 15] → [0, 1]
  ├── Ch 2: is_solid          {0, 1}
  ├── Ch 3: propagates_sky    {0, 1}
  └── Ch 4: is_air            {0, 1}

Model Architecture

U-Net 3D CNN (skip connections)
  enc1: Conv3d 5→32,   k=3, stride=1, ReLU
  enc2: Conv3d 32→64,  k=3, stride=2, ReLU
  enc3: Conv3d 64→128, k=3, stride=2, ReLU
  enc4: Conv3d 128→256, k=3, stride=2, ReLU
  bottleneck: Conv3d 256→256, k=3, ReLU
  dec1: DeConv3d + skip(e3) → 256 channels
  dec2: DeConv3d + skip(e2) → 128 channels
  dec3: DeConv3d + skip(e1) → 64 channels
  output: Conv3d 64→2, k=1, Sigmoid

Output: [B, 2, 16, 16, 16]
  ├── Ch 0: block_light  [0, 1] → [0, 15]
  └── Ch 1: sky_light    [0, 1] → [0, 15]

Key Metrics

Metric	Value
Parameters	4.38M
ONNX model size	~16.7 MB
Input shape	[1, 5, 16, 16, 16]
Output shape	[1, 2, 16, 16, 16]
Inference (GPU)	~2-5 ms (estimated)
Inference (CPU)	~15-30 ms (estimated)

Inference times are estimates. Actual performance depends on GPU/CPU model and system load.

Model Evaluation

Current checkpoint (epoch 4, skip-connection U-Net, synthetic BFS data):

Metric	Value
MAE	0.079 / 15.0
±1 tolerance accuracy	98.3%

These metrics are on synthetic BFS data, not real Minecraft gameplay. Real-world accuracy may differ significantly.

Training

Training data is generated via synthetic BFS — no Minecraft instance required.

cd training
pip install -r requirements.txt

# Train
python train.py --epochs 100

# Evaluate
python evaluate.py --checkpoint checkpoints/best_model.pt --visualize

# Export ONNX
python export_onnx.py --checkpoint checkpoints/best_model.pt

# Deploy to mod
cp light_engine.onnx ../src/main/resources/config/neurolux/

Script	Description
synthetic_data.py	Generate 16×16×16 block scenes + BFS ground truth
model.py	U-Net 3D CNN architecture (~4.38M params)
train.py	Training loop, L1 + gradient loss
evaluate.py	Per-scene evaluation with visualization
export_onnx.py	Export to ONNX format

Limitations

Rendering artifact at subchunk boundaries: the neural model only sees a single 16×16×16 subchunk, causing potential dark spots or discontinuities across boundaries.

• Synthetic training data — trained on simplified BFS simulations, not real-world edge cases
• Subchunk blind spot — CNN sees only one 16×16×16 subchunk; light sources in adjacent subchunks are invisible
• Rendering artifacts — neural predictions may incorrectly override BFS results, causing seams or dark spots (see above)
• Shader incompatibility — likely conflicts with Iris, OptiFine, and other shader mods
• Starlight conflict — do not use alongside Starlight (lighting engine rewrite conflict)
• No redstone awareness — the model does not account for redstone-controlled light sources
• Not production-ready — research prototype, use at your own risk in survival worlds

Project Structure

neuro-lux/
├── src/main/java/com/fengrru/neurolux/
│   ├── NeuroLuxMod.java                 # Mod entry point
│   ├── NeuroLuxEngine.java              # ONNX inference + pending queue
│   ├── config/NeuroLuxConfig.java       # Mod configuration
│   ├── command/NeuroLuxCommand.java     # /neural command (Brigadier)
│   ├── data/DataCollector.java          # Training data collection
│   └── mixin/
│       ├── WorldMixin.java              # Level → LightEngine registration
│       ├── NeuroLuxTriggerMixin.java    # checkBlock → enqueue → infer
│       └── LightEngineAnalysisMixin.java # ANALYSIS mode hooks
├── training/                            # Python training pipeline
├── src/main/resources/
│   ├── META-INF/neoforge.mods.toml
│   ├── neurolux.mixins.json
│   └── config/neurolux/
│       └── light_engine.onnx            # Trained model
├── .github/workflows/build.yml
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
├── .editorconfig
├── .gitattributes
└── LICENSE

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Citation

@software{neuro_lux,
  title  = {NeuroLux: CNN-based Light Propagation for Minecraft},
  author = {Fengrru},
  year   = {2026},
  url    = {https://github.com/Fengrru/neuro-lux},
  note   = {Experimental research prototype}
}

License

MIT

Acknowledgments

• Phosphor / Starlight — Pioneering lighting engine optimization, inspiring this project
• ONNX Runtime — Cross-platform ML inference engine
• NeoForge — Minecraft modding framework
• Mixin — Bytecode injection framework