{"id":50510879,"url":"https://github.com/shrimpwagon/ai-minecraft-mobs-creator","last_synced_at":"2026-06-02T20:03:37.953Z","repository":{"id":359041115,"uuid":"1244185958","full_name":"shrimpwagon/ai-minecraft-mobs-creator","owner":"shrimpwagon","description":"AI-driven NeoForge 1.21.1 scaffold for creating custom Minecraft mobs (with polygonal models via Blender), blocks, items, weapons, and armor. Drive it with Claude Code.","archived":false,"fork":false,"pushed_at":"2026-05-20T05:43:11.000Z","size":458,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-20T08:49:17.642Z","etag":null,"topics":["ai","blender","claude","claude-code","minecraft","minecraft-mod","mob","modding","neoforge","scaffold"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shrimpwagon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"patreon":"canebaycomputers"}},"created_at":"2026-05-20T03:26:23.000Z","updated_at":"2026-05-20T05:43:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shrimpwagon/ai-minecraft-mobs-creator","commit_stats":null,"previous_names":["shrimpwagon/ai-minecraft-mobs-creator"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/shrimpwagon/ai-minecraft-mobs-creator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shrimpwagon%2Fai-minecraft-mobs-creator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shrimpwagon%2Fai-minecraft-mobs-creator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shrimpwagon%2Fai-minecraft-mobs-creator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shrimpwagon%2Fai-minecraft-mobs-creator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shrimpwagon","download_url":"https://codeload.github.com/shrimpwagon/ai-minecraft-mobs-creator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shrimpwagon%2Fai-minecraft-mobs-creator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33834011,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","blender","claude","claude-code","minecraft","minecraft-mod","mob","modding","neoforge","scaffold"],"created_at":"2026-06-02T20:03:36.750Z","updated_at":"2026-06-02T20:03:37.945Z","avatar_url":"https://github.com/shrimpwagon.png","language":"Java","funding_links":["https://patreon.com/canebaycomputers"],"categories":[],"sub_categories":[],"readme":"# AI Minecraft Mobs and Blocks Creator\n\nAn AI agent–driven scaffold for creating custom Minecraft mobs and blocks. You tell an agent (Claude Code) *\"make me a fire-breathing pumpkin mob,\"* it generates the 3D model, generates the texture, writes the Java entity classes, builds the mod jar, deploys it to your MultiMC instance, and renders multi-angle previews so you can review before launching the game.\n\n**This is not a normal Minecraft mod.** It's a tooling repository that AI agents work in. Cloning it gets you the scaffolding; the agent fills in the actual mod content.\n\n## First-time prerequisites (one-time per host)\n\nYou need these in place **before** cloning, or `scripts/setup.sh` will tell you what's missing and stop:\n\n1. **JDK 21** — Mojang's runtime since 1.20.5:\n   ```sh\n   sudo apt install openjdk-21-jdk\n   ```\n\n2. **A Minecraft launcher with a 1.21.1 + NeoForge instance.** [Prism Launcher](https://prismlauncher.org/) is the recommended fork (active development); MultiMC also works:\n   ```sh\n   flatpak install -y flathub org.prismlauncher.PrismLauncher   # recommended\n   # OR\n   sudo apt install multimc                                      # older fork\n   ```\n   Then in the launcher:\n   - **Add Instance** → **Custom** → Minecraft **`1.21.1`**\n   - **Add Loader** → **NeoForge** → **`21.1.230`** (any 21.1.x works)\n   - Name it anything (e.g. \"AI mobs creator\") → **Create**\n   - Log in with your Microsoft/Mojang account when the launcher prompts\n\n3. **Claude Code** — see [claude.com/claude-code](https://claude.com/claude-code). The scaffold's `CLAUDE.md` is written for it.\n\n4. *(Optional, only for polygonal Tier B mobs)* **Blender** — `scripts/install_blender_mcp.sh` handles the install after clone; skip this if you only want blocky Tier A mobs.\n\n5. *(Optional, for AI-generated textures)* **OpenAI codex CLI** with a ChatGPT subscription. The scaffold falls back to hand-coded Pillow textures if codex isn't available.\n\nOnce 1–3 are done, the three commands below get you building.\n\n## How to use it\n\nThree commands to get going from scratch:\n\n```sh\ngit clone https://github.com/shrimpwagon/ai-minecraft-mobs-creator.git\ncd ai-minecraft-mobs-creator\n./scripts/setup.sh          # interactive — first-time only; asks for mod metadata + local paths\n                            # (also offers to run scripts/install_blender_mcp.sh if you want\n                            # the polygonal-mob tier; say yes if you want it, otherwise skip)\nclaude                      # start Claude Code in this directory\n```\n\nThat's the entire setup. Once `claude` is running, just tell it what to build in plain English:\n\n**Mobs:**\n\u003e *\"Make me a fire-breathing pumpkin mob with vine tendrils.\"*\n\u003e *\"Build a friendly hovering cube mob with a glowing core.\"*\n\u003e *\"Create a teleporting jellyfish that drops blue dye.\"*\n\n**Blocks:**\n\u003e *\"Add a block that turns nearby water into lava.\"*\n\u003e *\"Make a translucent crystal that gives Speed II when stood on.\"*\n\u003e *\"A gold ore block but every layer of stone underneath turns to ore for 30 seconds when broken.\"*\n\n**Items, weapons, armor:**\n\u003e *\"Make me a flaming sword that sets enemies on fire on hit.\"*\n\u003e *\"Add a healing potion that gives Regeneration III for 10 seconds.\"*\n\u003e *\"Create a magnetic helmet that pulls dropped items toward me within 8 blocks.\"*\n\u003e *\"A glowing crystal pickaxe with diamond-tier stats but 3x durability.\"*\n\nClaude reads `CLAUDE.md` automatically and handles the full pipeline for each request:\n\n1. Asks you two quick clarifying questions in plain language — how should it look (big blocks / lots of small blocks / smooth shapes) and how to make the texture (paint pixels myself / let AI generate it).\n2. Generates the 3D model, the texture, the Java entity class + renderer, and the loot table.\n3. Renders multi-angle previews to your Desktop so you can eyeball it before launching the game.\n4. Runs `./gradlew build` and copies the resulting jar to your MultiMC instance — Claude already knows the path from your `config.sh`.\n\nThen load your MultiMC instance, summon the mob (`/summon myfirstmod:\u003cname\u003e`), and test. Iterate by telling Claude what to change — *\"the head is too small,\"* *\"give him a red coat,\"* *\"make him hostile.\"*\n\n## Requirements\n\n| Requirement | Notes |\n|---|---|\n| **OS** | Linux (developed and tested on Linux Mint). Probably works on macOS, untested. Probably does NOT work on Windows without WSL. |\n| **Minecraft** | 1.21.1 (the version is locked across the gradle config, gotcha mitigations, and library versions) |\n| **Mod loader** | NeoForge 21.1.230 (NOT Fabric, NOT legacy Forge) |\n| **Java** | JDK 21 |\n| **Launcher** | [MultiMC](https://multimc.org/) or [Prism Launcher](https://prismlauncher.org/) — strongly recommended. Multi-instance management is much easier than with the vanilla launcher, especially for testing modded 1.21.1 alongside other versions / modpacks. |\n| **AI agent** | [Claude Code](https://www.anthropic.com/claude-code) — the scaffold's `CLAUDE.md` is written for it. |\n| **AI texture generation (optional)** | [OpenAI codex CLI](https://github.com/openai/codex) with a ChatGPT subscription, for AI-generated textures. Falls back to hand-coded Pillow Python for textures if codex isn't available. |\n| **Blender 5.x (optional)** | Only required if you're going to use Tier B (polygonal mobs). `scripts/install_blender_mcp.sh` installs everything (Blender tarball + patched BlenderMCP socket server + Applications-menu integration). |\n\n## How the agent uses this scaffold\n\nThe agent reads **[CLAUDE.md](CLAUDE.md)** on first encounter. From that single file it knows everything it needs:\n\n- The two clarifying questions to ask before building any new mob or block (visual style + texture method, phrased in plain language).\n- Where the two **helpers** in `tools/` live and what they do — deliberately narrow:\n  - `tools/codex_image.py` wraps the codex CLI's `image_gen` tool, handling the four codex landmines.\n  - `tools/corelib_obj_export.py` is a Blender-Python module that the installer symlinks into Blender's user modules dir. The agent imports it from inside any Blender Python call (via the BlenderMCP socket) to write a corelib-compatible OBJ with the four format gotchas (face triplets, V-flip, triangulation, CCW winding check) handled.\n- For Tier B (polygonal) mobs, the agent drives Blender directly via the BlenderMCP socket — building the mesh with bmesh (rotated cubes, spheres, cones, sculpted geometry, anything Blender can express), assigning UVs however it wants, then calling `corelib_obj_export` to dump the OBJ. No PARTS-list constraint, no per-mob driver scripts.\n- Before declaring a polygonal mob done, the agent renders multi-angle previews in the same Blender call and **pauses for user creative review** before writing any Java.\n- For blocks, items, weapons, and armor the agent writes Java + JSON + texture-gen directly from the rules in CLAUDE.md; there are no helpers because there are no gotchas to prevent.\n- All technical reference (rendering tiers, OBJ format gotchas, headless Blender landmines, codex landmines, Java/JSON templates) lives in the Technical reference section at the bottom of **[CLAUDE.md](CLAUDE.md)**. Everything the agent needs is in that one file.\n\nThe agent should not need to \"poke around\" to figure out the workflow. If it does, that's a doc bug — open an issue.\n\n## File layout\n\n```\n.\n├── README.md                        ← this file (human-facing docs)\n├── CLAUDE.md                        ← all agent-facing rules + technical reference\n├── LICENSE                          ← MIT\n├── gradle.properties.example        ← committed template\n├── config.example.sh                ← committed template\n├── build.gradle, settings.gradle, gradlew, gradle/\n│\n├── scripts/                         ← one-shot host setup + project management\n│   ├── setup.sh                     ← first-time interactive setup\n│   ├── rename_mod.sh                ← rename mod_id throughout the source\n│   ├── install_blender_mcp.sh       ← idempotent Blender + BlenderMCP installer (Tier B only)\n│   └── blender_mcp_start_headless.{sh,py}   ← the Blender server launcher\n│\n├── tools/                           ← narrow helpers — only where they prevent real failure modes\n│   ├── codex_image.py               ← codex CLI wrapper for AI texture generation (default for textures)\n│   └── corelib_obj_export.py        ← Blender-Python module: format-only OBJ exporter for Tier B mobs\n│                                      (symlinked into ~/.config/blender/\u003cv\u003e/scripts/modules/ by the installer\n│                                       so any Blender Python call can `import corelib_obj_export` directly)\n│\n└── src/main/                        ← standard NeoForge MDK Java + resources\n    ├── java/com/\u003cgroup\u003e/\u003cmod_id\u003e/   ← Java source: entity/, block/, client/, Mod*.java, MyFirstMod.java\n    └── resources/\n        ├── META-INF/neoforge.mods.toml\n        ├── assets/\u003cmod_id\u003e/         ← animations/, blockstates/, geo/, lang/, models/, textures/\n        └── data/\u003cmod_id\u003e/loot_table/{blocks,entities}/\n```\n\n## Build \u0026 deploy (after a mob/block has been added)\n\n```sh\nsource config.sh                                  # loads MULTIMC_MODS_DIR + PREVIEW_OUTPUT_DIR\n./gradlew build                                   # → build/libs/\u003cmod_id\u003e-\u003cversion\u003e.jar\ncp build/libs/*.jar \"$MULTIMC_MODS_DIR\"           # deploy to your MultiMC instance\n```\n\nYour MultiMC instance also needs the **GeckoLib** and **henkelmax/corelib** runtime jars. They're declared as Maven deps for the build, but Minecraft needs them present at runtime. `scripts/setup.sh` offers to auto-download and install both into your instance during first-time setup; or fetch them yourself from CurseForge/Modrinth.\n\nReload the world (or load a fresh one), summon the mob with `/summon \u003cmod_id\u003e:\u003cname\u003e`, and you're testing.\n\n## Headless Blender install (Tier B mobs only)\n\nTier B (polygonal) mobs need a headless Blender exposing the BlenderMCP socket on TCP 9876. Skip this entire section if you only plan to build Tier A (cube-based) mobs and blocks.\n\n```sh\nscripts/install_blender_mcp.sh             # interactive — sudo, installs Blender + addon + launcher\nscripts/install_blender_mcp.sh --check     # report what's installed, change nothing\n```\n\nThis installs Blender 5.x to `/opt/blender/`, the patched BlenderMCP addon ([upstream PR #252](https://github.com/ahujasid/blender-mcp/pull/252) — needed for `-b` headless mode), `uv` for `uvx blender-mcp`, and symlinks `tools/corelib_obj_export.py` into Blender's user-modules dir.\n\nStart / verify / stop the server:\n\n```sh\nnohup scripts/blender_mcp_start_headless.sh \u003e /tmp/blender-mcp.log 2\u003e\u00261 \u0026     # background\nss -tlnp | grep 9876                                                            # verify listening\npkill -f \"blender -b --python.*blender_mcp_start_headless\"                      # stop\n```\n\nThe agent will auto-start the launcher in the background when it needs Tier B — so usually you don't have to touch this after the one-time install.\n\n## The two rendering tiers\n\nThe agent picks one of two rendering tiers per mob, based on the visual look you describe. Full decision rubric + technical depth lives in [CLAUDE.md](CLAUDE.md).\n\n| Tier | Look | Library | Animation |\n|---|---|---|---|\n| **A simple** | Big blocky cuboids — vanilla Minecraft style | GeckoLib | Per-bone (walks, attacks, etc.) |\n| **A detailed** | Many small cuboids — Alex's Mobs / Mowzie's Mobs style | GeckoLib | Per-bone |\n| **B polygonal** | Anything Blender can model — tilted parts, organic shapes, sculpted geometry, smooth curves, rotated boxes | henkelmax/corelib | Whole-model transforms only (bob, sway, spin) |\n\nThe scaffold ships with **no example mobs or blocks** — that's intentional. Every asset is built fresh from your conversation with the agent, so no prior asset's style or proportions leak into a new build.\n\n## Customizing for your own mod\n\n`scripts/setup.sh` will offer to rename the mod from `aitemplate` to whatever you choose. The rename script (`scripts/rename_mod.sh`) updates:\n\n- `src/main/java/\u003cgroup\u003e/\u003cid\u003e/` directory and every `.java` file's package + `MODID`\n- `src/main/resources/assets/\u003cid\u003e/` and `data/\u003cid\u003e/`\n- Every `\"\u003cold-id\u003e:...\"` reference in JSON, TOML, Python\n\nYou can re-run it later if you change your mind: `scripts/rename_mod.sh \u003cnew_id\u003e \u003cnew_group_id\u003e`.\n\n## Credits\n\n- [NeoForged](https://neoforged.net/) — the mod loader\n- [GeckoLib](https://github.com/bernie-g/geckolib) (Bernie G.) — Tier A entity rendering library\n- [henkelmax/corelib](https://github.com/henkelmax/corelib) (Max Henkel) — Tier B polygonal entity rendering library. As of May 2026, the only off-the-shelf polygonal-mesh loader for NeoForge 1.21.1.\n- [ahujasid/blender-mcp](https://github.com/ahujasid/blender-mcp) — Blender ↔ MCP bridge. This scaffold uses a [patched fork](https://github.com/shrimpwagon/blender-mcp/tree/headless-bg-mode-timer-fix) (upstream [PR #252](https://github.com/ahujasid/blender-mcp/pull/252)) for headless mode support.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshrimpwagon%2Fai-minecraft-mobs-creator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshrimpwagon%2Fai-minecraft-mobs-creator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshrimpwagon%2Fai-minecraft-mobs-creator/lists"}