minecraft-e2e-test

name	minecraft-e2e-test
description	Control Minecraft for E2E testing. Use this skill when testing Minecraft mods, verifying game behavior, placing blocks, spawning entities, taking screenshots, or running any Minecraft-related tests. Invoke with /minecraft-test or when the user asks to test something in Minecraft.

Minecraft E2E Testing Skill

This skill enables you to control a Minecraft client for end-to-end testing of mods built with the Redstone Dart framework.

Prerequisites

The Minecraft MCP server must be configured in Claude Code settings. It does NOT need a mod path at startup - you provide that when starting Minecraft.

Starting Minecraft

To start Minecraft for testing, call startMinecraft with the absolute path to your mod:

startMinecraft(modPath: "/absolute/path/to/your/mod")

What happens automatically:

• Builds the mod with redstone run
• Creates and loads a superflat test world (dart_visual_test)
• Starts the MCP game server inside Minecraft
• Runs in background mode (won't steal window focus)
• Disables hot reload for stability

Just provide the mod path and everything else is handled!

Available Tools

When the Minecraft MCP is connected, you have access to these tools:

Lifecycle Management

• startMinecraft(modPath) - Start Minecraft with the specified mod (provide absolute path)
• stopMinecraft - Stop the Minecraft client
• getStatus - Check if Minecraft is running

Debugging

• getLogs(lastN?) - Get all output (Dart prints, Java logs, stderr). Default: last 100 lines.

World Operations

• placeBlock(x, y, z, blockId) - Place a block at coordinates
• getBlock(x, y, z) - Get block ID at coordinates
• fillBlocks(fromX, fromY, fromZ, toX, toY, toZ, blockId) - Fill a region with blocks

Entity Operations

• spawnEntity(entityType, x, y, z) - Spawn an entity
• getEntities(centerX, centerY, centerZ, radius) - Find entities in radius

Player & Camera

• teleportPlayer(x, y, z) - Teleport the player
• positionCamera(x, y, z, yaw, pitch) - Set camera position and rotation
• lookAt(x, y, z) - Make camera look at a position

Visual Verification

• takeScreenshot(name) - Capture a screenshot
• getScreenshot(name) - Get screenshot as base64 data

Input Simulation

• pressKey(keyCode) - Press a keyboard key
• click(button, x, y) - Click mouse at screen coordinates (button: 0=left, 1=right, 2=middle)
• holdMouse(button) - Hold mouse button down (for breaking blocks, using items)
• releaseMouse(button) - Release held mouse button
• moveMouse(x, y) - Move cursor to screen coordinates
• scroll(horizontal, vertical) - Scroll mouse wheel (positive vertical = scroll up)
• typeText(text) - Type text into input field

Time & Commands

• waitTicks(ticks) - Wait for game ticks (20 ticks = 1 second)
• setTimeOfDay(time) - Set game time (0=dawn, 6000=noon, 12000=dusk, 18000=midnight)
• executeCommand(command) - Run any Minecraft command

Testing Workflow

1. Start Minecraft

First, ensure Minecraft is running by checking status or starting it.

2. Set Up Test Environment

- Teleport player to test location
- Clear area with fillBlocks using air
- Set time of day for consistent lighting
- Wait for world to stabilize

3. Perform Test Actions

- Place blocks to test
- Spawn entities
- Simulate player input
- Execute commands

4. Verify Results

- Check block states with getBlock
- Query entities with getEntities
- Take screenshots for visual verification

5. Clean Up

- Remove test blocks/entities
- Reset player position if needed

Common Test Patterns

Testing Block Placement

1. teleportPlayer to test area
2. fillBlocks to clear area (use minecraft:air)
3. waitTicks(20) for world update
4. placeBlock with your custom block
5. waitTicks(5)
6. getBlock to verify placement
7. takeScreenshot for visual record

Testing Custom Entities

1. Set up clear test area
2. spawnEntity with your custom entity type
3. waitTicks(20) for entity to initialize
4. getEntities to verify spawn
5. takeScreenshot to capture entity appearance

Testing UI/Screens

1. pressKey to open UI (e.g., E for inventory)
2. waitTicks(5) for UI to render
3. takeScreenshot
4. click to interact with UI elements
5. pressKey to close UI

Testing Commands

1. executeCommand("give @p minecraft:diamond 64")
2. waitTicks(5)
3. takeScreenshot to verify

Block IDs

Common block IDs:

• minecraft:air - Remove blocks
• minecraft:stone - Stone block
• minecraft:dirt - Dirt block
• minecraft:grass_block - Grass
• minecraft:diamond_block - Diamond block

Custom mod blocks use format: modid:block_name

Key Codes

Common key codes for input simulation:

• 69 - E (Inventory)
• 27 - Escape
• 32 - Space (Jump)
• 87 - W (Forward)
• 65 - A (Left)
• 83 - S (Back)
• 68 - D (Right)
• 340 - Left Shift (Sneak)

Coordinate System

Modern Minecraft (1.18+) uses an extended height range:

• World extends from Y=-64 to Y=320
• Sea level is approximately Y=63
• Superflat test worlds have ground at Y=-60

When testing in the dart_visual_test world (superflat):

• Ground level: Y=-60
• Player spawn: teleport to Y=-59 or Y=-60
• Place blocks starting at Y=-60
• Spawn entities at Y=-59 (one block above ground)

Block Center Coordinates

Important: Integer coordinates (0, 1, 2, etc.) represent block edges/corners, not block centers. When using lookAt to look at a block, add 0.5 to each coordinate to target the center of the block:

• Block at (10, -60, 20) → Look at (10.5, -59.5, 20.5) to see the center
• Block at (0, 0, 0) → Look at (0.5, 0.5, 0.5) for the center

This is especially important when:

• Taking screenshots of specific blocks
• Verifying block appearance visually
• Positioning the camera to view block details

Tips

1. Always wait after actions - Use waitTicks after placing blocks, spawning entities, or any world modification
2. Use executeCommand for complex setups - Commands like /fill, /summon, /effect can simplify test setup
3. Take screenshots liberally - Visual verification helps confirm test results
4. Clear test areas first - Use fillBlocks with air to ensure clean test environment
5. Check status before testing - Verify Minecraft is running with getStatus

Example Test Session

Testing a custom diamond sword that deals extra damage (in superflat test world):

1. getStatus - Verify Minecraft running
2. teleportPlayer(100, -59, 100) - Move to test area (standing on ground at Y=-60)
3. fillBlocks(95, -60, 95, 105, -50, 105, "minecraft:air") - Clear area above ground
4. waitTicks(20)
5. executeCommand("give @p mymod:super_sword") - Give custom item
6. spawnEntity("minecraft:zombie", 100, -59, 103) - Spawn test target (on ground)
7. waitTicks(10)
8. takeScreenshot("before_attack")
9. // Simulate attack with click/key presses
10. waitTicks(20)
11. getEntities(100, -59, 100, 10) - Check if zombie was killed
12. takeScreenshot("after_attack")