Requirements Document: 2D Redstone Circuit Simulator

1. System Overview

The Redstone Simulator will provide a 2D grid environment for designing and testing redstone circuits with core Minecraft redstone components plus a new transistor element. The simulator will accurately model signal propagation, timing, and component interactions.

2. Grid Environment

• 2D Grid Structure: Finite or infinite grid with coordinate system
• Cell States: Each cell contains either a component or empty space
• View Controls: Pan, zoom, and grid navigation capabilities
• Visual Representation: Clear visual distinction between powered/unpowered states

3. Component Requirements

3.1 Basic Components

• Redstone Wire:

  • Transmits power levels 0-15
  • Decreases by 1 per block traveled
  • Connects automatically to adjacent redstone components
  • Visually indicates power level (brightness/color intensity)

• Power Sources:

  • Button: Momentary pulse generator (configurable duration)
  • Switch/Lever: Toggleable persistent power source

• Redstone Torch:

  • Provides power level 15
  • Inverts input signal when attached to a block
  • Supports burnout mechanics when rapidly toggled

• Repeater:

  • Restores signal to full strength (level 15)
  • Configurable delay (1-4 ticks)
  • One-way signal propagation
  • Optional signal locking functionality

3.2 New Component

• Transistor Block:
  • Three connection points: input, control, and output
  • Output signal passes only when control input is powered
  • Configurable behavior (AND/OR/XOR logic)
  • Adjustable output signal strength based on input

4. Signal Propagation System

• Power Levels: Support for 16 discrete power levels (0-15)
• Propagation Rules:
  • Signal decay of 1 per wire block
  • Component-specific propagation behaviors
  • Proper handling of signal branching and merging
• Timing System:
  • Discrete tick-based updates (0.1 second per tick)
  • Proper update order within each tick
  • Visualization of signal propagation timing

5. Simulation Features

• Real-time Simulation: Continuous circuit operation
• Step-by-Step Mode: Advance simulation by individual ticks
• Breakpoints: Pause simulation when specified conditions are met
• Signal Inspection: Tools to examine power levels at any point
• Clock Speed Control: Adjust simulation speed (slower/faster)

6. User Interface Requirements

• Component Palette: Easy selection of available components
• Placement Tools: Click-and-drag placement of components
• Rotation Controls: Ability to orient directional components
• Selection Tools: Select, copy, paste, and delete circuit sections
• Save/Load: Store and retrieve circuit designs

7. Analysis Tools

• Signal Tracing: Visualize signal path through the circuit
• Timing Diagram: Graph showing signal states over time
• Power Consumption: Statistics on component activity
• Logic Analyzer: Monitor multiple points in the circuit simultaneously

8. Export/Import Capabilities

• File Format: Custom format for saving circuit designs
• Image Export: Generate circuit diagrams/screenshots
• Sharing: Mechanism to share circuits with other users

9. Performance Requirements

• Minimum Circuit Size: Support for at least 100×100 grid
• Update Speed: Process at least 20 ticks per second on standard hardware
• Component Limit: Handle at least 1000 active components simultaneously

10. Future Considerations

• Additional component types (comparators, observers)
• 3D circuit support
• Programmable interface for automated testing
• Circuit optimization suggestions