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/Anuken/Mindustry 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.

WAIT — Mixed signals — read the receipts

• Last commit 1d ago
• 22+ active contributors
• GPL-3.0 licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 62% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{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 Anuken/Mindustry repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Anuken/Mindustry.

What it runs against: a local clone of Anuken/Mindustry — 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 Anuken/Mindustry | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | 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 ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Anuken/Mindustry. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Anuken/Mindustry.git
#   cd Mindustry
#
# 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 Anuken/Mindustry and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 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 "core/src/mindustry" \\
  && ok "core/src/mindustry" \\
  || miss "missing critical file: core/src/mindustry"
test -f "annotations/src/main/java/mindustry/annotations/entity/EntityProcess.java" \\
  && ok "annotations/src/main/java/mindustry/annotations/entity/EntityProcess.java" \\
  || miss "missing critical file: annotations/src/main/java/mindustry/annotations/entity/EntityProcess.java"
test -f ".github/workflows/pr.yml" \\
  && ok ".github/workflows/pr.yml" \\
  || miss "missing critical file: .github/workflows/pr.yml"
test -f "android/build.gradle" \\
  && ok "android/build.gradle" \\
  || miss "missing critical file: android/build.gradle"
test -f "CONTRIBUTING.md" \\
  && ok "CONTRIBUTING.md" \\
  || miss "missing critical file: CONTRIBUTING.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
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/Anuken/Mindustry"
  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).

Mindustry is a Java-based automation tower defense RTS game where players design production chains and defend against waves of enemies. It combines real-time strategy mechanics with factory-building puzzles, featuring complex resource processing systems (conveyor belts, refineries, reactors) and multiplayer cooperative/PvP gameplay. The core engine is written in Java using LibGDX (Arc framework), with GLSL shaders for rendering and cross-platform support (desktop, Android, server). Multi-module Gradle monorepo: core/ contains the shared game engine and asset pipeline (core/assets-raw/ for sprites, core/assets/ for compiled output); desktop/ is the LibGDX desktop runner; android/ is the Android-specific build with manifest and resource folders (res/drawable, res/mipmap); server/ is a headless server variant. Build tooling in tools/ (sprite packing via gradlew tools:pack). GitHub Actions workflows in .github/workflows/ handle CI and deployment to deploy/ folder.

Game developers interested in RTS/tower defense architecture, Java game engineers building simulation-heavy games, and open-source game modders who want to extend or fork a production-quality tower defense engine. Also: players creating custom maps and mods via Mindustry's scripting layer.

Highly mature and production-ready. The codebase is 6MB+ of Java with comprehensive CI/CD pipelines (.github/workflows/deployment.yml, gradle-wrapper-validation.yml, push.yml). Active development with automated bleeding-edge builds generated per commit. Well-documented with Javadoc, wiki, and structured issue templates (bug_report.yml, config.yml). Clear contribution guidelines (CONTRIBUTING.md, ISSUES.md, TRANSLATING.md) indicate an established community.

Low risk for a mature project. Single-maintainer (Anuken) means feature decisions are centralized but also potentially slower for external contributors. Requires JDK 17 specifically (not negotiable per README), which locks users to a specific version. Android build complexity (SDK setup, ndkVersion management in gradle) may cause friction for contributors unfamiliar with Android toolchain. Large monorepo (desktop + server + android + core modules) increases cognitive load for first-time contributors.

Project is under active development targeting Mindustry v7.0 (visible from .github/workflows and automated build pipeline). Sprite packing pipeline (tools:pack task) suggests ongoing asset refinement. Android build upgraded to compileSdk 36 and buildToolsVersion 36.0.0 (recent). Multiple concurrent deployment targets (desktop, server, Android APK) indicate feature parity maintenance across platforms.

Clone and build the desktop version:

git clone https://github.com/Anuken/Mindustry.git
cd Mindustry
./gradlew desktop:run

