# Lemonade Bench

Lemonade Bench lets a tool-using language model play **Lemonade Tycoon
Deluxe** as a text-only, long-horizon business benchmark while the original
game remains visible under Wine. The agent receives semantic MCP tools for the
same information and actions available through the game UI; it never receives
vision, arbitrary memory access, shell access, or internet access.

The project contains three pieces:

- a 32-bit Windows proxy DLL loaded by the game, exposing a loopback bridge;
- a Player MCP that turns UI state and actions into semantic tools;
- a provider-agnostic benchmark runner with tracing, crash recovery,
  compaction, optional model-authored notes, and reports.

The complete reverse-engineering and control path is explained in
[How it works](docs/how-it-works.md), from the FMOD proxy DLL to the zero-vision
MCP runner.

## Compatibility

The bridge and memory map are tested only with **Lemonade Tycoon Deluxe
1.1.9**, 32-bit Windows executable SHA-256:

```text
5f079edaba4963765ce650efe25f2c12673b8c889539c6dc8a426e34a94dc7e3
```

Earlier releases, later releases, localized executables, and modified binaries
are unsupported. Their memory addresses or UI coordinates may differ. The
launcher refuses an unknown executable unless the operator explicitly enables
the unsafe override.

This repository does not include the game, an installer, saves, assets, FMOD,
or a Wine prefix. You must provide your own legitimate installation.

## Requirements

- Lemonade Tycoon Deluxe 1.1.9;
- a Wine-compatible environment capable of running the game;
- Node.js 22 or newer;
- Tesseract available on `PATH` for menu/save bootstrap OCR;
- an i686 Windows Clang/MinGW toolchain to build the bridge;
- an OpenAI or OpenRouter API key for model-driven runs.

## Installation

Create a **dedicated copy** of the installed game directory. Benchmark
scenarios remove `Lemonade.dat` to create a fresh career, so never point the
runner at the only copy of personal saves.

```sh
npm install
cp .env.example .env.local
```

Edit `.env.local` and set at least:

```dotenv
LEMONADE_GAME_DIR=/absolute/path/to/dedicated/game-copy
LEMONADE_WINE_BIN=wine
LEMONADE_WINE_PREFIX=/absolute/path/to/dedicated/wine-prefix
LEMONADE_ALLOW_SAVE_RESET=true
```

Build the proxy before replacing the game's FMOD loader:

```sh
native/build_proxy.sh \
  /absolute/path/to/llvm-mingw \
  "/absolute/path/to/dedicated/game-copy/fmod.dll" \
  dist
```

Then install it. The setup script verifies the executable and original FMOD
hashes, renames the user's original to `fmod_original.dll`, installs the proxy,
and writes the dedicated-install safety marker.

```sh
npm run setup -- install-bridge
npm run setup -- doctor
```

Restore the original FMOD loader at any time with:

```sh
npm run setup -- uninstall-bridge
```

See [docs/installation.md](docs/installation.md) for the full bootstrap and
failure modes.

## Running a benchmark

First validate the local game and Player MCP without spending model tokens:

```sh
npm run runner:doctor
```

Then validate the selected paid model transport with one minimal tool call:

```sh
npm run runner:preflight
```

Run the 30-day validation or the 360-day benchmark:

```sh
npm run runner -- run benchmark-career-30d
npm run runner -- run benchmark-career
```

Resume an interrupted run without resetting the game:

```sh
npm run runner -- resume /absolute/path/to/run-directory
```

The standard scenario deletes saves only inside the marked dedicated game
copy, creates a new `BENCHMARK` career in slot 1, reaches Year 1 / Month 1 /
Day 1, and then hands control to the model.

## Scoring

The benchmark records two terminal signals:

```text
total economic value = cash + equipment value + inventory replacement value
liquid cash          = cash
```

Total economic value is primary; cash is the secondary liquidity score.
Equipment uses the value displayed by the game's balance sheet. Inventory is
valued at the lowest unit replacement cost available in the visible supply
catalog, with the final total rounded to the nearest cent. This makes a final
upgrade purchase score-neutral at purchase time instead of treating investment
as destroyed wealth.

Every run stores the exact scoring method and emits raw traces, a resumable
checkpoint, `analysis.json`, and `REPORT.md` under the ignored `runs/`
directory. See [docs/benchmark-contract.md](docs/benchmark-contract.md).

## Player boundary

The DLL contains developer primitives because the driver must capture the
window, click controls, type a company name, read mapped values, and stop the
game. Those primitives are never registered on the Player MCP. Before starting
a paid episode, the runner compares the complete tool surface with an exact
allowlist and rejects every unexpected or missing tool.

The semantic MCP deliberately exposes approximate popularity and satisfaction
bars instead of hidden percentages, and omits internal demand equations,
upgrade magnitudes, and optimal strategies. See
[docs/player-visibility-audit.md](docs/player-visibility-audit.md).
The complete local trust boundary is documented in
[docs/security-model.md](docs/security-model.md).

## Tests

Pure tests do not require the game:

```sh
npm test
```

Game integration tests require the configured dedicated installation:

```sh
npm run test:bridge
npm run test:player-visibility
npm run test:gameplay
```

## Legal and project status

This is an independent interoperability and AI research project. It is not
affiliated with or endorsed by the developers, publishers, or rights holders
of Lemonade Tycoon Deluxe. No game files or DRM bypass are provided. Users are
responsible for complying with the software license and applicable law in
their jurisdiction.

The code is provided under the [MIT License](LICENSE). The upstream repository
does not accept issues or pull requests; fork it if you want to modify or
maintain it. See [GOVERNANCE.md](GOVERNANCE.md).

## Development provenance

The original concept, product direction, benchmark requirements, and live game
validation were led by **Maxence Marchal**. Reverse engineering, implementation,
debugging, tests, and the initial documentation were produced collaboratively
through **Codex using GPT-5.6 Sol with High reasoning effort**.