# 🎮 Text Mafia Browser Game - Project Plan

**Inspired by Omerta & Torn City**  
**Built with Laravel**  
**Last Updated:** 2026-06-26

---

## 📋 Overview

A persistent browser-based text MMORPG where players build criminal empires, join factions, commit crimes, trade items, and engage in PvP/PvE combat. The game features deep economic systems, territory control, and social interactions.

---

## 🎯 Core Concept

- **Persistent World**: Game state continues even when players are offline
- **Text-Based**: Primary interface is text with minimal graphics
- **Turn-Based Actions**: Most actions cost energy and have cooldowns
- **Player-Driven Economy**: Players trade, control markets, and manage resources
- **Faction Warfare**: Competing criminal organizations battle for control
- **Progression System**: Level up characters through experience and training

---

## 📊 Phase Breakdown

---

### 🔹 Phase 1: Foundation (2-3 weeks)
*Core infrastructure, user management, and basic game loop*

| Priority | Feature | Description | Laravel Components |
|----------|---------|-------------|-------------------|
| ⭐⭐⭐ | **User Authentication** | Registration, login, password reset, email verification | `Auth`, `Breeze`, `Sanctum` |
| ⭐⭐⭐ | **Character Creation** | Name, gender, starting stats, backstory | `Character` model, migration, factory |
| ⭐⭐⭐ | **Basic Game UI** | Layout, navigation, responsive design | Blade templates, Tailwind CSS |
| ⭐⭐⭐ | **Energy System** | Actions cost energy, regenerates over time | `energy` column, scheduler |
| ⭐⭐⭐ | **Health System** | HP, hospital on death, regen timer | `health`, `in_hospital` columns |
| ⭐⭐ | **Basic Crimes** | Simple crimes (pickpocket, mugging) | `Crime`, `CrimeAttempt` models |
| ⭐⭐ | **Inventory System** | Items, equipment, consumables | `Item`, `Inventory` pivot table |
| ⭐⭐ | **Money System** | Cash, bank, interest | `money`, `bank` columns |
| ⭐ | **User Profile** | Stats display, avatar, status | `Profile` component |
| ⭐ | **News/Feed System** | Global and user-specific events | `ActivityLog`, `Notification` |

**Deliverables:**
- Working Laravel application with authentication
- Character creation flow
- Energy and health systems with regeneration
- 5-10 basic crimes to commit
- Inventory with item management
- Basic UI with navigation

---

### 🔹 Phase 2: Core Gameplay (3-4 weeks)
*Economy, combat, and faction basics*

| Priority | Feature | Description | Laravel Components |
|----------|---------|-------------|-------------------|
| ⭐⭐⭐ | **Attack System** | Attack other players, hit lists | `Attack`, `Hit` models, cooldowns |
| ⭐⭐⭐ | **Faction System** | Create/join factions, ranks, chat | `Faction`, `FactionMember`, `FactionChat` |
| ⭐⭐⭐ | **Skills System** | Strength, defense, speed, dexterity | `skill_*` columns, training |
| ⭐⭐⭐ | **Item Market** | Buy/sell items from other players | `MarketListing` model |
| ⭐⭐ | **Shops** | NPC shops for weapons, armor, items | `Shop`, `ShopItem` models |
| ⭐⭐ | **Jail System** | Sentenced after losing attacks | `jail_time` column, release scheduler |
| ⭐⭐ | **Hospital System** | Revive after death, medical items | `hospital_time`, `revive_cost` |
| ⭐⭐ | **Travel System** | Travel between cities/countries | `Location` model, travel costs |
| ⭐ | **Bank System** | Deposit/withdraw, interest | `Bank` model, daily interest job |
| ⭐ | **Mail System** | Send/receive messages | `Mail` model, `read_at` timestamp |

**Deliverables:**
- Full PvP combat system
- Faction creation and management
- Skill training and progression
- Player-to-player marketplace
- Jail and hospital mechanics
- Travel between multiple locations

---

### 🔹 Phase 3: Advanced Features (4-5 weeks)
*Depth, strategy, and social systems*

