Skip to content

3. MVP Development Task List

Jump to bottom
Zhoumy303 edited this page Sep 26, 2026 · 2 revisions

Version baseline: Minecraft 26.2, Fabric Loader 0.19.5, Loom 1.17-SNAPSHOT, Fabric API 0.161.0+26.2, Java 25.
Version configuration: All version numbers are centrally managed in modsmith/config.py.
Current MVP scope: Supports three item types: basic, food, and tool (fuel is not implemented for now due to Fabric API version compatibility issues).
Interaction modes: Dual modes: Chat (requirements clarification) + Execute (direct generation). The Web UI opens Chat by default.

Task 1: Project Initialization and Environment Setup

Corresponding document: 3.1 Project Initialization and Environment Setup.md

Goal: Create the Python project skeleton, configure dependencies and the development environment, and implement the LLM invocation module.

Key outputs:

  • pyproject.toml, .venv/, directory structure
  • modsmith/config.py (centralized version management)
  • modsmith/cli.py (basic CLI skeleton)
  • .env (Zhipu API key)
  • generate_blueprint() function in modsmith/llm/client.py

Notes:

  • Write all version numbers to config.py to avoid hardcoding.
  • Use Zhipu GLM as the LLM backend. Base URL: https://open.bigmodel.cn/api/anthropic.
  • The system prompt includes the complete Schema, few-shot examples, required-field descriptions, and version requirements.
  • When loading examples, override version fields with values from config.py.
  • Dependencies include anthropic, jsonschema, jinja2, pillow, typer, rich, and python-dotenv.

Task 2: Define Blueprint Schema

Corresponding document: 3.2 Define Blueprint Schema.md

Goal: Write a JSON Schema to constrain the blueprint structure output by the LLM.

Key outputs:

  • modsmith/blueprint/schema.json
  • Three examples under modsmith/blueprint/examples/ (basic, food, tool)

Notes:

  • Use allOf + if-then to implement conditional required fields.
  • mod_id and item id use pattern to restrict naming format.
  • Keep version field descriptions generic; concrete values are determined by config.py.
  • Version numbers in example files are automatically overridden by _load_examples().

Task 3: Prepare Fabric Project Template

Corresponding document: 3.3 Prepare Fabric Project Template.md

Goal: Convert fabric-example-mod into a parameterized template compatible with Minecraft 26.2+.

Key outputs:

  • Parameterized templates under modsmith/templates/fabric-project/
  • render_project() function in modsmith/generator/project.py

Notes:

  • Remove Yarn mappings; use official Mojang mappings.
  • Use the net.fabricmc.fabric-loom plugin, Java 25, and Gradle 9.5.1.
  • Remove all Mixin and client entry points.
  • In fabric.mod.json, depends uses ~{{ minecraft_version }}.
  • ExampleMod.java does not call ModItemsGenerated for now.

Task 4: Implement Blueprint Validation Module

Corresponding document: 3.4 Implement Blueprint Validation.md

Goal: Validate the blueprint returned by the LLM against the Schema; on failure, feed back corrections.

Key outputs:

  • validate_blueprint() and generate_validated_blueprint() in modsmith/blueprint/validator.py

Notes:

  • In retry feedback, list required fields and suggested default values for each type.
  • Handle jsonschema.ValidationError and json.JSONDecodeError separately.
  • Retry at most 3 times; throw RuntimeError on failure.

Task 5: Implement Project Generator

Corresponding document: 3.5 Implement Project Generator.md

Goal: Generate a complete project directory from the blueprint, integrating template rendering, Java code generation, and resource generation.

Key outputs:

  • generate_project() function in modsmith/generator/project.py
  • modsmith/generator/java.py skeleton
  • modsmith/generator/resources.py skeleton

Notes:

  • generate_project() calls render_project(), generate_java_items(), generate_resources(), and generate_all_textures() in sequence.
  • The context in project.py reads version defaults from config.py; the blueprint cannot override versions.

Task 6: Implement Java Code Generator

Corresponding document: 3.6 Implement Java Code Generator.md

Goal: Generate complete, compilable Java registration code for each item.

Key outputs:

  • modsmith/templates/java/ModItemIds.java.jinja
  • modsmith/templates/java/ModItems.java.jinja
  • modsmith/templates/java/ModItemsGenerated.java.jinja
  • Complete implementation in modsmith/generator/java.py

