170 lines
8.1 KiB
Markdown
170 lines
8.1 KiB
Markdown
# JevPlayer
|
||
|
||
> **Autonomous Minecraft Survival driven by TypeSafe AI's Jev model through Baritone**
|
||
|
||
[](https://github.com/oiupoyt/JevPlays/actions/workflows/build.yml)
|
||
[](https://opensource.org/licenses/MIT)
|
||
[](https://fabricmc.net/)
|
||
|
||
**JevPlayer** is a client-side Fabric mod that enables an autonomous player agent to play Minecraft survival mode from scratch for a full 1-hour episode without human intervention.
|
||
|
||
- **The Brain:** **Jev** (TypeSafe AI's "System One" decision model). It does not generate text or code; it returns fast (70–500 ms), calibrated typed decisions, confidence ratings, and urgency scores.
|
||
- **The Actuator:** **Baritone** (public API). Handles pathfinding, mining, obstacle clearing, and movement physics smoothly.
|
||
- **The Engine:** An allocation-light, multi-module core featuring emergency reflexes, watchdog monitoring, a 9-stage milestone ladder, in-game HUD telemetry, and deterministic headless simulation.
|
||
|
||
---
|
||
|
||
## Key Features
|
||
|
||
- **Multi-Version Architecture:** Modular design separates pure game logic (`core`) from versioned Fabric adapters (`adapter-1_21_11`, `adapter-26_1`, `adapter-26_2`).
|
||
- **Hybrid System 0 / System 1 Decision Loop:**
|
||
- **Reflex Engine (System 0):** Zero-latency ($< 0.05 \text{ ms}$) synchronous emergency reactions for lava, drowning, point-blank combat, and starvation.
|
||
- **Jev Model (System 1):** Fast asynchronous strategic choices across 14 high-level survival actions.
|
||
- **Mock Mode:** Built-in calibrated heuristic decision engine requiring no API keys or internet connection.
|
||
- **Decision Replay:** Replay recorded JSONL decision logs to reproduce runs deterministically.
|
||
- **Robust Watchdogs:**
|
||
- **Stuck Watchdog:** Detects stationary states ($< 1.5$ blocks moved over 45s without inventory change) and automatically clears pathing and sidesteps.
|
||
- **Loop Breaker:** Detects repeated action failures and temporarily blacklists problematic actions.
|
||
- **Instant Kill Switch (`F9`):** Immediately relinquishes all control and stops all Baritone processes.
|
||
- **In-Game HUD Overlay (`F8`):**
|
||
- Displays current action, decision confidence, rolling latency (p50/p95), active watchdog status, and cumulative spend.
|
||
- **Enterprise Safety & Privacy:**
|
||
- Strict key redaction: API keys are never logged, committed, or rendered in plain text (`sk-live_***abcd`).
|
||
- Singleplayer protection: `allowMultiplayer=false` by default prevents accidental activation on public servers.
|
||
- Hard spend cap: Gracefully falls back to MockProvider when spend reaches the configured limit ($1.00 default).
|
||
|
||
---
|
||
|
||
## Directory Structure
|
||
|
||
```
|
||
JevPlays/
|
||
├── core/ # Pure Java (no Minecraft/Fabric imports)
|
||
│ ├── src/main/java/ # Config, state, actions, reflexes, watchdogs, director, Jev HTTP client
|
||
│ └── src/test/java/ # 100% deterministic unit tests & headless simulator
|
||
├── adapter-1_21_11/ # Fabric Loom adapter for Minecraft 1.21.11
|
||
├── adapter-26_1/ # Adapter for Minecraft 26.1 (unobfuscated)
|
||
├── adapter-26_2/ # Adapter for Minecraft 26.2 (unobfuscated)
|
||
├── libs/ # Official Baritone API jars
|
||
├── docs/
|
||
│ └── PERFORMANCE.md # Latency budgets, zero-GC rules, Spark & JFR profiling
|
||
├── ARCHITECTURE.md # Sense-Decide-Act lifecycle, threading & Baritone binding
|
||
├── ASSUMPTIONS.md # Documented parameters, thresholds, and fallback rules
|
||
└── jevplayer.sample.json # Sample configuration template
|
||
```
|
||
|
||
---
|
||
|
||
## Getting Started
|
||
|
||
### Prerequisites
|
||
- **Java Development Kit:** JDK 21+ (JDK 25 recommended)
|
||
- **Minecraft Launcher:** Fabric Loader 0.16+ installed for Minecraft 1.21.11
|
||
- **Baritone:** Ensure the Baritone Fabric jar is present in your `.minecraft/mods` folder.
|
||
|
||
### 1. Build the Mod
|
||
Clone the repository and build all modules using the Gradle wrapper:
|
||
|
||
```bash
|
||
git clone https://github.com/oiupoyt/JevPlays.git
|
||
cd JevPlays
|
||
./gradlew build
|
||
```
|
||
|
||
The compiled mod JAR will be located at:
|
||
```
|
||
adapter-1_21_11/build/libs/adapter-1_21_11-1.0.0.jar
|
||
```
|
||
|
||
### 2. Configure Your API Key
|
||
JevPlayer supports two methods for setting the TypeSafe API key:
|
||
|
||
#### Option A: Environment Variable (Recommended)
|
||
```bash
|
||
export TYPESAFE_AI_API_KEY="your-actual-api-key-here"
|
||
```
|
||
|
||
#### Option B: Configuration File
|
||
Copy `jevplayer.sample.json` into `.minecraft/config/jevplayer.json` and insert your credentials:
|
||
```json
|
||
{
|
||
"apiKey": "your-actual-api-key-here",
|
||
"endpoint": "https://api.typesafe.ai/v1/systemone",
|
||
"mockMode": false,
|
||
"confidenceThreshold": 0.65,
|
||
"fairMode": true,
|
||
"spendCapUsd": 1.0,
|
||
"debugOverlay": true,
|
||
"cinematicCamera": true
|
||
}
|
||
```
|
||
*Note: If no API key is found, JevPlayer automatically starts in **Mock Mode**.*
|
||
|
||
### 3. Launch Development Client
|
||
To launch the client directly from Gradle:
|
||
```bash
|
||
./gradlew :adapter-1_21_11:runClient
|
||
```
|
||
|
||
---
|
||
|
||
## Controls & Keybindings
|
||
|
||
| Key | Action | Description |
|
||
| :---: | :--- | :--- |
|
||
| **`F8`** | **Toggle HUD** | Shows/hides the JevPlayer telemetry card (active milestone, confidence, latency, spend). |
|
||
| **`F9`** | **Kill Switch** | Emergency abort. Instantly disengages autonomous ticking and cancels all Baritone goals. |
|
||
|
||
---
|
||
|
||
## Configuration Reference
|
||
|
||
Configuration is loaded from `config/jevplayer.json`:
|
||
|
||
| Key | Type | Default | Description |
|
||
| :--- | :---: | :---: | :--- |
|
||
| `apiKey` | `string` | `""` | TypeSafe API key (or set via `TYPESAFE_AI_API_KEY`). |
|
||
| `endpoint` | `string` | `https://api.typesafe.ai/v1/systemone` | TypeSafe Jev inference endpoint. |
|
||
| `mockMode` | `boolean` | `false` | When `true`, uses the internal heuristic model instead of the cloud API. |
|
||
| `confidenceThreshold` | `float` | `0.65` | Minimum confidence score required to accept a Jev decision. |
|
||
| `fairMode` | `boolean` | `true` | Enforces `legitMine=true` in Baritone (no X-Ray / cheating perception). |
|
||
| `allowMultiplayer` | `boolean` | `false` | Guard against running automation on external servers. |
|
||
| `spendCapUsd` | `double` | `1.00` | Maximum spend limit per run before falling back to MockProvider ($0.042/1M tokens). |
|
||
| `debugOverlay` | `boolean` | `true` | Enables the in-game HUD overlay. |
|
||
| `cinematicCamera` | `boolean` | `true` | Enables `smoothLook=true` in Baritone for video recordings. |
|
||
| `hudRefreshRateMs` | `long` | `200` | Telemetry refresh interval to eliminate per-frame GC allocations. |
|
||
| `logReplay` | `boolean` | `false` | Replays decisions from a recorded log file. |
|
||
| `replayLogPath` | `string` | `decision_log.jsonl` | Path to the recorded JSONL log for replay mode. |
|
||
|
||
---
|
||
|
||
## Testing & Simulation
|
||
|
||
The `core` module includes a deterministic headless simulation engine that runs complete survival loops without launching Minecraft:
|
||
|
||
```bash
|
||
# Run all unit tests, legal action masks, watchdogs, and simulated loops:
|
||
./gradlew :core:test
|
||
```
|
||
|
||
### Tested Capabilities
|
||
- Legal action masking across health, tool, and environmental states.
|
||
- Emergency reflex preemption and watchdog transitions.
|
||
- Spend cap tracking and automatic fail-soft fallback.
|
||
- Token rate calculations ($0.042 / 1M tokens) and JSON schema validation.
|
||
- Recorded decision log parsing and replay fidelity.
|
||
|
||
---
|
||
|
||
## Additional Documentation
|
||
|
||
- [Architecture Specification](file:///home/oiupoyt/projects/JevPlays/ARCHITECTURE.md): In-depth diagrams of the Sense-Decide-Act loop and thread synchronization.
|
||
- [Assumptions & Design Choices](file:///home/oiupoyt/projects/JevPlays/ASSUMPTIONS.md): Recorded decisions on confidence thresholds, spend caps, and reflex priorities.
|
||
- [Performance Guide](file:///home/oiupoyt/projects/JevPlays/docs/PERFORMANCE.md): Profiling protocols with Spark and JFR, allocation budgets, and soak testing.
|
||
|
||
---
|
||
|
||
## License & Compliance
|
||
|
||
- **Mod Code:** Licensed under the [MIT License](LICENSE).
|
||
- **Baritone Actuator:** Interfaced strictly via public API interfaces (`baritone.api.BaritoneAPI`) in compliance with the **LGPL-3.0** license. No Baritone source code is forked, bundled, or modified.
|