minecraft-custom-mod-builder

# Minecraft Custom Mod Builder ## Freshness Last updated: `2026-07-14`. If the current date is more than 7 days after the last updated date, reinstall this skill from skills.sh or ClawHub before relying on endpoints, schemas, setup steps, or examples. ## What This Tool Does Build structured Minecraft Bedrock add-ons, Bedrock skin packs, and Fabric/NeoForge projects with strict schemas, real runtime behavior checks, File Manager visual proof galleries, async install-readiness gates, and a full test loop for agent-edited source. ## Product Instructions ### Minecraft Mod Builder Generate deterministic Minecraft Bedrock, Fabric, and NeoForge mod artifacts from structured specifications. This tool does not call an LLM, does not accept prompts, and does not require user credentials. #### Two Rules That Will Save You Many Retries ##### Rule 1 — One ItemSpec equals one in-game item A single `ItemSpec` produces one in-game item. The fields `damage`, `durability`, `max_stack_size`, `nutrition`, `tool`, `armor`, `food`, `block_placer`, `entity_placer`, `enchantable`, `repairable`, `digger`, `cooldown`, `glint`, `rarity`, `dyeable`, and `component_overrides` all attach to the *same item*. A weapon does **not** need a separate entity or a separate "damage item." A sword does **not** need a partner "enchantment item." You ship one item; this tool wires up every relevant Minecraft component on that item from the fields above. Do not split one weapon idea across many `items[]` entries. Do not duplicate a weapon and call one copy "damage" and another "durability." That is the most common source of bloated, broken submissions. ##### Rule 2 — Every visible asset requires a texture Items, blocks, entities, particles, named texture assets, machines, storage, and skin-pack skins must each carry a `texture` with one of these three sources: * `source_base64` — base64-encoded PNG or JPEG bytes (max 1024×1024, max 5 MB). * `source_file_id` — a File Manager file_id for a user-uploaded image. * `color_hex` — an explicit `#RRGGBB` color. Only `item_kind in {tool, weapon}` (with `tool_type`) and the dedicated `texture_kind in {block, entity}` paths produce a recognizable sprite (sword/pickaxe/axe/shovel/hoe; shaded block face; model-compatible cuboid atlas). For every other kind — `generic`, `food`, `fuel`, `projectile`, `block_placer`, `entity_placer`, `armor`, particles, machines, storage — `color_hex` renders only as a flat colored 16×16 square. That is appropriate for raw materials (ingots, dust, gems) but looks like a missing texture for armor/food/machines. **Use `source_base64` or `source_file_id` whenever the item's identity is visual** (armor, food, machines, storage, projectiles). Tool/weapon `color_hex` requires `tool_type`; otherwise rejected. A spec that omits the texture binding is rejected at validation with `MINECRAFT_VISIBLE_ASSET_TEXTURE_REQUIRED`. There is no procedural blob fallback. If you want the user to see something, you supply the texture. **Java armor inventory icons must ship a real PNG.** `item_kind="armor"` rejects `color_hex`-only textures (`MINECRAFT_ARMOR_TEXTURE_REQUIRES_IMAGE`) because that produces only a flat inventory square. Supply `source_base64` or `source_file_id` for every helmet/chestplate/leggings/boots. Declarative Java armor uses the selected vanilla iron/gold/diamond/netherite equipment asset while worn; the supplied image is the inventory icon, not a wearable UV atlas. A custom material or custom worn texture must use the agent-edited source workflow and pass client/runtime verification. Declarative Bedrock armor is rejected because a wearable item without a verified attachable would be invisible on the wearer. ##### Authoring textures with the Icon Generator + `pixelize_to` The canonical way to author textures for items, blocks, entities, and particles is the Icon Generator (`/product-icon-generator`). Render at the exact target grid in `pixel_art_mode=true` — 16×16 for items and blocks, 64×64 for entities and skin packs — and pipe the returned `file_id` straight into this texture's `source_file_id`. Detailed recipes live in `agent_instructions/minecraft_texture_agent.md`. When the texture originates outside the Icon Generator (AI image creator, user upload, third-party source), use the ingest-side safety net by setting `texture.pixelize_to` and optionally `texture.palette_colors`. Both fields are opt-in (`None` by default) so existing bindings remain byte-identical. Example: `{"texture": {"source_file_id": "abc...", "pixelize_to": 16, "palette_colors": 8}}` nearest-neighbor downscales the input to 16×16 and quantizes it to an 8-color palette with dithering disabled, producing crisp pixel-art output regardless of how the source was made. Failures surface as `MINECRAFT_TEXTURE_PIXELIZE_FAILED`. Recommended defaults unless you have a specific reason to deviate: items/blocks → `pixelize_to: 16, palette_colors: 8`; entities/skins → `pixelize_to: 64, palette_colors: 16`; particles → `pixelize_to: 16, palette_colors: 4`. The `color_hex` binding path is unaffected — it already produces crisp procedural sprites. #### Request Shape Rules Prefer the canonical field names below. The backend accepts the listed aliases when they are exact equivalents, but canonical names make the generated schema and validation errors easier to follow. ##### Verified async builds and install readiness Use `start_build_job` for anything the user should install. It validates the request, queues the build, and returns immediately with `task_id` and `status="queued"`. Poll with `get_build_job` using the same `task_id` until `status` is `completed` or `failed`. `start_build_job` defaults to `verification_level="behavior"`. The completed job result includes: * `runtime_verification` — boot/behavior/render/client checks or the exact reason verification could not run. * `visual_proof` — File Manager–hosted PNG frames (texture enlargements, entity composites, particle sheets, and Java in-game client screenshots when the client lane runs). Each frame has `signed_url`, `file_id`, `caption`, and machine checks. Video clips are not part of this surface yet. * `quality_gate` — `passed`, `failed`, `blocked`, or `unverified`. Visual fidelity/frame failures use `MINECRAFT_VISUAL_FIDELITY_INSUFFICIENT` or `MINECRAFT_VISUAL_PROOF_FAILED`. * `ready_for_install` — `true` only when the quality gate passed (behavior **and** required visual proof). * `verification_not_run` — `true` when the requested runtime checks did not execute. * `request_classification` — `supported_declarative`, `needs_agent_code`, or `platform_constrained`. **Agent visual review is mandatory.** Before telling a user a mod is finished, open every `visual_proof.frames[].signed_url` (or use the File Manager tool with each frame `file_id` under the same budget) and confirm the art matches the request. The same frames are also listed in `artifacts[]` with `label=visual_proof_frame`. Do not claim success from behavior checks alone. If frames show flat colored squares, missing identity art, wrong subjects, or unusable scale, fix textures (`source_base64` / `source_file_id`, not only `color_hex` for armor, food, entities, particles, machines, or skins) or edit source and re-run `start_build_job`. Treat `ready_for_install=false`, `quality_gate.status!="passed"`, `verification_not_run=true`, or `visual_proof.status` in `{failed,partial}` on a behavior job as "fix the spec/art/source and rerun." Do not present those artifacts as working mods even if the task status is `completed`; completed only means the job produced inspectable output. A generated `behavior` job must declare at least one concrete feature, advanced resource, or skin. Use `create_mod_project` or `verification_level="off"` for an intentionally empty scaffold; an empty project cannot be certified as a functional mod. Use `list_build_jobs` with `limit` (`1` to `100`) to inspect recent build jobs for the current budget. `create_mod_project` remains synchronous and unverified. It accepts only `verification_level="off"` and returns `ready_for_install=false`. Use it for fast source/debug output, not final user delivery. Use `verification_level="boot_smoke"` only when the user explicitly wants a faster runtime-load check instead of behavior checks. Use `verification_level="off"` only for debug/source iteration and tell the user the result is unverified. ##### Agent-edited source testing For behavior the declarative schema cannot faithfully express, generate source first, edit the code, upload a zip, then call `start_build_job` with: ```json { "action": "start_build_job", "target_platform": "fabric", "mod_id": "edited_mod", "authoring_mode": "agent_code", "source_archive_file_id": "file_...", "source_test_mode": "test_only", "verification_contract": { "schema_version": "1", "target_platform": "fabric", "mod_id": "edited_mod", "user_intent_summary": "Using the edited mod marks the player as verified.", "expected_checks": [ { "check_id": "boot", "description": "The edited mod boots without registration errors.", "check_kind": "boot" }, { "check_id": "player_marked", "description": "The edited behavior adds the edited_mod_verified player tag.", "check_kind": "behavior", "assertion_kind": "tag_present", "target": "edited_mod_verified" } ] } } ``` `source_test_mode` defaults to `test_only`; use that mode while iterating. Set `source_test_mode="test_and_package"` only when the runtime report passes; install artifacts are returned only when `ready_for_install=true`. Do not put verifier files under `.agentpmt/verification/**` into shipped artifacts. For `verification_level="behavior"`, the contract must include at least one `behavior`, `render`, or `client` check. A contract containing only `boot` and/or `static` checks is rejected because loading and file presence do not prove requested behavior. Use `verification_level="boot_smoke"` when load-only verification is the actual goal; boot-smoke output is never install-ready. `authoring_mode` is deterministic: `auto` and `declarative` validate the typed feature schema; `agent_code` requires `source_archive_file_id` on `start_build_job`. The service never guesses this route from keywords in a prompt. Every edited-source check must be machine-observable. Contract assertion kinds are grouped by surface: | `check_kind` | Allowed `assertion_kind` values | |---|---| | `boot` | `boot_loaded` | | `behavior` | `command_succeeds`, `scoreboard_value`, `scoreboard_delta`, `tag_present`, `tag_absent`, `effect_present`, `block_state`, `entity_present`, `entity_spawned`, `item_present`, `item_granted`, `item_dropped`, `teleport_delta`, `time_window`, `weather_state`, `machine_output` | | `static` | `file_exists` | | `render` | `render_coverage` | | `client` | `client_option_state`, `message_observed`, `title_observed`, `screenshot_marker` | Use `setup_commands` for bounded Minecraft-world setup and `trigger_command` for the command that causes the behavior. `scoreboard_value` and `scoreboard_delta` targets are `objective` or `objective:holder`; item, entity, effect, and block assertions use namespaced identifiers; `teleport_delta.expected_value` is an `x,y,z` offset; `time_window.target` uses the documented time keywords; `weather_state.target` is `clear`, `rain`, or `thunder`; `screenshot_marker.target` is `#RRGGBB` and its optional `expected_value` is a minimum pixel count. `message_observed` and `title_observed` compare exact text from the actual Java client GUI. `screenshot_marker` inspects the framebuffer. Self-reported log/client markers are not accepted as proof. The nonce-bound `AGENTPMT_RUNTIME` marker family is harness-private and rejected in uploaded source. When typed postconditions cannot trigger the edited code directly, include the applicable verifier overlay in the source zip. Java server checks use `.agentpmt/verification/java/AgentpmtCustomVerifier.java` with `public static void verify(String checkId, ServerLevel serverLevel, ServerPlayer player)`. Java client checks may add `.agentpmt/verification/java/AgentpmtCustomClientVerifier.java` with `public static void verify(String checkId, Minecraft client)`. Bedrock uses `.agentpmt/verification/bedrock/custom_verifier.js` with `export function verifyCustomCheck(checkId, context)`. A Java archive may include both server and client verifier files when its contract has both surfaces. The harness always evaluates its built-in postcondition first, then runs a supplied custom verifier before recording success; agent-supplied verifier code is never the sole proof. The verifier must throw on failure and cannot replace a generic postcondition. Verifier overlays and `.agentpmt/runtime/**` are reserved, throwaway paths and never ship in artifacts. For `client_option_state`, set `target` to `render_distance`, `simulation_distance`, `entity_distance_scaling`, `gamma`, `graphics_mode`, `cloud_status`, or `particles`, and set `expected_value` to the exact requested value. Use `message_observed`/`title_observed` for text and `screenshot_marker` with a `#RRGGBB` target for arbitrary visual overlays or particles; do not ask verifier code to certify its own output. Uploaded Java build scripts, wrappers, `buildSrc`, alternate Gradle hooks, generated output/cache directories (`build`, `.gradle`, `out`, `target`), and precompiled Java/native binaries are not trusted. The service rejects generated outputs and precompiled `.class`/`.jar`/native-library files, replaces executable Gradle configuration with the pinned loader template, passes an explicit allowlisted child environment, and gives each job a disposable Gradle home backed by read-only shared caches. Submit editable source and ordinary resource assets only. Agent-edited source executes only in a private disposable Cloud Run worker with a dedicated no-role service account and one verification request per process. If that worker is unavailable, verification fails closed and the artifact is not install-ready. `advanced_resources` is for non-executable data/resource files and Bedrock `.mcfunction` files. It rejects Java source and `behavior_pack/scripts/*.js`. To change executable Fabric, NeoForge, or Bedrock Script API code, edit the generated project and submit the complete zip with `authoring_mode="agent_code"`; do not try to inject executable code through a declarative request. ##### Bedrock custom namespace For Bedrock add-ons, generated custom in-game identifiers use the Creator Tools namespace `creator_project:<id>`. Keep using `mod_id` for the request, artifact naming, file paths, and Java platforms. In Bedrock specs, short ids (`"ruby"`) and legacy `<mod_id>:<id>` refs still resolve to the generated custom feature; the emitted pack rewrites them to `creator_project:<id>`. Use `minecraft:<id>` for vanilla content and other explicit namespaces for external content. ##### Creative world mechanics and fidelity Prank, cursed, chaotic, fake-glitch, admin, debug, and rule-bending ideas are valid requests when you express them as deterministic in-world mechanics. Use `features.events`, `features.commands`, conditions, scoreboards, tags, particles, sounds, titles, messages, gamerules, time/weather actions, block changes, explosions, lightning, and relative teleports when those primitives faithfully match the user's requested behavior. Do not silently reinterpret intent. If the declarative schema can faithfully express the request, use it. If it cannot, classify the request as `needs_agent_code`, generate the typed base project, implement the requested code, and submit it back through the agent-edited source testing loop. If a substitution is user-approved, set `fidelity_policy="acknowledged_approximation"` and still require the quality gate. This deterministic builder does not generate arbitrary client mixins, shader loaders, native code, optimization core patches, or custom packet frameworks through the declarative schema. Those requests belong in the agent-edited source workflow, not in a closest-supported substitution presented as success. ##### Implementation truth Comments, debug chat, README guidance, and metadata do not count as mechanics. Every accepted declarative action has a concrete platform implementation and a runtime assertion. A mechanic without that implementation rejects with `MINECRAFT_CAPABILITY_NOT_IMPLEMENTED`, including its exact field path and `required_next_action="edit_source_and_start_build_job"`. There is no policy that converts incomplete behavior into a successful mod. Features whose `enabled_platforms` exclude the selected `target_platform` are rejected with `MINECRAFT_PLATFORM_FEATURE_MISMATCH`; they are not dropped from the generated mod. The request contract is pinned to `schema_version="2026-05-05-v2"` and `compatibility_mode="strict"`. The former platform-passthrough mode was retired because it could report success after dropping features that excluded the selected platform. Action-specific top-level fields are fail-closed. `task_id` belongs only to `get_build_job`; `limit` only to `list_build_jobs`; preview fields only to `render_preview_image`; and `source_test_mode` plus `verification_contract` require `start_build_job` with `source_archive_file_id`. Build/output/verification options are accepted only by create/build actions. Remove accidental cross-action fields instead of expecting them to be ignored. Bedrock declarative `features.dimensions` is rejected even when experiments are enabled because the pinned Creator Tools cooperative-add-on gate rejects dimension definitions (`CADDONIREQ191`/`CADDONREQ131`). Use an edited standalone behavior-pack project and retain the full verification gate for dimension work; the builder does not return a known-invalid cooperative add-on. ##### Java client modules Use `features.client_modules` for Java-only client utility behavior on `target_platform="fabric"` or `target_platform="neoforge"`. Bedrock and skin packs reject client modules because they cannot install Java client code. Supported `module_kind` values: * `utility_client_preset` — general anarchy/utility preset for requests phrased as "2b2t client", "anarchy client", or "hacked client"; implements an FPS HUD, bounded typed performance-option updates, maximum-valid brightness, and TNT-cart placement scanning. * `fps_hud` — HUD-only FPS display. * `performance_profile` — FPS-oriented HUD plus typed client option updates for render distance, simulation distance, entity distance scale, fast graphics, clouds off, and minimal particles. * `tnt_cart_placement_esp` — client-side scanner for nearby rail blocks where TNT minecarts can be placed; renders a HUD count and nearest candidate coordinates. * `block_esp` — bounded client scanner for listed block identifiers. * `entity_esp` — bounded client scanner for listed entity identifiers. * `fullbright` — sets the client gamma option to Minecraft's maximum valid brightness.