| Priority | Feature | Description | Laravel Components |
|----------|---------|-------------|-------------------|
| ⭐⭐⭐ | **Faction Wars** | Faction vs faction warfare | `FactionWar`, `WarAttack` models |
| ⭐⭐⭐ | **Territory System** | Control areas for bonuses | `Territory`, `TerritoryControl` |
| ⭐⭐⭐ | **Missions/Quests** | Storyline and daily missions | `Mission`, `MissionStep` models |
| ⭐⭐ | **Casino** | Gambling games (roulette, blackjack) | `CasinoGame`, `Bet` models |
| ⭐⭐ | **Stock Market** | Invest in game companies | `Stock`, `Portfolio` models |
| ⭐⭐ | **Properties** | Buy houses, businesses | `Property`, `PropertyUpgrade` |
| ⭐⭐ | **Vehicles** | Faster travel, combat bonuses | `Vehicle` model |
| ⭐⭐ | **Awards/Medals** | Achievements system | `Award`, `UserAward` |
| ⭐ | **Bounties** | Place bounties on players | `Bounty` model |
| ⭐ | **Alliances** | Faction alliances | `Alliance` pivot table |
| ⭐ | **Spies** | Infiltrate other factions | `SpyReport` model |
| ⭐ | **Merits** | Premium currency system | `merits` column |

**Deliverables:**
- Faction warfare and territory control
- Mission/quest system with rewards
- Casino with multiple games
- Stock market with fluctuations
- Property ownership system
- Advanced social features

---

### 🔹 Phase 4: Polish & Scale (2-3 weeks)
*Performance, moderation, and extras*

| Priority | Feature | Description | Laravel Components |
|----------|---------|-------------|-------------------|
| ⭐⭐⭐ | **Admin Panel** | Manage users, items, economy | `Nova` or custom admin |
| ⭐⭐⭐ | **Moderation Tools** | Ban, mute, freeze users | `ModerationLog` model |
| ⭐⭐ | **API for Mobile** | REST/GraphQL endpoints | `Sanctum`, API resources |
| ⭐⭐ | **Real-time Chat** | WebSocket-based chat | `Laravel Echo`, `Pusher` |
| ⭐⭐ | **Leaderboards** | Top players, factions, wealth | Cached queries, weekly resets |
| ⭐⭐ | **Event System** | Holiday events, double XP | `GameEvent` model |
| ⭐ | **Referral System** | Invite friends for rewards | `Referral` model |
| ⭐ | **Two-Factor Auth** | Security for accounts | `Jetstream` 2FA |
| ⭐ | **Backup System** | Database backups | Scheduled commands |
| ⭐ | **Caching** | Optimize performance | Redis, cache helpers |

**Deliverables:**
- Full admin dashboard
- Moderation capabilities
- Mobile API (if needed)
- Real-time features
- Performance optimizations

---

## 🗄️ Database Schema

### Core Tables (Phase 1-2)

```sql
-- Users & Characters
users (id, name, email, password, email_verified_at, last_active_at, ip_address, user_agent, created_at, updated_at)
characters (id, user_id, name, gender, level, experience, money, bank, energy, max_energy, 
            health, max_health, strength, defense, speed, dexterity, location_id, 
            faction_id, in_hospital_until, in_jail_until, last_action_at, status, created_at, updated_at)

-- Game World
locations (id, name, slug, description, travel_cost, requires_level, faction_control, created_at)

-- Economy
items (id, name, slug, description, type, value, buy_price, sell_price, requires_level, 
      attack_bonus, defense_bonus, health_bonus, energy_bonus, is_tradeable, is_usable, created_at)
inventories (id, character_id, item_id, quantity, equipped, created_at, updated_at)
shops (id, name, slug, location_id, restock_interval, restock_amount, created_at)
shop_items (id, shop_id, item_id, stock, price, created_at, updated_at)

-- Actions
crimes (id, name, slug, description, difficulty, success_rate, reward_min, reward_max, 
        experience, energy_cost, cooldown, requires_level, location_id, created_at)
crime_attempts (id, character_id, crime_id, success, reward, experience_gained, attempted_at)

attacks (id, attacker_id, defender_id, attacker_health_after, defender_health_after,
        attacker_damage, defender_damage, weapon_id, armor_id, result, attacked_at)
hits (id, target_id, bounty, placed_by_id, expires_at, claimed_by_id, claimed_at, created_at)

-- Factions
factions (id, name, tag, slug, description, leader_id, bank, respect, founded_at, created_at)
faction_members (id, faction_id, character_id, rank, joined_at, created_at)
faction_ranks (id, faction_id, name, level_requirement, permissions, created_at)
faction_chat (id, faction_id, character_id, message, created_at)

-- Communication
mail (id, sender_id, recipient_id, subject, body, read_at, is_system, created_at)
notifications (id, user_id, type, data, read_at, created_at)

-- System
activity_logs (id, character_id, action, description, ip_address, user_agent, created_at)
game_events (id, name, slug, description, start_at, end_at, is_active, created_at)
```

