Game Building Guide - CourseBuilder

📚 Overview: How Game Building Works

CourseBuilder uses a shared assets + unique configurations architecture. This means:

✅ Efficient Design: Upload assets (characters, backgrounds, objects) once → Use them in unlimited courses → Delete a course, assets remain for other courses.

The Complete Workflow

1. Upload Shared Assets
Create or find sprites, backgrounds, and audio files → Upload to shared library

↓

2. Create Game Definition
Set up areas (game zones) and scenes (specific locations within areas)

↓

3. Design Scene Layout
Place assets, NPCs, portals, and decorations on the canvas

↓

4. Create Challenges
Write questions, answers, hints, and link them to NPCs

↓

5. Preview & Test
Play through the game, interact with NPCs, answer challenges

↓

6. Export to EmpowerEd
Package course + game + assets → Import into production platform

🎨 Step 1: Creating and Uploading Assets

What Are Game Assets?

Assets are reusable visual and audio files used across all your games:

Asset Type	Description	Recommended Size	Format
Characters	Player sprites, NPCs, enemies	64x64 px or 128x128 px	PNG (transparent)
Objects	Trees, rocks, interactive items	64x64 px to 256x256 px	PNG (transparent)
Obstacles	Fences, walls, barriers	128x64 px to 256x128 px	PNG (transparent)
Decorations	Flowers, grass, visual elements	32x32 px to 128x128 px	PNG (transparent)
Backgrounds	Scene backgrounds	1920x1080 px	PNG or JPG
Audio	Background music, sound effects	< 5 MB	MP3 or OGG

1 Create Your Asset

Option A: Use Free Asset Tools

Piskel (piskelapp.com) - Free pixel art editor, great for sprites
GIMP (gimp.org) - Free Photoshop alternative
Canva (canva.com) - Simple background creator
OpenGameArt.org - Free game assets (check license!)
Itch.io - Free and paid asset packs

💡 Pro Tip: For characters and objects, use transparent backgrounds (PNG format) so they blend seamlessly into scenes.

Option B: AI-Generated Assets (Recommended!)

🎨 We Use Leonardo.ai and ChatGPT:

Our team creates all game assets using AI tools. This is fast, cost-effective, and produces high-quality results!

Using Leonardo.ai (leonardo.ai):

Sign up for free account (150 credits/day)
Select "Image Generation"
Choose model: "Leonardo Diffusion XL" for realistic or "Pixel Art" for retro style
Enter your prompt (see examples below)
Set dimensions: 512x512 for characters, 1920x1080 for backgrounds
Click "Generate"
Download PNG with transparent background (use "Remove Background" feature)

Leonardo.ai Prompt Examples:

// Character Sprite (NPC Teacher)
"friendly female teacher character, cartoon style, standing facing forward,
simple design, clean lines, white background, game sprite, full body,
educational setting, warm smile, professional outfit"

// Background Scene (Village)
"cartoon village scene, daytime, bright colors, simple geometric buildings,
trees and flowers, flat design, top-down view, game background,
educational game aesthetic, cheerful atmosphere, 1920x1080"

// Object (Tree)
"simple cartoon tree, bright green leaves, brown trunk, game asset,
clean lines, flat design, isolated on white background, side view"

// NPC Shopkeeper
"friendly shopkeeper character, cartoon style, standing behind counter,
apron, welcoming expression, simple design, game sprite, full body"
        

Using ChatGPT (OpenAI):

Use ChatGPT-4 or higher (has DALL-E 3 integration)
Type: "Generate an image: [your description]"
ChatGPT will create the image automatically
Download and use background removal tool if needed

ChatGPT Image Prompt Examples:

// Character Asset
"Generate an image: A friendly cartoon math teacher character,
simple 2D game sprite style, standing position facing forward,
bright colors, suitable for educational game, transparent background"

// Background
"Generate an image: A colorful classroom interior background for
an educational game, bright and inviting, cartoon style, wide view,
no characters, 16:9 aspect ratio"

// Interactive Object
"Generate an image: A wooden door entrance, cartoon game asset style,
simple design, front view, suitable for 2D game portal"
        

Post-Processing Steps:

Remove Background: Use Leonardo's built-in tool, remove.bg, OR use CourseBuilder's automatic background removal ✨
Resize if needed: Use GIMP or Photopea to resize to exact dimensions
Save as PNG: Always PNG format for transparency support
Optimize: Use TinyPNG.com to reduce file size (keep under 500KB)

✨ NEW: Automatic Background Removal!

CourseBuilder now has built-in AI background removal! When uploading game assets, simply check the "Remove Background" option and our AI will automatically remove the background for you.

🤖 How It Works:

AI Model: U²-Net (U-squared Network) - deep learning model designed for salient object detection
Processing: Analyzes image → Identifies main subject → Separates from background → Creates transparent PNG
Processing Time: 2-5 seconds per image (server-side CPU processing)
Model Location: Cached on server at /root/.u2net/u2net.onnx (176 MB)
Script Location: /var/www/EECourses/scripts/remove-bg.py

✅ Benefits:

Professional quality: 90-95% accuracy on most subjects with clear edges
Completely private: Runs on OUR server, not 3rd party (images never leave our infrastructure)
Free: No per-image costs, unlimited usage
Automatic PNG conversion: Converts to RGBA PNG with transparency
Open source: Powered by Python rembg library + ONNX runtime

📋 Technical Details:

Dependencies: Python 3.12, rembg, onnxruntime, pillow
Format: Input: JPG/PNG/WEBP → Output: PNG with alpha channel (RGBA)
File Size: Typically increases slightly (~10-20%) due to alpha channel data
Integration: Node.js calls Python script via child_process

⚠️ Best Practices for AI Assets:

Be specific: "cartoon style" vs "realistic" makes a big difference
Request "simple design" for better game performance
Ask for "transparent background" or "white background" (easier to remove)
Generate multiple variations and pick the best one
Keep consistent art style across all assets in a course

🔧 Background Removal Troubleshooting

When to Use Background Removal:

✅ Character sprites (NPCs, heroes, enemies)
✅ Objects (trees, rocks, items, furniture)
✅ AI-generated images with backgrounds
✅ Photos with simple, contrasting backgrounds
❌ Scene backgrounds (keep the background!)
❌ Already transparent PNGs
❌ Images with complex, intertwined backgrounds

If Background Removal Fails:

Subject is cut off: Background color too similar to subject - try editing in Leonardo.ai or use a contrasting background
Background remains: Subject edges not well-defined - the AI works best with clear subject boundaries
Processing takes too long: Large images (>5MB) take longer - resize to 2000x2000px or smaller before uploading
Error during upload: Check server logs at /var/www/EECourses/logs/coursebuilder-error.log

Alternative Solutions:

Use Leonardo.ai's built-in "Remove Background" feature before downloading
Use GIMP or Photoshop for manual background removal (best for complex images)
Request "transparent background" or "white background" when generating AI images
Upload without background removal and manually edit later

Option C: Traditional Asset Libraries (if you prefer pre-made)

Free Sources:
• OpenGameArt.org - Thousands of free sprites
• Itch.io (free section) - Community-created assets
• Kenney.nl - High-quality free game assets

