Code Harvest: Educational RTS Game Design Document

Teaching Programming Through Resource Management

Executive Summary

Code Harvest transforms Unreal's Cropout RTS template into a programming education game where managing villagers teaches real coding concepts. Players aged 5-15 learn variables, functions, loops, and algorithms by optimizing resource gathering on procedurally generated islands.

Core Innovation: Every game mechanic teaches programming. Variables track resources. Functions become reusable villager commands. Loops automate repetitive tasks. Better code = more efficient gameplay.

Core Gameplay Loop

60-Second Micro Loop

1. Observe (10s): Watch villagers work inefficiently
2. Code (20s): Assign new behaviors using visual programming
3. Execute (20s): Villagers perform improved routines
4. Reward (10s): See efficiency metrics improve

Session Flow (15-20 minutes)

1. Daily Challenge: Specific programming puzzle
2. Free Play: Expand island using learned concepts
3. Bug Battle: Debug errors attacking your village
4. Lesson Unlock: New programming concept = new game mechanic

Programming Concepts as Game Mechanics

Variables = Resource Tracking

Without Variables (Tutorial Phase)

• Count resources manually
• Forget how much you need
• Villagers wander aimlessly
• Frustration: "Did I collect 30 or 40 wood?"

With Variables (Lesson Unlock)

Visual: Floating number displays above resources

woodCount = 45
woodNeeded = 100
woodRemaining = 55

Gameplay Advantages:

• Auto-tracking eliminates counting
• Set collection goals: GATHER until woodCount >= 100
• Villagers show progress: "Carrying 8/10"
• Enable smart decisions: IF foodCount < 20 THEN prioritize farming

Strategic Uses:

• Speed Runs: Track exact requirements
• Multi-tasking: Monitor multiple resources simultaneously
• Efficiency: Stop gathering when goals met
• Trade Prep: Know exact inventory for market

Functions = Villager Skills

Without Functions (Default)

• Click every single action
• Repeat same commands for each villager
• No consistency between workers
• Problem: 100 clicks for morning routine

With Functions (Lesson Unlock)

Visual: Skill cards you drag onto villagers

Function MorningRoutine():
    1. WakeUp()
    2. Eat(breakfast)
    3. CheckTools()
    4. GoToWork()

Gameplay Advantages:

• One card = complete routine
• Copy to all villagers instantly
• Modify once, updates everywhere
• Chain functions: MorningRoutine() → GatherLoop() → EveningReturn()

Advanced Functions:

Function SmartGather(resource, amount, quality):
    WHILE gathered < amount:
        target = FindBest(resource, quality)
        IF target exists:
            Gather(target)
        ELSE:
            Return("Not enough high quality")

• Parameters customize behavior
• Return values enable decisions
• Unlock: Elite villagers with complex routines

Loops = Automation Power

Without Loops (Base Game)

• Click plant seed, click water, repeat 50 times
• RSI from repetitive clicking
• Time: 5 minutes to plant field

Basic Loops (Lesson Unlock)

FOR i = 1 to 50:
    PlantSeed()
    WaterSeed()

• Time: 5 seconds
• Visual: Progress bar shows iterations
• Unlock: Auto-farming villagers

Advanced Loops

WHILE (season == "Spring"):
    FOR each emptyField:
        PlantOptimalCrop(season, soilType)
    WaitForGrowth()
    HarvestRipeCrops()

• Nested loops for complex patterns
• Conditional loops that adapt
• Unlock: Fully automated production chains
• Leaderboard: "Most efficient farm layout"

Conditionals = Smart Decision Making

Without Conditionals (Tutorial Island)

• Villagers harvest unripe crops (waste)
• Build in rain (materials ruined)
• Fight bugs with wrong tools (ineffective)

Basic IF-THEN (Lesson Unlock)

IF crop.ripeness >= 100:
    Harvest()
ELSE:
    Water()