On Windows, use gradlew desktop:run (no ./). Requires JDK 17 from Adoptium (https://adoptium.net/temurin/releases/?os=any&arch=any&version=17) — other versions will fail.

Daily commands: Desktop: ./gradlew desktop:run (macOS/Linux) or gradlew desktop:run (Windows). Server: ./gradlew server:run. Android emulator: ./gradlew android:installDebug android:run. Sprite repacking (rarely needed): ./gradlew tools:pack. All commands run from repository root. Desktop executable builds to desktop/build/libs/ via ./gradlew desktop:dist.

• core/src/mindustry — Core game logic root—all game mechanics, entities, and systems originate here
• annotations/src/main/java/mindustry/annotations/entity/EntityProcess.java — Annotation processor that generates entity component code; understanding this is essential for modifying game entities
• .github/workflows/pr.yml — Pull request validation pipeline—defines code style, testing, and merge requirements every contributor must pass
• android/build.gradle — Android build configuration; critical for platform-specific builds and deployment
• CONTRIBUTING.md — Defines code style, PR guidelines, and contribution workflow for the project
• annotations/src/main/resources/classids.properties — Class ID registry used by serialization/networking layer; modifications require careful coordination
• annotations/src/main/java/mindustry/annotations/impl/StructProcess.java — Struct code generation processor; handles serialization and data structure definitions

Add a New Entity Type (Building, Unit, Projectile)

1. Create entity component class annotated with @EntityDef in core/src/mindustry with fields for your entity (core/src/mindustry)
2. The EntityProcess.java annotation processor automatically generates component constructors, getters, and serialization (annotations/src/main/java/mindustry/annotations/entity/EntityProcess.java)
3. Register entity class ID in classids.properties for network serialization (annotations/src/main/resources/classids.properties)
4. Add entity schema revision JSON in annotations/src/main/resources/revisions/ to track version changes (annotations/src/main/resources/revisions)
5. Implement entity logic in core game systems; the generated component handles serialization automatically (core/src/mindustry)

Add a Remote Procedure Call (RPC) for Multiplayer Sync

1. Define remote method in a game class annotated with @Remote in core/src/mindustry (core/src/mindustry)
2. RemoteProcess.java annotation processor generates serialization stubs and client/server method dispatch (annotations/src/main/java/mindustry/annotations/remote/RemoteProcess.java)
3. SerializerResolver automatically maps parameter types to network I/O handlers (annotations/src/main/java/mindustry/annotations/remote/SerializerResolver.java)
4. Rebuild project; generated code handles network marshaling transparently (annotations/src/main/java/mindustry/annotations/remote/CallGenerator.java)

Update Android Build or Add Platform-Specific Code

1. Modify android/build.gradle for new dependencies, SDK versions, or build variants (android/build.gradle)
2. Add Android-specific logic in android/src/mindustry/android/; AndroidLauncher.java is the entry point (android/src/mindustry/android/AndroidLauncher.java)
3. Update android/AndroidManifest.xml for permissions, activities, or platform features (android/AndroidManifest.xml)
4. Test via android/build.gradle tasks; CI will validate in .github/workflows/pr.yml (.github/workflows/pr.yml)

Modify Code Style or CI/CD Pipeline

1. Update code style rules in .github/Mindustry-CodeStyle-IJ.xml and document in CONTRIBUTING.md (.github/Mindustry-CodeStyle-IJ.xml)
2. Modify PR validation checks in .github/workflows/pr.yml (.github/workflows/pr.yml)
3. Update main build/test flow in .github/workflows/push.yml (.github/workflows/push.yml)
4. Regenerate builds and verify in .github/workflows/deployment.yml if release process changes (.github/workflows/deployment.yml)

• Java — Cross-platform game engine support (JVM runs on desktop, Android, web via GWT) with strong typing for automation tower-defense complexity
• Gradle build system — Multi-module builds (core, android, annotations) with custom task orchestration for code generation and platform-specific packaging
• Compile-time annotation processors (EntityProcess, StructProcess, RemoteProcess) — Zero-runtime reflection overhead; generates entity component boilerplate, serialization, and RPC code at build time for performance-critical game loop
• GitHub Actions CI/CD — Free, integrated workflow validation on every PR/push; enforces code style, runs test suite, and manages releases
• Android SDK & framework — Mobile platform support with native JVM integration; separate build artifact from desktop/headless server builds

• Compile-time code generation instead of runtime reflection

  • Why: Game loop must run at high tick rates (60+ FPS); pre-generated component code eliminates reflection overhead
  • Consequence: Requires annotation processor toolchain and rebuild on entity schema changes; developers must understand generated code patterns

• Single-repo monolith (core + Android + annotations) with shared versioning

  • Why: Game engine and platform builds tightly coupled; easier to ensure consistency and prevent version skew
  • Consequence: Larger CI matrix; not suitable for independent mobile/desktop release cycles without restructuring

• Class ID registry (classids.properties) for networked entity serialization

  • Why: Deterministic, compact network protocol for multiplayer sync without reflection overhead
  • Consequence: Manual registration required; risk of ID collisions if not carefully managed; serialization breaks if IDs are reused

• Android as co-primary platform with desktop via libGDX framework

  • Why: Larger audience reach and monetization potential on mobile; Java codebase with platform abstraction layer
  • Consequence: Desktop

JDK version lock: Must use JDK 17 exactly; JDK 21 or 11 will cause gradle/compilation failures. Android SDK setup is fussy: Requires Android SDK cmdline-tools with a latest/ subfolder and sdkmanager --licenses run beforehand; skipping this step fails silently at build time. Sprite packing: Raw assets in core/assets-raw/sprites/ must be repacked via gradlew tools:pack before changes appear in-game; omitting this step causes assets to not load. Version file auto-update: Modifying core/assets/version.properties directly will be overwritten on next build; changes go through gradle version properties. Monorepo gradle complexity: Changing core module code requires understanding gradle subproject dependencies; simple typos can break all three platforms (desktop, android, server) simultaneously.

• Tile-grid-based game world — Mindustry's gameplay is built on fixed 8x8 or 16x16 tile grids; understanding this spatial quantization is essential for building mechanics, pathfinding, and collision systems.
• Entity-Component System (ECS) — Units and buildings in Mindustry likely use ECS architecture to decouple rendering, physics, and behavior; this is critical for understanding how to add new unit types or buildings.
• Procedural Content Generation (PCG) — Mindustry generates maps and waves dynamically; understanding noise functions, seed management, and constraint satisfaction is key to map design and balance tuning.
• Double buffering / Framebuffer objects — GLSL shaders in core/assets/shaders/ likely use framebuffers for post-processing effects (bloom, shadows); critical for rendering pipeline optimization.
• Cross-platform abstraction (LibGDX Arc pattern) — Arc abstracts away platform differences (desktop LWJGL, Android JNI); understanding how Arc bridges these layers is essential for debugging platform-specific crashes.
• Code obfuscation (Proguard) — android/build.gradle includes Proguard configuration; stripped code names in crash logs make Android debugging harder; knowledge of obfuscation rules is needed for stack trace mapping.
• Gradle multi-module builds — The monorepo uses core, desktop, android, and server modules with shared dependencies; misunderstanding gradle subproject configuration causes hard-to-debug compilation failures.

• Anuken/Arc — LibGDX fork that Mindustry depends on; contains the rendering engine and cross-platform abstractions (Arc/natives/ has Android JNI bindings referenced in android/build.gradle)
• Anuken/Mindustry-Suggestions — Companion repo for feature requests and issues tagged 'candidate'; primary source of scoped tasks for new contributors per CONTRIBUTING.md
• Anuken/MindustryBuilds — Automated release artifact repository; bleeding-edge .jar and .apk files generated per-commit by the deployment.yml CI pipeline
• libgdx/libgdx — Upstream game framework; Mindustry's Arc is a fork, so understanding libgdx core (rendering, input, audio) is useful for engine-level debugging
• google/android-gradle-plugin — Dependency for android/build.gradle (gradle:8.2.2); required knowledge for Android build configuration changes

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 GitHub Actions workflow for Android APK build validation on PRs

The repo has deployment.yml and pr.yml workflows, but no dedicated Android build validation. The android/build.gradle file shows complex configuration (buildToolsVersion 36.0.0, compileSdk 36, multiDex, etc.) that should be tested on every PR to catch Android-specific regressions early, especially given the minSdkVersion 14 compatibility requirement.

• [ ] Create .github/workflows/android-build.yml that runs 'gradle assembleDebug' for the android module
• [ ] Add validation for android/build.gradle syntax and dependency resolution
• [ ] Configure the workflow to trigger on PR changes to android/, core/assets/, and build.gradle files
• [ ] Add a check that verifies APK output exists in build/outputs/apk/

Add comprehensive issue template for Android-specific bugs

The .github/ISSUE_TEMPLATE/ directory has bug_report.yml but it's generic. Given the multi-platform nature (Java desktop + Android with minSdkVersion 14 support), Android-specific crashes need their own template to capture logcat output, Android version, device info, and native library loading issues (note the jniLibs configuration in build.gradle).

• [ ] Create .github/ISSUE_TEMPLATE/android_bug.yml with fields for: Android version, Device model, logcat output, whether app was built locally vs downloaded, and native library stack traces
• [ ] Update .github/ISSUE_TEMPLATE/config.yml to route issues with 'android' label to this new template
• [ ] Add guidance for contributors on how to capture logcat using 'adb logcat' in the template

Add Gradle dependency vulnerability scanning to CI pipeline

The build.gradle files show external dependencies (Android Gradle plugin 8.2.2, Google Maven repository) but there's no automated scanning for CVEs in transitive dependencies. This is critical for a popular game with millions of Android users. Add a GitHub Actions job to detect and report vulnerable dependencies.

• [ ] Add dependency-check or similar scanning tool to .github/workflows/push.yml and pr.yml
• [ ] Configure it to scan android/build.gradle, core/build.gradle, and all module dependencies
• [ ] Set the workflow to fail on high-severity CVEs found in direct or transitive dependencies
• [ ] Add a suppression file (e.g., dependency-check-suppressions.xml) in the root for any accepted risk dependencies

• Add unit tests for core/src/mindustry/type/ item and block definitions to validate balance numbers and circular dependencies; currently no test files visible for content validation.
• Create a GLSL shader documentation guide in the wiki (not in repo but referenced) explaining the vertex/fragment shader pipeline in core/assets/shaders/; new graphics contributors are likely confused by shader organization.
• Fix or document the Android jniLibs.srcDirs conditional logic in android/build.gradle (lines ~30-35) which assumes localArc property; add a README.md to android/ explaining the Arc dependency setup and local vs. remote native library handling.

The Mindustry Android build configuration has several security concerns. The most critical issues are: (1) extremely outdated minSdkVersion 14 exposing users to years of known vulnerabilities, (2) use of mavenLocal() in buildscript repositories creating supply chain risks, and (3) incomplete/unclear version property handling. The codebase lacks visible secrets or obvious injection vulnerabilities in the provided configuration. Recommend immediately updating minimum SDK version, securing the build dependency chain, and completing the build configuration. No Docker/Infrastructure misconfigurations detected in provided snippets.

• High · Outdated Android Build Tools and SDK — android/build.gradle - compileSdk, buildToolsVersion, minSdkVersion. The project uses buildToolsVersion 36.0.0 and compileSdk 36, which appear to reference future/unreleased Android SDK versions. This may indicate the build configuration is incorrect or using unstable tooling. Additionally, minSdkVersion 14 is extremely outdated (released in 2013) and exposes the application to numerous known security vulnerabilities in older Android versions. Fix: Update to stable, current Android SDK versions (compileSdk 34+, buildToolsVersion 34.0.0+). Increase minSdkVersion to at least 24 (API level 7.0+, released 2015) or preferably 26+ to exclude devices with known critical vulnerabilities.
• High · Insecure Gradle Plugin Repository — android/build.gradle - buildscript repositories section. The buildscript uses mavenLocal() as the first repository, which could allow local Maven repositories to override legitimate dependencies. This creates a potential supply chain attack vector if the local Maven repository is compromised or if dependencies are accidentally installed there. Fix: Remove mavenLocal() from the repositories list or place it last. Use only verified, official repositories (mavenCentral, google()). Implement dependency verification and use gradle dependency locking.
• Medium · Version Properties File Generation Without Validation — android/build.gradle - defaultConfig block. The build script generates a version.properties file in the assets directory using props.store() without apparent validation. This file is written to a location accessible to the application and could potentially be manipulated. Fix: Validate version properties before writing. Consider moving version.properties outside of accessible assets. Implement file integrity checks. Use BuildConfig class generated by Gradle instead of properties files for version data.
• Medium · Hardcoded Package Name and Application ID — android/build.gradle - defaultConfig. The applicationId 'io.anuke.mindustry' is hardcoded in build.gradle. While normal, ensure this matches the actual package structure. No evidence of dynamic or injectable applicationId that could lead to package confusion attacks. Fix: Maintain hardcoded applicationId for release builds. Consider using flavor-based variants for different build types if needed. Document the official package name in security documentation.
• Medium · MultiDex Enabled Without Documentation — android/build.gradle - defaultConfig. multiDexEnabled = true is set without visible justification or mitigation strategies. This could indicate method count issues or complex dependencies that might harbor security issues. Fix: Document why MultiDex is required. Analyze and reduce dependency count if possible. Ensure proper MultiDex support library is included. Test thoroughly for ClassLoader issues.
• Low · Incomplete Source Configuration — android/build.gradle - compileOptions section. The compileOptions block in android/build.gradle appears incomplete (sourceCompatibility is not assigned a value). This could cause unexpected compilation behavior. Fix: Complete the compileOptions configuration with explicit sourceCompatibility and targetCompatibility versions (e.g., JavaVersion.VERSION_11).
• Low · ProGuard Rules May Need Review — android/proguard-rules.pro. ProGuard rules file exists (android/proguard-rules.pro) but content was not provided for review. Misconfigured ProGuard rules could expose sensitive code or introduce runtime failures. Fix: Review ProGuard rules to ensure: keep rules don't expose sensitive code, proper obfuscation is applied, exception classes are kept for debugging, third-party library keep rules are correct.

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.