FoundryVTT/README.md

Foundry VTT + Pathfinder 1e Development Environment

A complete development environment for creating custom macros and automating Foundry VTT with Pathfinder 1e

Version: 1.0.0 | Last Updated: 2025-01-30 | Repository: Gitea

---

🎯 Quick Start

New to this project? Start here: QUICKSTART.md (5-minute read)

Need complete details? See: CLAUDE.md (comprehensive project guide)

---

📋 What This Project Includes

This is a professional development environment for Foundry VTT + Pathfinder 1e that combines:

Core Components

✅ Foundry VTT v11.315

• Complete Electron-based virtual tabletop platform
• Express.js server backend with NeDB database
• PIXI.js canvas rendering system
• Socket.io real-time multiplayer support

✅ Pathfinder 1e System v10.8

• Full PF1 game rules implementation
• Character sheets and NPC templates
• Spell and feat compendiums
• Automated action resolution system
• Built with Vite + ES Modules + TypeScript

✅ Custom Macros & Automation

• Arcane Pool enhancement system (Magus class feature)
• Haste buff automation with attack interception
• Reusable macro patterns and templates
• Dialog-based user interfaces

✅ AI-Assisted Development

• Claude Code integration with 8 MCP servers
• Semantic code navigation (Serena)
• Complex problem solving (Sequential Thinking)
• Real-time library documentation (Context7)
• Persistent project memory (Knowledge Graph)

---

🚀 Getting Started

1. Prerequisites

• Foundry VTT License (required to download official builds)
• Node.js v16-19 (for PF1 system development)
• npm (Node Package Manager)
• Git (version control)
• Visual Studio Code (recommended IDE)

2. Initial Setup

# Navigate to project root
cd "C:\DEV\Foundry2\Foundry_VTT"

# Install PF1 system dependencies
cd src/foundryvtt-pathfinder1-v10.8
npm install

# Build the PF1 system
npm run build

# Or use watch mode for development
npm run build:watch

3. Running Foundry VTT

# Option 1: Run Foundry directly
cd src/FoundryVTT-11.315
.\foundryvtt.exe

# Option 2: Launch via Node.js
node resources/app/main.js

4. Creating & Using Macros

1. Open Foundry VTT
2. Click "Macro Directory" in the sidebar
3. Create a new macro (type: Script)
4. Copy content from src/macro.js or src/macro_haste.js
5. Save and drag to hotbar

---

📁 Project Structure

Foundry_VTT/
├── src/
│   ├── FoundryVTT-11.315/           # Foundry core application
│   │   ├── resources/app/           # Electron app resources
│   │   ├── node_modules/            # Foundry dependencies
│   │   └── Data/                    # User worlds & data (gitignored)
│   │
│   ├── foundryvtt-pathfinder1-v10.8/# PF1 system module
│   │   ├── module/                  # System source code (ES modules)
│   │   ├── packs/                   # Compendium databases
│   │   ├── public/system.json       # System manifest
│   │   ├── package.json             # Dev dependencies & scripts
│   │   └── vite.config.js           # Build configuration
│   │
│   ├── macro.js                     # Arcane Pool macro
│   ├── macro_haste.js               # Haste automation macro
│   └── zeratal.json                 # Example character data
│
├── CLAUDE.md                        # Complete project documentation
├── QUICKSTART.md                    # Quick start guide
├── README.md                        # This file
├── .claude/                         # Claude Code configuration
├── .mcp.json                        # MCP servers configuration
└── .git/                            # Git repository

See CLAUDE.md for detailed project structure and file descriptions.

---

🛠️ Development Workflow

Building the PF1 System

cd src/foundryvtt-pathfinder1-v10.8

# Production build
npm run build

# Development build with hot reload
npm run build:watch

# Lint code
npm run lint

# Format code
npm run format

Creating a New Macro

All macros follow the IIFE (Immediately Invoked Function Expression) pattern:

(async () => {
  // 1. Validation
  if (!token) {
    ui.notifications.warn("You must select a token!");
    return;
  }

  // 2. Data access
  const actor = token.actor;
  const arcanePool = actor.system.resources.classFeat_arcanePool;

  // 3. Business logic
  async function doSomething() {
    // Implementation
  }

  // 4. Execute
  await doSomething();

  // 5. User feedback
  ui.notifications.info("Done!");
})();

See CLAUDE.md § Macro Development Patterns for detailed macro examples.

Debugging Macros

Press F12 to open browser console:

• Use Console tab for logs and errors
• Use Network tab for API calls
• Add console.log() for debugging
• Check error messages in notifications

Testing Changes

1. Make changes to PF1 system or macros
2. Run npm run build to rebuild
3. Reload Foundry VTT (F5)
4. Test macros or features
5. Check console (F12) for errors

---

📚 Documentation

Document	Purpose	Read Time
CLAUDE.md	Complete project guide & API reference	30 min
QUICKSTART.md	Quick start setup guide	5 min
Manual_dmgtracking.md	Damage tracking implementation	Reference
ARCANE_POOL_ANALYSIS.md	Arcane Pool macro analysis	Reference

---

🎮 Foundry VTT & PF1 API

Global Objects (Available in Macros)

game                        // Main game instance
game.actors                 // Actor collection
game.items                  // Item collection
game.scenes                 // Scene collection
game.macros                 // Macro collection
game.settings               // Settings registry

ui                          // UI manager
ui.notifications            // Toast notifications
ui.chat                     // Chat sidebar