• Visual: Decision diamonds above villagers
• Result: 40% better yields
• Unlock: Weather-aware villagers

Complex Logic

IF (weather == "Storm" AND buildingHealth < 50):
    RepairBuilding()
ELSE IF (enemyBugs > 5 OR resources < 100):
    DefendMode()
ELSE:
    ContinueGathering()

• Multiple condition checks
• Priority-based decisions
• Unlock: Strategic AI villagers
• Competition: "Best defensive algorithm"

Algorithms = Ultimate Efficiency

Without Algorithms (Basic Play)

• Random resource gathering
• Inefficient paths
• Slow sorting
• Problem: Friends finish challenges faster

Sorting Algorithms

Bubble Sort (Default):

• Visual: Resources slowly swap positions
• Time: 60 seconds for 100 items
• Learning: See why it's slow

Quick Sort (Unlock):

• Visual: Resources split and conquer
• Time: 5 seconds for 100 items
• Advantage: 12x faster crafting
• Leaderboard: "Fastest sorter award"

Pathfinding Algorithms

Random Walk (Default):

• Villagers wander aimlessly
• Hit obstacles repeatedly

A Pathfinding* (Unlock):

• Visual: Optimal path highlights
• Benefit: 70% less travel time
• Strategic: First to rare resources
• PvP: Outmaneuver opponents

Bug Battles: The Core Conflict

Why Bug Battles Matter

Bugs represent coding errors that actively harm your village. Without proper defenses (good coding practices), bugs multiply and destroy progress. Each lesson teaches how to prevent and fix specific bug types.

Bug Wave Events (Every 10 Minutes)

Wave 1: Syntax Bugs (Free Tutorial)

• Appearance: Scrambled letter swarms
• Attack: Jumble villager commands
• Effect: Villagers do random actions
• Defense: Spell-check towers (free)
• Lesson Value: Learn proper syntax

Bug Types Without Defense

Syntax Bugs

• Attack Pattern: Scramble villager commands
• Game Effect: "Gather Wood" becomes "Gather Wodo" - villager confused
• Player Impact: 50% actions fail
• Defense Lesson: Proper syntax checking

Logic Bugs

• Attack Pattern: Reverse conditional statements
• Game Effect: Villagers store food in lumber yard
• Player Impact: Resources in wrong places
• Defense Lesson: Boolean logic mastery

Memory Leaks

• Attack Pattern: Slowly drain all resources
• Game Effect: -5 resources per minute
• Player Impact: Economy collapse over time
• Defense Lesson: Resource management

Infinite Loop Bugs

• Attack Pattern: Trap villagers in endless actions
• Game Effect: Villager keeps walking in circles
• Player Impact: Workers become useless
• Defense Lesson: Loop control structures

Race Condition Bugs

• Attack Pattern: Cause timing conflicts
• Game Effect: Two villagers grab same resource, both lose it
• Player Impact: 30% resource loss
• Defense Lesson: Synchronization concepts

Bug Battle Rewards

• Debug 10 bugs → Efficiency +10%
• Debug 50 bugs → Unlock Bug Radar
• Debug 100 bugs → Legendary Debugger Title
• Never lose to bugs → Perfect Code Achievement

Why Buy Lessons: The Value Proposition

Immediate Gameplay Benefits

Speed Advantage

• Without Loops: 5 minutes to plant field
• With Loops: 5 seconds (60x faster)
• Result: Complete daily challenges first

Resource Efficiency

• Without Variables: Waste 30% gathering excess
• With Variables: Perfect resource management
• Result: Build faster than competitors

Combat Superiority

• Without Bug Defense: Lose 50% to attacks
• With Bug Defense: Immune to disruption
• Result: Maintain top leaderboard spot

Progressive Unlocks

$1.99 Starter Lessons

• Variables: Track everything
• Basic Loops: 10x faster actions
• Simple Functions: Reusable commands
• Value: Transform gameplay fundamentally

