first commit

2026-06-27 14:38:18 +03:00
commit 96d317480b
165 changed files with 20061 additions and 0 deletions
@@ -0,0 +1,937 @@
+# 🎮 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