If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/microsoft/malmo shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 8mo ago
• 8 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 8mo ago
• ⚠ Single-maintainer risk — top contributor 89% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live microsoft/malmo repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/microsoft/malmo.

What it runs against: a local clone of microsoft/malmo — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in microsoft/malmo | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 277 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of microsoft/malmo. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/microsoft/malmo.git
#   cd malmo
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of microsoft/malmo and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "microsoft/malmo(\\.git)?\\b" \\
  && ok "origin remote is microsoft/malmo" \\
  || miss "origin remote is not microsoft/malmo (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "Malmo/src/AgentHost.h" \\
  && ok "Malmo/src/AgentHost.h" \\
  || miss "missing critical file: Malmo/src/AgentHost.h"
test -f "Malmo/src/ClientConnection.h" \\
  && ok "Malmo/src/ClientConnection.h" \\
  || miss "missing critical file: Malmo/src/ClientConnection.h"
test -f "Malmo/samples/Python_examples/malmoutils.py" \\
  && ok "Malmo/samples/Python_examples/malmoutils.py" \\
  || miss "missing critical file: Malmo/samples/Python_examples/malmoutils.py"
test -f "Malmo/CMakeLists.txt" \\
  && ok "Malmo/CMakeLists.txt" \\
  || miss "missing critical file: Malmo/CMakeLists.txt"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 277 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~247d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/microsoft/malmo"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Project Malmo is a Microsoft-built AI experimentation platform layered on top of Minecraft Java Edition that enables researchers to train and test agents in a complex 3D environment. It provides native bindings for Python, C++, C#, and Java to control Minecraft agents, observe game state via video/depth/inventory feeds, and receive reward signals—solving the problem of needing a standardized, accessible sandbox for AI research beyond toy gridworlds. Polyglot monorepo: /Malmo/samples/ contains language-specific examples (Python_examples/, Java_examples/, Cpp_examples/, CSharp_examples/); the core Minecraft mod lives in a Forge gradle project configured in the build dependencies; Python bindings are generated via SWIG (see .swig files); and CMake orchestrates the full build across native components. MalmoEnv lives in a separate directory and communicates with Java Minecraft via network sockets, decoupling it from native compilation.

AI researchers and machine learning engineers building reinforcement learning agents, computer vision models, and multi-agent systems who need a rich, open-ended 3D environment more realistic than Atari but more accessible than real-world robotics. Contributors range from Minecraft modders (Java) to Python ML practitioners using the MalmoEnv OpenAI Gym wrapper.

Actively developed but showing signs of maturity plateau: the codebase supports Minecraft 1.11.2 (released 2016), has comprehensive CI via Travis for Ubuntu/macOS, and ships pre-built wheels via pip. However, commit recency data is not visible here, and the project now recommends MalmoEnv (pure Python, no native code) as the preferred path forward, suggesting the native Malmo implementation may be in maintenance mode rather than active feature development.