$4.99 Power Packs

• Advanced Functions: Complex behaviors
• Nested Loops: Pattern mastery
• Logic Gates: Smart decisions
• Value: Compete at higher levels

$9.99 Master Bundles

• Algorithms: Ultimate efficiency
• Data Structures: Perfect organization
• Debugging: Bug immunity
• Value: Dominate leaderboards

Social Pressure

• Leaderboard: "Sarah unlocked QuickSort and jumped to #1"
• Class Progress: "18/25 students have Variables"
• Daily Challenge: "Requires Functions to compete"
• Friend Battles: "Tom's algorithm beat yours by 300%"

Exclusive Content per Lesson

Variables Lesson Includes:

• 3 Variable villager skins
• Floating number customization
• "Memory Master" title
• Bonus: 500 starting resources

Functions Lesson Includes:

• 5 Pre-made function cards
• Function editor unlock
• "Efficient Coder" badge
• Bonus: Speed boost items

Algorithm Bundle Includes:

• All sorting animations
• Algorithm race mode
• "Speed Demon" effects
• Bonus: Exclusive island theme

Parent Appeal

• Progress Reports: "Your child mastered loops today"
• Real Skills: "Learning actual programming"
• Screen Time Value: "Educational gameplay"
• Price Point: "Less than a movie ticket"

Data Structures = Storage Buildings

Array Barn (Instant Access Storage)

Visual: 10 numbered doors [0-9], see all contents Gameplay Advantage:

• Instant retrieval if you know position: Get wood from slot[3]
• Perfect for: Recipes requiring specific items
• Trade-off: Limited slots, wastes space if not full Example: Building a house needs 5 wood, 3 stone, 2 iron. Store in slots [0], [1], [2] for one-click collection.

Stack Silo (Last-In-First-Out)

Visual: Tall glass tube, items stack vertically Gameplay Advantage:

• Unlimited capacity (grows upward)
• Perfect for: Daily food supply, temporary storage
• Trade-off: Can only access top item Example: Morning harvest goes on top, eat freshest food first. But if you need specific item at bottom, must remove everything above.

Queue Workshop (Fair Processing)

Visual: Conveyor belt with entry/exit points Gameplay Advantage:

• Automatic processing in order received
• Perfect for: Crafting stations, villager task lists
• Trade-off: Can't skip ahead or prioritize Example: Villagers drop raw materials at entrance, processed goods emerge in order. Fair but inflexible.

HashMap Market (Instant Trading)

Visual: Color-coded key system, magic portal storage Gameplay Advantage:

• Instant lookup with key: "Red key = all wood"
• Perfect for: Trading post, rare item storage
• Trade-off: Expensive to build, key management Example: Trade requests arrive as "Need 50 wood." One key press delivers exact amount.

Tree Treasury (Hierarchical Organization)

Visual: Branching storage system, items organized by type/quality Gameplay Advantage:

• Automatic sorting and categorization
• Perfect for: Large diverse inventories
• Trade-off: Slower than direct access, complex to set up Example: All wood types stored together, sorted by quality. Easy to find "best available wood."

Strategic Building Choices

Scenario 1: Rush Strategy

• Build Stack Silos for quick resource dumping
• Villagers work faster, no sorting time
• Risk: Disorganized late game

Scenario 2: Recipe Master

• Array Barns near crafting stations
• Pre-arrange ingredients in order
• Instant crafting combos

Scenario 3: Trade Empire

• HashMap Markets at island edges
• Instant response to trade requests
• Dominate multiplayer economy

Age-Adaptive Design

Ages 5-8: Visual Programming

• Controls: Drag picture blocks
• Variables: Icons only (🍎=3)
• Functions: Pre-made, single purpose
• Goal: Pattern recognition
• Failure: None - only slower progress

Ages 9-12: Logical Thinking

• Controls: Text + visual blocks
• Variables: Named with math (total = food + wood)
• Functions: Customizable parameters
• Goal: Efficiency optimization
• Failure: Mild slowdowns

