🎮 Pokémon FireRed Web Game

A fully functional Pokémon FireRed-style game built with React JS, featuring turn-based battles, world exploration, and clean architecture designed for scalability.

✨ Features

🗺️ World & Movement

• ✅ Tile-based Pokémon-style map system
• ✅ Smooth player movement (WASD or Arrow keys)
• ✅ Camera follows player
• ✅ Collision detection with objects and NPCs
• ✅ Enter buildings (houses, PokéCenter)
• ✅ Multiple interconnected maps

💬 Interaction System

• ✅ Talk to NPCs
• ✅ Dialog system with typewriter effect
• ✅ Read signs and interact with objects
• ✅ Trigger events and story moments

⚔️ Battle System

• ✅ Turn-based Pokémon battles
• ✅ Attack with different moves
• ✅ Switch Pokémon mid-battle
• ✅ Run from wild encounters
• ✅ Trainer battles (can't run)
• ✅ HP bars with color indicators
• ✅ Type-based move system
• ✅ Battle animations

📋 Pokémon Management

• ✅ Party screen (view all Pokémon)
• ✅ Detailed stats display
• ✅ Type badges with colors
• ✅ HP and status indicators
• ✅ Switch Pokémon order
• ✅ Support for up to 6 Pokémon

🏥 PokéCenter

• ✅ Heal all party Pokémon
• ✅ Nurse Joy interaction
• ✅ Healing animation
• ✅ Full HP restoration

🎨 UI/UX

• ✅ Clean, modern UI inspired by Pokémon FireRed
• ✅ Heads-up display (HUD)
• ✅ Quick party view
• ✅ Smooth animations and transitions
• ✅ Keyboard controls with hints
• ✅ Responsive design

🗺️ Map Designer

• ✅ Visual map editor with drag-and-drop
• ✅ 9 brush types (grass, trees, buildings, portals, etc.)
• ✅ Auto-populate maps with nature
• ✅ Layer toggles and zoom controls
• ✅ Export maps as JSON
• ✅ Real-time statistics display
• ✅ Portal visualization
• ✅ Animated tile previews

🌀 Portal System

• ✅ Fast travel between discovered locations
• ✅ Auto-discovery when walking over portals
• ✅ Beautiful portal menu UI
• ✅ Teleportation animations
• ✅ Persistent portal state
• ✅ Multiple portal types (standard, one-way, locked, hidden)

🎯 Game Controls

In Game Mode

Key	Action
W A S D or Arrow Keys	Move player
Enter or Space	Interact / Confirm
E or Enter (on portal)	Use portal
P	Open global portal menu
M	Open party menu
Esc	Cancel / Close

In Map Designer Mode

Action	How To
Select Brush	Click on brush icons in toolbar
Paint Tiles	Click and drag on canvas
Toggle Layers	Check/uncheck layer boxes
Zoom	Use +/− buttons
Auto-Populate	Click "🌳 Populate with Nature"
Export Map	Click "💾 Export Map"

🚀 Quick Start

Prerequisites

• Node.js 16+ installed
• npm or yarn package manager

Installation

# Clone the repository
git clone <your-repo-url>

# Navigate to project directory
cd pokemon-web

# Install dependencies
npm install

# Start development server
npm run dev

The game will be available at http://localhost:5173

Switching Modes

• Click "🎮 Play Game" to play the game
• Click "🎨 Map Designer" to create/edit maps visually

Build for Production

# Create production build
npm run build

# Preview production build
npm run preview

📁 Project Structure

pokemon-web/
├── src/
│   ├── components/         # React components
│   │   ├── Battle/        # Battle system
│   │   ├── Dialog/        # Dialog boxes
│   │   ├── Map/           # Map and world
│   │   ├── MapDesigner/   # 🆕 Visual map editor
│   │   ├── Menu/          # Game menus
│   │   ├── PokeCenter/    # Healing station
│   │   ├── Portal/        # 🆕 Portal system
│   │   └── UI/            # HUD and UI
│   ├── contexts/          # React Context (state management)
│   ├── data/              # JSON data files
│   │   ├── pokemon/       # Pokémon data
│   │   ├── moves/         # Move data
│   │   ├── trainers/      # Trainer/NPC data
│   │   ├── maps/          # Map layouts
│   │   └── items/         # Item data
│   ├── hooks/             # Custom React hooks
│   ├── pages/             # Main game page
│   ├── services/          # API service layer
│   │   ├── api.js         # Fake API
│   │   ├── battleService.js    # Battle engine
│   │   ├── encounterService.js # Wild encounters
│   │   └── portalService.js    # 🆕 Portal management
│   └── utils/             # Utility functions
├── ARCHITECTURE.md        # Detailed architecture docs
├── IMPROVEMENTS_GUIDE.md  # Extensions documentation
├── PORTAL_SYSTEM.md       # 🆕 Portal system guide
├── MAP_DESIGNER_GUIDE.md  # 🆕 Map designer guide
└── README.md             # This file

🏗️ Architecture Highlights

Clean Architecture

• Component Separation: Each component has a single responsibility
• Service Layer: Fake API that can be easily swapped with real endpoints
• State Management: Context API + useReducer for predictable state
• Custom Hooks: Game logic separated from UI components

Data Flow

User Input → Hooks → Actions → State Update → Component Re-render
                ↓
           API Service

API Service Layer

The game uses a fake API service that loads local JSON files asynchronously:

// Current implementation
const result = await pokemonAPI.getAll();
// Loads from: src/data/pokemon/pokemon.json

// Future: Just change the service, not the components!
const result = await fetch('/api/pokemon').then(r => r.json());

All components are already prepared for real API integration! They handle:

• ✅ Loading states
• ✅ Error handling
• ✅ Async data

See ARCHITECTURE.md for complete documentation.

🎮 Gameplay

Starting the Game

1. You start in Pallet Town with 3 starter Pokémon:

   • Charmander (Fire type)
   • Squirtle (Water type)
   • Bulbasaur (Grass/Poison type)

2. Use WASD or Arrow Keys to move around

3. Press Enter/Space to interact with NPCs and objects

Wild Pokémon Encounters

• Walk through grass to trigger random wild Pokémon encounters
• Encounter rate: ~15% per step in grass
• You can Run from wild battles

Trainer Battles

• Trainers will challenge you when you enter their line of sight
• You cannot run from trainer battles
• Defeat trainers to mark them as defeated

Healing Your Pokémon

1. Enter the PokéCenter (red building)
2. Talk to Nurse Joy
3. Accept healing to restore all Pokémon to full HP

Managing Your Party

• Press M to open the party menu
• View detailed stats for each Pokémon
• Switch Pokémon order by clicking

📊 Game Data

Pokémon (5 included)

• Charmander (Fire)
• Squirtle (Water)
• Bulbasaur (Grass/Poison)
• Pikachu (Electric)
• Rattata (Normal)

Moves (5 included)

• Scratch (Normal)
• Tackle (Normal)
• Water Gun (Water)
• Bite (Dark)
• Vine Whip (Grass)

Maps (5 included)

• Pallet Town
• Route 1
• Viridian City
• PokéCenter (interior)
• Player House (interior)

NPCs/Trainers (5 included)

• Bug Catcher Joey (Trainer)
• Nurse Joy (Healer)
• Professor Oak (Story NPC)
• Youngster Ben (Trainer)
• Shop Keeper (Merchant)

Items (5 included)

• Potion (Heal 20 HP)
• Super Potion (Heal 50 HP)
• Poké Ball (Catch Pokémon)
• Antidote (Cure poison)
• Escape Rope (Escape dungeons)

🔧 Customization

Adding New Pokémon

1. Add entry to src/data/pokemon/pokemon.json:

{
  "id": 6,
  "name": "Charizard",
  "type": ["fire", "flying"],
  "baseStats": {
    "hp": 78,
    "attack": 84,
    "defense": 78,
    "speed": 100
  },
  "moves": [1, 2],
  "sprite": "charizard.png",
  "level": 36
}

2. The API service will automatically load it!

Adding New Maps

Option 1: Use the Map Designer (Recommended)

1. Click "🎨 Map Designer" button
2. Click "🌳 Populate with Nature" for instant terrain
3. Use brush tools to customize
4. Click "💾 Export Map" to download JSON
5. Add JSON to src/data/maps/maps.json

Option 2: Manual JSON Editing Edit src/data/maps/maps.json to add new map layouts with tiles, collisions, and encounters.

See MAP_DESIGNER_GUIDE.md for complete instructions.

Adding New Moves

Edit src/data/moves/moves.json to add new moves with type, power, and accuracy.

🚀 Future Enhancements

Planned Features

• Inventory system (use items in battle)
• Experience and leveling system
• Pokémon evolution
• Type effectiveness chart
• Status conditions (poison, burn, etc.)
• Save/Load game (LocalStorage)
• Sound effects and music
• More maps and Pokémon
• Catching wild Pokémon
• Trading system

Backend Integration

• REST API backend (Node.js + Express)
• PostgreSQL database
• User authentication
• Online battles
• Cloud save system

🛠️ Development

Tech Stack

• React 18.3.1 - UI framework
• Vite 5.4.2 - Build tool
• Context API - State management
• CSS3 - Styling and animations
• Press Start 2P - Retro game font

Code Quality

• ✅ Functional components with hooks
• ✅ Clean separation of concerns
• ✅ Commented code explaining decisions
• ✅ Reusable components and hooks
• ✅ Type-safe props (via JSDoc comments)
• ✅ No hardcoded data in components

Performance

• ✅ Optimized re-renders
• ✅ CSS animations (GPU accelerated)
• ✅ Event throttling for movement
• ✅ Lazy loading of data
• ✅ Small bundle size (~172KB)

📖 Documentation

• ARCHITECTURE.md - Complete architecture documentation
• IMPROVEMENTS_GUIDE.md - Wild encounters, battle AI, map transitions
• PORTAL_SYSTEM.md - Portal/fast travel system guide
• MAP_DESIGNER_GUIDE.md - Visual map editor documentation
• MAP_DESIGNER_SUMMARY.md - Map designer implementation details
• Code comments throughout the project
• JSDoc documentation for complex functions

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License.

🙏 Acknowledgments

• Inspired by Pokémon FireRed by Game Freak
• Built with React by Facebook/Meta
• Font: Press Start 2P by CodeMan38

📧 Contact

For questions or feedback, please open an issue on GitHub.

---

Built with ❤️ and React by a senior game engineer and front-end architect

This is a fan project and is not affiliated with Nintendo, Game Freak, or The Pokémon Company.