Learn AI development by playing a game! A fun, interactive JavaScript adventure that teaches you how to use Microsoft Foundry Local and AI tools, one level at a time.

No installation required! Play the web version directly in your browser:

👉 Play Foundry Learning Adventure 👈

The web version includes all 5 levels and works completely in your browser with simulated AI responses.

For the full AI experience, install Foundry Local. No port configuration needed. The CLI game uses the foundry-local-sdk npm package to discover, download, and load models automatically. The web game scans for the Foundry Local service on known ports.

# Install Foundry Local
winget install Microsoft.FoundryLocal

# CLI game: the SDK downloads and loads the model for you
cd game && npm install && npm start

• What is This Game?
• What You'll Learn
• Play Online (GitHub Pages)
• Quick Start
• Installation Guide
• How to Play
• Level Guide
• Game Screenshots
• Commands Reference
• Rewards & Badges
• Deploy to GitHub Pages
• Troubleshooting
• FAQ
• Project Structure
• Running Tests
• Contributing

The Foundry Local Learning Adventure is an educational game designed for complete beginners who want to learn about:

• 🤖 AI/ML Basics - How AI models work and respond
• 💬 Prompt Engineering - Writing effective prompts
• 🔍 Embeddings - How AI understands meaning
• ⚡ AI Workflows - Chaining operations together
• 🔧 Tool Building - Extending AI capabilities

You do not need any prior AI experience! Just follow along, complete challenges, and earn badges as you learn.

• 👨‍🎓 Students learning about AI
• 👩‍💻 Developers new to AI tools
• 🎨 Anyone curious about how AI works
• 📚 Educators teaching AI concepts

The web version runs entirely in your browser with no installation required:

• All 5 levels with interactive challenges
• Progress saved automatically (localStorage)
• Works on desktop, tablet, and mobile
• Starts in Demo Mode; connects to real Foundry Local automatically if installed
• Model selector dropdown lets you switch between available models
• Real-time connection status shows scanning, loading, and download progress

Tip for educators: Fork the repo, enable GitHub Pages, and share the link with your class. Students can start learning immediately with zero setup.

When you are ready for real AI interactions, try the CLI version with Foundry Local.

Choose how you want to play:

All three options start in Demo Mode (simulated AI). Install Foundry Local for real AI responses. The game discovers models automatically.

No installation required - play directly in your browser:

👉 Play Now 👈

Using startup scripts (easiest):

Windows (Batch):

cd game
scripts\start-web.bat

Windows (PowerShell):

cd game
powershell -ExecutionPolicy Bypass -File scripts\start-web.ps1

Mac/Linux:

cd game
chmod +x scripts/start-web.sh
./scripts/start-web.sh

Or manually start a server:

# Navigate to web folder
cd game/web

# Start a local server (choose one):
npx http-server -p 8080 -c-1
# OR
python -m http.server 8080
# OR
python3 -m http.server 8080

Then open http://localhost:8080 in your browser.

For real AI responses with Foundry Local:

1. Download or clone this repository

2. Navigate to the game folder

3. Run one of these options:

   Option A - Batch File (double-click):

   scripts\start-game.bat

   Option B - PowerShell (recommended):

   powershell -ExecutionPolicy Bypass -File scripts\start-game.ps1

4. Follow the on-screen prompts

5. Start playing!

# Clone the repository
git clone <repository-url>
cd game

# Make the script executable
chmod +x scripts/start-game.sh

# Run the game
./scripts/start-game.sh

cd game
npm install
npm start

Node.js is required to run this game. It is free and easy to install.

1. Visit nodejs.org
2. Download the LTS version (green button)
3. Run the installer
4. Click "Next" through all options
5. Restart your terminal after installing
6. Done! ✅

# Using Homebrew (recommended)
brew install node

# Or download from nodejs.org

sudo apt update
sudo apt install nodejs npm

Open a terminal/command prompt and type:

node --version

You should see something like v18.x.x or higher.

