# DigiSim Circuit Playground

> The DigiSim Circuit Playground is the main interface for designing, simulating, and analyzing digital circuits. It provides a comprehensive workspace with drag-and-drop components, real-time simulation, and advanced visualization tools.

## Workspace Interface

The playground consists of several key areas:
- **Component Palette**: Organized library of digital logic components
- **Design Canvas**: Main workspace for circuit construction
- **Connection Layer**: Visual wire routing and management
- **Control Panel**: Simulation controls and settings
- **Properties Panel**: Component configuration and pin details

## Component Categories

### Input Components
- **INPUT_SWITCH**: Toggle switch for manual input control
- **CLOCK**: Configurable frequency clock generator (1Hz default)
- **CONSTANT/CONSTANT_ZERO**: Fixed logic values for circuit testing

### Basic Logic Gates
- **AND/NAND**: 2-8 input AND gates with normal and inverted outputs
- **OR/NOR**: 2-8 input OR gates with normal and inverted outputs
- **XOR/XNOR**: 2-8 input exclusive OR gates
- **NOT**: Single input inverter
- **BUFFER**: Non-inverting buffer for signal conditioning

### Sequential Logic Components
- **D_FLIP_FLOP**: Data flip-flop with clock, preset, and clear
- **JK_FLIP_FLOP**: JK flip-flop with toggle capability
- **T_FLIP_FLOP**: Toggle flip-flop for frequency division
- **SR_LATCH**: Set-reset latch for basic memory
- **D_LATCH**: Data latch with enable control

### Memory and Storage
- **REGISTER**: 4-bit parallel register
- **REGISTER_8BIT**: 8-bit register with parallel load
- **SHIFT_REGISTER**: 4-bit shift register with serial I/O
- **SHIFT_REGISTER_8BIT**: 8-bit shift register with serial I/O
- **COUNTER**: 4-bit counter with enable and clear
- **COUNTER_8BIT**: 8-bit counter with enable and clear
- **RAM**: Random access memory with address and data buses
- **ROM**: Read-only memory for program storage

### Arithmetic Components
- **HALF_ADDER**: Single-bit addition without carry input
- **FULL_ADDER**: Single-bit addition with carry input
- **ADDER**: 4-bit binary adder with carry
- **ADDER_8BIT**: 8-bit binary adder with carry
- **COMPARATOR**: 4-bit magnitude comparator
- **COMPARATOR_8BIT**: 8-bit magnitude comparator
- **ALU**: 4-bit arithmetic logic unit
- **ALU_8BIT**: 8-bit arithmetic logic unit with multiple operations

### Data Routing Components
- **TRI_STATE_BUFFER**: Single tri-state buffer with enable
- **TRI_STATE_BUFFER_8BIT**: 8-bit tri-state buffer
- **MULTIPLEXER**: 2-to-1 data selector
- **MULTIPLEXER_4TO1**: 4-to-1 data selector
- **MULTIPLEXER_8TO1**: 8-to-1 data selector
- **DEMULTIPLEXER**: 1-to-2 data distributor
- **DEMULTIPLEXER_1TO4**: 1-to-4 data distributor
- **DEMULTIPLEXER_1TO8**: 1-to-8 data distributor
- **ENCODER**: 4-to-2 priority encoder
- **ENCODER_8TO3**: 8-to-3 priority encoder
- **DECODER**: 2-to-4 binary decoder
- **DECODER_3TO8**: 3-to-8 binary decoder

### Output and Visualization
- **OUTPUT_LIGHT**: Simple LED indicator for logic states
- **DIGIT_DISPLAY**: 7-segment display for hexadecimal values
- **SEVEN_SEGMENT_DISPLAY**: Individual 7-segment display
- **OSCILLOSCOPE**: 2-channel signal analyzer
- **OSCILLOSCOPE_8CH**: 8-channel signal analyzer for timing diagrams
- **PIXEL_SCREEN_16x16**: 16x16 pixel display matrix
- **TEXT**: Text label component

### CPU Architecture Components
- **PROGRAM_COUNTER_8BIT**: 8-bit program counter
- **INSTRUCTION_REGISTER**: Instruction storage and decode
- **CONTROL_UNIT**: CPU control unit for instruction execution
- **ASSEMBLY_PROGRAM_LOADER**: Assembly code compilation and loading
- **FLAGS_REGISTER**: CPU status flags storage
- **PIXEL_SCREEN_16x16**: 16x16 pixel display with memory mapping

