tinytorch/README.md

TinyTorch

A Minecraft Fabric mod that makes lighting more realistic and atmospheric by reducing torch brightness and adding optional flickering effects.

Features

Core Features

• Reduced Light Radius: Normal torch brightness reduced from light level 14 to configurable level (default: 8)
• Works for all torch types: Both standing and wall torches affected
• Configurable: All settings customizable via tinytorch.json

Optional Effects

• Flicker Effect: Light level oscillates randomly ±1 every few ticks to simulate flickering flame
• Particle Effects: Small smoke and spark particles appear occasionally around torches
• Held Light: Torches emit weak light (level 4-5) when held in main/offhand
• Smart Updates: Held light only updates when player moves for performance

Advanced Features

• Light Falloff Curve: Sharper brightness drop-off after a few blocks (dark corners stay dark)
• Material-Based Lighting:
  • Stone/Cobblestone/Deepslate absorb light slightly
  • Iron/Copper/Gold blocks reflect light slightly
• Performance Optimized: Lightweight implementation compatible with OptiFine/Sodium

Configuration

In-Game Configuration

TinyTorch supports multiple ways to configure settings in-game:

ModMenu Integration (Recommended)

1. Install ModMenu
2. Go to Mods menu → TinyTorch → Config
3. Adjust settings with sliders and toggles
4. Changes save automatically

In-Game Commands

For server operators, use commands to configure settings:

# Show current configuration
/tinytorch config show

# Reload configuration from file  
/tinytorch config reload

# Set torch light level (0-15)
/tinytorch config set torch_light_level 8

# Set held torch light level (0-15)
/tinytorch config set held_light_level 5

# Enable/disable flicker effects
/tinytorch config set enable_flicker true

# Set flicker speed (1-20, higher = slower)
/tinytorch config set flicker_speed 5

# Enable/disable held torch lighting
/tinytorch config set held_light true

# Enable/disable sharp light falloff
/tinytorch config set use_falloff_curve true

Manual Configuration File

The mod creates a tinytorch.json file in your config folder:

{
  "torch_light_level": 8,
  "held_light_level": 5, 
  "enable_flicker": true,
  "flicker_speed": 5,
  "use_falloff_curve": true,
  "held_light": true
}

Config Options

• torch_light_level (0-15): Light level emitted by placed torches (default: 8)
• held_light_level (0-15): Light level when holding a torch (default: 5)
• enable_flicker (true/false): Enable flickering flame effect (default: true)
• flicker_speed (1+): Ticks between flicker changes, higher = slower (default: 5)
• use_falloff_curve (true/false): Use custom sharp light falloff (default: true)
• held_light (true/false): Enable dynamic lighting when holding torches (default: true)

Gameplay Impact

• Caves become darker even with torches, forcing closer placement
• Building interiors have cozy, dim lighting atmosphere
• Night exploration feels eerie but natural
• Torches glow gently in-hand when walking at night
• Strategic lighting becomes more important for visibility

In-Game Configuration

TinyTorch provides three convenient ways to adjust settings:

1. ModMenu GUI (Recommended)

• Install ModMenu
• Access via Mods → TinyTorch → Config button
• User-friendly sliders and toggles
• Changes save automatically

2. In-Game Commands (Server Admins)

• /tinytorch config show - View current settings
• /tinytorch config set torch_light_level 6 - Change values
• /tinytorch config reload - Reload from file
• Requires OP permissions

3. Config File (Advanced Users)

• Edit .minecraft/config/tinytorch.json
• Use /tinytorch config reload to apply changes

Installation

1. Download and install Fabric Loader
2. Download Fabric API
3. (Optional but recommended) Download ModMenu for in-game config
4. Download TinyTorch and place in your mods folder
5. Launch the game and enjoy atmospheric lighting!