# Rusty Emu - Cross-Platform System Emulator

![Rust](https://img.shields.io/badge/language-Rust-orange.svg)
![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Platform](https://img.shields.io/badge/platform-cross--platform-lightgrey.svg)

## 🎯 Project Overview

**Rusty Emu** is a modular, cross-platform system emulator written in Rust, designed to emulate various historical computing systems and embedded devices with a focus on accuracy and performance.

### Currently Supported Systems

| System | Status | Description |
|--------|---------|-------------|
| **Intel MCS-4** | ✅ Implemented | Historical 4-bit microprocessor family |
| **Commodore VIC-20** | 🔄 Planned | Classic 8-bit home computer |
| **Yamaha TG100** | 🔄 Planned | AWM tone generator module |

---

## 🏗️ Architecture

### Core Components
```text
rusty_emu/
├── src/
│   ├── core/              # Emulator core infrastructure
│   │   ├── cpu/           # CPU emulation base
│   │   ├── memory/        # Memory management
│   │   └── peripherals/   # I/O device handling
│   ├── systems/           # System-specific implementations
│   │   ├── intel_mcs4/    # Intel MCS-4 emulation
│   │   ├── vic20/         # VIC-20 emulation (planned)
│   │   └── yamaha_tg100/  # Yamaha TG100 emulation (planned)
│   └── ui/                # User interface components
```
---

### Key Features

- **Modular Design**: Easily extensible for new systems
- **Cross-Platform**: Runs on Windows, macOS, and Linux
- **Cycle-Accurate**: Precise timing emulation
- **Debugging Support**: Built-in debugging capabilities
- **Hardware Rendering**: Efficient graphics emulation

---

## 🚀 Getting Started

### Prerequisites

- Rust **1.70+** toolchain
- Cargo package manager
- System dependencies for graphics/audio

### Installation

```bash
# Clone the repository
git clone https://github.com/jhunnius/rusty_emu.git
cd rusty_emu

# Build in release mode
cargo build --release

# Run with specific system
cargo run --release -- --system intel_mcs4 --rom path/to/rom.bin
```

### Quick Examples

```bash
# Emulate Intel MCS-4 system
./rusty_emu --system intel_mcs4 --rom examples/mcs4/demo.rom

# Enable debug mode
./rusty_emu --system intel_mcs4 --rom demo.rom --debug

# Load with specific configuration
./rusty_emu --system intel_mcs4 --rom demo.rom --config mcs4_config.toml
```

---

## 📋 System Specifications

### Intel MCS-4 Implementation

**Supported Components:**  
✅ Intel 4004 CPU (4-bit processor)  
✅ 4001 ROM (2560-bit ROM with I/O)  
✅ 4002 RAM (320-bit RAM with output port)  
✅ 4003 Shift Register (10-bit I/O expander)

**Memory Architecture:**
- Instruction ROM: 4KB
- Data RAM: 1280 bits
- I/O Ports: Multiple 4-bit ports

---

### VIC-20 Emulation (Planned)

**Target Specifications:**
- CPU: MOS 6502 @ 1.108 MHz
- Memory: 5KB RAM (expandable to 32KB)
- Graphics: VIC-I chip, 176×184 resolution
- Sound: 3 voices + noise
- I/O: Tape, Serial, User Port

---

### Yamaha TG100 Emulation (Planned)

**Target Features:**
- Tone Generation: AWM (Advanced Wave Memory)
- Polyphony: 16–32 voices
- Effects: Reverb, Chorus
- MIDI Implementation

---

## 🛠️ Development

### Adding New Systems

**Create System Module**
```rust
// systems/my_system/mod.rs
pub struct MySystem {
    cpu: MyCpu,
    memory: MemoryMap,
    peripherals: Vec<Box<dyn Peripheral>>,
}

impl System for MySystem {
    fn step(&mut self) -> EmulatorResult<()> {
        // System emulation logic
    }
}
```

**Implement CPU Core**
```rust
// systems/my_system/cpu.rs
impl Cpu for MyCpu {
    fn execute_instruction(&mut self) -> EmulatorResult<()> {
        // Instruction execution
    }
}
```

**Register System**
```rust
// src/lib.rs
pub mod systems {
    pub mod my_system;
}
```

---

### Building from Source
```bash
# Debug build with logging
RUST_LOG=debug cargo build

# Run tests
cargo test

# Benchmark performance
cargo bench

# Check code quality
cargo clippy
cargo fmt
```

---

## 🧪 Testing
```bash
# Run all tests
cargo test

# System-specific tests
cargo test --test intel_mcs4

# Integration tests
cargo test --test integration

# Performance benchmarks
cargo bench
```

---

## 📊 Performance

**Current performance targets:**
- Intel MCS-4: 740 kHz emulation speed (real-time)
- VIC-20: 1.108 MHz emulation speed (real-time)
- Yamaha TG100: Audio processing at 44.1 kHz

---

## 🔧 Configuration

**Example Configuration (TOML)**
```toml
[system.intel_mcs4]
clock_speed = 740000  # 740 kHz
memory_size = 4096    # 4KB ROM

[display]
width = 800
height = 600
scale = 2
fullscreen = false

[audio]
sample_rate = 44100
buffer_size = 1024

[debug]
breakpoints = [0x1234, 0x5678]
log_level = "info"
```

---

## 🤝 Contributing

We welcome contributions! Please see our **Contributing Guide** for details.

### Development Workflow
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit changes (`git commit -m 'Add amazing feature'`)
4. Push to branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Code Style
- Follow Rust conventions and `cargo fmt`
- Use meaningful variable names
- Include documentation comments
- Write tests for new functionality

---

## 📝 License

This project is licensed under the **MIT License** — see the `LICENSE` file for details.

---

## 🙏 Acknowledgments

- **Intel MCS-4:** Reference documentation from Intel archives
- **VIC-20:** VICE emulator team for reference implementation
- **Yamaha TG100:** Yamaha technical documentation
- **Rust Community:** Excellent emulation resources and crates

---

## 📚 Resources

### Documentation
- [Intel MCS-4 Manuals](https://archive.org/details/intel-4004)
- [VIC-20 Programmer's Reference](https://archive.org/details/VIC-20_Programmers_Reference_Guide)
- Yamaha TG100 Service Manual

### Related Projects
- **VICE:** [Versatile Commodore Emulator](https://github.com/VICE-Team/svn-mirror)
- **MAME:** [Multiple Arcade Machine Emulator](https://github.com/mamedev/mame)
- **Yuzu:** [Nintendo Switch Emulator](https://github.com/yuzu-emu/yuzu)

---

## 🐛 Issue Reporting

If you find a bug, please open an issue with:
- System and ROM information
- Steps to reproduce
- Expected vs. actual behavior
- Log output (if available)

---

## 📞 Support

- **Discussions:** [GitHub Discussions](https://github.com/jhunnius/rusty_emu/discussions)
- **Issues:** [GitHub Issues](https://github.com/jhunnius/rusty_emu/issues)

> *Rusty Emu — Preserving computing history through accurate emulation.* 🕹️