1. Click the green "Code" button on the repository page
2. Select "Download ZIP"
3. Extract to a folder you can easily find (e.g., Desktop)

git clone https://github.com/leestott/FoundryLocal-LearningAdventure.git
cd FoundryLocal-LearningAdventure

Open a terminal in the game folder:

cd game
npm install

This downloads all required packages. You only need to do this once.

The game works without Foundry Local (in demo mode), but for the full AI experience:

winget install Microsoft.FoundryLocal

The CLI game uses the foundry-local-sdk to discover, download, and load models automatically. You do not need to start a model manually:

cd game
npm install
npm start

The SDK will find available models, download any that are missing, and load the best one for you.

Windows (Batch):

cd game
scripts\start-game.bat

Windows (PowerShell):

cd game
powershell -ExecutionPolicy Bypass -File scripts\start-game.ps1

Mac/Linux:

cd game
chmod +x scripts/start-game.sh
./scripts/start-game.sh

npm start

When you start the game, you will see a welcome screen:

╔══════════════════════════════════════════════════════════════════╗
║     🎮 FOUNDRY LOCAL LEARNING ADVENTURE 🎮                       ║
║                                                                  ║
║     Master Microsoft Foundry AI - One Level at a Time!           ║
╚══════════════════════════════════════════════════════════════════╝

1. Start a level: Type play 1 to start Level 1
2. Follow instructions: Each level explains what to do
3. Complete the task: Try the challenge
4. Get help if stuck: Type hint for tips
5. Earn rewards: Complete levels to unlock badges!

Throughout the game, Sage will guide you:

• 📖 Introduces each level
• 💡 Provides helpful hints
• ❓ Answers your questions
• 🎉 Celebrates your wins!

Type ask [your question] anytime to chat with Sage.

What you will do: Send your first message to an AI and get a response.

What you will learn:

• How AI models communicate
• The request/response pattern
• What happens when you call an AI

Example:

Your prompt: Hello! Please introduce yourself.

Tips:

• Just type a friendly greeting
• Watch how the AI responds
• There is no wrong answer here!

Badge Earned: 🎯 Prompt Apprentice (100 points)

What you will do: Improve a poorly written prompt and compare results.

What you will learn:

• Why prompt quality matters
• How to be specific and clear
• The difference good prompts make

The Challenge:

Bad prompt:  "tell me stuff about coding"
Your task:   Write a better version!

Tips:

• Be specific (what topic? what language?)
• Add context (your skill level, format wanted)
• Ask for examples

Badge Earned: ✍️ Prompt Engineer (150 points)

What you will do: Search a knowledge base using semantic similarity.

What you will learn:

• How AI understands meaning (not just keywords)
• What embeddings are and how they work
• How semantic search finds related content

Example:

Your query: "How do I run AI offline?"
Result: Finds content about Foundry Local's offline capabilities

Tips:

• Think about meaning, not exact words
• Try different ways of asking the same thing
• See how similar concepts connect

Badge Earned: 🔍 Embedding Explorer (200 points)

What you will do: Build a 3-step AI pipeline that processes text.

What you will learn:

• How to chain AI operations together
• Passing output from one step to the next
• Automating complex multi-step tasks

The Pipeline:

Step 1: Summarize text
    ↓
Step 2: Extract keywords
    ↓
Step 3: Generate questions

Tips:

• Watch how each step uses the previous output
• Think about other workflows you could build
• This is how real AI applications work!

Badge Earned: ⚡ Workflow Wizard (250 points)

What you will do: Create a JavaScript function and let AI use it.

What you will learn:

• What AI tools/functions are
• How agents call external code
• Extending what AI can do

Example Tool:

// A simple calculator tool
function add_numbers(a, b) {
    return a + b;
}

Tips:

• Keep your function simple
• Add clear descriptions
• The AI will learn to call your tool!

Badge Earned: 🏆 Foundry Champion (300 points)

When you first open the game, you will see a friendly welcome screen:

After entering your name, choose from 5 progressive levels:

Your first interaction with an AI model:

Watch the AI respond to your prompts in real-time:

Get help anytime from Sage, your friendly mentor:

Stuck? Use hints to guide your learning:

Track your points, badges, and completion status:

Earn badges as you master each concept:

Note: Screenshots are captured automatically using Playwright. The terminal version has similar functionality with a text-based interface.

See the game in action with our walkthrough videos:

• Desktop Walkthrough: Full game experience (1280×720)
• Mobile Walkthrough: Mobile-responsive view (375×812)

• 👣 First Steps - Complete your first level
• 🌟 Halfway Hero - Complete 50% of levels
• ⚡ Speed Learner - Complete a level in under 5 minutes
• 🧠 Hint-Free Hero - Complete without using hints
• ❓ Curious Mind - Ask 10 questions
• 🎓 Master Graduate - Complete everything!

Deploy your own copy of the game to GitHub Pages for free hosting!

1. Fork this repository to your GitHub account

2. Enable GitHub Pages:

   • Go to your repo's Settings → Pages
   • Source: Select GitHub Actions

3. Push to main branch - deployment happens automatically!

4. Access your game at: https://YOUR-USERNAME.github.io/FoundryLocal-LearningAdventure/

1. Fork this repository

2. Enable GitHub Pages:

   • Go to Settings → Pages
   • Source: Deploy from a branch
   • Branch: main
   • Folder: /game/web

3. Wait 2-3 minutes for deployment

4. Visit https://YOUR-USERNAME.github.io/FoundryLocal-LearningAdventure/

Local testing: See the Quick Start section for running the web version on your machine.

What happened: Node.js is not installed or is not in your PATH.

Fix:

1. Download Node.js from nodejs.org
2. Choose the LTS version
3. Run the installer (accept defaults)
4. Close and reopen your terminal
5. Try again

What happened: The game cannot connect to Foundry Local.

This is fine! The game will work in "demo mode" with simulated responses.

To enable full AI:

1. Install Foundry Local: winget install Microsoft.FoundryLocal
2. Run npm start in the game folder
3. The SDK will discover, download, and load a model automatically

Note: The CLI game uses the foundry-local-sdk npm package, which manages the Foundry Local service lifecycle (starting, model loading) internally. You do not need to start a model or configure a port manually. The web version scans common ports (61341, 5272, 51319, 5000, 8080) to find the running service.

What happened: Dependencies are not installed.

Fix:

cd game
npm install
npm start

What happened: The game cannot write to the progress file.

Fix:

• Use quit command to exit (not Ctrl+C)
• Check that data/progress.json exists
• Make sure you have write permission
• Try: npm run reset to create a fresh progress file

What happened: The AI call is taking a while.

Fix:

• Wait 10 to 15 seconds (AI can be slow)
• If using Foundry Local, check it is still running
• Press Ctrl+C to cancel and try again
• The game will use demo mode if AI is unavailable

No! The game teaches concepts through interaction. You will learn as you go.

No! Everything runs on your computer. That is what "Local" means.

No! The game has a demo mode. But you will get better responses with it.

No, levels unlock in order. Each one builds on previous concepts.

Most people finish in 1 to 2 hours. Take your time and enjoy!

No problem! That is how you learn. Use hint or ask for help.

Yes! Type play [number] to replay any completed level.

Type reset in the game, or run npm run reset.