Paid Sources:
• Unity Asset Store - Professional quality
• GameDevMarket.net - Wide variety
• Creative Market - Premium illustrations
      

2 Upload to Shared Library

Via Game Builder Interface:

Navigate to Game Builder page
Click "Asset Library" tab
Click "Upload New Asset" button
Fill out the form:
- Name: "Hero Character" or "Village Background"
- Type: Select category (character, object, background, etc.)
- Category: Specific folder (characters, backgrounds, etc.)
- Tags: Keywords for searching (e.g., "teacher", "npc", "math")
- File: Choose your PNG/JPG/MP3 file
- ✨ Remove Background: Check this box to automatically remove the background (for images only)
Click "Upload"
⏳ If background removal is enabled, wait 2-5 seconds for AI processing
✅ Your asset is now uploaded with transparent background!

Upload Form Example:

┌─────────────────────────────────────────┐
│  Upload New Asset                       │
├─────────────────────────────────────────┤
│  Name: [Math Teacher NPC              ] │
│  Type: [Character ▼]                    │
│  Category: [characters ▼]               │
│  Tags: [teacher, npc, math            ] │
│  File: [Choose File] teacher.png        │
│                                         │
│  ☑ Remove Background (AI-powered)      │
│    Automatically remove background      │
│    and convert to transparent PNG       │
│                                         │
│  [Cancel]             [Upload Asset]    │
└─────────────────────────────────────────┘

💡 When to Use Background Removal:

✅ Characters/NPCs - Remove background for clean sprites
✅ Objects/Trees - Isolate objects from their backgrounds
✅ AI-generated images - Clean up white/colored backgrounds
❌ Backgrounds - Don't use (you want to keep the background!)
❌ Already transparent - Not needed if PNG is already transparent

3 Upload via API (Advanced)

// Using JavaScript Fetch API
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('name', 'Hero Character');
formData.append('type', 'character');
formData.append('category', 'characters');
formData.append('tags', JSON.stringify(['hero', 'player', 'main']));
formData.append('removeBackground', 'true');  // ← Enable background removal