## Simulation Engines

### Event-Driven Simulator
The primary simulation engine provides:
- **Real-time Processing**: Handles timing-dependent components like clocks
- **State Management**: Maintains flip-flop and counter states across simulation cycles
- **Bus Resolution**: Manages multiple drivers on shared connections
- **Performance Optimization**: Efficient event scheduling and propagation

### Component Evaluation
Each component type has specialized evaluation logic:
- **Combinational Logic**: Immediate calculation based on current inputs
- **Sequential Elements**: State-based evaluation with clock edge detection
- **Memory Components**: Address-based data storage and retrieval
- **Display Elements**: Visual rendering of output signals

## Circuit Construction

### Component Placement
1. **Drag from Palette**: Select component from organized categories
2. **Drop on Canvas**: Position component in workspace
3. **Configure Properties**: Set component-specific parameters
4. **Label Components**: Add descriptive text labels

### Connection Management
1. **Pin Identification**: Hover over components to see pin labels
2. **Wire Routing**: Click and drag between pins to create connections
3. **Connection Validation**: System prevents invalid connections
4. **Visual Feedback**: Connected pins highlighted with color coding

### Circuit Organization
- **Grid Alignment**: Components snap to grid for clean layouts
- **Layered Rendering**: Components, connections, and labels on separate layers
- **Zoom Controls**: Scale workspace for detailed editing or overview
- **Pan Navigation**: Move around large circuits efficiently

## Template System Integration

### Educational Templates
The playground integrates with DigiSim's educational template system:
- **Template Browser**: Modal interface for discovering circuits
- **Category Filtering**: Logic Fundamentals, Sequential Logic, CPU Architecture
- **Difficulty Levels**: Beginner, Intermediate, Advanced
- **One-Click Loading**: Instant template loading into workspace

### Featured Circuits
- **AND Gate Security System**: Basic logic gate introduction
- **4-Bit Binary Counter**: Sequential logic demonstration
- **8-Bit ALU System**: Arithmetic logic unit showcase
- **Sequential Instruction Executor**: CPU instruction cycle

## Export and Sharing

### PNG Export
- **Workspace Capture**: Export current circuit as high-quality PNG
- **Automatic Sizing**: Optimal bounds calculation around circuit components
- **Clean Output**: Removes interactive elements for documentation

### Circuit Files
- **Save/Load**: JSON-based circuit file format with metadata
- **Version Control**: Track circuit modifications and creation dates
- **AI Summaries**: Automatic circuit description generation

## Subscription Integration

### Component Access Control
- **FREE Tier**: Basic logic gates, switches, lights
- **BASIC Tier**: Sequential logic, displays, oscilloscope
- **PROFESSIONAL Tier**: CPU components, memory systems, advanced tools

### Visual Indicators
- **Disabled Styling**: Restricted components shown with reduced opacity
- **Upgrade Prompts**: Click-to-upgrade for premium components
- **Real-time Updates**: Component availability changes with subscription status

## Animation System

DigiSim features step-by-step animated circuit tutorials for learning digital logic:

### Animation Playback
- **Step-by-Step Building**: Watch circuits being built component by component
- **Audio Narration**: Voice-over explanations synchronized with animations
- **Subtitles**: Text descriptions for each step
- **Playback Controls**: Play, pause, step forward/backward, speed adjustment

### Animation Features
- **Component Placement**: See how components are positioned on the canvas
- **Wire Connections**: Watch connections being drawn between pins
- **State Changes**: Observe input toggles and signal propagation
- **Visual Highlighting**: Components glow or pulse for emphasis
- **Camera Focus**: Automatic pan and zoom to relevant areas

### File Support
- **Import**: Load animation tutorials from files
- **Export**: Save animations for sharing
- **Online Library**: Access pre-built educational animations

## Performance Optimization

### Rendering Efficiency
- **Virtual Scrolling**: Efficient handling of large component palettes
- **Canvas Optimization**: Hardware-accelerated rendering for smooth interactions
- **Connection Caching**: Optimized wire routing calculations

### Simulation Performance
- **Event Batching**: Group related simulation events for efficiency
- **State Caching**: Minimize redundant component evaluations
- **Memory Management**: Efficient cleanup of simulation resources