FoundryLocal-LearningAdventure/
├── README.md               # This file!
├── AGENTS.md               # AI agent conventions
├── changelog.md            # Version history
├── LICENSE                 # MIT Licence
├── CONTRIBUTING.md         # Contribution guidelines
├── SECURITY.md             # Security policy
├── .gitignore              # Git ignore rules
├── .github/                # GitHub configuration
│   └── workflows/          # CI/CD workflows
│       ├── deploy.yml      # GitHub Pages deployment
│       └── test.yml        # Automated testing
└── game/                   # Game source code
    ├── src/                # Source code (Node.js version)
    │   ├── game.js         # Main game engine (uses foundry-local-sdk)
    │   ├── levels.js       # Level management and tasks
    │   └── mentor.js       # AI mentor (Sage)
    ├── web/                # Web version (GitHub Pages)
    │   ├── index.html      # Main HTML page
    │   ├── styles.css      # Game styling
    │   ├── game-web.js     # Web game engine
    │   └── game-data.js    # Levels, rewards, mentor data
    ├── data/               # Game data (JSON)
    │   ├── levels.json     # Level definitions
    │   ├── rewards.json    # Badges and achievements
    │   └── progress.json   # Your saved progress
    ├── screenshots/        # Game screenshots
    ├── tests/              # Test files
    ├── scripts/            # All startup scripts
    │   ├── start-game.bat  # Windows CLI launcher
    │   ├── start-game.ps1  # PowerShell CLI launcher
    │   ├── start-game.sh   # Mac/Linux CLI launcher
    │   ├── start-web.bat   # Windows Web launcher
    │   ├── start-web.ps1   # PowerShell Web launcher
    │   └── start-web.sh    # Mac/Linux Web launcher
    ├── config.json         # Settings
    └── package.json        # Node.js configuration (includes foundry-local-sdk)

Make sure everything is working:

# Run all tests
npm test

# Check Foundry Local status (Windows)
npm run test:foundry

# Reset your progress
npm run reset

Capture screenshots automatically using Playwright:

# Navigate to game folder
cd game

# Install Playwright (first time only)
npm run test:install

# Capture all screenshots
npm run test:screenshots

Screenshots are saved to game/screenshots/.

Test output shows:

• ✅ Passed tests (green)
• ❌ Failed tests (red)
• ⏭️ Skipped tests (yellow - usually means Foundry Local not running)

Edit config.json to customise:

{
  "foundryLocal": {
    "defaultModel": "Phi-3.5-mini-instruct-generic-cpu:1",
    "sdkAppName": "FoundryLearningAdventure",
    "sdkLogLevel": "warn"
  },
  "azureFoundry": {
    "enabled": false,
    "endpoint": "https://YOUR-RESOURCE.openai.azure.com",
    "apiKey": "YOUR-API-KEY",
    "apiVersion": "2024-02-01",
    "deploymentName": "gpt-4o-mini"
  },
  "game": {
    "maxHintsPerLevel": 3,
    "demoModeEnabled": true
  }
}

The game automatically detects available AI services:

To use Azure OpenAI instead of local models:

1. Create an Azure OpenAI resource at Azure Portal
2. Deploy a model (e.g., gpt-4o-mini)
3. Update config.json:

   {
     "azureFoundry": {
       "enabled": true,
       "endpoint": "https://your-resource.openai.azure.com",
       "apiKey": "your-api-key",
       "deploymentName": "gpt-4o-mini"
     }
   }

4. Run the game - it will connect to Azure!

• Different model: Change defaultModel to your preferred model alias
• More hints: Increase maxHintsPerLevel
• SDK logging: Set sdkLogLevel to "info" or "debug" for more detailed output

We welcome contributions! Here is how:

1. Fork the repository
2. Create a branch: git checkout -b my-feature
3. Make your changes
4. Test: npm test
5. Commit: git commit -m "Add my feature"
6. Push: git push origin my-feature
7. Open a Pull Request

• 🆕 New levels teaching more concepts
• 🌍 Translations to other languages
• 🎨 Visual/UX improvements
• 🐛 Bug fixes
• 📖 Documentation improvements
• 🧪 More tests

• Foundry Local Documentation
• Prompt Engineering Guide
• Understanding Embeddings
• AI Fundamentals Learning Path

MIT Licence - Feel free to use, modify, and share!

See LICENSE for details.

• 🐛 Bug? Open an issue
• 💡 Idea? Start a discussion
• ❓ Question? Check FAQ or open an issue