MyGymCraft

Introduction

Turn Minecraft into an agent training ground

GymCraft is a NeoForge mod for reinforcement learning, LLM agents, and game automation experiments. It wraps Minecraft mobs—or its built-in simulated player entity—as Gymnasium-style environments, allowing external Python programs to observe the world, take actions, and receive rewards over gRPC.

Whether you want to train a mob to move and build upward, ask a language model to gather and craft resources, or create your own Minecraft agent benchmark, GymCraft provides an extensible foundation for the job.

GymCraft is an agent development and research tool rather than a traditional content mod. A typical setup runs both the Minecraft mod and an external Python agent.

Highlights

• Gymnasium-style API: The Python client exposes the familiar reset() and step() workflow.
• Control almost any mob: Attach an environment to an existing mob, or use PlayerSimEntity, a player-shaped controllable entity with player-like attributes.
• Rich world interaction: Move, navigate, look, jump, fight, mine, place blocks, use items, pick up and drop items, chat, and operate menus.
• Structured observations: Read self state, world data, nearby entities, blocks, dropped items, menus, tracked blocks, and chat messages.
• Ordered action batches: Execute multiple actions sequentially within one step under a shared timeout.
• LLM-ready tooling: Includes compact observation text, a Minecraft-like action DSL, conversation context management, and a Chat Completions compatible wrapper.
• Multiplayer and dedicated-server friendly: Manage environments with in-game tools, commands, RCON, or remote gRPC clients.
• English and Simplified Chinese UI: Item names, entity names, and common operation messages are localized.

Built-in environments

Quick start

1. Install NeoForge and the GymCraft mod JAR matching your Minecraft version.
2. Start a world or server. GymCraft starts its gRPC service at localhost:50051 by default.
3. Take the Environment Tool and UUID Copier from the GymCraft creative tab.
4. Hold Shift and scroll to choose an environment, then right-click a mob with the Environment Tool.
5. Right-click the same entity with the UUID Copier to obtain its UUID.
6. Install the Python client:

pip install -U gymcraft

Run the Q-learning parkour demo:

gymcraft-demo parkour <entity_uuid> --episodes 200

Or connect any Chat Completions compatible model:

gymcraft-demo llm-chat <entity_uuid> --task "Find the nearest chest and inspect its contents"

Run gymcraft-demo --help to list all bundled demos and options.

Compatibility

The Python client requires Python 3.11 or newer.

Who is it for?

• Reinforcement-learning and imitation-learning researchers
• Developers building LLM agents for Minecraft
• Evaluation and education projects that need repeatable game tasks
• Mod developers extending custom actions, observations, environments, or reward functions