JevPlays/README.md

JevPlayer

Autonomous Minecraft Survival driven by TypeSafe AI's Jev model through Baritone

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:

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)

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:

{
  "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:

./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:

# 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: In-depth diagrams of the Sense-Decide-Act loop and thread synchronization.
• Assumptions & Design Choices: Recorded decisions on confidence thresholds, spend caps, and reflex priorities.
• Performance Guide: Profiling protocols with Spark and JFR, allocation budgets, and soak testing.

---

License & Compliance

• Mod Code: Licensed under the MIT 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.