RedLog - Minecraft Redstone Builder

A Python package for building redstone logic circuits in Minecraft Java Edition save files offline. Features a clean class-based architecture with rotation support for creating and composing logic gates programmatically.

Quick Start

1. Installation

# Clone or download the repository
cd RedLog

# Create and activate virtual environment
python -m venv venv

# Windows
venv\Scripts\activate

# Linux/Mac
source venv/bin/activate

# Install the package in development mode
pip install -e .

2. Configure Your World

Edit examples/world-path.txt with your Minecraft world path and coordinates:

C:\Users\YourName\AppData\Roaming\.minecraft\saves\YourWorld

100,64,200

3. Run the Examples

cd examples
python basic_usage.py

That's it! Open your Minecraft world to see the logic gates.

Project Structure

RedLog/
├── redlog/                    # Main Python package
│   ├── core/                  # Core framework classes
│   │   ├── circuit.py         # LogicCircuit base class
│   │   └── factory.py         # RedstoneFactory
│   └── gates/                 # Gate implementations
│       ├── not_gate.py        # NOT gate (inverter)
│       └── nor_gate.py        # NOR gate
├── examples/                  # Example scripts
│   ├── basic_usage.py         # Usage examples
│   └── world-path.txt         # Configuration
└── tests/                     # Tests

Usage Examples

Basic Usage

from redlog.core import RedstoneFactory
from redlog.gates import NOTGate, NORGate

# Configure world path
world_path = "C:/path/to/your/minecraft/saves/WorldName"

# Create factory
factory = RedstoneFactory(world_path)

# Create gates
not_gate = NOTGate(x=100, y=64, z=200)
nor_gate = NORGate(x=110, y=64, z=200)

# Build them in the world
factory.add_circuit(not_gate).add_circuit(nor_gate).build()

print(f"NOT gate: {not_gate.get_dimensions()}")  # (3, 3, 1)
print(f"NOR gate: {nor_gate.get_dimensions()}")  # (3, 3, 2)

With Rotation

All gates support rotation using type-safe enums:

from redlog.core import RedstoneFactory, Rotation
from redlog.gates import NOTGate

factory = RedstoneFactory(world_path)

# Create 4 gates facing different directions using Rotation enum
rotations = [Rotation.NONE, Rotation.CLOCKWISE_90, Rotation.CLOCKWISE_180, Rotation.CLOCKWISE_270]
for i, rotation in enumerate(rotations):
    gate = NOTGate(x=100 + (i * 10), y=64, z=200, rotation=rotation)
    factory.add_circuit(gate)

factory.build()

# You can also use integers for backwards compatibility
gate = NOTGate(x=100, y=64, z=200, rotation=90)  # Still works!

Method Chaining

from redlog.core import RedstoneFactory
from redlog.gates import NOTGate

# Build multiple gates with elegant syntax
(RedstoneFactory(world_path)
    .add_circuit(NOTGate(x=100, y=64, z=200))
    .add_circuit(NOTGate(x=100, y=64, z=210, rotation=90))
    .add_circuit(NOTGate(x=100, y=64, z=220, rotation=180))
    .build())

Architecture Overview

RedLog uses a clean separation of concerns:

LogicCircuit (Base Class)

• Defines block layout as relative coordinates
• Circuits are relocatable by changing origin
• Supports rotation (0°, 90°, 180°, 270°)
• Child classes populate blocks list in __init__

RedstoneFactory

• Handles world manipulation
• Loads world once, places all blocks, saves
• Efficient batch building for multiple circuits
• Supports method chaining

Key Principles:

• Gates are lightweight data structures (no world access)
• Relative coordinate system makes circuits easily relocatable
• Direct instantiation - developers create gate objects directly
• Factory pattern enables efficient batch operations
• Automatic rotation support for all gates

Available Gates

Gate	Inputs	Outputs	Size (W×H×D)	Description
NOTGate	1	1	3×3×1	Inverter - outputs opposite of input
NORGate	2	1	3×3×2	Outputs ON only when both inputs are OFF

Note: NOR is a universal gate - any boolean function can be built using only NOR gates.

Gate Truth Tables

NOT Gate

Input	Output
0	1
1	0

NOR Gate

A	B	Output
0	0	1
0	1	0
1	0	0
1	1	0

Creating Custom Gates

Inherit from LogicCircuit and use the _add_block() helper with type-safe enums:

from typing import List, Tuple
from redlog.core import LogicCircuit, Rotation, ComponentType, WireConnection