canvas                      // Canvas rendering system
CONFIG                      // Global configuration
CONFIG.PF1                  // PF1-specific config

Common API Patterns

// Get documents
const actor = game.actors.get(actorId);
const item = game.items.getName("Item Name");
const doc = fromUuidSync("Actor.abc123.Item.def456");

// Update documents
await actor.update({
  "system.hp.value": 50,
  "system.attributes.ac.total": 25
});

// Find items
const buffs = actor.items.filter(i => i.type === "buff");
const haste = actor.items.find(i => i.name === "Haste");

// Use hooks
Hooks.on("updateActor", (actor, change, options, userId) => {
  console.log(`${actor.name} was updated`);
});

See CLAUDE.md § Foundry VTT API Reference for complete API documentation.

---

🔧 Git Workflow

Check Status

git status          # Show working tree status
git log --oneline   # Show recent commits
git diff            # Show unstaged changes

Make Changes

# Create feature branch
git checkout -b feature/my-feature

# Make changes...

# Commit
git add src/
git commit -m "feat(macro): add new feature"

# Push
git push -u origin feature/my-feature

Commit Message Format

Follow Conventional Commits:

<type>(<scope>): <subject>

<body>

<footer>

Types: feat, fix, docs, refactor, test, chore, style Scopes: macro, system, core, config, docs

Examples:

feat(macro): add arcane pool enhancement UI
fix(system): correct haste buff duration
docs(readme): update setup instructions

---

🐛 Troubleshooting

Foundry Won't Start

# Check logs in Data/Logs/
cat "src/FoundryVTT-11.315/Data/Logs/foundry.log"

# Try running directly
cd src/FoundryVTT-11.315
node resources/app/main.js

Macro Not Working

1. Check token selection: Click a token on the canvas
2. Check console (F12): Look for error messages
3. Verify actor exists: console.log(token.actor)
4. Check syntax: Paste into browser console
5. Clear cache: Hard refresh (Ctrl+Shift+R)

Build Failures

cd src/foundryvtt-pathfinder1-v10.8

# Clean and rebuild
rm -r dist node_modules
npm install
npm run build

Git Issues

# Reset to last commit (discard changes)
git reset --hard HEAD

# Pull latest changes
git pull origin main

# Check remote
git remote -v

---

🎯 Common Tasks

Add a New Macro

1. Create src/macro_myfeature.js
2. Follow IIFE pattern (see examples)
3. Test in Foundry VTT
4. Commit: git add src/macro_myfeature.js && git commit -m "feat(macro): add myfeature"

Modify PF1 System

1. Edit files in src/foundryvtt-pathfinder1-v10.8/module/
2. Run npm run build:watch
3. Reload Foundry VTT (F5)
4. Test changes
5. Commit: git add src/foundryvtt-pathfinder1-v10.8/ && git commit -m "feat(system): describe change"

Add Compendium Content

1. Extract packs: npm run packs:extract
2. Edit JSON files
3. Compile packs: npm run packs:compile
4. Commit changes

---

📖 Resources

Official Documentation

• Foundry VTT API v11: https://foundryvtt.com/api/v11/
• Foundry VTT Docs: https://foundryvtt.com/kb/
• PF1 System GitHub: https://github.com/Furyspark/foundryvtt-pathfinder1

Project Documentation

• CLAUDE.md - Complete project guide (technology stack, API reference, configuration)
• QUICKSTART.md - Setup and first steps
• ARCANE_POOL_ANALYSIS.md - Arcane Pool macro implementation
• Manual_dmgtracking.md - Damage tracking system

Community

• Foundry VTT Discord: https://discord.gg/foundryvtt
• Foundry VTT Reddit: https://reddit.com/r/FoundryVTT
• PF1 System Issues: https://github.com/Furyspark/foundryvtt-pathfinder1/issues

---

🤝 Contributing

Code Style

• Use camelCase for variables and functions
• Use PascalCase for classes
• Use UPPER_SNAKE_CASE for constants
• Follow ESLint rules: npm run lint
• Format code: npm run format

Before Committing

# Lint and format
npm run lint
npm run format

# Build to check for errors
npm run build

# Commit
git add .
git commit -m "feat(...): description"
git push

---

📊 Project Statistics

• Foundry VTT Version: v11.315
• PF1 System Version: v10.8
• Runtime: Node.js v16-19 (Electron)
• Languages: JavaScript (ES6+), TypeScript definitions
• Repository: https://gitea.gowlershome.dyndns.org/Gowler/FoundryVTT.git

---

📝 Version History

• v1.0.0 (2025-01-30) - Initial project setup with Foundry VTT v11.315 and PF1e v10.8

---

🎓 Learning Path

Day 1: Setup

1. Read QUICKSTART.md
2. Install dependencies
3. Build PF1 system
4. Launch Foundry VTT

Week 1: Basics

1. Create a simple macro
2. Test macro in game
3. Understand actor/item API
4. Explore Foundry console (F12)

Month 1: Advanced

1. Build complex macros with dialogs
2. Modify PF1 system code
3. Add compendium content
4. Integrate Claude Code for automation

---

💬 Questions?

• Check CLAUDE.md for detailed documentation
• See QUICKSTART.md for setup help
• Review macro examples: src/macro.js, src/macro_haste.js
• Check browser console (F12) for errors

---

Ready to start? → QUICKSTART.md

Need details? → CLAUDE.md

Have questions? Check the troubleshooting section above.