### Additional Tables (Phase 3-4)

```sql
-- Phase 3
missions (id, name, slug, description, type, difficulty, reward_money, reward_exp, reward_item_id, cooldown, created_at)
mission_steps (id, mission_id, step_number, description, requirements, created_at)
character_missions (id, character_id, mission_id, step_completed, completed_at, created_at)

faction_wars (id, attacker_faction_id, defender_faction_id, started_by_id, start_reason, 
              start_at, end_at, status, winner_faction_id, created_at)
war_attacks (id, war_id, attacking_faction_id, defending_faction_id, attacker_id, defender_id, 
             attacker_damage, defender_damage, result, attacked_at)
territories (id, name, slug, location_id, controlling_faction_id, income_bonus, defense_bonus, created_at)

stocks (id, company_name, symbol, current_price, min_price, max_price, volatility, created_at)
portfolios (id, character_id, stock_id, quantity, average_price, created_at, updated_at)
stock_history (id, stock_id, price, volume, recorded_at)

properties (id, name, slug, location_id, owner_id, type, level, purchase_price, sell_price, 
           income_per_hour, defense_bonus, storage_capacity, created_at)
vehicles (id, name, slug, type, speed_bonus, attack_bonus, defense_bonus, purchase_price, 
         sell_price, fuel_capacity, fuel_consumption, created_at)
character_vehicles (id, character_id, vehicle_id, fuel, created_at)

-- Phase 4
bounties (id, target_id, amount, placed_by_id, reason, expires_at, claimed_by_id, claimed_at, created_at)
alliances (id, faction_id_1, faction_id_2, initiated_by_id, status, created_at, accepted_at, ended_at)
spy_reports (id, faction_id, target_faction_id, reported_by_id, report_type, data, created_at)
awards (id, name, slug, description, icon, created_at)
character_awards (id, character_id, award_id, awarded_at, created_at)

referrals (id, referrer_id, referred_id, code, reward_claimed, created_at)
moderation_logs (id, moderator_id, target_id, action, reason, duration, expires_at, created_at)

-- Admin
admin_settings (id, key, value, description, created_at, updated_at)
reports (id, reporter_id, reported_id, type, reason, status, handled_by_id, handled_at, created_at)
```

---

## 🏗️ Laravel Architecture

### Directory Structure

```
app/
├── Console/
│   └── Commands/
│       ├── Game/
│       │   ├── ProcessEnergyRegen.php
│       │   ├── ProcessHealthRegen.php
│       │   ├── ReleaseFromJail.php
│       │   ├── ReleaseFromHospital.php
│       │   ├── DailyInterest.php
│       │   └── RestockShops.php
│       └── ...
├── Http/
│   ├── Controllers/
│   │   ├── Auth/
│   │   │   └── (Laravel default)
│   │   ├── Game/
│   │   │   ├── CharacterController.php
│   │   │   ├── CrimeController.php
│   │   │   ├── AttackController.php
│   │   │   ├── FactionController.php
│   │   │   ├── InventoryController.php
│   │   │   ├── ShopController.php
│   │   │   ├── MarketController.php
│   │   │   ├── MailController.php
│   │   │   └── ...
│   │   └── Admin/
│   │       ├── DashboardController.php
│   │       ├── UserController.php
│   │       └── ...
│   ├── Middleware/
│   │   ├── CheckEnergy.php
│   │   ├── CheckInJail.php
│   │   ├── CheckInHospital.php
│   │   ├── VerifyCharacter.php
│   │   ├── CheckLevel.php
│   │   ├── RateLimitActions.php
│   │   └── LogActivity.php
│   └── Requests/
│       ├── Game/
│       │   ├── AttemptCrimeRequest.php
│       │   ├── AttackRequest.php
│       │   └── ...
│       └── Admin/
├── Models/
│   ├── Character.php
│   ├── Crime.php
│   ├── Faction.php
│   ├── Item.php
│   ├── Attack.php
│   ├── Location.php
│   ├── ActivityLog.php
│   ├── Notification.php
│   └── ...
├── Policies/
│   ├── CharacterPolicy.php
│   ├── FactionPolicy.php
│   └── ...
├── Services/
│   ├── Game/
│   │   ├── CombatService.php
│   │   ├── EconomyService.php
│   │   ├── EnergyService.php
│   │   ├── CrimeService.php
│   │   ├── FactionService.php
│   │   ├── InventoryService.php
│   │   └── NotificationService.php
│   └── ...
├── Traits/
│   ├── HasCharacter.php
│   ├── HasInventory.php
│   ├── HasExperience.php
│   └── ...
├── Enums/
│   ├── ActionResult.php
│   ├── AttackResult.php
│   ├── CharacterStatus.php
│   ├── CrimeType.php
│   ├── ItemType.php
│   └── ...
└── Providers/
    └── GameServiceProvider.php

routes/
├── web.php
├── api.php
└── channels.php

resources/
├── views/
│   ├── layouts/
│   │   ├── app.blade.php
│   │   ├── game.blade.php
│   │   └── auth.blade.php
│   ├── game/
│   │   ├── partials/
│   │   │   ├── energy-bar.blade.php
│   │   │   ├── health-bar.blade.php
│   │   │   ├── nav.blade.php
│   │   │   ├── notifications.blade.php
│   │   │   └── ...
│   │   ├── dashboard.blade.php
│   │   ├── character/
│   │   │   ├── show.blade.php
│   │   │   ├── create.blade.php
│   │   │   └── edit.blade.php
│   │   ├── crimes/
│   │   │   ├── index.blade.php
│   │   │   └── attempt.blade.php
│   │   ├── attack/
│   │   │   ├── index.blade.php
│   │   │   └── hit-list.blade.php
│   │   ├── factions/
│   │   │   ├── index.blade.php
│   │   │   ├── show.blade.php
│   │   │   └── manage.blade.php
│   │   ├── inventory.blade.php
│   │   ├── shops.blade.php
│   │   ├── market.blade.php
│   │   ├── mail/
│   │   │   ├── inbox.blade.php
│   │   │   └── compose.blade.php
│   │   └── leaderboards.blade.php
│   └── auth/
│       └── (Laravel default)
└── lang/
    └── en/
        ├── game.php
        └── ...

database/
├── migrations/
├── seeders/
└── factories/

public/
├── css/
├── js/
└── images/

config/
├── game.php
└── ...

storage/
logs/

 tests/
```

