FoundryVTT/QUICKSTART.md

# Foundry VTT + Pathfinder 1e Quick Start Guide

> **Get started with Foundry VTT development in 5 minutes**
>
> **Version**: 1.0.0 | **Last Updated**: 2025-01-30

---

## 🚀 What You'll Do in 5 Minutes

1. Install PF1 system dependencies (**1 min**)
2. Build the PF1 system (**2 min**)
3. Launch Foundry VTT (**1 min**)
4. Create and test a macro (**1 min**)

---

## Step 1: Install Dependencies (1 minute)

```bash
# Navigate to PF1 system directory
cd src/foundryvtt-pathfinder1-v10.8

# Install npm packages
npm install
```

✅ **Done!** Dependencies are installed.

---

## Step 2: Build the PF1 System (2 minutes)

```bash
# Still in src/foundryvtt-pathfinder1-v10.8

# Production build (one-time)
npm run build

# OR for development (watches for changes)
npm run build:watch
```

✅ **Done!** System is built and ready.

---

## Step 3: Launch Foundry VTT (1 minute)

### Option A: Run Executable (Recommended)

```bash
# Navigate to Foundry directory
cd ../FoundryVTT-11.315

# Run Foundry (Windows)
.\foundryvtt.exe

# Or double-click foundryvtt.exe in File Explorer
```

### Option B: Run via Node.js

```bash
cd src/FoundryVTT-11.315
node resources/app/main.js
```

✅ **Done!** Foundry VTT is running.

---

## Step 4: Test a Macro (1 minute)

### Create & Import Arcane Pool Macro

1. Open Foundry VTT in browser (usually http://localhost:30000)
2. Create or open a world
3. Click **Macro Directory** in the sidebar
4. Click **Create Macro**
5. Set **Macro Type** to "Script"
6. Copy content from `src/macro.js`
7. Click **Save Macro**
8. Drag macro to hotbar

### Test the Macro

1. Select a token on the canvas (any character)
2. Click the macro on the hotbar
3. You should see a notification or dialog

✅ **Done!** Your first macro works!

---

## 📚 Next Steps (10-30 minutes)

### Option A: Build a Custom Macro

1. Open browser console (F12)
2. Try simple commands:
   ```javascript
   // Get current token's actor
   console.log(token.actor.name);

   // Get actor's HP
   console.log(token.actor.system.attributes.hp);

   // Get Arcane Pool resource
   console.log(token.actor.system.resources.classFeat_arcanePool);
   ```

3. Create `src/macro_mytest.js`:
   ```javascript
   (async () => {
     if (!token) {
       ui.notifications.warn("Select a token!");
       return;
     }

     const actor = token.actor;
     ui.notifications.info(`Selected: ${actor.name}`);
   })();
   ```

4. Import macro in Foundry and test

### Option B: Modify the PF1 System

1. Edit a file in `src/foundryvtt-pathfinder1-v10.8/module/`
2. Run `npm run build` (already running in watch mode)
3. Reload Foundry (F5)
4. Test your change

### Option C: Explore the Code

1. Read [CLAUDE.md](CLAUDE.md) for complete documentation
2. Check out macro examples: `src/macro.js`, `src/macro_haste.js`
3. Review PF1 system structure: `src/foundryvtt-pathfinder1-v10.8/module/`

---

## 🔧 Common Commands

```bash
# Build PF1 system
npm run build

# Development mode (auto-rebuild)
npm run build:watch

# Lint code
npm run lint

# Format code
npm run format

# Extract compendium packs
npm run packs:extract

# Compile compendium packs
npm run packs:compile
```

---

## 🎮 Foundry VTT Basics

### Global Objects Available in Macros

```javascript
game.actors              // All actors
game.items              // All items
game.macros             // All macros
game.scenes             // All scenes
ui.notifications        // Toast notifications
canvas                  // Canvas/rendering
```

### Common Macro Pattern

```javascript
(async () => {
  // 1. Validate
  if (!token) {
    ui.notifications.warn("Select a token!");
    return;
  }

  // 2. Get data
  const actor = token.actor;
  const hp = actor.system.attributes.hp;

  // 3. Do something
  await actor.update({
    "system.attributes.hp.value": hp.value - 10
  });

  // 4. Feedback
  ui.notifications.info("Damage applied!");
})();
```

---

## 🐛 Troubleshooting

### Macro Not Working?

```javascript
// Check browser console (F12)
console.log(token);           // Is token selected?
console.log(token.actor);     // Does actor exist?
console.log(actor.system);    // What data is available?
```

### Build Failed?

```bash
# Clean and rebuild
cd src/foundryvtt-pathfinder1-v10.8
rm -r dist node_modules
npm install
npm run build
```

### Foundry Won't Start?

```bash
# Check logs
cat src/FoundryVTT-11.315/Data/Logs/foundry.log

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

### Port Already in Use?

Foundry defaults to port 30000. If in use:
```bash
# Find process using port
netstat -ano | findstr :30000

# Kill process (Windows)
taskkill /PID <PID> /F
```

---

## 📖 Documentation

| Document | Purpose | Read Time |
|----------|---------|-----------|
| **[README.md](README.md)** | Project overview & setup | 10 min |
| **[CLAUDE.md](CLAUDE.md)** | Complete technical documentation | 30 min |
| **Foundry API** | https://foundryvtt.com/api/v11/ | Reference |
| **PF1 GitHub** | https://github.com/Furyspark/foundryvtt-pathfinder1 | Reference |

---

## 🎯 Success Checklist

After this quickstart, you should be able to:

- [x] Install and build PF1 system
- [x] Launch Foundry VTT
- [x] Create a macro
- [x] Execute a macro in-game
- [x] Access browser console (F12)
- [x] Modify macro code
- [x] Understand basic actor/item API

---

## 🎓 Learn More

### Beginner Topics
- Creating your first macro
- Understanding actor/item structure
- Using the browser console

### Intermediate Topics
- Dialog-based user interfaces
- Buff management systems
- Macro chaining

### Advanced Topics
- Modifying PF1 system code
- Adding compendium content
- Integrating Claude Code automation

See [CLAUDE.md](CLAUDE.md) for detailed tutorials on all topics.

---

## 💡 Quick Tips

1. **Always select a token** - Most macros require a token to be selected
2. **Use F12 for debugging** - Browser console shows errors and logs
3. **F5 reloads Foundry** - Refresh after system changes
4. **Check notification** - Macros often provide user feedback via notifications
5. **Save often** - Macros are stored in Foundry's database

---

## 🆘 Need Help?

1. **Check [CLAUDE.md](CLAUDE.md)** - Complete documentation
2. **Review examples** - `src/macro.js`, `src/macro_haste.js`
3. **Browser console (F12)** - Error messages and debugging
4. **Foundry logs** - `src/FoundryVTT-11.315/Data/Logs/foundry.log`

---

## ✅ Ready to Continue?

**Next steps:**
1. Try modifying the Arcane Pool macro
2. Create your own custom macro
3. Read [CLAUDE.md](CLAUDE.md) for advanced topics
4. Explore PF1 system code

---

**Questions?** Check [README.md](README.md) or [CLAUDE.md](CLAUDE.md)