Hearthbound

A living world where every soul remembers

A Valheim-style open world RPG with AI-powered NPCs using Claude API, built in Godot with Cursor IDE.

🔥 About Hearthbound

Hearthbound is a session-based RPG where NPCs have daily routines, memories, and personalities powered by Claude AI. Explore a realistic low-poly world of villages, forests, mountains, and seas. Every conversation matters. Every quest has consequences. Every session tells a new story.

🚀 Quick Start

Prerequisites

1. Godot 4.3+ - Download from https://godotengine.org/download/
2. Cursor IDE - Download from https://cursor.com/
3. Anthropic API Key - Get from https://console.anthropic.com/

Setup (5 minutes)

1. Open in Cursor:

   cd Hearthbound
   cursor .

2. Install Godot:

   • Download Godot 4.3
   • Extract to your system
   • Note the path (you'll need it)

3. Configure Cursor for Godot:

   • Open Cursor Settings (Cmd/Ctrl + ,)
   • Search for "Python Path" or create a task
   • Add Godot path for GDScript support

4. Add Your API Key:

   • Open scripts/managers/ai_manager.gd
   • Replace YOUR_API_KEY with your actual Anthropic API key
   • Or create .env file (see below)

5. Download Assets:

   • Follow instructions in docs/ASSET_DOWNLOAD_GUIDE.md
   • Download Quaternius packs (all FREE)
   • Place in models/ folder

6. Open Project in Godot:

   • Launch Godot
   • Click "Import"
   • Select project.godot in this folder
   • Click "Import & Edit"

📁 Project Structure

Hearthbound/
├── README.md                          # This file
├── project.godot                      # Godot project file
├── .cursorrules                       # Cursor AI configuration
├── .gitignore                         # Git ignore rules
│
├── docs/                              # All documentation
│   ├── ARCHITECTURE.md               # Game architecture
│   ├── VALHEIM_STYLE_ASSETS.md       # Asset guide
│   ├── COMPLETE_WORLD_ASSETS.md      # World building guide
│   ├── GODOT_SETUP_GUIDE.md          # Godot setup
│   ├── QUICK_REFERENCE.md            # Quick reference
│   └── CURSOR_WORKFLOW.md            # How to use Cursor
│
├── scenes/                            # Godot scenes
│   ├── main.tscn                     # Main game scene
│   ├── world/
│   │   ├── village.tscn              # Village area
│   │   └── forest.tscn               # Forest area
│   ├── characters/
│   │   ├── player.tscn               # Player
│   │   └── npcs/
│   │       ├── npc_base.tscn         # NPC template
│   │       ├── farmer.tscn           # Farmer NPC
│   │       └── bartender.tscn        # Bartender NPC
│   └── ui/
│       ├── dialogue.tscn             # Dialogue UI
│       └── quest_log.tscn            # Quest log UI
│
├── scripts/                           # GDScript files
│   ├── player.gd                     # Player controller
│   ├── npc.gd                        # NPC base class
│   ├── managers/
│   │   ├── game_manager.gd           # Game state
│   │   ├── quest_manager.gd          # Quest system
│   │   ├── time_manager.gd           # Day/night cycle
│   │   └── ai_manager.gd             # Claude API integration
│   └── data/
│       ├── npc_data.gd               # NPC definitions
│       └── quest_data.gd             # Quest templates
│
├── models/                            # 3D models (import here)
│   ├── characters/
│   ├── buildings/
│   ├── environment/
│   └── props/
│
├── materials/                         # Materials & shaders
│   └── water.gdshader                # Water shader
│
├── audio/                             # Sound effects & music
│
└── tests/                             # Test scenes
    └── test_ai.tscn                  # Test Claude API

🤖 Using Cursor + Claude Code

What is Cursor?

Cursor is an AI-powered code editor built on VS Code that integrates Claude directly into your workflow.

Two Ways to Use Claude:

1. Cursor's Built-in AI (Quick Edits)

• Cmd/Ctrl + K - Inline edit (select code, describe change)
• Cmd/Ctrl + L - AI chat (ask questions, get help)
• Perfect for: Quick fixes, explanations, small changes

2. Claude Code CLI (Complex Tasks)

• Run in terminal: claude-code
• Agentic coding assistant
• Reads .clinerules configuration
• Perfect for: Creating files, refactoring, complex features

See docs/CLAUDE_CODE_GUIDE.md for complete Claude Code tutorial!

1. Ask Claude to Generate Code:

   Cmd/Ctrl + K - Open inline AI edit
   Cmd/Ctrl + L - Open AI chat
   

2. Example Prompts:

   "Create a GDScript function to spawn NPCs in a circle around the tavern"
   
   "Add a quest system that tracks multiple objectives"
   
   "Write shader code for animated grass that responds to wind"
   
   "Create a day/night cycle system with dynamic lighting"
   

3. Claude Code Understands Context:

   • It knows you're using Godot
   • It knows the project structure
   • It follows GDScript conventions
   • It integrates with your existing code

4. Best Practices:

   • Keep .cursorrules file (tells Claude about your project)
   • Ask specific questions
   • Review generated code before running
   • Test one feature at a time

Cursor Features for Godot

• Code Completion: GDScript autocomplete
• Error Detection: Catch bugs before running
• Refactoring: Rename variables across files
• AI Chat: Ask questions about Godot API
• Multi-file Editing: Edit multiple scripts at once

📖 Documentation

Must-Read First:

1. CURSOR_WORKFLOW.md - How to use Cursor's built-in AI
2. CLAUDE_CODE_GUIDE.md - How to use Claude Code CLI (agentic coding)
3. GODOT_SETUP_GUIDE.md - Complete Godot setup
4. VALHEIM_STYLE_ASSETS.md - Download assets

Reference:

• ARCHITECTURE.md - Game systems design
• COMPLETE_WORLD_ASSETS.md - World building
• QUICK_REFERENCE.md - Quick lookup

🎮 Development Workflow

Day 1: Setup & First Scene

1. Download Quaternius Medieval Village pack
2. Import to models/buildings/
3. Create village.tscn in Godot
4. Place one building
5. Test (F5)

Day 2: Player & Movement

1. Use Cursor to generate player controller
2. Prompt: "Create a 3rd person player controller for Godot"
3. Test movement
4. Add camera follow

Day 3: First NPC

1. Create NPC scene
2. Use Cursor: "Add interaction system for NPCs"
3. Connect Claude API
4. Test dialogue

Week 1 Goal: Walking in village, talking to 1 NPC

🔧 Common Cursor Commands

Generate Code:

Cmd/Ctrl + K, then type:
"Generate a function that..."

Explain Code:

Select code, Cmd/Ctrl + L:
"What does this code do?"

Fix Errors:

Cmd/Ctrl + L:
"I'm getting this error: [paste error]"

Refactor:

Select code, Cmd/Ctrl + K:
"Refactor this to use signals instead"

🐛 Troubleshooting

Cursor Not Finding Godot:

• Install Godot extension for VS Code
• Add Godot to PATH

AI Not Understanding GDScript:

• Check .cursorrules file exists
• Be explicit: "In GDScript, create..."

Claude API Not Working:

• Check API key in ai_manager.gd
• Verify key has credits
• Check console for errors

Assets Not Showing:

• Ensure files are in correct folders
• Refresh Godot FileSystem (F5)
• Check file formats (.gltf or .fbx)

📚 Learning Resources

Godot:

• Official Docs: https://docs.godotengine.org/
• GDQuest: https://www.gdquest.com/

Cursor:

• Cursor Docs: https://cursor.com/docs
• Cursor Discord: https://discord.gg/cursor

Assets:

• Quaternius: https://quaternius.com/
• All assets are CC0 (free to use)

🎯 Milestones

• Week 1: Village scene + player movement + 1 NPC
• Week 2: Quest system + dialogue UI + 3 NPCs
• Week 3: Forest area + monster encounters
• Week 4: Time system + NPC routines
• Week 5: Combat system
• Week 6: Quest variety + polish
• Week 7: Co-op (optional)
• Week 8: Playtesting + balance

🚀 Next Steps

1. Read: docs/CURSOR_WORKFLOW.md
2. Setup: Follow Quick Start above
3. Download Assets: See docs/ASSET_DOWNLOAD_GUIDE.md
4. Start Coding: Open Cursor and ask Claude!

💡 Pro Tips

• Use Cursor chat for architecture questions
• Use inline edit (Cmd+K) for code generation
• Test frequently in Godot (F5)
• Commit to git after each feature
• Ask Claude to explain Godot concepts

🤝 Contributing

This is your project! Use Cursor + Claude Code to:

• Generate new features
• Refactor existing code
• Fix bugs
• Add content

📝 License

• Code: MIT (do whatever you want)
• Assets: CC0 from Quaternius (free to use)

🎉 You're Ready!

Open Cursor, start the Godot editor, and begin building your living world RPG!

Questions? Ask Claude in Cursor: Cmd/Ctrl + L