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)

# 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)

# 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)

# 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

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:

   // 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:

   (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 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

# 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

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

(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?

// 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?

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

Foundry Won't Start?

# 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:

# Find process using port
netstat -ano | findstr :30000

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

---

📖 Documentation

Document	Purpose	Read Time
README.md	Project overview & setup	10 min
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:

• Install and build PF1 system
• Launch Foundry VTT
• Create a macro
• Execute a macro in-game
• Access browser console (F12)
• Modify macro code
• 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 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 - 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 for advanced topics
4. Explore PF1 system code

---

Questions? Check README.md or CLAUDE.md