Notes:

  • Supports basic, food, and tool types (fuel is not implemented for now).
  • Tools use Item.Properties methods such as .sword() and .axe().
  • Food uses FoodProperties and Consumable; effects use ApplyStatusEffectsConsumeEffect (package path updated).
  • Static field declaration order: declare FoodProperties, Consumable, and ToolMaterial first, then Item.
  • ModItemsGenerated handles creative tab registration and outputs item registration logs (for runtime verification).
  • ExampleMod.java calls ModItemsGenerated.initialize().

Task 7: Implement Resource File Generator

Corresponding document: 3.7 Implement Resource File Generator.md

Goal: Generate client item definitions, model JSON, and translation files for each item.

Key outputs:

  • Complete implementation in modsmith/generator/resources.py

Notes:

  • Tool types use the minecraft:item/handheld parent; others use minecraft:item/generated.
  • Translation key format: item.<mod_id>.<item_id>.
  • Generate en_us.json and zh_cn.json (if there is a Chinese name).

Task 8: Implement Texture Generator

Corresponding document: 3.8 Implement Texture Generator.md

Goal: Generate a 16x16 pixel texture for each item; shape, color, and pattern are determined by the visual field in the blueprint. The LLM proactively infers visual from the item name, type, and effects; users do not need to mention textures in the description.

Key outputs:

  • modsmith/generator/textures.py: generate_texture(), generate_all_textures()

Notes:

  • The visual object as a whole is optional, but its internal fields are required if provided. If missing, fall back to defaults; if partially filled, trigger a retry.
  • Fallback mechanism: when there is no visual, use an MD5 hash to generate a deterministic color; the default shape is abstract.

Task 9: Implement Compilation Verification Module

Corresponding document: 3.9 Implement Compilation Verification Module.md

Goal: Automatically run ./gradlew build; on failure, feed errors back to the LLM to correct the blueprint.

Key outputs:

  • run_gradle_build() and build_with_retry() in modsmith/verifier/gradle.py

Notes:

  • Use subprocess.run to execute gradlew build with a 5-minute timeout.
  • project_dir uses .resolve() to convert to an absolute path.
  • _extract_errors extracts error lines from stdout/stderr and normalizes them to str.
  • Retry at most 3 times; each time feed the error information back to the LLM to correct the blueprint.

Task 10: Implement Packaging Output

Corresponding document: 3.10 Implement Packaging Output.md

Goal: Package the project as a zip, copy the jar, and save the blueprint and README.

Key outputs:

  • package_output() in modsmith/packager/archive.py
  • run_pipeline() in modsmith/pipeline.py

Notes:

  • Source zip excludes build/, .gradle/, .idea/, and run/ directories.
  • Find the non-sources, non-dev jar under build/libs/.
  • README includes installation instructions and the complete blueprint JSON.
  • run_pipeline() integrates blueprint generation, project generation, compilation verification, and packaging output.

Task 11: Implement CLI Entry Point

Corresponding document: 3.11 Implement CLI Entry Point.md

Goal: Integrate ModSmith into a user-friendly command-line tool.

Key outputs:

  • version, generate, chat, and web commands in modsmith/cli.py

Notes:

  • The generate command supports --output, --project-dir, and --max-retries options.
  • The chat command supports one-shot questions and interactive conversation (/quit, /clear, /history).
  • Use rich to beautify output (panels, colored text).
  • Catch exceptions and provide friendly messages.

Task 12: End-to-End Testing and Documentation

Corresponding document: 3.12 End-to-End Testing and Documentation.md

Goal: Write unit tests, perform end-to-end verification, and improve the README.

Key outputs:

  • Test files under tests/
  • test_e2e.py
  • README.md

Notes:

  • Unit tests use mocks to avoid real calls to the LLM and Gradle.
  • Fix the SCHEMA_PATH path in tests to avoid adding an extra modsmith layer.
  • End-to-end tests cover at least 1-2 item types.
  • README includes installation, configuration, usage, and development instructions.

Task 13: Implement Web UI (Execute Mode)

Corresponding document: 3.13 Implement Web UI.md

Goal: Provide a browser-based graphical interface supporting generation, download, viewing blueprint/README, and one-click game launch verification.

Key outputs:

  • modsmith/web/app.py (FastAPI backend)
  • modsmith/web/static/index.html (frontend page)
  • modsmith web CLI command

Notes:

  • Use SSE to push real-time logs.
  • After generation completes, display the contents of blueprint.json and README.md directly on the page.
  • Provide a "🎮 Verify in Game" button that runs ./gradlew runClient when clicked.
  • All file paths use .resolve() to convert to absolute paths.
  • run_client uses subprocess.Popen to launch the game in the background without blocking the response.
  • Do not reference Google Fonts; use system font stacks (--font-sans, --font-mono) so they load directly in mainland China environments.
  • Test file test_web.py verifies basic APIs.