---

### Key Services (Business Logic Layer)

| Service | Purpose | Key Methods |
|---------|---------|-------------|
| **CombatService** | Handles all attack calculations | `calculateDamage()`, `processAttack()`, `determineWinner()`, `applyCrit()` |
| **EconomyService** | Money, bank, transactions | `transfer()`, `deposit()`, `withdraw()`, `applyInterest()`, `addMoney()`, `removeMoney()` |
| **EnergyService** | Energy management | `consumeEnergy()`, `regenEnergy()`, `getMaxEnergy()`, `getRegenRate()` |
| **HealthService** | Health management | `takeDamage()`, `heal()`, `revive()`, `isDead()`, `isInHospital()` |
| **CrimeService** | Crime attempts | `attemptCrime()`, `calculateSuccess()`, `applyRewards()`, `applyPenalties()` |
| **FactionService** | Faction operations | `createFaction()`, `joinFaction()`, `leaveFaction()`, `promoteMember()`, `demoteMember()` |
| **InventoryService** | Item management | `addItem()`, `removeItem()`, `useItem()`, `equipItem()`, `unequipItem()` |
| **NotificationService** | User notifications | `sendNotification()`, `broadcastEvent()`, `factionAnnouncement()`, `systemMessage()` |
| **TravelService** | Location travel | `travelTo()`, `calculateCost()`, `isUnlocked()`, `getLocations()` |
| **MarketService** | Player marketplace | `createListing()`, `purchaseListing()`, `cancelListing()`, `getListings()` |

---

## ⚡ Scheduled Commands

```php
// In app/Console/Kernel.php

protected function schedule(Schedule $schedule)
{
    // Energy regen (every 5 minutes)
    $schedule->command('game:regen-energy')->everyFiveMinutes()->name('energy-regen');

    // Health regen (every 10 minutes)
    $schedule->command('game:regen-health')->everyTenMinutes()->name('health-regen');

    // Release from hospital (every minute)
    $schedule->command('game:release-hospital')->everyMinute()->name('hospital-release');

    // Release from jail (every minute)
    $schedule->command('game:release-jail')->everyMinute()->name('jail-release');

    // Daily bank interest (midnight)
    $schedule->command('game:daily-interest')->dailyAt('00:00')->name('daily-interest');

    // Restock shops (every 6 hours)
    $schedule->command('game:restock-shops')->everySixHours()->name('restock-shops');

    // Cleanup old activity (daily)
    $schedule->command('game:cleanup-logs')->dailyAt('01:00')->name('cleanup-logs');

    // Faction wars reset (weekly)
    $schedule->command('game:reset-wars')->weekly()->mondays()->at('00:00')->name('reset-wars');

    // Process cooldowns (every minute)
    $schedule->command('game:process-cooldowns')->everyMinute()->name('process-cooldowns');

    // Update leaderboards (hourly)
    $schedule->command('game:update-leaderboards')->hourly()->name('update-leaderboards');
}
```