class MyGate(LogicCircuit):
    """
    Custom gate example.
    """

    def __init__(self, x: int, y: int, z: int, rotation: Rotation | int = Rotation.NONE):
        super().__init__(x, y, z, rotation)

        # Add blocks with RELATIVE coordinates using type-safe enums
        # Helper automatically handles rotation
        self._add_block(0, 0, 0, ComponentType.WIRE, WireConnection.EAST_WEST)
        self._add_block(1, 0, 0, ComponentType.TORCH)
        self._add_block(2, 0, 0, ComponentType.WIRE, WireConnection.EAST_WEST)

    def get_input_positions(self) -> List[Tuple[int, int, int]]:
        """Return ABSOLUTE input positions."""
        return [(self.origin_x - 1, self.origin_y, self.origin_z)]

    def get_output_positions(self) -> List[Tuple[int, int, int]]:
        """Return ABSOLUTE output positions."""
        return [(self.origin_x + 3, self.origin_y, self.origin_z)]

Helper Method: _add_block(dx, dy, dz, top, wire_connection)

Automatically creates stone blocks with components on top using type-safe enums:

ComponentType enum:

• ComponentType.TORCH - Adds redstone torch
• ComponentType.WIRE - Adds redstone wire (requires wire_connection parameter)
• None - Just the stone block

WireConnection enum (used with ComponentType.WIRE):

• WireConnection.EAST_WEST - Wire connecting East-West
• WireConnection.NORTH_SOUTH - Wire connecting North-South
• WireConnection.ALL - Wire connecting all four directions (NESW)
• WireConnection.NONE - Wire with no specific connections

Rotation is automatic! The helper rotates both coordinates and wire connections.

How Rotation Works

# Same gate definition, different orientations
gate_0   = NOTGate(x=0, y=64, z=0, rotation=0)    # Faces East
gate_90  = NOTGate(x=10, y=64, z=0, rotation=90)  # Faces South
gate_180 = NOTGate(x=20, y=64, z=0, rotation=180) # Faces West
gate_270 = NOTGate(x=30, y=64, z=0, rotation=270) # Faces North

# Wire connections auto-rotate:
# wire:EW at 0°   → wire:EW
# wire:EW at 90°  → wire:NS
# wire:EW at 180° → wire:EW
# wire:EW at 270° → wire:NS

Coordinate System

Blocks are stored with relative coordinates internally:

# In your gate's __init__:
self._add_block(0, 0, 0, top="wire:EW")  # Relative (0, 0, 0)
self._add_block(1, 0, 0, top="torch")    # Relative (1, 0, 0)

# RedstoneFactory transforms to absolute when building:
# If origin is (100, 64, 200):
#   - Wire at (100, 64, 200)
#   - Torch at (101, 64, 200)

# Change origin to (500, 80, 300) - same circuit, new location!

Development

Adding a New Gate

1. Create redlog/gates/your_gate.py
2. Inherit from LogicCircuit
3. Export in redlog/gates/__init__.py

Example structure:

from typing import List, Tuple
from redlog.core import LogicCircuit

class YourGate(LogicCircuit):
    def __init__(self, x: int, y: int, z: int, rotation: int = 0):
        super().__init__(x, y, z, rotation)
        # Build your gate using _add_block()

    def get_input_positions(self) -> List[Tuple[int, int, int]]:
        return [...]  # Absolute positions

    def get_output_positions(self) -> List[Tuple[int, int, int]]:
        return [...]  # Absolute positions

Running Examples

See examples/basic_usage.py for complete working examples:

• Single gate building
• Multiple gates (efficient batch building)
• Rotation examples
• Method chaining

Important Notes

• Always backup your world before running scripts
• Make sure Minecraft is closed when running scripts
• Y coordinate should be valid (typically 60-80 for overworld, 0-319 in 1.20.1)
• Signal sources are external - gates don't include levers/buttons
• Place your own levers, torches, etc. to power the inputs
• Rotation changes dimensions: 3×3×1 (0°/180°) ↔ 1×3×3 (90°/270°)

Requirements

• Python 3.10 or higher (3.12 recommended)
• Minecraft Java Edition save file
• Dependencies: amulet-core, amulet-nbt (installed automatically)

Troubleshooting

Import errors:

# Make sure you've installed the package
pip install -e .

Module not found:

# Activate virtual environment first
venv\Scripts\activate  # Windows
source venv/bin/activate  # Linux/Mac

World doesn't load:

• Check that the path is correct in world-path.txt
• Ensure Minecraft is closed
• Verify you have write permissions

Blocks don't appear:

• Verify coordinates are in loaded chunks
• Check Y coordinate is valid for the dimension
• Make sure world save was successful (check console output)

License

This is an open-source educational project for learning redstone logic and Python programming.

Contributing

Contributions welcome! To add new gates:

1. Follow the project structure
2. Inherit from LogicCircuit
3. Use the _add_block() helper for consistency
4. Test with different rotations
5. Add examples to examples/

Future Development

Planned features:

• Additional logic gates (AND, OR, NAND, XOR, XNOR)
• Wire connection utilities
• Multi-gate circuit composition
• Circuit templates and patterns
• Unit tests

---

Happy building! 🎮⚡