novafarma/docs/PHASE28_WORLD_EXPANSION_PLAN.md

🌍 PHASE 28: WORLD EXPANSION - Implementation Plan

Start Date: 15.12.2025
Estimated Duration: 10-20 hours
Status: IN PROGRESS

---

📋 PROJECT OVERVIEW

Transform the game from a small 100x100 farm to a massive explorable world with multiple biomes, rivers, roads, and points of interest.

Key Goals:

1. Expand map from 100x100 to 500x500 tiles (25x larger!)
2. Implement 5 distinct biomes with unique features
3. Add smooth biome transitions
4. Create rivers, lakes, and natural features
5. Implement chunk loading for performance
6. Add roads, ruins, and landmarks

---

🎯 SESSION BREAKDOWN

SESSION 1: FOUNDATION (2-3h) - 15.12.2025 ✅ IN PROGRESS

Goal: Set up core systems and expand world size

Tasks:

• Create implementation plan document
• Create BiomeSystem.js
• Expand Flat2DTerrainSystem to support 500x500
• Implement chunk loading system
• Test performance with larger map
• Update camera bounds

Deliverables:

• BiomeSystem.js (~300 lines)
• Updated Flat2DTerrainSystem.js
• ChunkManager.js (~200 lines)
• 500x500 map generation working

---

SESSION 2: BIOMES - BASIC (3-4h) - Future

Goal: Implement first 2 biomes (Grassland, Forest)

Tasks:

• Grassland biome (current default)
• Forest biome (dense trees, wildlife)
• Biome data structures
• Biome-specific tile generation
• Biome boundaries and transitions

Deliverables:

• 2 working biomes
• Smooth transitions between them

---

SESSION 3: BIOMES - ADVANCED (3-4h) - Future

Goal: Implement remaining 3 biomes

Tasks:

• Desert biome (sand, cacti, heat)
• Mountain biome (rocks, caves, snow)
• Swamp biome (water, fog, danger)

Deliverables:

• 5 total biomes functional
• Unique visual identity for each

---

SESSION 4: WORLD FEATURES (2-3h) - Future

Goal: Add natural features (rivers, lakes)

Tasks:

• River generation algorithm
• Lake placement system
• Water flow simulation (visual)
• Shoreline transition tiles

Deliverables:

• Realistic rivers crossing map
• Natural-looking lakes

---

SESSION 5: STRUCTURES (2-3h) - Future

Goal: Add roads, paths, and ruins

Tasks:

• Road generation (connecting biomes)
• Path network
• Ruin structures (abandoned buildings)
• Landmarks (towers, monuments)

Deliverables:

• Road system
• 5-10 unique ruins
• 3-5 landmarks

---

SESSION 6: POLISH & OPTIMIZATION (1-2h) - Future

Goal: Performance and visual polish

Tasks:

• Optimize chunk loading
• Minimap for 500x500 world
• Fog of war (unexplored areas)
• Biome-specific weather
• Performance profiling

Deliverables:

• Smooth 60 FPS on 500x500 map
• Polished minimap
• Complete world expansion

---

🏗️ TECHNICAL ARCHITECTURE

1. BiomeSystem

class BiomeSystem {
    biomes = {
        grassland: { color, features, spawns },
        forest: { color, features, spawns },
        desert: { color, features, spawns },
        mountain: { color, features, spawns },
        swamp: { color, features, spawns }
    }
    
    getBiomeAt(x, y) // Returns biome type
    generateBiomeMap() // Perlin noise-based
    applyBiomeFeatures() // Trees, rocks, etc.
}

2. ChunkManager

class ChunkManager {
    chunkSize = 50 // 50x50 tiles per chunk
    activeChunks = new Map()
    
    loadChunk(chunkX, chunkY)
    unloadChunk(chunkX, chunkY)
    updateActiveChunks(playerX, playerY)
}

3. Expanded TerrainSystem

• Support 500x500 tiles
• Biome-aware tile generation
• Chunk-based rendering
• LOD (Level of Detail) for distant chunks

---

📊 TECHNICAL SPECS

Map Size:

• Current: 100x100 = 10,000 tiles
• New: 500x500 = 250,000 tiles
• Increase: 25x larger!

Chunk System:

• Chunk Size: 50x50 tiles (2,500 tiles)
• Total Chunks: 10x10 = 100 chunks
• Active Chunks: ~9 (3x3 around player)
• Loaded Tiles: ~22,500 at once (9 chunks)

Performance Target:

• FPS: 60 stable
• Load Time: <2 seconds
• Memory: <500MB

---

🎨 BIOME SPECIFICATIONS

1. Grassland (Current Default)

• Color: Green (#4a9d5f)
• Features: Grass, flowers, small trees
• Weather: Normal rainfall
• Spawns: Farm animals, basic wildlife

2. Forest 🌲

• Color: Dark green (#2d5016)
• Features: Dense trees (60% coverage), bushes, mushrooms
• Weather: More rain, shade
• Spawns: Deer, bears, wolves
• Resources: Wood (abundant), berries

3. Desert 🏜️

• Color: Tan/sand (#d4c4a1)
• Features: Sand, cacti, dead trees, rocks
• Weather: Hot, no rain, sandstorms
• Spawns: Scorpions, snakes, lizards
• Resources: Stone, rare plants
• Hazard: Heat damage without protection

4. Mountain ⛰️

• Color: Gray/stone (#808080)
• Features: Rocks, cliffs, snow (high altitude), caves
• Weather: Cold, snow at peaks
• Spawns: Mountain goats, eagles
• Resources: Stone (abundant), ore, gems
• Hazard: Cold damage at peaks

5. Swamp 🌿

• Color: Dark green/brown (#3d5a3d)
• Features: Water patches, fog, dead trees, vines
• Weather: Foggy, humid
• Spawns: Frogs, snakes, mosquitos, zombies (more)
• Resources: Rare herbs, swamp plants
• Hazard: Poison damage, slow movement

---

🗺️ WORLD LAYOUT STRATEGY

Biome Distribution (500x500 map):

[Mountain]  [Mountain]  [Forest]    [Forest]    [Grassland]
[Mountain]  [Forest]    [Forest]    [Grassland] [Grassland]
[Forest]    [Forest]    [FARM]      [Grassland] [Desert]
[Swamp]     [Forest]    [Grassland] [Desert]    [Desert]
[Swamp]     [Swamp]     [Desert]    [Desert]    [Desert]

Farm Location: Center (250, 250) - always Grassland biome
Biome Sizes: 100-150 tile radius
Transitions: 20-30 tile gradual blend zones

---

🔧 IMPLEMENTATION PRIORITIES

Critical (Must Have):

1. ✅ BiomeSystem core
2. ✅ 500x500 map expansion
3. ✅ Chunk loading
4. ✅ 2 biomes (Grassland, Forest)

High Priority:

5. Desert, Mountain, Swamp biomes
6. Rivers and lakes
7. Biome transitions

Medium Priority:

8. Roads and paths
9. Ruins and structures
10. Minimap

Low Priority:

11. Fog of war
12. Biome-specific weather
13. Advanced landmarks

---

📈 SUCCESS METRICS

Technical:

• 500x500 map loads successfully
• 60 FPS maintained
• No memory leaks
• Smooth chunk loading

Gameplay:

• 5 distinct biomes visible
• Smooth biome transitions
• Rivers flow naturally
• World feels explorable

Visual:

• Each biome has unique appearance
• Transitions look natural
• Features placed realistically
• Professional quality

---

⚠️ KNOWN CHALLENGES

1. Performance: 250k tiles is HUGE - need efficient chunk system
2. Transitions: Making biome blends look natural
3. Rivers: Pathfinding algorithm for natural flow
4. Balance: Each biome must feel equally interesting
5. Generation: Repeatable seed-based world gen

---

🚀 GETTING STARTED (SESSION 1)

Today's immediate tasks:

1. Create BiomeSystem.js skeleton
2. Expand Flat2DTerrainSystem to 500x500
3. Create ChunkManager.js
4. Test with simple 2-biome setup
5. Verify performance

Time: 2-3 hours
Complexity: High
Impact: Foundation for entire expansion

---

📚 RESOURCES

• Perlin Noise: For biome generation
• Phaser Tilemap: Chunk management
• Minimap: MinimapSystem.js (existing)
• Camera: Update bounds to 500x500

---

Ready to start Session 1! 🚀

Let's build this massive world! 🌍