---

## 🛡️ Middleware

| Middleware | Purpose | Logic |
|------------|---------|-------|
| **CheckEnergy** | Ensure user has enough energy | Redirect if energy < action cost |
| **CheckInJail** | Block actions if in jail | Redirect to jail page with release time |
| **CheckInHospital** | Block actions if in hospital | Redirect to hospital page with release time |
| **VerifyCharacter** | Ensure user has a character | Redirect to character creation |
| **CheckLevel** | Verify level requirements | Abort 403 if level too low |
| **RateLimitActions** | Prevent action spamming | Throttle by action type (configurable) |
| **LogActivity** | Track user actions | Create activity log entries automatically |
| **CheckCooldown** | Prevent action spamming | Check if action is on cooldown |
| **CheckAlive** | Ensure character is alive | Redirect if health <= 0 |

---

## 🎨 Frontend Approach

### Tech Stack
- **CSS Framework**: Tailwind CSS (via Laravel Breeze)
- **JavaScript**: Alpine.js (lightweight reactivity)
- **Real-time**: Laravel Echo + Pusher (for chat, notifications)
- **Charts**: Chart.js (for stats, leaderboards)
- **Icons**: Heroicons or Font Awesome

### Key Pages

#### Phase 1 Pages
1. **Home/Dashboard** - Overview, stats, recent activity, quick actions
2. **Character Create** - Name, gender, starting stats selection
3. **Character Profile** - Stats, equipment, achievements
4. **Crimes** - Available crimes list, attempt history
5. **Inventory** - Items, equipment, use/equip actions
6. **Shops** - Browse and purchase items
7. **City/Locations** - Current location info, available actions
8. **Leaderboards** - Top players by level, money, etc.

#### Phase 2 Pages
9. **Attack** - Find targets, view hit lists, attack history
10. **Factions** - Faction list, create/join, member list
11. **Faction Management** - Ranks, members, bank, chat
12. **Market** - Player-to-player item trading
13. **Mail** - Inbox, compose, read messages
14. **Bank** - Deposit, withdraw, transfer
15. **Travel** - Map, travel between locations
16. **Jail** - Current sentence, breakout attempt
17. **Hospital** - Revive options, healing items

#### Phase 3+ Pages
18. **Missions** - Available missions, progress tracking
19. **Faction Wars** - Active wars, attack history
20. **Territory** - Controlled areas, income bonuses
21. **Casino** - Gambling games
22. **Stock Market** - Company listings, portfolio
23. **Properties** - Owned properties, upgrades
24. **Admin Dashboard** - User management, game settings

### UI Components (Blade + Alpine)

```html
<!-- Energy Bar Component -->
<div class="w-full bg-gray-200 rounded-full h-4">
    <div 
        class="bg-blue-600 h-4 rounded-full transition-all duration-500"
        style="width: {{ $character->energy_percentage }}%"
        x-data="{ energy: {{ $character->energy }}, max: {{ $character->max_energy }} }"
        x-text="energy + '/' + max"
    ></div>
</div>

<!-- Cooldown Timer -->
<span 
    x-data="{ 
        cooldown: {{ $cooldownSeconds }}, 
        formatTime(seconds) { 
            const mins = Math.floor(seconds / 60);
            const secs = seconds % 60;
            return `${mins}:${secs.toString().padStart(2, '0')}`;
        }
    }"
    x-text="formatTime(cooldown)"
    x-init="setInterval(() => { if(cooldown > 0) cooldown--; }, 1000)"
></span>

<!-- Action Button with Energy Check -->
<button 
    @click="attemptCrime({{ $crime->id }})"
    :disabled="energy < {{ $crime->energy_cost }}"
    class="px-4 py-2 bg-blue-600 text-white rounded disabled:opacity-50"
>
    Attempt ({{ $crime->energy_cost }} energy)
</button>
```

---

## ⚙️ Game Configuration

