# EnthusiaRecomp: Static Recompilation of Enthusia Professional Racing

![Enthusia Professional Racing](https://img.youtube.com/vi/placeholder/0.jpg)

**EnthusiaRecomp** is a project to create a native PC port of *Enthusia Professional Racing* (a PlayStation 2 racing simulation game by Konami) using the [PS2Recomp](https://github.com/ran-j/PS2Recomp) static recompilation framework.

## Overview

This project uses static recompilation to convert the PlayStation 2's MIPS R5900 machine code from Enthusia Professional Racing into equivalent C++ code that can be compiled and run natively on modern platforms (Windows, Linux, macOS).

### What is Static Recompilation?

Unlike traditional emulation which interprets or dynamically recompiles machine code at runtime, static recompilation:
- **Analyzes** the original PS2 ELF binary
- **Translates** each MIPS instruction to equivalent C++ operations
- **Generates** portable C++ source code
- **Compiles** the code natively for the target platform
- **Links** with a runtime that provides PS2 hardware emulation

This approach offers:
- **Native performance** - No runtime translation overhead
- **Portability** - Can run on any platform with a C++20 compiler
- **Debuggability** - Full access to generated C++ code
- **Modifiability** - Easy to modify and extend the game

## Project Status

⚠️ **EXPERIMENTAL / WORK IN PROGRESS**

This project is in the very early stages. The framework is set up, but the actual recompilation of Enthusia requires:
1. The Enthusia ELF file (not included due to legal reasons)
2. Extensive reverse engineering and stub implementation
3. Hardware emulation for PS2-specific features

## Requirements

### Prerequisites
- **C++20 Compiler** (GCC 14+, Clang 17+, MSVC 2022+)
- **CMake 3.20+**
- **Git**
- **PS2Recomp Framework** (included as submodule)

### Recommended Tools
- **Ghidra** - For ELF analysis and symbol extraction
- **PCSX2** - For reference and testing
- **Hex Editor** - For examining game data files

## Quick Start

### 1. Clone the Repository

```bash
git clone https://github.com/Lilicris12/EnthusiaRecomp.git
cd EnthusiaRecomp
```

### 2. Build PS2Recomp Tools

The PS2Recomp framework needs to be built first:

```bash
cd /workspace/PS2Recomp
cmake -S . -B out/build -DCMAKE_BUILD_TYPE=Release
cmake --build out/build -j$(nproc)
cd /workspace/github__Lilicris12__EnthusiaRecomp
```

### 3. Obtain the Enthusia ELF

You need to provide the Enthusia Professional Racing ELF file:

```bash
# Place the ELF in the game directory
mkdir -p game
# Copy your enthusia.elf here
cp /path/to/enthusia.elf game/
```

**Note:** The ELF can be extracted from the ISO using various tools:
- `ps2-extract` from ps2tools
- `cdrdao` for CD/DVD extraction
- PS2 homebrew dumping tools

### 4. Configure the Recompilation

Edit `config/enthusia_config.toml` to match your ELF:

```toml
[general]
input = "./game/enthusia.elf"
output = "./output/recompiled"
```

### 5. Run the Build Script

```bash
# Make the build script executable
chmod +x scripts/build.sh

# Run the full build process
./scripts/build.sh
```

This will:
1. Analyze the ELF file
2. Generate C++ code from the MIPS instructions
3. Compile the generated code with the runtime
4. Create the final executable

### 6. Run the Game

```bash
# After successful build
./scripts/build.sh --run

# Or manually
cd build
./enthusia_entry
```

## Project Structure

```
EnthusiaRecomp/
├── config/                      # Configuration files
│   ├── enthusia_config.toml     # Main recompilation configuration
│   └── enthusia_ghidra_export.csv # (Generated) Ghidra export
├── game/                        # Game files
│   └── enthusia.elf             # (Required) The PS2 ELF file
├── include/                     # Project headers
│   └── game_overrides.h         # Game-specific declarations
├── output/                      # Generated output
│   └── recompiled/              # Generated C++ code
├── scripts/                     # Build and utility scripts
│   └── build.sh                 # Main build script
├── src/                         # Source code
│   ├── main.cpp                 # Main entry point
│   ├── entry.cpp                # Runtime entry point
│   ├── game_overrides.cpp       # Game-specific overrides
│   └── custom_stubs.cpp         # Custom stub implementations
├── CMakeLists.txt               # Main CMake configuration
├── README.md                    # This file
└── docs/                        # Documentation
    └── BUILD_WORKFLOW.md         # Detailed build workflow
```

## Configuration

### Main Configuration File

The main configuration is in `config/enthusia_config.toml`:

```toml
[general]
input = "./game/enthusia.elf"          # Path to ELF file
output = "./output/recompiled"          # Output directory
ghidra_output = "./config/export.csv"   # Ghidra export (optional)
single_file_output = false             # One file per function
low_memory_mode = true                 # Reduce memory usage

[general.stubs]
values = [
    "sceCdRead",                      # CD/DVD access
    "SifLoadModule",                 # Module loading
    "printf",                         # Standard I/O
    # ... hundreds more
]

[general.skip]
values = ["_start", "_exit"]            # Functions to skip
```

### Runtime Configuration

Runtime behavior can be configured in the CMake options:

```bash
# Enable debug features
cmake -DENTHUSIA_ENABLE_DEBUG=ON ..

# Enable runtime logging
cmake -DENTHUSIA_ENABLE_RUNTIME_LOGS=ON ..

# Enable aggressive/verbose logging
cmake -DENTHUSIA_ENABLE_AGGRESSIVE_LOGS=ON ..
```

## Implementation Status

### Completed
- [x] Project structure setup
- [x] PS2Recomp framework integration
- [x] Build system configuration
- [x] Configuration templates
- [x] Custom stub implementations (basic)
- [x] Game override system
- [x] Build scripts
- [x] Documentation

### In Progress
- [ ] ELF file analysis
- [ ] Function boundary detection
- [ ] Symbol extraction
- [ ] Memory layout configuration

### Not Started
- [ ] CD/DVD access implementation
- [ ] Graphics Synthesizer (GS) emulation
- [ ] Vector Units (VU0/VU1) emulation
- [ ] Audio (SPU2) emulation
- [ ] Input handling
- [ ] File system mapping
- [ ] Threading and synchronization
- [ ] Game-specific patches

## Known Challenges

### 1. Stripped ELF Files

Retail PS2 games have stripped ELFs without debug symbols. This makes function detection challenging. Solutions:
- Use Ghidra for analysis
- Use relocation-symbol auto-binding
- Manual address mapping with `handler@0xADDRESS` syntax

### 2. Hardware-Specific Code

PS2 has unique hardware that needs emulation:
- **Graphics Synthesizer (GS)** - 2D/3D graphics
- **Vector Units (VU0/VU1)** - Vector processing
- **IPU (Image Processing Unit)** - MPEG decoding
- **SPU2** - Audio processing
- **DMA Controller** - Direct Memory Access

### 3. Syscall Implementations

Hundreds of PS2 syscalls need implementations:
- CD/DVD access (`sceCd*`)
- Module loading (`Sif*`)
- File I/O (`fio*`)
- Memory management
- Threading
- Networking
- And many more...

### 4. Game-Specific Code

Enthusia has unique requirements:
- Car physics simulation
- Track rendering
- AI opponents
- Game modes (Enthusia Life, Driving Revolution)
- Replay system

## Contributing

Contributions are welcome! Please see our [Contribution Guidelines](CONTRIBUTING.md) (coming soon).

### How to Help

1. **Reverse Engineering** - Help identify functions in the ELF
2. **Stub Implementation** - Implement missing PS2 syscalls
3. **Hardware Emulation** - Improve GS/VU/SPU2 emulation
4. **Testing** - Test on different platforms
5. **Documentation** - Improve documentation

## Resources

### PS2Recomp
- [PS2Recomp GitHub](https://github.com/ran-j/PS2Recomp)
- [PS2Recomp Wiki](https://github.com/ran-j/PS2Recomp/wiki)
- [PS2Recomp Documentation](https://github.com/ran-j/PS2Recomp/blob/main/README.md)

### PS2 Development
- [PS2Dev.net](https://ps2dev.net/) - PS2 development resources
- [PS2 SDK Documentation](https://github.com/ps2dev/ps2sdk-docs)
- [PS2 Homebrew Wiki](https://www.ps2homebrew.net/)

### Enthusia Professional Racing
- [Wikipedia](https://en.wikipedia.org/wiki/Enthusia_Professional_Racing)
- [Konami Official Site (Archived)](https://web.archive.org/web/*/http://www.konami.com/games/enthusia/)
- [GameFAQs](https://gamefaqs.gamespot.com/ps2/925376-enthusia-professional-racing)

### Tools
- [Ghidra](https://ghidra-sre.org/) - Reverse engineering
- [PCSX2](https://pcsx2.net/) - PS2 emulator for reference
- [PS2Dis](https://github.com/mips2000/ps2dis) - PS2 disassembler
- [ps2-extract](https://github.com/ps2dev/ps2-extract) - ELF extraction

## Legal Notice

This project does **NOT** include any copyrighted game files (ROMs, ISOs, ELFs). You must provide your own legally obtained copy of *Enthusia Professional Racing* for use with this project.

The code in this repository is for educational and research purposes only. It is not affiliated with or endorsed by Konami or Sony Interactive Entertainment.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- **ran-j** - Creator of PS2Recomp, the foundation of this project
- **PS2Recomp Community** - For their contributions and support
- **Ghidra Team** - For the amazing reverse engineering tool
- **PCSX2 Team** - For the reference emulator
- **All contributors** - For their time and expertise

## Contact

For questions or support:
- Open an issue on GitHub
- Join the PS2Recomp Discord server
- Follow the project on GitHub

---

*Enthusia Professional Racing is a trademark of Konami Digital Entertainment. PlayStation 2 is a trademark of Sony Interactive Entertainment.*