# Harvest Moon 64 PC Port / Recomp (WIP)

Join the Discord: https://discord.gg/tugayjWw

Work-in-progress static recompilation project for Harvest Moon 64.

This repository is currently based on the Mario Kart 64 recompilation scaffold and is still being converted and cleaned up.

This repo does not contain ROMs, ELFs, or extracted game assets. You must provide your own legally obtained copy of the game.

## Screenshots

![Intro](/docs/screenshots/intro.png)
![Intro 2](/docs/screenshots/intro2.png)
![Start Screen](/docs/screenshots/start-screen.png)
![Season Screen](/docs/screenshots/season-screen.png)
![In Game](/docs/screenshots/in-game.png)

## Attribution / Credits

- Scaffold / upstream reference: [sonicdcer/MarioKart64Recomp](https://github.com/sonicdcer/MarioKart64Recomp) and its contributors.
- Runtime/tooling: N64: Recompiled modern runtime + toolchain (submodule `lib/N64ModernRuntime` and `N64Recomp/` in this repo).
- Rendering: RT64 (submodule).
- UI: RmlUi (submodule).
- Licensing: see `COPYING` and the license files in submodules.

Note: GitHub's "Contributors" list may show upstream contributors due to the scaffold/history this repo is based on. That is expected and intentional attribution.

## Project Goal

One of the goals of this repo is to explore setting up and iterating on N64 recompilation projects with the help of AI:

- Quickly compare against reference recomp projects and reuse proven patterns.
- Add targeted instrumentation (logs/trace/overlays) to debug black screens, hangs, and scheduler issues without guessing.

## Current State

- Playable: boots, starts the game, video + audio work, controller input works.
- Saving: uses SRAM (save type mismatch fixed).
- Known issues: this is still WIP and may have rendering or gameplay glitches.

## Debugging (AI-Assisted)

This repo intentionally keeps short, evidence-based debug notes and repro scripts so others (including LLM agents)
can follow the same workflow:

- Flicker root cause + A/B repro: `docs/debug/flicker.md`
- Instant present A/B runner: `scripts/ab_instant_present.sh`
- Trace logging defaults off (avoids stutter); toggle documented in `BUILDING.md`

### What We Fixed (Reference-First, No Guessing)

- Flicker/tearing on bright areas: RT64 "instant present" (PresentEarly). Fixed by defaulting `HM64_DISABLE_INSTANT_PRESENT=1` unless explicitly overridden.
- No controller input: `nuContDataGetExAll` depended on a recompiled bcopy at `0x801008E0` that was a stub, so `contData` never updated. Fixed by hooking `nuContDataGetExAll` and copying pad data + triggers directly.
- SRAM popup / exit: save type was misconfigured (EEP4K). Fixed by switching to SRAM in the supported game metadata.
- Logging stutter: trace logging now defaults off (no `/tmp/hm64_trace.log` writes unless explicitly enabled).

## Quick Start (macOS)

1. Clone with submodules:
   - `git clone --recurse-submodules https://github.com/ai-tdd-labs/harvest-moon-64-recompiled.git`
2. Provide your local ROM/ELF (local-only; do not commit them):
   - `roms/baserom.us.z64`
   - `roms/hm64.elf`
3. Generate recompiled code:
   - `../N64Recomp/build/N64Recomp hm64.us.toml`
4. Configure and build:
   - `cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release`
   - `cmake --build build --target HarvestMoon64Recompiled -j$(sysctl -n hw.ncpu)`
5. Run:
   - `./build/HarvestMoon64Recompiled.app/Contents/MacOS/HarvestMoon64Recompiled`

Tip: on macOS you can also double-click `Run-HM64-Recompiled.command` to open the repo in Finder and run the built app.

## Notes

- App/binary target name: `HarvestMoon64Recompiled`.
- For more build details, see `BUILDING.md`.

## Community / Discord

Discord invite: https://discord.gg/tugayjWw