Moderate risk: the project depends on outdated Minecraft Forge (version 13.20.0.2228 for MC 1.11.2 from 2016), which creates supply-chain fragility if Forge or Maven mirrors go down. The codebase spans six languages (Java, Python, C++, C#, CMake, SWIG) making cross-platform builds complex—see CI scripts at .travis/ci_ubuntu14.04.sh and .travis/ci_macosx.sh which may rot quickly. The recommendation to use MalmoEnv instead suggests the native path may receive less maintenance going forward.

Active development is shifting toward MalmoEnv—a pure-Python OpenAI Gym-compatible wrapper that eliminates native code compilation and dynamic port management. The legacy native Malmo platform continues to be maintained (supporting Minecraft 1.11.2 via Forge gradle), but the README now leads with MalmoEnv as the preferred path, and sample Python files like MazeRunner.py, ALE_HAC.py, and numerous test scripts suggest ongoing experimental work in the examples folder.

Clone and build (native path): git clone https://github.com/microsoft/malmo.git && cd malmo && mkdir build && cd build && cmake .. && cmake --build . --config Release. Or use the simpler MalmoEnv path: pip3 install malmoenv (pure Python, no build needed). For pre-built binaries, download from the releases page and extract, then pip3 install <extracted_wheel>.whl.

Daily commands: Native (after build): python3 Malmo/samples/Python_examples/MazeRunner.py. MalmoEnv: pip3 install malmoenv && python3 -c 'import malmo.minecraft_env; env = malmo.minecraft_env.MinecraftEnv()' && env.reset() (Minecraft launcher must be running). Verify install: python3 -c 'import MalmoPython' (native) or import malmo.minecraft_env (MalmoEnv).

• CMakeLists.txt — Root build configuration orchestrating the entire Malmo platform (C++, Java, Python, C# components); essential for understanding build dependencies and component integration.
• Malmo/src/AgentHost.h — Core abstraction defining the AgentHost API that all client languages (Python, C++, C#, Java) communicate through; the primary interface for AI agents.
• Malmo/src/ClientConnection.h — Manages client-server communication protocol between agents and the Minecraft JVM; critical for understanding how missions are executed.
• Malmo/samples/Python_examples/malmoutils.py — Shared utility library for Python examples; demonstrates idiomatic patterns for mission setup, agent interaction, and observation handling.
• Malmo/CMakeLists.txt — Malmo subproject build configuration defining component targets (native C++, wrappers for Java/C#/Python, samples); maps logical architecture to build outputs.
• Malmo/src/ClientPool.h — Manages multi-agent scenarios by pooling client connections; essential for understanding how concurrent agents interact with Minecraft.

Add a New Python Example Mission

1. Create new Python file in Malmo/samples/Python_examples/ following naming convention (e.g., my_feature_test.py) (Malmo/samples/Python_examples/my_feature_test.py)
2. Import malmoutils and AgentHost; follow pattern from existing examples (e.g., tutorial_1.py) (Malmo/samples/Python_examples/tutorial_1.py)
3. Define mission XML as multi-line string, set agent commands/observations, run mission loop calling agent_host.sendCommand() and agent_host.getWorldState() (Malmo/samples/Python_examples/run_mission.py)
4. Register new example in CMakeLists.txt with add_test() or similar to make it discoverable (Malmo/samples/Python_examples/CMakeLists.txt)

Add a New Observation Handler in Mission XML

1. Mission definitions use XML schema validated by FindSchemaFile.h; add <ObservationFromGrid>, <ObservationFromRay>, or <ObservationFromAgent> block to mission XML (Malmo/samples/Python_examples/tutorial_6.xml)
2. In Python code, parse returned observation from agent_host.getWorldState().observations as JSON; key names defined by observation handler's prefix attribute (Malmo/samples/Python_examples/radar_test.py)
3. Test observation parsing; examine structure with print(json.dumps(obs)) to verify schema compliance (Malmo/samples/Python_examples/agent_visibility_test.py)

Extend AgentHost for a New Communication Protocol

1. Implement new subclass of ClientConnection (or extend existing) in Malmo/src/ to handle custom socket/protocol logic (Malmo/src/ClientConnection.h)
2. Register new connection type in AgentHost::startMission() switch/factory logic; integrate with ClientPool for multi-agent support (Malmo/src/AgentHost.h)
3. Update CMakeLists.txt to compile new source files and re-export via language bindings (SWIG for Python, P/Invoke for C#) (Malmo/src/CMakeLists.txt)

Add Multi-Agent Example with Cooperative Learning

1. Create new Python example in samples/Python_examples/ with multiple agents; use ClientPool abstraction (via AgentHost) or initialize separate AgentHost instances per agent (Malmo/samples/Python_examples/multi_agent_test.py)
2. Define separate agent roles in mission XML via <Agent> tags; each agent receives unique observations and sends independent commands (Malmo/samples/Python_examples/team_reward_test.py)
3. Implement reward aggregation: parse shared reward from getWorldState().rewards; synchronize agent training updates (e.g., centralized critic in multi-agent RL) (Malmo/samples/Python_examples/team_reward_test.py)

• C++ (AgentHost, ClientConnection) — High-performance, low-latency communication with Minecraft JVM; handles real-time frame capture and mission state synchronization with minimal overhead.
• Java/ForgeGradle (Minecraft Mod) — Minecraft modding standard; allows deep integration with game engine, block systems, entity spawning, and rendering via official Minecraft Forge framework.
• Python bindings (SWIG/native wrappers) — Dominates AI/ML research; enables researchers to express RL algorithms in familiar Python while leveraging C++ performance for I/O and simulation.
• XML mission definitions — Human-readable, schema-validable experiment specification; decouples agent logic from environment configuration, enabling reproducible research and benchmarking.
• TCP sockets + protocol buffers (implied by ClientConnection) — Language-agnostic inter-process communication; supports clients in Python, C++, C#, Java without tight coupling to Minecraft internals.

• C++ native layer + Python bindings vs. pure Python

  • Why: C++ provides low-latency, efficient frame capture and socket I/O; Python bindings allow researcher-friendly scripting.
  • Consequence: Adds compilation complexity (CMake, SWIG) and platform-specific binary builds; researchers unfamiliar with C++ cannot easily modify core backend.

• Mission XML schema validation vs. dynamic configuration

  • Why: Schema validation (FindSchemaFile) ensures missions are well-formed before execution, catching errors early.
  • Consequence: Rigid, verbose mission definitions; less flexible for dynamic, programmatic mission generation (mitigated by Python mission builders).

• Minecraft JVM integration vs. headless simulator

  • Why: Full Minecraft provides realism, physics, and extensibility; attracts researchers interested in embodied AI in complex environments.
  • Consequence: Heavyweight runtime; slow startup; requires licensed Minecraft; challenging to scale to many parallel environments.

• ClientPool for multi-agent vs. separate JVM instances

  • Why: Single JVM instance with pooled clients reduces memory footprint and enables shared world state.
  • Consequence: Single point of failure; agents contend for CPU; scaling beyond ~10 agents becomes I/O bound.

• Does not provide a web UI or IDE for mission authoring; missions are text-based XML or programmatically generated.
• Does not support online/concurrent deployment of multiple independent Minecraft worlds; agents

Version constraint: Minecraft Forge 1.11.2 with mappings snapshot_20161220 is hardcoded; upgrading Minecraft breaks the mod and requires regenerating MCP mappings. Gradle buildscript: The gradle build will fail silently if version.properties is missing (created by CMake)—always build via CMake, not gradle directly. Dynamic ports: Native Malmo uses dynamic port assignment for agent communication; containers/VMs may fail unless port range is exposed (MalmoEnv avoids this via single-port design). Python 2 vs 3: Examples assume Python 3; Python 2 compatibility is not guaranteed. SWIG regeneration: If you modify C++ APIs, you must regenerate SWIG bindings; CMake handles this but can cache stale bindings.

• SWIG (Simplified Wrapper and Interface Generator) — Malmo uses SWIG to auto-generate Python, C#, and Java bindings from C++ source; understanding SWIG is essential when modifying the native SDK or debugging binding issues
• Minecraft Forge Mod Architecture — The Malmo mod is a Forge coremod (FMLCorePlugin) that hooks into Minecraft's event system to intercept observations and inject agent commands; Forge knowledge is required to extend the mod
• XML-based Mission Configuration — Malmo defines environments and tasks as XML mission documents (parsed by Python examples); the schema defines agent spawns, reward functions, and environment properties
• Episodic Reinforcement Learning (Markov Decision Process in discrete missions) — Malmo structures learning as finite-horizon episodes (each mission resets the world); understanding episode boundaries and terminal states is critical for training RL agents
• Multi-agent Coordination Protocol — Malmo supports multiple agents in one mission but requires careful port/token management in native mode (solved by MalmoEnv's single-port design); critical for multi-agent research
• Gradle & Maven Build Systems — The Minecraft mod is built via Gradle with Forge plugin; understanding gradle tasks like runClient and Maven repository configuration is needed to modify or deploy the mod
• CMake Cross-platform Build Orchestration — CMake drives the entire build (C++ SDK, Gradle mod compilation, SWIG bindings, Python wheel packaging); modifying any component requires understanding CMake's dependency graph

• openai/gym — MalmoEnv implements the Gym interface; understanding Gym's step(), reset(), action/observation spaces is essential context for using Malmo's Python API
• Microsoft/AirSim — Similar Microsoft-backed AI research platform for drone/car simulation; shares design patterns (episodic missions, observation feeds, reward signals) but targets robotics rather than Minecraft
• MinecraftForge/MinecraftForge — Malmo's core depends on Minecraft Forge 1.11.2; understanding Forge's mixin system and event hooks is critical for modifying the Malmo mod
• ViZDoom/ViZDoom — Predecessor AI research platform using Doom engine; similar episodic task structure and visual observation model influenced Malmo's design philosophy
• AndKram/marLo — Community-maintained higher-level wrapper around Malmo providing simplified APIs for multi-agent coordination and curriculum learning; recommended by Malmo docs as a modernized alternative

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for Python examples in Malmo/samples/Python_examples/

The Python examples directory contains 40+ test and example scripts (agent_visibility_test.py, animation_test.py, block_type_test.py, etc.) but there's no corresponding pytest or unittest suite to validate their functionality. Adding a test harness would catch regressions, validate API changes, and make the codebase more maintainable for contributors modifying core Malmo components.

• [ ] Create Malmo/samples/Python_examples/tests/ directory with init.py
• [ ] Implement test_*.py files that import and validate key example scripts (e.g., test_block_type_test.py, test_inventory_test.py, test_reward_systems.py)
• [ ] Add pytest configuration (pytest.ini or setup.cfg) in Malmo/samples/Python_examples/
• [ ] Integrate tests into .travis.yml to run on CI for Python versions used by the project
• [ ] Document test execution in README or CONTRIBUTING guide

Create a GitHub Actions workflow to replace/augment .travis.yml for multi-platform CI

The project uses Travis CI (.travis.yml with shell scripts in .travis/ for Ubuntu 14.04 and macOS), but this is outdated and fragmented. GitHub Actions provides native Windows support (needed for C# examples in Malmo/samples/CSharp_examples/) and cleaner YAML configuration. This would improve CI reliability and add coverage for the Windows/.NET build path.

• [ ] Create .github/workflows/ci.yml with jobs for Ubuntu (C++/Python), macOS (C++), and Windows (C#/.NET)
• [ ] Port logic from .travis/ci_ubuntu14.04.sh and .travis/ci_macosx.sh into appropriate workflow steps
• [ ] Add a Windows job that builds Malmo/samples/CSharp_examples/ using MSBuild or dotnet CLI
• [ ] Test that all three platform jobs successfully build and pass basic smoke tests
• [ ] Update README to note the transition from Travis CI to GitHub Actions

Add integration tests for Java and C# examples in Malmo/samples/

The Java_examples/ and CSharp_examples/ directories contain build configurations and example code (JavaExamples_run_mission.java, RunMission.cs), but there are no automated tests validating their compilation or basic execution. Unlike Python examples which can be tested in isolation, these require proper build setup validation. Adding CMake-based test targets would catch breaking changes early.

• [ ] Modify Malmo/samples/Java_examples/CMakeLists.txt to add a test_java target that compiles and validates JavaExamples_run_mission.java
• [ ] Modify Malmo/samples/CSharp_examples/CMakeLists.txt to add a test_csharp target that validates RunMission.csproj configuration and performs a dry-run build
• [ ] Create Malmo/samples/CMakeLists.txt test section that runs all language-specific tests via ctest
• [ ] Document test execution in Malmo/samples/README (create if missing) with language-specific prerequisites
• [ ] Integrate into .travis.yml and new GitHub Actions workflow to run these tests on appropriate platforms

• Add type hints to Malmo/samples/Python_examples/malmoutils.py: malmoutils.py is the bridge between all Python examples and the Malmo SDK but lacks type annotations; adding them would improve IDE autocomplete and catch bugs in downstream examples
• Document mission XML schema with examples in Malmo/samples/Python_examples/: Many Python examples generate mission XML dynamically (e.g., MazeRunner.py) but there's no canonical schema reference; a README in Python_examples/ with XML tags and examples would unblock new users
• Port high-value examples to MalmoEnv (e.g., decision_tree_test.py, depth_map_runner.py): The codebase is transitioning to MalmoEnv but only a few examples exist for it; porting decision_tree_test.py and depth_map_runner.py would demonstrate the new API and help validate MalmoEnv stability

The Project Malmo codebase has significant security concerns primarily related to outdated dependencies, insecure repository configuration, and incomplete build configuration. The most critical issue is the use of HTTP (rather than HTTPS) for Maven dependency downloads, which creates MITM attack risk. The Minecraft 1.11.2 and ForgeGradle 2.2-SNAPSHOT versions are obsolete and likely contain multiple known vulnerabilities. The project lacks evidence of automated security scanning in its CI/CD pipeline. Immediate remediation should focus on upgrading to current stable versions, securing Maven repository URLs with HTTPS, and implementing dependency vulnerability scanning in the CI/CD pipeline.

• High · Insecure Maven Repository Configuration — build.gradle - buildscript repositories section. The build.gradle file uses an HTTP URL (http://files.minecraftforge.net/maven) instead of HTTPS for downloading dependencies. This creates a vulnerability to man-in-the-middle (MITM) attacks where malicious artifacts could be injected during the build process. Fix: Replace 'http://files.minecraftforge.net/maven' with 'https://files.minecraftforge.net/maven' to ensure secure, encrypted communication during dependency downloads.
• High · Outdated Minecraft and Forge Versions — build.gradle - minecraft version and ForgeGradle dependency. The project uses Minecraft version 1.11.2 and ForgeGradle 2.2-SNAPSHOT, which are significantly outdated (released in 2016-2017). These versions likely contain known security vulnerabilities and are no longer maintained. Fix: Update to the latest stable versions of Minecraft and ForgeGradle. Review security advisories for the current versions and implement regular dependency updates.
• Medium · SNAPSHOT Dependency Version — build.gradle - classpath dependency for ForgeGradle. The build configuration uses ForgeGradle:2.2-SNAPSHOT, which pulls unstable snapshot builds. Snapshot versions can be modified after initial download, creating potential supply chain risks and unpredictable behavior. Fix: Use a stable, released version of ForgeGradle instead of SNAPSHOT. Pin to a specific version (e.g., 2.3 or higher stable release) rather than allowing automatic updates.
• Medium · Incomplete Build Configuration — build.gradle - end of file. The build.gradle file contains truncated code at the end ('JavaExec exec = project.getTasks().ge'), suggesting incomplete or malformed configuration. This could indicate the file was corrupted or improperly edited, potentially masking or introducing security issues. Fix: Complete the build.gradle configuration by reviewing the intended JavaExec task setup. Ensure all build configurations are properly closed and tested.
• Medium · Missing Security Headers in Repository Configuration — .travis.yml, .travis/ directory. The project does not appear to have security scanning integration (.gitignore and CI config suggest limited security tooling). The .travis.yml CI configuration may not include dependency vulnerability scanning or security linting. Fix: Integrate security scanning tools into CI/CD pipeline such as OWASP Dependency-Check, Snyk, or WhiteSource to identify vulnerable dependencies automatically.
• Low · FML Core Plugin Auto-Loading — build.gradle - jar manifest configuration. The jar manifest configuration automatically loads 'com.microsoft.Malmo.OverclockingPlugin' as an FML core plugin. While not inherently vulnerable, auto-loading plugins increases the attack surface if the plugin code contains vulnerabilities. Fix: Review the OverclockingPlugin code for security issues. Ensure it follows principle of least privilege and doesn't execute potentially dangerous operations automatically.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.