Ages 13-15: Code Mastery

• Controls: Syntax-aware editor
• Variables: Typed (int count = 0)
• Functions: Return values, recursion
• Goal: Algorithm optimization
• Failure: Real consequences

Learning Progression

Week 1: Foundations

1. Sequences: Order of operations
2. Variables: Store and track values
3. Functions: Reusable commands
4. Loops: Basic repetition

Week 2-3: Building Blocks

5. Parameters: Flexible functions
6. Conditionals: If-then-else logic
7. Arrays: Organized storage
8. While Loops: Smart repetition

Week 4-6: Problem Solving

9. Debugging: Find and fix errors
10. Nested Loops: Complex patterns
11. Functions with Returns: Calculate values
12. Boolean Logic: AND/OR operations

Advanced Topics (Optional)

• Sorting algorithms (visual races)
• Pathfinding (A* visualization)
• Recursion (tree chopping)
• Objects (custom villagers)

Lesson System & Progression

Core Lesson Unlocks

• Variables: Resource tracking mastery
• Functions: Reusable command sequences
• Loops: Automation fundamentals
• Conditionals: Smart decision making
• Arrays: Organized storage systems
• Algorithms: Advanced efficiency techniques

Progression Mechanics

• Complete tutorials to unlock lessons
• Each lesson includes practice challenges
• Master concepts through gameplay
• Unlock advanced content with mastery
• Compete in concept-specific leaderboards

Educational Value

• Real programming concepts
• Visual learning reinforcement
• Immediate gameplay application
• Progress tracking for parents/teachers
• Skill certificates upon completion

Technical Implementation

Cropout Modifications

1. Villager Enhancement
   • Add variable display system
   • Implement visual programming
   • Create skill card interface
2. Building System
   • Transform storage into data structures
   • Add visual feedback for algorithms
   • Implement debugging mechanics
3. Resource System
   • Add efficiency tracking
   • Create visual comparisons
   • Implement metric collection
4. UI Adaptation
   • Age-specific interfaces
   • Code visualization panel
   • Real-time performance graphs

Detailed Gameplay Mechanics

Resource Gathering Evolution

Phase 1: Manual Chaos (No Programming)

• Click each villager individually
• Click resource, click storage, repeat
• Problem: 50 clicks to gather 10 wood
• Frustration: Watch friends finish faster

Phase 2: Basic Automation (Variables + Loops)

woodGoal = 30
REPEAT until woodGoal reached:
    gather wood
    store wood

• Improvement: 3 clicks instead of 50
• Visible: Progress bar shows wood: 24/30

Phase 3: Smart Gathering (Functions + Conditions)

Function SmartHarvest(resource, amount):
    WHILE (collected < amount):
        target = FindBest(resource)
        IF (target.quality > 80%):
            harvest(target)
        ELSE:
            skip(target)

• Improvement: Higher quality resources
• Visible: Quality meters, efficiency score

Phase 4: Optimized Operations (Algorithms)

• Villagers use pathfinding algorithms
• Sort resources while gathering
• Parallel processing with multiple workers
• Improvement: 400% efficiency gain
• Leaderboard: "You rank #3 in your class!"

Combat Through Debugging

Bug Types and Solutions

Syntax Bug (Typo Monster)

• Appearance: Scrambled letters floating around
• Effect: Villager commands get mixed up
• Solution: Spell-check your code blocks
• Reward: +10% typing speed

Logic Bug (Paradox Ghost)

• Appearance: Villager doing opposite actions
• Effect: Storing food in wood pile
• Solution: Fix IF-THEN conditions
• Reward: Unlock AND/OR gates

Infinite Loop Bug (Spiral Demon)

• Appearance: Hypnotic spinning creature
• Effect: Villager stuck in repetitive action
• Solution: Add break condition
• Reward: Advanced loop controls