const response = await fetch('/api/game/assets/upload', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`
  },
  body: formData
});

const data = await response.json();
console.log('Asset uploaded:', data.asset._id);
console.log('Background removed:', data.asset.backgroundRemoved);
      

⚙️ How Background Removal Works (Technical Flow):

Upload: Image uploaded to /uploads/shared/game/[category]/
Detection: Node.js detects removeBackground=true flag
Python Call: Executes /var/www/EECourses/scripts/remove-bg.py
Model Load: Python loads U²-Net AI model from /root/.u2net/u2net.onnx (176 MB, cached)
AI Processing: Model analyzes image and creates segmentation mask
Background Removal: Background pixels set to alpha=0 (transparent)
PNG Conversion: Saved as PNG with RGBA (alpha channel)
Cleanup: Original file deleted, transparent version kept
Response: Asset metadata returned with backgroundRemoved: true
Processing time: 2-5 seconds total

🔧 Technical Components:

Python Script: /var/www/EECourses/scripts/remove-bg.py
Node.js Service: /var/www/EECourses/backend/services/fileUploadService.js (processImage function)
Controller: /var/www/EECourses/backend/controllers/assetController.js (uploadAssets function)
AI Model: U²-Net ONNX model (salient object detection)
Dependencies: Python 3.12, rembg, onnxruntime, pillow, numpy

📁 Where Assets Are Stored: Assets are saved to /uploads/shared/game/[category]/ and available to ALL users and courses.

🗺️ Step 2: Creating Areas and Scenes

Understanding the Hierarchy

Game Definition (1 per course)
  └── Area (e.g., "Starting Village")
      ├── Scene 1: "Village Center" (default)
      ├── Scene 2: "General Store"
      └── Scene 3: "Teacher's House"

Area: A themed zone with a specific learning concept (e.g., "Addition Village", "Multiplication Mountains")

Scene: A specific location within an area (e.g., "Main Square", "Shop Interior")

1 Create Game Definition for Your Course

POST /api/courses/{courseId}/game

{
  "areas": [],
  "challenges": []
}
      

This creates an empty game attached to your course. You only do this once per course.

2 Add an Area

Standard Areas (Pre-configured):

starting_village - Addition & Subtraction
multiplication_mountains - Multiplication
division_desert - Division
fraction_forest - Fractions
geometry_gardens - Geometry
problem_solving_peak - Problem Solving

Or Create Custom Area:

POST /api/courses/{courseId}/game/areas

{
  "areaId": "science_lab",
  "areaName": "Science Laboratory",
  "isCustom": true,
  "isStandard": false,
  "difficulty": "medium",
  "concept": "Scientific Method",
  "scenes": []
}
      

3 Add a Scene to the Area

POST /api/courses/{courseId}/game/areas/{areaId}/scenes

{
  "sceneId": "main_square",
  "name": "Village Main Square",
  "isDefault": true,
  "visualConfig": {
    "backgroundColor": "#87CEEB",
    "backgroundImage": "/uploads/shared/game/backgrounds/village.png",
    "canvasWidth": 1920,
    "canvasHeight": 1080,
    "assets": [],
    "portals": [],
    "interactiveObjects": []
  }
}
      

💡 Best Practice: Always mark your first scene as "isDefault": true. This is where players spawn when entering the area.

4 🎨 NEW: Parallax Backgrounds (Advanced)

What is Parallax?

Parallax scrolling creates depth by moving background layers at different speeds. Far layers move slowly, close layers move faster - just like looking out a car window!

✨ Why Use Parallax Backgrounds?

Professional depth: Makes 2D games look modern and polished
Visual interest: Creates dynamic, engaging environments
Industry standard: Used in AAA indie games (Celeste, Hollow Knight)
Easy to create: Generate 3 layers with Leonardo.ai + CourseBuilder AI background removal

Setting Up Parallax Backgrounds:

Option 1: Simple Background (Current Default)

{
  "visualConfig": {
    "backgroundColor": "#87CEEB",
    "backgroundImage": "/uploads/shared/game/backgrounds/village.png"  ← Single image
  }
}

Option 2: Parallax Layers (NEW!) ⭐

{
  "visualConfig": {
    "backgroundColor": "#87CEEB",
    "backgroundLayers": [
      {
        "imageUrl": "/uploads/shared/game/backgrounds/cave-far.png",
        "depth": 0,           // Furthest back
        "scrollFactor": 0.2,  // Moves SLOWLY (20% of camera speed)
        "zIndex": -100,
        "parallaxEnabled": true
      },
      {
        "imageUrl": "/uploads/shared/game/backgrounds/cave-mid_no_bg.png",
        "depth": 50,          // Mid distance
        "scrollFactor": 0.5,  // Moves MEDIUM speed (50% of camera)
        "zIndex": -50,
        "parallaxEnabled": true
      },
      {
        "imageUrl": "/uploads/shared/game/backgrounds/cave-near_no_bg.png",
        "depth": 100,         // Closest
        "scrollFactor": 0.8,  // Moves FAST (80% of camera)
        "zIndex": -10,
        "parallaxEnabled": true
      }
    ]
  }
}

📋 Parallax Layer Guidelines:

Layer	Depth	Scroll Factor	What to Include	Background Removal?
Layer 1 (Far)	0	0.1 - 0.3	Sky, distant mountains, far walls	❌ No (solid background)
Layer 2 (Mid)	50	0.4 - 0.6	Trees, buildings, mid-distance objects	✅ Yes (transparent PNG)
Layer 3 (Near)	100	0.7 - 0.9	Grass, rocks, foreground elements	✅ Yes (transparent PNG)

Creating Parallax Layers with Leonardo.ai:

Step 1: Generate Layer 1 (Deep Background)
Prompt: "A mystical cave interior, distant stone walls,
atmospheric blue-purple haze, soft focus, far away perspective,
dark fantasy style, wide angle, 8k, game background art"

→ Pick your favorite → Save the SEED number
→ Download as PNG → Upload to CourseBuilder (NO background removal)

Step 2: Generate Layer 2 (Mid Background)
Prompt: "Medieval cave with stone pillars and archways in middle ground,
semi-detailed rock formations, medium distance,
same blue-purple lighting, dark fantasy style, 8k"

→ Use SAME SEED for consistency
→ Download as PNG → Upload with ✅ Remove Background (AI)

Step 3: Generate Layer 3 (Foreground)
Prompt: "Cave foreground elements, sharp stalactites and rocks,
close-up details, high definition, crystal formations,
blue-purple lighting, dark fantasy style, 8k"

→ Use SAME SEED
→ Download as PNG → Upload with ✅ Remove Background (AI)
      

Uploading via Game Builder UI:

┌─────────────────────────────────────────┐
│  Background Section                     │
├─────────────────────────────────────────┤
│  Background Type:                       │
│  ○ Simple (1 Image)                     │
│  ● Parallax (Layers) ← Select this      │
│                                         │
│  Layer 1 - Deep Background *            │
│  [Upload cave-far.png]                  │
│  Speed: [Slow (0.2) ▼]                  │
│                                         │
│  Layer 2 - Mid Background (Optional)    │
│  [Upload cave-mid.png]                  │
│  Speed: [Medium (0.5) ▼]                │
│  ☑ Remove Background (AI)               │
│                                         │
│  Layer 3 - Foreground (Optional)        │
│  [Upload cave-near.png]                 │
│  Speed: [Very Fast (0.8) ▼]             │
│  ☑ Remove Background (AI)               │
│                                         │
│  [Upload Parallax Layers]               │
└─────────────────────────────────────────┘

💡 Performance Impact:

Memory: +3-4 MB (negligible on modern devices)
FPS: Zero impact on desktop, -1 to -2 FPS on old mobile
Load time: +0.1 seconds
Worth it? YES! Visual quality improvement is 10x the small cost

5 Place Assets in the Scene

Assets are placed by referencing shared assets and specifying their position:

PUT /api/courses/{courseId}/game/areas/{areaId}/scenes/{sceneId}

{
  "visualConfig": {
    "assets": [
      {
        "id": "tree_1",
        "assetId": "673abc123...",  // Reference to shared asset
        "type": "decoration",
        "position": { "x": 300, "y": 400 },
        "size": { "width": 128, "height": 256 },
        "rotation": 0,
        "zIndex": 1
      },
      {
        "id": "tree_2",
        "assetId": "673abc123...",  // Same asset, different position!
        "type": "decoration",
        "position": { "x": 800, "y": 400 },
        "size": { "width": 128, "height": 256 },
        "rotation": 0,
        "zIndex": 1
      }
    ]
  }
}
      

🔑 Key Concept: One asset file can be placed multiple times. Each placement has unique position/size but shares the same image.

Scene Coordinate System

(0, 0) ─────────────────────────── (1920, 0)
  │                                      │
  │         Your Scene Canvas            │
  │                                      │
  │         (960, 540) = Center          │
  │                                      │
  │                                      │
(0, 1080) ─────────────────────── (1920, 1080)

X-axis: Left (0) → Right (1920)
Y-axis: Top (0) → Bottom (1080)

👥 Step 3: Creating NPCs and Interactions

What is an NPC?

NPC = Non-Player Character

NPCs are interactive characters that:

Display dialogue when clicked or approached
Trigger learning challenges (math questions, quizzes)
Provide hints and guidance
Give rewards (gems) for correct answers

1 Add NPC to Scene

PUT /api/courses/{courseId}/game/areas/{areaId}/scenes/{sceneId}

{
  "visualConfig": {
    "interactiveObjects": [
      {
        "id": "npc_teacher_1",
        "type": "npc",
        "name": "Ms. Johnson - Math Teacher",
        "sprite": "/uploads/shared/game/characters/teacher.png",
        "position": { "x": 600, "y": 400 },
        "size": { "width": 64, "height": 64 },
        "challengeId": null,  // Will add later
        "dialogue": "Hello! I have a math challenge for you. Are you ready?",
        "interactionRadius": 80
      }
    ]
  }
}
      

NPC Properties Explained

Property	Description	Example
`id`	Unique identifier for this NPC placement	"npc_teacher_1"
`type`	Object type (always "npc")	"npc"
`name`	Display name shown to player	"Ms. Johnson - Math Teacher"
`sprite`	Path to character image	"/uploads/shared/game/characters/teacher.png"
`position`	X,Y coordinates on canvas	{ "x": 600, "y": 400 }
`size`	Width and height in pixels	{ "width": 64, "height": 64 }
`challengeId`	Links to a challenge question	"68e1234..." (ObjectId)
`dialogue`	Text shown when player interacts	"Hello! Ready for a challenge?"
`interactionRadius`	Distance in pixels player can interact from	80 (player must be within 80px)

2 Create a Challenge (Question)

POST /api/courses/{courseId}/game/challenges

{
  "moduleId": "68e1234...",  // Link to course module
  "lessonId": "68e5678...",  // Link to specific lesson
  "areaId": "starting_village",
  "sceneId": "main_square",
  "difficulty": "easy",
  "problemType": "multiple_choice",
  "question": {
    "text": "What is 5 + 3?",
    "audioUrl": "/uploads/courses/{courseId}/game/challenge-audio/q1.mp3",
    "visualUrl": "/uploads/courses/{courseId}/game/challenge-images/q1.png"
  },
  "answers": [
    {
      "value": "8",
      "isCorrect": true,
      "feedback": "Correct! Great job!"
    },
    {
      "value": "7",
      "isCorrect": false,
      "feedback": "Not quite. Try adding again."
    },
    {
      "value": "9",
      "isCorrect": false,
      "feedback": "Close! Count carefully."
    }
  ],
  "hints": [
    {
      "level": 1,
      "text": "Try counting on your fingers: 5... 6, 7, 8!"
    },
    {
      "level": 2,
      "text": "5 + 3 means start at 5 and count up 3 more."
    }
  ],
  "gemsAwarded": 10,
  "concept": "Addition"
}
      

This will return a challenge with an _id. Save that ID!

3 Link Challenge to NPC

Update the NPC's challengeId field:

PUT /api/courses/{courseId}/game

{
  "areas": [{
    "areaId": "starting_village",
    "scenes": [{
      "sceneId": "main_square",
      "visualConfig": {
        "interactiveObjects": [{
          "id": "npc_teacher_1",
          "type": "npc",
          "name": "Ms. Johnson",
          "sprite": "/uploads/shared/game/characters/teacher.png",
          "position": { "x": 600, "y": 400 },
          "size": { "width": 64, "height": 64 },
          "challengeId": "68e91011...",  // ← Challenge ID here!
          "dialogue": "Ready for a math challenge?",
          "interactionRadius": 80
        }]
      }
    }]
  }]
}
      

💡 Player Interaction Flow:

Player walks near NPC (within interactionRadius)
Indicator (!) appears above NPC
Player clicks NPC or presses SPACE
Dialogue box appears with NPC's message
Challenge UI opens with question and multiple choice answers
Player selects an answer
Feedback shows (correct/incorrect)
If correct, gems are awarded and challenge marked complete

Challenge Problem Types

Problem Type	Description	Use Case
`multiple_choice`	Select one answer from 2-4 options	Basic math, reading comprehension
`numeric_input`	Type in a number	Math problems requiring exact answers
`drag_drop`	Drag items to correct positions	Matching, sorting, sequencing
`draw`	Draw shapes or solutions	Geometry, art activities
`array_builder`	Build visual arrays	Multiplication, grouping
`number_line`	Place numbers on a line	Number sense, fractions
`word_problem`	Multi-step problem solving	Real-world math applications
`fact_family`	Related math facts	Addition/subtraction relationships

🚪 Step 4: Creating Portals Between Scenes

What is a Portal?

Portals are interactive zones that transport the player to a different scene (like doors, stairs, or teleporters).

📌 Portal Use Cases:

Entering a building (outdoor scene → indoor scene)
Going upstairs (1st floor → 2nd floor)
Moving between areas (village → forest)
Unlocking new zones after completing challenges

1 Add Portal to Scene

PUT /api/courses/{courseId}/game/areas/{areaId}/scenes/{sceneId}

{
  "visualConfig": {
    "portals": [
      {
        "id": "portal_to_shop",
        "name": "General Store Entrance",
        "targetSceneId": "shop_interior",
        "position": { "x": 500, "y": 300 },
        "size": { "width": 150, "height": 200 },
        "triggerType": "both",
        "sprite": "/uploads/shared/game/objects/door.png",
        "requiresCompletion": false,
        "requiredChallenges": []
      }
    ]
  }
}
      

Portal Properties Explained

Property	Description	Options/Example
`id`	Unique portal identifier	"portal_to_shop"
`name`	Display name shown to player	"General Store Entrance"
`targetSceneId`	Scene to transport to	"shop_interior"
`position`	X,Y coordinates	{ "x": 500, "y": 300 }
`size`	Interaction hitbox size	{ "width": 150, "height": 200 }
`triggerType`	How portal activates	"click" \| "proximity" \| "both"
`sprite`	Visual representation	"/uploads/.../door.png"
`requiresCompletion`	Lock until challenges done?	true \| false
`requiredChallenges`	Array of challenge IDs needed	["68e123...", "68e456..."]

2 Create the Target Scene

The targetSceneId must exist! Create it first:

POST /api/courses/{courseId}/game/areas/{areaId}/scenes

{
  "sceneId": "shop_interior",
  "name": "General Store - Inside",
  "isDefault": false,
  "visualConfig": {
    "backgroundColor": "#D2B48C",
    "backgroundImage": "/uploads/shared/game/backgrounds/shop_interior.png",
    "assets": [],
    "portals": [
      {
        "id": "portal_exit",
        "name": "Exit to Village",
        "targetSceneId": "main_square",
        "position": { "x": 100, "y": 500 },
        "triggerType": "both",
        "sprite": "/uploads/shared/game/objects/door.png"
      }
    ],
    "interactiveObjects": []
  }
}
      

⚠️ Important: Always create a return portal in the target scene so players can go back! Otherwise they'll be stuck.

3 Lock Portals Behind Challenges (Optional)

To unlock a portal only after completing specific challenges:

{
  "id": "portal_to_mountain",
  "name": "Path to Multiplication Mountain",
  "targetSceneId": "mountain_base",
  "position": { "x": 1800, "y": 500 },
  "triggerType": "both",
  "sprite": "/uploads/shared/game/objects/mountain_path.png",
  "requiresCompletion": true,
  "requiredChallenges": [
    "68e123...",  // Addition challenge 1
    "68e456...",  // Addition challenge 2
    "68e789..."   // Addition challenge 3
  ]
}
      

When a player approaches this portal:

If challenges incomplete: "Complete 3 more challenges to unlock!"
If challenges complete: Portal glows and becomes usable

Portal Trigger Types

Trigger Type	Behavior	Best For
`"click"`	Must click portal to activate	Explicit choices, important transitions
`"proximity"`	Auto-activates when player walks near	Automatic transitions, seamless movement
`"both"`	Click OR walk near to activate	Most common - flexible interaction

Example: Multi-Scene Game Flow

┌─────────────────┐
│ Village Square  │ (Default scene - players spawn here)
│                 │
│  🚪 → Shop      │ (Portal: click door to enter)
│  🚪 → School    │
│  🌲🌲 → Forest  │ (Portal: walk to edge, auto-transition)
└─────────────────┘
        ↓ (Portal)
┌─────────────────┐
│ General Store   │
│                 │
│  👤 Shopkeeper  │ (NPC with challenge)
│  🚪 ← Exit      │ (Return portal to village)
└─────────────────┘

🎯 Step 5: Advanced Challenge Creation

Linking Challenges to Course Content

Every challenge must be linked to your course structure:

Course
  └── Module: "Introduction to Math"
      └── Lesson: "Addition Basics"
          └── Challenge: "What is 2 + 2?"

// IMPORTANT: Get these IDs from your course
const moduleId = "68e1234...";  // From course.modules[0]._id
const lessonId = "68e5678...";  // From course.modules[0].lessons[0]._id

// Then create challenge
POST /api/courses/{courseId}/game/challenges
{
  "moduleId": moduleId,
  "lessonId": lessonId,
  // ... rest of challenge data
}
      

1 Writing Effective Questions

✅ Good Question Example:

{
  "question": {
    "text": "Sarah has 3 apples. Her friend gives her 2 more. How many apples does Sarah have now?",
    "audioUrl": "/uploads/courses/{id}/game/challenge-audio/sarah_apples.mp3",
    "visualUrl": "/uploads/courses/{id}/game/challenge-images/sarah_apples.png"
  }
}
        

Why it's good:

Clear scenario with context
Audio narration for accessibility
Visual diagram showing apples

2 Creating Answer Options

Best Practices:

Provide 3-4 answer choices
Make incorrect answers plausible (common mistakes)
Give specific feedback for each option
Only mark ONE answer as correct

"answers": [
  {
    "value": "5",
    "isCorrect": true,
    "feedback": "Correct! 3 + 2 = 5. Great job!"
  },
  {
    "value": "4",
    "isCorrect": false,
    "feedback": "Not quite. Try counting: 3... 4, 5. The answer is 5!"
  },
  {
    "value": "6",
    "isCorrect": false,
    "feedback": "That's too many. Remember, Sarah started with 3 apples."
  },
  {
    "value": "1",
    "isCorrect": false,
    "feedback": "That would be 3 - 2. But we're adding! 3 + 2 = ?"
  }
]
      

3 Adding Helpful Hints

Hints unlock progressively if student struggles:

"hints": [
  {
    "level": 1,
    "text": "Think about starting at 3 and counting up.",
    "audioUrl": "/uploads/.../hint1.mp3"
  },
  {
    "level": 2,
    "text": "Use your fingers! Hold up 3 fingers, then add 2 more.",
    "audioUrl": "/uploads/.../hint2.mp3"
  },
  {
    "level": 3,
    "text": "3 + 2 = 5. Count with me: 3... 4... 5!",
    "audioUrl": "/uploads/.../hint3.mp3"
  }
]
      

Gem Rewards Strategy

Difficulty	Gems Awarded	Reasoning
Easy	5-10 gems	Simple recall, basic concepts
Medium	15-25 gems	Multi-step problems, applying concepts
Hard	30-50 gems	Complex word problems, synthesis
Bonus	100+ gems	Optional challenges, mastery demonstrations

4 Uploading Challenge Media

Question Audio: Record narration of the question

// File: sarah_apples.mp3
// Script: "Sarah has 3 apples. Her friend gives her 2 more.
//          How many apples does Sarah have now?"

Upload to: /uploads/courses/{courseId}/game/challenge-audio/sarah_apples.mp3
      

Question Visual: Diagram or illustration

// File: sarah_apples.png
// Content: Drawing showing 3 apples + 2 apples

Upload to: /uploads/courses/{courseId}/game/challenge-images/sarah_apples.png
      

📁 File Organization:

Shared assets: /uploads/shared/game/ (sprites, backgrounds)
Course-specific: /uploads/courses/{courseId}/game/ (challenge media)

🧪 Step 6: Testing Your Game

1 Launch Preview Mode

Open the preview URL with your course ID:

https://courses.empowered.adams-ai.com/preview.html?courseId={yourCourseId}

2 Testing Checklist

Test Item	What to Check	How to Test
Background Removal	Assets have transparent backgrounds	Check sprites have no white/colored boxes around them
Movement	Player can move smoothly	Use arrow keys, check all directions
NPCs	NPCs are visible and interactive	Walk near NPC, look for (!) indicator, press SPACE
Dialogue	Dialogue text displays correctly	Click NPC, read dialogue, press SPACE to close
Challenges	Questions load and are readable	Interact with NPC, verify question text/images
Answers	Correct answer awards gems	Select correct answer, watch gem count increase
Feedback	Feedback is specific and helpful	Try wrong answers, verify feedback messages
Portals	Portals transport to correct scenes	Walk through portal, verify new scene loads
Return Portals	Can get back to previous scenes	Use return portal, confirm you're back
Locked Portals	Locked until requirements met	Try portal before completing challenges
Progress	Sidebar updates correctly	Complete challenge, check gems/progress %
Audio	Background music and narration work	Unmute browser, verify audio playback
Assets	All images load correctly	Look for broken image icons

3 Common Issues and Fixes

Problem	Cause	Solution
NPC not visible	Wrong position or sprite path	Check `position` is within canvas bounds (0-1920, 0-1080)
Can't interact with NPC	No challengeId linked	Verify `challengeId` is set and valid
Portal doesn't work	Target scene doesn't exist	Create target scene first, verify `sceneId` matches
Stuck in scene	No return portal	Add return portal in target scene
Image not loading	Wrong file path	Check path starts with `/uploads/`
Gems not awarded	Wrong answer marked correct	Verify only ONE answer has `isCorrect: true`

4 Quick Test Script

Run this to create a test course instantly:

node test-preview.js

This creates:

A course with 2 lessons
A game with 1 area and 1 scene
1 NPC with 2 challenges
A preview URL you can test immediately

📦 Step 7: Exporting to EmpowerEd

Once you've tested your game and it works perfectly:

1 Validate Course

POST /api/courses/{courseId}/validate

Response:
{
  "valid": true,
  "warnings": [],
  "stats": {
    "modules": 1,
    "lessons": 2,
    "challenges": 2,
    "totalAssets": 5
  }
}
      

2 Export Package

GET /api/export/{courseId}

Downloads: course-export-{courseId}.zip

Contains:
├── course-data.json           (Course structure and content)
├── game-definition.json       (Areas, scenes, challenges)
├── media/
│   ├── content/               (Lesson content files)
│   └── game/
│       ├── challenge-audio/   (Question narration)
│       ├── challenge-images/  (Question diagrams)
│       └── shared-assets/     (Copied sprites & backgrounds)
└── import-instructions.txt    (How to import into EmpowerEd)
      

3 Import to EmpowerEd

Follow the instructions in the ZIP file to import into the production EmpowerEd platform.

💡 What Gets Exported:

✅ Course structure (modules, lessons)
✅ Game definition (areas, scenes, NPCs, portals)
✅ All challenges and answers
✅ COPIES of shared assets (so export is self-contained)
✅ Challenge-specific media files

📋 Quick Reference

API Endpoints Summary

# Assets
POST   /api/game/assets/upload          Upload shared asset
GET    /api/game/assets                 List all assets

# Game Definition
POST   /api/courses/{id}/game           Create game
GET    /api/courses/{id}/game           Get game
PUT    /api/courses/{id}/game           Update game

# Scenes
POST   /api/courses/{id}/game/areas/{areaId}/scenes        Add scene
PUT    /api/courses/{id}/game/areas/{areaId}/scenes/{sceneId}  Update scene

# Challenges
POST   /api/courses/{id}/game/challenges        Create challenge
GET    /api/courses/{id}/game/challenges        List challenges
PUT    /api/courses/{id}/game/challenges/{challengeId}  Update challenge

# Preview & Export
GET    /preview.html?courseId={id}      Test game
GET    /api/export/{id}                 Export package

Keyboard Controls in Preview

Key	Action
Arrow Keys	Move player character
SPACE	Interact with nearby NPC/portal
E	Interact (alternative to SPACE)
ESC	Close dialogue/challenge UI
Click	Interact with NPC/portal/answer

🎨 AI Image Generation with Leonardo.ai

CourseBuilder integrates with Leonardo.ai to generate high-quality characters and backgrounds with ControlNet precision and character consistency. No drawing skills required!

🎯 Why Leonardo.ai?

Character Consistency: Use the same character across unlimited scenes
Precision Control: ControlNet ensures 95%+ accuracy for feature placement
Professional Quality: Uses Leonardo Kino XL with Alchemy (high quality mode)
Cost Effective: ~$0.06/image with API access

🔑 Getting Your Leonardo.ai API Key

1 Create Leonardo.ai Account

1. Go to https://leonardo.ai
2. Sign up for a free account
3. Choose a subscription plan (starts at $12/month for 8,500 credits)

2 Get Your API Key

1. Go to Settings → API Access
2. Click "Generate API Key"
3. Copy your key (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
4. Keep it secure - you'll use it in the Depth Map Builder

🗺️ Creating Backgrounds with the Depth Map Builder

The Depth Map Builder is a visual tool that lets you control exactly where features appear in your generated scenes - without needing to draw or sketch anything!

1 Open the Depth Map Builder

Click here: Open Depth Map Builder

2 Choose a Template or Draw Your Depth Map

💡 What is a Depth Map?
A depth map is a grayscale image that tells the AI which parts of your scene should be far, mid, or near:

Black areas (Far): Sky, distant mountains, far walls
Gray areas (Mid): Mid-ground features like trees, buildings
White areas (Near): Foreground elements like paths, floors

Option A: Use a Built-In Template

🏔️ Mountain Pass: Sky, mountains, path layout
🌲 Forest Clearing: Sky, trees, ground
🏰 Castle Entrance: Sky, walls, courtyard
🕳️ Cave Interior: Deep cave, walls, floor
🏙️ City Street: Sky, buildings, street

Click any template to load it instantly!

Option B: Draw Your Own

Tools Available:
┌─────────────────────────────────────┐
│ 🖌️ Brush   - Paint depth regions   │
│ 🪣 Fill    - Flood fill areas      │
│ ▭ Rectangle - Draw precise boxes   │
│ 📐 Gradient - Smooth transitions   │
└─────────────────────────────────────┘

Steps:
1. Select depth layer (Far, Mid, Near)
2. Choose your tool (Brush recommended)
3. Paint on the canvas
4. Use Undo if you make mistakes
5. Save as custom template (optional)
      

3 Generate Scene with Leonardo.ai

Once your depth map is ready:

Click "Generate Scene with Leonardo.ai"
Enter your Leonardo.ai API key
Write a detailed scene description (prompt)
Add negative prompt for what to avoid (optional)
Adjust ControlNet weight (0.7 recommended)
Choose number of images (4 recommended for options)
Click "Generate Scene"
Wait 30-60 seconds for generation to complete

✨ Example Prompts for Backgrounds:

Mountain Pass:
"Epic fantasy mountain pass with snow-capped peaks, rocky cliffs,
stone path, dramatic sunset lighting, detailed, 4K quality"

Negative: "characters, people, blurry, low quality, distorted"

---

Forest Clearing:
"Magical forest clearing with tall ancient trees, sunbeams through
leaves, grass meadow, mystical atmosphere, high detail"

Negative: "buildings, urban, concrete, characters"

---

Castle Interior:
"Medieval castle throne room, stone walls with torches, red carpet,
stained glass windows, royal atmosphere, cinematic lighting"

Negative: "modern, futuristic, people, low quality"
        

4 Download and Use in Game Builder

After generation completes:

Review the generated images (you'll get 1-4 options)
Right-click and save your favorite
Go to Game Builder
Upload to Background → Simple or use for Parallax Layers

🎭 Creating Consistent Characters

Leonardo.ai's Character Reference feature ensures the same character appears consistently across all your scenes.

1 Generate Your First Character

Go to Leonardo.ai Web Interface

Settings:
• Model: Leonardo Kino XL (or Anime XL for anime style)
• Size: 1024x1024 (square) or 1024x1536 (portrait)
• Quality: Alchemy ON, High Resolution ON

Example Character Prompts:
┌──────────────────────────────────────────────────────┐
│ Fantasy Wizard:                                      │
│ "Elderly wizard with long white beard, purple robes,│
│  wooden staff with glowing crystal, wise expression,│
│  detailed face, fantasy RPG character, full body,   │
│  white background, character design sheet"          │
│                                                      │
│ Young Adventurer:                                    │
│ "Young female adventurer, brown hair in ponytail,   │
│  leather armor, blue eyes, determined expression,   │
│  character portrait, detailed, white background,    │
│  RPG game character"                                 │
│                                                      │
│ Knight Character:                                    │
│ "Noble knight in silver armor, red cape, helmet off,│
│  short brown hair, heroic pose, full body character │
│  design, white background, high detail"             │
└──────────────────────────────────────────────────────┘
      

⚡ Character Design Tips:

Always include "white background" for easy background removal
Use "character design sheet" or "full body" for consistent angles
Specify exact details: hair color, clothing, facial features
Generate 4 variations, pick the best one
Save the image - this becomes your character reference!

2 Use Character Reference for Consistency

Once you have your base character image:

In Leonardo.ai, click "Image Guidance"
Upload your character image
Select "Character Reference" mode
Set weight to 0.7-0.8 (higher = more similar)
Generate new poses/expressions using different prompts

Example: Reusing Your Wizard Character
┌────────────────────────────────────────────────────┐
│ Original: "Wizard with white beard, purple robes"  │
│                                                    │
│ New Variations (with Character Reference):        │
│ • "wizard casting spell, glowing hands"           │
│ • "wizard reading ancient book, sitting"          │
│ • "wizard surprised expression, pointing"         │
│ • "wizard walking with staff, side view"          │
│                                                    │
│ Result: Same character, different poses! ✨        │
└────────────────────────────────────────────────────┘
      

3 Prepare Characters for Game Builder

After generating character images:

Download the image from Leonardo.ai
Upload to Game Builder → Assets → Upload Asset
Check "Remove Background (AI)" - this uses U²-Net AI to remove the background automatically!
Set asset type to "Character" or "NPC"
Place in your scene as an interactive object or decoration

🎬 Advanced: Generating Parallax Layers

Use the same depth map with different prompts to create 3 parallax layers:

Layer	Depth Map Focus	Prompt Focus	Example
Layer 1 (Far)	Black regions	Sky, distant mountains, atmospheric	"Sunset sky with distant snow peaks, soft focus, atmospheric perspective"
Layer 2 (Mid)	Gray regions	Mid-ground features, moderate detail	"Rocky cliffs and pine trees, medium distance, moderate detail"
Layer 3 (Near)	White regions	Foreground elements, sharp detail	"Stone path with grass edges, close-up detail, sharp focus"

💡 Parallax Layer Workflow:

Create ONE depth map in Depth Map Builder
Generate Layer 1 with far-focused prompt + check "Remove Background"
Generate Layer 2 with mid-focused prompt + check "Remove Background"
Generate Layer 3 with near-focused prompt + check "Remove Background"
Upload all 3 to Game Builder → Background → Parallax (Layers)
Set scroll speeds: Far=0.2, Mid=0.5, Near=0.8

📊 Cost Reference

Task	Credits	Cost (Artisan Plan)
1024x1024 image (Kino XL, Alchemy ON)	~5 credits	~$0.007
4 variations (recommended)	~20 credits	~$0.028
Complete parallax scene (3 layers, 4 variations each)	~60 credits	~$0.084
10 unique characters	~200 credits	~$0.28

Artisan Plan ($12/month): 8,500 credits = ~425 high-quality images
Maestro Plan ($30/month): 25,000 credits = ~1,250 high-quality images

🔗 Quick Links

🗺️ Open Depth Map Builder 🎨 Open Leonardo.ai 🔑 Get API Key

🎵 Audio Generation and Management

CourseBuilder includes a complete Audio Library with AI-powered voice generation, sound effects, and support for background music. All courses share a global audio library for consistency and efficiency.

✨ Audio System Features:

AI Text-to-Speech: Generate NPC dialogue using ElevenLabs (29 voices available)
Character Voice Consistency: Same character = same voice across all courses
Sound Effects: AI-generated SFX for correct/wrong answers, portals, scene transitions
Background Music: Upload music from Mubert.com or other sources
Global Library: All audio assets shared across all courses
Usage Tracking: See where each audio file is used (prevents accidental deletion)

🔑 Audio Library Access

1 Open the Audio Library

Access the Audio Library from the Game Builder:

🎵 Open Audio Library

The Audio Library has 6 tabs:

Overview: Usage statistics and ElevenLabs subscription info
Character Voices: Manage consistent character voices
Generate Speech: Create TTS dialogue for NPCs
Sound Effects: Generate AI sound effects
Background Music: Upload music files
Browse Library: View all audio assets with filters

🎭 Character Voices (Consistency)

Character voices ensure the same character sounds the same everywhere they appear. For example, if "Wizard Merlin" appears in 5 different courses, he always uses the same voice.

1 Create a Character Voice

1. Go to Audio Library → Character Voices tab
2. Click "Create Character Voice"
3. Fill out the form:

┌─────────────────────────────────────────────┐
│  Create Character Voice                     │
├─────────────────────────────────────────────┤
│  Character Name: [Wizard Merlin           ] │
│  Description: [Wise old wizard, mentor    ] │
│                                             │
│  ElevenLabs Voice: [Adam (Deep) ▼]         │
│                                             │
│  Voice Settings (Advanced):                 │
│  Stability: [━━━━━━━╺━━] 0.5               │
│  Similarity: [━━━━━━━━━━] 0.75             │
│  Style: [━╺━━━━━━━━] 0.0                   │
│  ☑ Use Speaker Boost                       │
│                                             │
│  [Cancel]           [Create Character]      │
└─────────────────────────────────────────────┘

💡 Available ElevenLabs Voices (29 total):

Adam (Deep male)
Antoni (Well-rounded male)
Arnold (Crisp male)
Bella (Soft female)
Callum (Intense male)
Charlie (Casual male)
Charlotte (Seductive female)
Clyde (War veteran male)
Daniel (Deep British male)
Dave (British male)
Domi (Strong female)
Dorothy (British female)
Emily (Calm female)
Ethan (Warm male)
Fin (Irish male)
Freya (Young female)
George (Warm British male)
Gigi (Childish female)
Giovanni (Italian male)
Glinda (Witch female)
Grace (Smooth female)
Harry (Anxious male)
James (Calm male)
Jeremy (Irish male)
Jessie (Raspy female)
Joseph (British male)
Liam (Neutral male)
Lily (Warm female)
Matilda (British female)

2 Add Voice Variations (Optional)

Voice variations let you temporarily change a character's voice for special situations:

Helium Voice: Character inhaled helium balloon (high-pitched)
Underwater: Character speaking underwater (muffled)
Echo: Character in a cave or large room
Whispering: Character trying to be quiet

Example:
┌────────────────────────────────────────────┐
│ Character: Wizard Merlin                   │
│ Default Voice: Adam (Deep)                 │
│                                            │
│ Variations:                                │
│ • helium → Freya (Young female, high)     │
│ • underwater → Same voice, stability 0.3   │
│ • echo → Same voice, style 0.8             │
└────────────────────────────────────────────┘
      

🎤 Generating Text-to-Speech Dialogue

1 Generate NPC Dialogue

1. Go to Audio Library → Generate Speech tab
2. Fill out the form:

┌─────────────────────────────────────────────┐
│  Generate Text-to-Speech                    │
├─────────────────────────────────────────────┤
│  Audio Name: [Wizard Greeting             ] │
│                                             │
│  Character Voice: [Wizard Merlin ▼]        │
│  Voice Variation: [Default ▼]              │
│                                             │
│  Text to Speak:                             │
│  ┌─────────────────────────────────────┐   │
│  │ Greetings, young adventurer!        │   │
│  │ I have a riddle for you. Are you    │   │
│  │ ready to test your wits?            │   │
│  └─────────────────────────────────────┘   │
│  Characters: 94 / 5000                      │
│                                             │
│  [Cancel]              [Generate Speech]    │
└─────────────────────────────────────────────┘

3. Click "Generate Speech"
4. Wait 2-5 seconds for ElevenLabs to generate audio
5. Play the preview to verify it sounds correct
6. Audio is automatically saved to the library

⚠️ ElevenLabs Pricing:

Free Tier: 10,000 characters/month (~3-5 minutes of audio)
Starter ($5/month): 30,000 characters (~10 minutes)
Creator ($22/month): 100,000 characters (~33 minutes)
Pro ($99/month): 500,000 characters (~166 minutes)
Current Usage: Shown in Overview tab

💡 TTS Best Practices:

Keep dialogue concise (50-200 characters per audio file)
Use punctuation for natural pauses (commas, periods)
Add emotion with exclamation marks (!), question marks (?)
Test different voices - some work better for specific characters
Generate all dialogue for one character at once for consistency

🔊 Generating Sound Effects

1 Generate AI Sound Effects

1. Go to Audio Library → Sound Effects tab
2. Fill out the form:

┌─────────────────────────────────────────────┐
│  Generate Sound Effect                      │
├─────────────────────────────────────────────┤
│  Effect Name: [Correct Answer Chime       ] │
│                                             │
│  Description:                               │
│  ┌─────────────────────────────────────┐   │
│  │ Bright magical chime sound,         │   │
│  │ triumphant, success, bell-like      │   │
│  └─────────────────────────────────────┘   │
│                                             │
│  Duration: [━━━━╺━━━━━] 2.0 seconds        │
│                                             │
│  [Cancel]               [Generate SFX]      │
└─────────────────────────────────────────────┘

✨ Common Sound Effect Examples:

Correct Answer:
"Bright magical chime, triumphant success sound, bell-like"

Wrong Answer:
"Soft buzzer sound, gentle failure, low pitch, sympathetic"

Portal Activation:
"Magical whoosh, teleportation sound, sparkles, mystical"

Scene Enter:
"Door opening, wooden creaking, fantasy dungeon entrance"

Gem Collect:
"Coin pickup sound, light sparkle, rewarding chime"

NPC Greeting:
"Friendly notification, soft pop, attention grabber"
        

⚠️ Sound Effect Limitations:

Duration: 0.5 to 22 seconds (shorter is better for game SFX)
Quality varies - generate 3-4 variations and pick the best
Best for: abstract sounds (chimes, whooshes, magical effects)
Not ideal for: realistic speech, complex music, specific melodies

🎼 Background Music with Mubert.com

For background music, we recommend Mubert.com - an AI music generator that creates royalty-free tracks perfectly suited for game soundtracks.

1 Generate Music with Mubert

1. Go to Mubert Render
2. Sign up for a free account or log in
3. Choose your music generation method:

┌─────────────────────────────────────────────┐
│  Mubert Render Options                      │
├─────────────────────────────────────────────┤
│  1. Select Genre/Mood                       │
│     • Ambient, Chill, Cinematic, Electronic│
│     • Fantasy, Adventure, Mystery, Peaceful│
│                                             │
│  2. Choose Duration                         │
│     • 30 sec - 25 minutes                   │
│     • Recommended: 2-3 minutes (loops)      │
│                                             │
│  3. Generate Track                          │
│     • AI creates unique track               │
│     • Download as MP3                       │
│     • Royalty-free for your project         │
└─────────────────────────────────────────────┘

🎵 Mubert.com Pricing (2025):

Free: 25 tracks/month, up to 25 minutes each (perfect for most courses!)
Ambassador ($14/month): 500 tracks/month
Pro ($39/month): Unlimited tracks, commercial use

2 Recommended Music Styles for Educational Games

Scene Type	Mubert Genre/Mood	Why It Works
Starting Village	Peaceful, Ambient, Chill	Non-distracting, calming, helps focus
Forest/Nature	Nature, Cinematic, Ambient	Immersive, atmospheric
Cave/Dungeon	Dark Ambient, Mystery, Suspense	Creates tension, engaging
Castle/Palace	Classical, Cinematic, Epic	Majestic, motivating
Boss Challenge	Epic, Dramatic, Intense	Builds excitement, focus
Shop/Town	Upbeat, Cheerful, Folk	Friendly, welcoming atmosphere

3 Upload Music to Audio Library

After downloading your music from Mubert:

1. Go to Audio Library → Background Music tab
2. Drag and drop your MP3 file, or click to browse
3. Fill out the metadata:

┌─────────────────────────────────────────────┐
│  Upload Background Music                    │
├─────────────────────────────────────────────┤
│  Track Name: [Village Peaceful Theme      ] │
│  Genre: [Ambient ▼]                         │
│  Mood: [Peaceful, Calm, Educational       ] │
│                                             │
│  ☑ Loop this track                         │
│     (Recommended for background music)      │
│                                             │
│  File: village_theme.mp3 (2.4 MB)          │
│  Duration: 2:45                             │
│                                             │
│  [Cancel]                    [Upload]       │
└─────────────────────────────────────────────┘

💡 Music Upload Tips:

Always enable "Loop this track" for background music
Keep file size under 5 MB for faster loading
Use descriptive names: "village_peaceful", "dungeon_mystery", "boss_epic"
2-3 minutes is ideal duration (not too short, not too long)
Supported formats: MP3, WAV, OGG
✨ Auto-conversion: WAV files are automatically converted to MP3 (Mubert downloads as WAV - just upload directly!)

🎮 Assigning Audio to Game Scenes

1 Add Audio to Scene Configuration

1. Open Game Builder
2. Select your scene
3. Scroll to the "Audio" section in the sidebar
4. Configure scene audio:

┌─────────────────────────────────────────────┐
│  Scene Audio Configuration                  │
├─────────────────────────────────────────────┤
│  Background Music:                          │
│  [Village Peaceful Theme ▼]                 │
│  Volume: [━━━━━━━╺━━] 0.5                   │
│                                             │
│  Ambient Sound (Optional):                  │
│  [Forest Birds Chirping ▼]                  │
│  Volume: [━━━╺━━━━━━] 0.3                   │
│                                             │
│  Sound Effects:                             │
│  Correct Answer: [Magical Chime ▼]         │
│  Wrong Answer: [Soft Buzzer ▼]             │
│  Portal Activate: [Whoosh SFX ▼]           │
│                                             │
│  Master Volume:                             │
│  Music: [━━━━━━━╺━━] 0.7                    │
│  SFX: [━━━━━━━━╺━] 0.8                      │
│  Voice: [━━━━━━━━━━] 1.0                    │
│                                             │
│  [🎵 Open Audio Library]                    │
└─────────────────────────────────────────────┘

2 Assign Voice to NPCs

When creating or editing an NPC:

NPC Configuration:
┌────────────────────────────────────────────┐
│ NPC Name: Wizard Merlin                   │
│ Character Voice: [Wizard Merlin ▼]        │
│                                            │
│ Dialogue:                                  │
│ [Select from TTS Library ▼]               │
│ • Wizard Greeting                          │
│ • Wizard Challenge Intro                   │
│ • Wizard Encouragement                     │
│ • (Generate new...)                        │
└────────────────────────────────────────────┘
      

📊 Audio Usage Tracking

The Audio Library automatically tracks where each audio file is used:

Audio Asset: "Wizard Greeting"
┌────────────────────────────────────────────┐
│ Used In: 3 places                          │
│                                            │
│ 1. Scene: Village Square (Main Area)      │
│    NPC: Wizard Merlin                      │
│                                            │
│ 2. Scene: Magic Tower (Advanced Area)     │
│    NPC: Wizard Merlin                      │
│                                            │
│ 3. Scene: Final Boss Room (Challenge)     │
│    NPC: Wizard Merlin (variation)          │
│                                            │
│ [Cannot delete - in use]                   │
└────────────────────────────────────────────┘

⚠️ Deletion Protection:

You cannot delete audio assets that are currently being used in any course. This prevents accidentally breaking audio in published games. To delete an audio file, first remove it from all scenes/NPCs where it's used.

🎧 Alternative Free Music Sources

If you don't want to use Mubert, here are other royalty-free music sources:

Source	License	Quality	Best For
Incompetech	Free (CC BY)	Good	Classical, cinematic tracks
OpenGameArt	Various (mostly free)	Varies	Game-specific loops
Freesound	CC licenses	Varies	Sound effects, ambient
Pixabay Music	Free	Good	Background music, diverse styles
Bensound	Free (attribution)	High	Professional background tracks

🔗 Quick Links

🎵 Open Audio Library 🎼 Generate Music (Mubert) 🎤 ElevenLabs TTS

🎓 You're Ready to Build!

You now have everything you need to create engaging educational games in CourseBuilder. Start by uploading a few assets, creating a simple scene with one NPC and challenge, then test it in preview mode. Build from there!

Open Game Builder Test Preview Back to Dashboard

🎮 Game Building Guide

📚 Overview: How Game Building Works

The Complete Workflow

🎨 Step 1: Creating and Uploading Assets

What Are Game Assets?

🗺️ Step 2: Creating Areas and Scenes

Understanding the Hierarchy

Scene Coordinate System

👥 Step 3: Creating NPCs and Interactions

What is an NPC?

NPC Properties Explained

Challenge Problem Types

🚪 Step 4: Creating Portals Between Scenes

What is a Portal?

Portal Properties Explained

Portal Trigger Types

🎯 Step 5: Advanced Challenge Creation

Linking Challenges to Course Content

Gem Rewards Strategy

🧪 Step 6: Testing Your Game

📦 Step 7: Exporting to EmpowerEd

📋 Quick Reference

API Endpoints Summary

Keyboard Controls in Preview

🎨 AI Image Generation with Leonardo.ai

🔑 Getting Your Leonardo.ai API Key

🗺️ Creating Backgrounds with the Depth Map Builder

🎭 Creating Consistent Characters

🎬 Advanced: Generating Parallax Layers

📊 Cost Reference

🔗 Quick Links

🎵 Audio Generation and Management

🔑 Audio Library Access

🎭 Character Voices (Consistency)

🎤 Generating Text-to-Speech Dialogue

🔊 Generating Sound Effects

🎼 Background Music with Mubert.com

🎮 Assigning Audio to Game Scenes

📊 Audio Usage Tracking

🎧 Alternative Free Music Sources

🔗 Quick Links

🎓 You're Ready to Build!