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](https://gitea.gowlershome.dyndns.org/Gowler/FoundryVTT.git)

---

## 🎯 Quick Start

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

**Need complete details?** See: **[CLAUDE.md](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

```bash
# 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

```bash
# 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](CLAUDE.md) for detailed project structure and file descriptions.**

---

## 🛠️ Development Workflow

### Building the PF1 System

```bash
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:

```javascript
(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](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](CLAUDE.md)** | Complete project guide & API reference | 30 min |
| **[QUICKSTART.md](QUICKSTART.md)** | Quick start setup guide | 5 min |
| **[Manual_dmgtracking.md](Manual_dmgtracking.md)** | Damage tracking implementation | Reference |
| **[ARCANE_POOL_ANALYSIS.md](ARCANE_POOL_ANALYSIS.md)** | Arcane Pool macro analysis | Reference |

---

## 🎮 Foundry VTT & PF1 API

### Global Objects (Available in Macros)

```javascript
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

```javascript
// 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](CLAUDE.md#foundry-vtt-api-reference) for complete API documentation.**

---

## 🔧 Git Workflow

### Check Status

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

### Make Changes

```bash
# 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](https://www.conventionalcommits.org/):

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

<body>

<footer>
```

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

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

---

## 🐛 Troubleshooting

### Foundry Won't Start

```bash
# 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

```bash
cd src/foundryvtt-pathfinder1-v10.8

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

### Git Issues

```bash
# 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](CLAUDE.md)** - Complete project guide (technology stack, API reference, configuration)
- **[QUICKSTART.md](QUICKSTART.md)** - Setup and first steps
- **[ARCANE_POOL_ANALYSIS.md](ARCANE_POOL_ANALYSIS.md)** - Arcane Pool macro implementation
- **[Manual_dmgtracking.md](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

```bash
# 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](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](CLAUDE.md) for detailed documentation
- See [QUICKSTART.md](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](QUICKSTART.md)**

**Need details?** → **[CLAUDE.md](CLAUDE.md)**

**Have questions?** Check the troubleshooting section above.