Content
# NeoForge 1.21.1 AI Starter
[](https://github.com/c2717649225-rgb/neoforge-1.21.1-ai-starter/actions/workflows/build.yml)
[](https://www.minecraft.net/)
[](https://neoforged.net/)
[](https://adoptium.net/)
## What is this project?
This is a ready-to-use **development starter** for **Minecraft Java Edition 1.21.1 + NeoForge**.
After cloning or using this template, you will get:
1. A **1.21.1 NeoForge modding project template** (compilable and runnable on client);
2. A **`.agents` folder**: containing tools, skills, MCP probes, etc., to help AI write code, check source code, and perform compilation self-inspection.
---
## Repository Structure (two parts)
| | Part | What is it | Mainly provides |
|---|------|--------|----------|
| ① | **[`.agents/`](.agents/)** | AI-assisted development **toolkit** (reusable in other 1.21.1 NeoForge projects) | Development guidelines, NeoForge skills/reference documentation, source code MCP probes, initialization and compilation self-inspection scripts |
| ② | **Rest of the directory** | Mod development **template** (Gradle / NeoForge project) | `src/`, `build.gradle`, `gradle.properties`, `gradlew`, minimal example `tutorialmod` |
```text
neoforge-1.21.1-ai-starter/
├── .agents/ ← ① AI toolkit
├── src/ ← ② Mod source code (tutorialmod starter)
├── build.gradle ← ② Build configuration
├── gradle.properties ← ② Mod metadata (mod_id, etc.)
├── gradlew / .bat ← ② Gradle Wrapper
└── README.md ← This page (GitHub homepage)
```
- **Create a new mod**: use this repository as a template → change metadata → initialize → connect MCP → write code.
- **Use AI capabilities only**: copy `.agents/` to an existing project (version must be 1.21.1 / Neo 21.1.x).
- `tutorialmod` is just a compilable skeleton, not a complete gameplay example.
> GitHub **Languages** may show more Python/JS (due to tool scripts); the mod itself is still **Java + Gradle**.
For more detailed file-level explanations, see the [`.agents` directory description](#agents-directory-description) (expandable).
---
## Requirements
- **JDK 21** (`JAVA_HOME` or PATH; `java -version` displays 21)
- **Python 3** (init / MCP / self-inspection scripts)
- Git; initial build requires network connection and sufficient disk space
---
## Four Steps to Get Started
### 1. Configure Metadata
Edit `gradle.properties`:
```properties
mod_id=yourmod
mod_name=Your Mod Name
mod_group_id=com.yourpackage.yourmod
```
### 2. Initialize Workspace
Tell AI: `Help me initialize this workspace`
Or run in terminal:
```bash
python .agents/init_workspace.py
```
Align package names, resource namespaces, main class constants, mixins, etc. according to `gradle.properties`.
### 3. Register Source Code MCP (required)
Script: `.agents/mcp/minecraft_mcp.py`
Register in AI client's MCP configuration; steps see [`.agents/README.md`](.agents/README.md).
AI should not invent Minecraft / NeoForge API without MCP connection.
### 4. Compilation Self-Inspection
```bash
# Default: compileJava only
python .agents/skills/workspace_setup/scripts/compile_and_repair.py
# If changed registration items or DataGen Provider, run with --with-data
python .agents/skills/workspace_setup/scripts/compile_and_repair.py --with-data
```
Optional: `./gradlew runClient`
---
## `.agents` Directory Description
<details>
<summary><strong>Directory Tree</strong></summary>
```text
.agents/
├── AGENTS.md # AI guidelines (load to client)
├── README.md # Connection instructions (MCP, etc.)
├── VERSION # Toolkit version and target platform
├── agent_workflow.md # Implementer / Reviewer process description
├── init_workspace.py # One-click initialization entry
├── mcp/
│ └── minecraft_mcp.py
└── skills/
├── neoforge/ # ★ 1.21.1 writing and references
├── workspace_setup/ # Renaming / compilation scripts
└── … # Planning, debugging, review, and other process skills
```
Generated locally, not committed: `mcp/mcp_jar_cache.json`, `**/__pycache__/` (see root `.gitignore`).
</details>
<details>
<summary><strong>Root Files</strong></summary>
| Path | Function |
|------|------|
| [`AGENTS.md`](.agents/AGENTS.md) | Global guidelines: Data Components, client isolation, network threads, DataGen exceptions, MCP access control, compilation levels, etc. |
| [`README.md`](.agents/README.md) | 5-minute connection and MCP registration instructions |
| [`VERSION`](.agents/VERSION) | Version and platform anchoring (e.g., 1.0.0 / MC 1.21.1 / Neo 21.1.x) |
| [`agent_workflow.md`](.agents/agent_workflow.md) | Implementer / Reviewer roles and "compile before review" process (not bound to specific model brands) |
| [`init_workspace.py`](.agents/init_workspace.py) | Initialization entry (forwarded to real script under `workspace_setup`) |
</details>
<details>
<summary><strong>mcp/ Source Code Probe</strong></summary>
| File | Function |
|------|------|
| [`minecraft_mcp.py`](.agents/mcp/minecraft_mcp.py) | Local MCP: search/read Gradle cache and project MC, NeoForge source code (e.g., `search_class`, `grep_source`) |
Connection method see [`.agents/README.md`](.agents/README.md). Cache files used locally only.
</details>
<details>
<summary><strong>skills/ Overview</strong></summary>
Each subdirectory usually has a `SKILL.md` for AI to select by task.
**Mod-related (priority)**
| Directory | Function |
|------|------|
| **neoforge** | Core: 1.21.1 constraints, code skeleton, `references/` topics, `examples/`; compile / `--with-data` agreement |
| **workspace_setup** | Renaming and initialization process; contains `init_workspace.py`, `compile_and_repair.py` |
**Project process (general)**
| Directory | Function |
|------|------|
| using-superpowers | Read before using applicable skills |
| brainstorming | Demand and solution clarification |
| writing-plans | Write executable implementation plans |
| executing-plans | Implement according to plan (Implementer / Reviewer) |
| subagent-driven-development | Multi-subagent implementation and task review |
| dispatching-parallel-agents | Independent task parallel dispatch |
| test-driven-development | Test before writing |
| systematic-debugging | Systematic error checking |
| verification-before-completion | Verification evidence required before completion |
| requesting-code-review / receiving-code-review | Initiate / handle code review |
| finishing-a-development-branch | Feature closure (merge / PR, etc.) |
| using-git-worktrees | Worktree isolation development |
| task_monitor | Long task monitoring ideas |
| writing-skills | Maintain / write skills themselves |
</details>
<details>
<summary><strong>neoforge and Script Details</strong></summary>
**neoforge/**
| Content | Function |
|------|------|
| `SKILL.md` | Total entry and skeleton, reference index |
| `references/*.md` | Thematic writing (components, network, entities, Mixin, DataGen, etc., about 40 articles) |
| `examples/*.md` | Registration, creative tab, DataGen, recipe tags, etc. examples |
Package names in documentation may be placeholders or `tutorialmod`; replace according to current `gradle.properties` before writing to the project.
**workspace_setup/scripts/**
| Script | Function |
|------|------|
| `init_workspace.py` | Align namespace, MODID, mixins, AGENTS top-level metadata, etc. |
| `compile_and_repair.py` | Default `compileJava`; `--with-data` runs `runData`; provide error context when failing |
</details>
---
## Related Links
- Full guidelines: [`.agents/AGENTS.md`](.agents/AGENTS.md) (root [`AGENTS.md`](AGENTS.md) only serves as a pointer)
- Connection Checklist: [`.agents/README.md`](.agents/README.md)
- License: [`LICENSE`](LICENSE) (MIT); original MDK text see [`TEMPLATE_LICENSE.txt`](TEMPLATE_LICENSE.txt)
- Your specific mod: declare in `gradle.properties`'s `mod_license`
---
## English
**NeoForge 1.21.1 AI Starter** — ready-to-use **Minecraft 1.21.1 / NeoForge 21.1.x** setup in two parts:
| Part | Role |
|------|------|
| **`.agents/`** | AI modding toolkit (rules, skills, local source MCP, init & compile scripts). Reusable in other 1.21.1 NeoForge projects. |
| **Rest of the repo** | Mod template (Gradle scaffold + `tutorialmod` starter). |
1. Set `mod_id` / `mod_name` / `mod_group_id` in `gradle.properties`
2. `python .agents/init_workspace.py`
3. Register `.agents/mcp/minecraft_mcp.py` as MCP ([guide](.agents/README.md))
4. `python .agents/skills/workspace_setup/scripts/compile_and_repair.py`
Requires **JDK 21** and **Python 3**. Folder details: expandable section **「.agents directory description」** above.
