Hearthbound — BMAD-Inspired Project Documentation Pack

Hearthbound is a Minecraft Java NeoForge 1.21.1 medieval Vanilla+ colony mod concept.

It is inspired by the colony fantasy of MineColonies, but its core improvement is freeform player-built settlements: players build structures freely, then Hearthbound evaluates them through functional requirements, rooms, tags, quality scores, citizen needs, jobs, and templates.

This repository is currently in the vision and planning phase. No implementation should begin until the project artifacts are read and a scoped MVP is selected.

Root Files

• README.md — entry point and pack overview.
• CLAUDE.md — AI agent operating instructions.
• CODE_STYLEGUIDE.md — Java / NeoForge code quality rules.
• DOCUMENT_MANIFEST.md — document index and reading order.
• CHANGELOG.md — documentation pack change history.

All long design documents are in docs/.

Project Name

The project is named Hearthbound.

Do not use the old working name Freeform Colonies in code, documentation, package names, mod metadata, IDs, commits, or prompts.

Core Vision

Hearthbound is a modular medieval Vanilla+ colony mod where custom human citizens live, eat, work, rest, complain, and progress inside player-built freeform settlements. Buildings are declared by huts, selected through zones, validated through required blocks, evaluated through data-driven tags and profiles, and preserved or restored through survival-based templates and Builders.

Primary Design Loop

Town Hall
→ starting custom citizens
→ homeless citizens shelter at Town Hall
→ player builds Residential Huts
→ player manually defines Rooms
→ citizens are assigned to Rooms
→ room quality affects happiness, rest, job eligibility, and efficiency
→ player assigns jobs through Work Huts
→ citizens need tools, food, work buildings, and schedules
→ Cookhouse / Tavern handles meals
→ Builder builds, repairs, copies, demolishes, and clears using real resources
→ Storage / requests / logistics support the settlement

Technical Target

• Minecraft Java: 1.21.1
• Mod loader: NeoForge 1.21.1
• Build system: NeoGradle Userdev
• Dedicated server support: mandatory
• Architecture: server-authoritative
• Content architecture: hybrid modular
  • Java registries/providers for behavior
  • JSON/datapack definitions for profiles and balance
  • tags for block compatibility
  • server config for difficulty and tuning

First Reading Order

1. CLAUDE.md
2. CODE_STYLEGUIDE.md
3. DOCUMENT_MANIFEST.md
4. docs/00_vision_and_project_brief.md
5. docs/01_product_requirements_document.md
6. docs/02_project_constitution.md
7. docs/05_modularity_and_extension_architecture.md
8. docs/06_technical_architecture_neoforge_1_21_1.md
9. docs/21_mvp_roadmap_epics_stories.md

Documentation Philosophy

This pack is BMAD-inspired: it separates vision, product requirements, architecture, UX, implementation guardrails, QA gates, and stories so AI agents do not rely on scattered chat history.