Task 14: Implement Automatic Verification Loop Upgrade

Corresponding document: 3.14 Automatic Verification Loop Upgrade.md

Goal: Upgrade "launch game + manual check" to "launch game + parse logs to automatically determine mod loading and item registration."

Key outputs:

  • run_client_with_log() in modsmith/verifier/runtime.py
  • Output item registration logs in ModItemsGenerated.java.jinja
  • Add a /api/auto_verify endpoint in modsmith/web/app.py
  • Add a "🔍 Log Verification" button in index.html

Notes:

  • subprocess.Popen reads runClient output line by line and detects key logs in real time.
  • mod_loaded is determined by Hello Fabric world from.
  • item_registered is determined by item.<mod_id>.<item_id> registered.
  • Set a timeout to prevent waiting indefinitely when game startup fails.
  • Results are returned to the frontend via SSE or direct JSON.

Task 15: Implement Chat Mode (Requirements Clarification)

Corresponding document: 3.15 Implement Chat Mode.md

Goal: Make ModSmith act as a requirements consultant, helping users clarify vague ideas into clear, executable mod descriptions. Chat mode does not generate code; it only outputs natural-language answers.

Key outputs:

  • chat_response() and _build_chat_system_prompt() in modsmith/llm/chat.py
  • Add a chat command in modsmith/cli.py
  • Test script test_chat.py

Notes:

  • Role: requirements consultant, not technical mentor.
  • Clear capability boundaries: only basic, food, and tool are supported; out-of-scope requests (blocks, crops, entities, etc.) are gently declined and guided to a similar type.
  • Clarification dimensions are limited: only ask about type, name, effects, values, and appearance; do not ask about acquisition methods, crafting, planting, enchanting, or other content ModSmith does not generate.
  • Do not answer technical questions: if the user asks "how many hearts" or "what acquisition methods are there," briefly acknowledge and steer back to requirements.
  • Do not fabricate out-of-scope content: do not design planting steps or crafting recipes.
  • End with a fixed format: mark with 【需求摘要】 (Requirements Summary) for easy frontend extraction.
  • Answer style: Simplified Chinese, conversational, 3-4 sentences, no technical jargon, no code blocks.
  • Support multi-turn conversation (history parameter); CLI interactive mode supports /quit, /clear, /history.

Task 16: Implement Mode Routing and Frontend Integration

Corresponding document: 3.16 Implement Mode Routing and Frontend Integration.md

Goal: Support both Chat and Execute modes in the Web UI with tab switching; open Chat by default; after a Chat conversation ends, generate a requirements summary in one click and switch to Execute to generate the mod.

Key outputs:

  • Add four endpoints in modsmith/web/app.py: /api/chat, /api/chat/stream/{session_id}, /api/chat/clear, /api/chat/summarize
  • Add mode-switching tabs in index.html (Chat first, Execute second), with Chat open by default
  • Chat UI: message bubbles, input box, send button, quick chips, clear button, organize-requirements button
  • summarizeToExecute() calls the backend summary endpoint and fills the result into the Execute description box

Notes:

  • CHAT_SESSIONS in-memory storage is completely independent from TASKS.
  • Chat supports SSE streaming output (typewriter effect).
  • Chat history is persisted with localStorage, restored after refresh, and remains on the Chat tab.
  • /api/chat/summarize first extracts the 【需求摘要】 marker, with LLM rewrite as fallback.
  • If the summary is empty or "not specified," prompt the user to continue the conversation instead of generating a junk description.
  • Mode switching does not lose existing Execute results.
  • The default tab is Chat: currentMode = 'chat', and DOMContentLoaded explicitly calls switchMode('chat', ...).
  • Tab order: Concept Q&A (Chat) → Generate Mod (Execute).

Future Extensions

  • Support more item types (blocks, armor, entities)
  • Add fuel support (waiting for a stable Fabric API solution on 26.2+)
  • Change /api/auto_verify to an async task + SSE progress push
  • True streaming output for Chat (calling Zhipu API's streaming endpoint)
  • Persist Chat conversations to SQLite so they survive service restarts
  • Multi-item requirements: describe multiple items in one conversation and clarify them one by one
  • Multi-user concurrency and task history
  • Publish to PyPI
  • Integrate more LLM backends

End of task list. Execute in order; commit to Git after each completed task to keep it rollback-friendly. Record and resolve issues as they arise.

Clone this wiki locally