```php
// config/game.php

return [
    'energy' => [
        'start_amount' => 100,
        'max' => 100,
        'regen_rate' => 5,          // Energy regenerated per interval
        'regen_interval' => 300,    // Seconds between regen (5 minutes)
        'action_costs' => [
            'crime' => 10,
            'attack' => 15,
            'travel' => 5,
            'train' => 20,
        ],
    ],

    'health' => [
        'start_amount' => 100,
        'max' => 100,
        'regen_rate' => 2,          // Health regenerated per interval
        'regen_interval' => 600,    // Seconds between regen (10 minutes)
        'hospital_cost' => 1000,    // Cost to revive from hospital
        'death_threshold' => 0,     // Health <= 0 = dead
    ],

    'combat' => [
        'base_damage' => 5,
        'damage_variation' => 0.20, // +/- 20% random variation
        'crit_chance' => 0.10,      // 10% chance for critical hit
        'crit_multiplier' => 2.0,    // Critical hits do 2x damage
        'defense_reduction' => 0.5, // Each defense point reduces damage by 0.5
        'min_damage' => 1,          // Minimum damage per hit
        'attack_cooldown' => 300,   // 5 minutes between attacks
        'hit_list_cost' => 5000,    // Cost to place a hit
    ],

    'crime' => [
        'success_rate' => 0.70,     // 70% base success rate
        'failure_penalty' => 0.10,  // 10% health loss on failure
        'cooldown_reduction' => 0.10, // 10% cooldown reduction per level
        'reward_multiplier' => 1.10, // 10% more reward per level
    ],

    'jail' => [
        'sentence_length' => 3600, // 1 hour base sentence
        'breakout_chance' => 0.05,  // 5% chance to break out per attempt
        'breakout_cost' => 1000,   // Cost to attempt breakout
        'sentence_multiplier' => 1.5, // Sentence increases by 50% for repeat offenses
    ],

    'economy' => [
        'bank_interest' => 0.05,   // 5% daily interest
        'tax_rate' => 0.10,        // 10% tax on faction bank withdrawals
        'start_money' => 5000,     // Starting cash
        'start_bank' => 0,         // Starting bank balance
        'max_bank' => 10000000,    // Maximum bank balance
    ],

    'leveling' => [
        'exp_curve' => 'exponential', // 'linear' or 'exponential'
        'exp_per_level' => 1000,    // Base EXP per level
        'exp_multiplier' => 1.20,   // 20% more EXP needed per level
        'stat_points_per_level' => 2, // Points to allocate per level
        'max_level' => 100,        // Maximum character level
    ],

    'skills' => [
        'strength' => [
            'attack_bonus' => 0.5,   // +0.5 damage per point
            'max' => 100,
        ],
        'defense' => [
            'damage_reduction' => 0.5, // -0.5 damage per point
            'max' => 100,
        ],
        'speed' => [
            'attack_first_chance' => 0.02, // +2% chance to attack first per point
            'max' => 100,
        ],
        'dexterity' => [
            'crit_chance' => 0.005,  // +0.5% crit chance per point
            'max' => 100,
        ],
        'training_cost' => 100,      // Money cost to train a stat
        'training_limit' => 5,       // Max stat points per training session
    ],

    'factions' => [
        'create_cost' => 10000,    // Cost to create a faction
        'create_level' => 10,      // Minimum level to create a faction
        'max_members' => 50,       // Maximum faction members
        'respect_per_win' => 10,   // Respect gained per war win
        'respect_per_loss' => -5,  // Respect lost per war loss
        'bank_tax' => 0.05,        // 5% tax on faction bank deposits
    ],

    'locations' => [
        'start_location' => 1,      // ID of starting location
        'travel_cost_base' => 100, // Base travel cost
        'travel_cost_per_level' => 10, // Additional cost per location level
    ],

    'limits' => [
        'max_inventory_items' => 100,
        'max_equipped_items' => 10,
        'max_mail_messages' => 50,
        'max_market_listings' => 20,
        'max_faction_chat_history' => 100,
    ],

    'cooldowns' => [
        'default' => 60,           // 1 minute default cooldown
        'attack' => 300,          // 5 minutes
        'crime' => 120,           // 2 minutes
        'travel' => 60,           // 1 minute
        'train' => 300,           // 5 minutes
        'market_listing' => 60,   // 1 minute
    ],
];
```

---

## 🎯 Character Progression

### Starting Stats (Level 1)
- **Health**: 100/100
- **Energy**: 100/100
- **Money**: $5,000
- **Bank**: $0
- **Strength**: 5
- **Defense**: 5
- **Speed**: 5
- **Dexterity**: 5
- **Experience**: 0/1000
- **Level**: 1

### Level Up Rewards
- **Experience**: Reset to 0, next level requires more EXP
- **Stat Points**: +2 points to distribute among stats
- **Health**: +5 max health
- **Energy**: +5 max energy
- **Money**: +$1,000 bonus