Memory Leak (Resource Vampire)

• Appearance: Growing shadow blob
• Effect: Resources slowly disappear
• Solution: Build garbage collector
• Reward: Automatic cleanup system

Daily Challenge Examples

Monday: "Variable Valley"

• Goal: Track 5 different resources simultaneously
• Constraint: Only 3 villagers
• Solution: Use variables to optimize routes
• Leaderboard: Time to reach quotas

Wednesday: "Function Factory"

• Goal: Process 100 mixed resources
• Constraint: Write only 3 functions
• Solution: Parameterized functions with returns
• Leaderboard: Least code used

Friday: "Algorithm Arena"

• Goal: Sort 500 resources by type and quality
• Constraint: Compare sorting methods
• Solution: Implement quicksort
• Leaderboard: Big-O efficiency score

Multiplayer Competitive Modes

Code Golf

• Challenge: Achieve goal with minimum code
• Example: "Gather 50 wood in 10 lines or less"
• Winner: Shortest elegant solution
• Learn: Code optimization

Speed Coding

• Challenge: First to debug and fix broken village
• Setup: Everyone starts with same buggy code
• Winner: Fastest accurate fix
• Learn: Quick problem identification

Efficiency Wars

• Challenge: Best resource-per-minute rate
• Duration: 10-minute rounds
• Winner: Highest efficiency score
• Learn: Algorithm optimization

Leaderboard System

Individual Rankings

Class 5B - This Week's Top Coders
1. Alice     - 2,847 efficiency points ⭐
2. You       - 2,644 efficiency points 
3. Bob       - 2,521 efficiency points
4. Carol     - 2,455 efficiency points

Your Improvements:
- Variables: +400 points
- Loops: +300 points  
- Functions: +250 points

Team Challenges

School Tournament - Quarter Finals
Team Blue Loops vs Team Red Arrays

Challenge: Collaborative Island
- Shared resources
- Combined code
- Real-time cooperation

Concept Mastery Boards

Loops Leaderboard:
1. David - 98% efficiency
2. Eve - 95% efficiency
3. You - 92% efficiency ↑2

Your Best: FOR loop (97%)
Need Work: WHILE loop (87%)

Global Algorithm Championship

• Monthly themed challenges
• Age-bracketed competitions
• Showcase best solutions
• Unlock exclusive content

Building Synergies and Strategies

Production Line Setup

Queue Workshop → Array Barn → HashMap Market
    ↓               ↓              ↓
Raw Materials → Sorted Goods → Instant Trades

• Queue processes materials fairly
• Array stores in recipe order
• HashMap enables quick sales
• Efficiency Gain: 300% faster than random storage

Emergency Response System

IF (under attack):
    Stack Silo provides immediate supplies
ELSE IF (building):
    Array Barn provides exact materials
ELSE:
    Tree Treasury organizes everything

Common Mistakes (Learning Opportunities)

1. All Stacks: Fast input, but retrieval nightmare
2. All Arrays: Limited space, constant reorganizing
3. All Queues: Fair but inflexible
4. Solution: Mixed approach based on use case

Progression Rewards

Performance Tiers

• Wood League: Basic variables and loops
• Stone League: Functions and conditions
• Iron League: Data structures mastery
• Gold League: Algorithm optimization
• Diamond League: System architecture

Unlock Examples

• Score 500+ efficiency → Unlock parallel processing
• Debug 20 bugs → Unlock error prevention tools
• Win 5 multiplayer matches → Unlock advanced algorithms
• Teach 3 friends → Unlock mentor rewards

Social Features

Classroom Integration

• Teacher dashboard shows real-time progress
• Assign specific challenges
• Group students by skill level
• Export performance reports

Friend System

• Share custom islands
• Trade algorithm cards
• Cooperative debugging
• Friendly competitions

Showcase Gallery

• Upload best solutions
• Vote on elegant code
• Learn from others
• Weekly featured coder