### Experience Sources
| Action | EXP Reward |
|--------|------------|
| Successful Crime | 50-200 (scaled by difficulty) |
| Failed Crime | 10-50 |
| Winning Attack | 100-300 |
| Losing Attack | 25-100 |
| Killing Player | 500 |
| Training Stat | 10 |
| Completing Mission | 100-1000 |
| Faction War Win | 500 |
| Daily Login | 50 |

---

## 💰 Economy Balance

### Money Sources
| Source | Amount | Frequency |
|--------|--------|-----------|
| Starting | $5,000 | Once |
| Crime Rewards | $50-$500 | Per crime |
| Attack Wins | $100-$1,000 | Per win |
| Selling Items | Variable | Per sale |
| Bank Interest | 5% daily | Daily |
| Faction Bank | Variable | Per deposit |
| Property Income | $100-$10,000 | Per hour |
| Stock Market | Variable | Per trade |

### Money Sinks
| Sink | Amount | Frequency |
|------|--------|-----------|
| Attack Loses | $50-$500 | Per loss |
| Crime Failures | $10-$100 | Per failure |
| Hospital Revival | $1,000 | Per death |
| Jail Breakout | $1,000 | Per attempt |
| Training Stats | $100 | Per point |
| Travel | $100-$1,000 | Per trip |
| Buying Items | Variable | Per purchase |
| Faction Creation | $10,000 | Once |
| Hit List Placement | $5,000 | Per hit |
| Property Purchase | Variable | Per property |

---

## 🎲 Game Mechanics Details

### Combat System

```
Attacker Rolls Initiative:
- Base: 50% chance to attack first
- Speed bonus: +2% per speed point
- Random: +/- 10% variation

If Attacker goes first:
1. Attacker calculates damage
2. Defender calculates damage (if still alive)

Damage Calculation:
Base Damage = attacker_strength * 0.5 + weapon_attack_bonus
Damage Variation = Base Damage * (0.8 + random(0, 0.4))
Critical Check = if random(0, 1) < (0.1 + attacker_dexterity * 0.005)
    Damage *= 2

Defender Reduction:
Defense Reduction = defender_defense * 0.5
Actual Damage = max(1, Damage - Defense Reduction)

Defender Health -= Actual Damage

If Defender Health <= 0:
    Attacker wins
    Defender goes to hospital
    Attacker gets EXP and money rewards
```

### Crime System

```
Success Check:
Base Success Rate = crime_success_rate
Modified Rate = Base Rate + (player_level * 0.01) - (crime_difficulty * 0.05)
Final Rate = clamp(Modified Rate, 0.1, 0.95)

Roll = random(0, 1)
If Roll <= Final Rate:
    Success!
    Reward = random(crime_reward_min, crime_reward_max)
    EXP = crime_experience * (1 + player_level * 0.01)
Else:
    Failure
    Health Loss = max(1, player_max_health * crime_failure_penalty)
    No reward
```

### Faction Wars

```
War Declaration:
- Requires: 5,000 respect
- Cooldown: 24 hours between declarations
- Duration: 7 days (configurable)

War Actions:
- Members can attack enemy faction members
- Each kill: +10 respect for faction
- Each death: -5 respect for faction

War Victory:
- Faction with most kills wins
- Winner gets: 50% of loser's faction bank
- Loser gets: Respect penalty, temporary debuffs
```

---

## 📅 Development Timeline

| Phase | Duration | Deliverables | Team Size | Status |
|-------|----------|--------------|-----------|--------|
| **Phase 1: Foundation** | 2-3 weeks | Auth, Character, Energy, Crimes, Inventory, UI | 1-2 devs | ⬜ Not Started |
| **Phase 2: Core Gameplay** | 3-4 weeks | Combat, Factions, Skills, Market, Jail/Hospital | 2 devs | ⬜ Not Started |
| **Phase 3: Advanced Features** | 4-5 weeks | Wars, Territory, Missions, Casino, Stock Market | 2-3 devs | ⬜ Not Started |
| **Phase 4: Polish** | 2-3 weeks | Admin, Moderation, API, Real-time | 1-2 devs | ⬜ Not Started |
| **Testing** | 2 weeks | Bug fixes, balance, stress testing | All | ⬜ Not Started |
| **Launch** | 1 week | Deployment, monitoring | All | ⬜ Not Started |

**Total Estimated Time: 14-17 weeks (3.5-4 months)**

---

## 🚀 Deployment Strategy

### Environment Requirements
- **PHP**: 8.2+
- **Laravel**: 11.x
- **Database**: MySQL 8.0+ or PostgreSQL 15+
- **Cache**: Redis 7.0+
- **Queue**: Redis + Supervisor
- **Web Server**: Nginx or Apache
- **OS**: Ubuntu 22.04 LTS

### Hosting Options
1. **Laravel Forge + DigitalOcean** (Recommended for simplicity)
2. **Laravel Vapor** (Serverless, scales automatically)
3. **AWS EC2 + RDS** (For enterprise scale)
4. **Self-hosted VPS** (For full control)

### Deployment Steps
1. Set up server with PHP, MySQL, Redis, Nginx
2. Configure Laravel environment variables
3. Run migrations and seeders
4. Set up cron jobs for scheduled commands
5. Configure queue workers
6. Set up SSL certificate (Let's Encrypt)
7. Configure monitoring (Sentry, Laravel Horizon)
8. Set up backups (daily database backups)

### Scaling Considerations
- **Database**: Use read replicas for leaderboards and reports
- **Queue**: Separate queue workers for different job types
- **Caching**: Aggressive caching for:
  - Leaderboards (cache for 5-10 minutes)
  - Shop items (cache for 1 hour)
  - Character stats (cache for 1 minute)
- **Rate Limiting**: Per-action rate limits to prevent abuse
- **Horizontal Scaling**: Stateless app servers behind load balancer

### Security Measures
- HTTPS everywhere (301 redirect from HTTP)
- CSRF protection (Laravel default)
- Input validation (Form Requests)
- Rate limiting (Laravel ThrottleRequests)
- SQL injection prevention (Eloquent ORM)
- XSS protection (Blade {{ }} escaping)
- Regular backups (daily, encrypted)
- Security headers (CSP, X-Frame-Options, etc.)
- Fail2Ban for brute force protection

---

## 💡 Implementation Checklist

### Phase 1 Checklist

- [ ] Set up Laravel project with Breeze
- [ ] Configure database connection
- [ ] Create User model (extend Laravel default)
- [ ] Create Character model and migration
- [ ] Create Character factory and seeder
- [ ] Create Location model and migration
- [ ] Create Item model and migration
- [ ] Create Inventory pivot table
- [ ] Create Crime model and migration
- [ ] Create ActivityLog model and migration
- [ ] Create Notification model and migration
- [ ] Set up relationships between models
- [ ] Create CharacterController
- [ ] Create CrimeController
- [ ] Create InventoryController
- [ ] Create EnergyService
- [ ] Create HealthService
- [ ] Create EconomyService
- [ ] Create CrimeService
- [ ] Create NotificationService
- [ ] Create middleware: CheckEnergy, CheckInJail, CheckInHospital, VerifyCharacter
- [ ] Create scheduled commands for energy/health regen
- [ ] Create game config file
- [ ] Set up Tailwind CSS
- [ ] Create base layout (app.blade.php)
- [ ] Create game layout (game.blade.php)
- [ ] Create character creation pages
- [ ] Create dashboard page
- [ ] Create crimes page
- [ ] Create inventory page
- [ ] Create partials: energy-bar, health-bar, nav, notifications
- [ ] Add Alpine.js for interactivity
- [ ] Test character creation flow
- [ ] Test energy consumption and regen
- [ ] Test crime attempts
- [ ] Test inventory management
- [ ] Deploy to staging environment

---

## 📝 Notes & Assumptions

1. **Game Name**: "The Crime Syndicate" (can be changed)
2. **Single Character per User**: Initially, one character per user account
3. **Turn-Based**: Actions are not real-time; players take turns
4. **Persistent World**: Game state updates even when players are offline
5. **Browser-Based**: No downloads required; works in any modern browser
6. **Mobile-Friendly**: Responsive design for mobile devices
7. **Free to Play**: Core gameplay is free; premium features optional

---

## 🔗 Resources & References

- **Omerta Game**: https://www.omertagame.com/
- **Torn City**: https://www.torn.com/
- **Laravel Documentation**: https://laravel.com/docs
- **Tailwind CSS**: https://tailwindcss.com/docs
- **Alpine.js**: https://alpinejs.dev/

---

## 📞 Contacts & Contributors

- **Project Lead**: [Your Name]
- **Developers**: [Team Members]
- **Designers**: [Team Members]
- **Testers**: [Team Members]

---

**Document Version**: 1.0  
**Last Updated**: 2026-06-26  
**Next Review**: After Phase 1 completion