feat(world): add persistent citizen simulation with needs, jobs, and social features

- Adds Character model with survival needs (hunger, thirst, energy) and state machine
- Implements city:tick world ticker for offline progression every minute
- Adds city territory expansion and building construction system
- Introduces job economy, inventory, and transaction audit trail
- Adds social graph (friends, marriage, children) and character chat
- Implements admin approval workflow for new registrations
- Adds hospital admission system for traffic accidents
- Includes comprehensive feature tests and world seeders

database/factories/CharacterFactory.php

@@ -0,0 +1,52 @@
+<?php
+
+namespace Database\Factories;
+
+use App\Models\Character;
+use App\Models\City;
+use App\Models\User;
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+/**
+ * @extends Factory<Character>
+ */
+class CharacterFactory extends Factory
+{
+    /**
+     * Define the model's default state.
+     *
+     * @return array<string, mixed>
+     */
+    public function definition(): array
+    {
+        return [
+            'user_id' => User::factory(),
+            'city_id' => City::factory(),
+            'name' => fake()->firstName(),
+            'skin' => fake()->numberBetween(1, 4),
+            'hair' => fake()->numberBetween(1, 4),
+            'shirt' => fake()->numberBetween(1, 5),
+            'pos_x' => 0,
+            'pos_y' => 0,
+            'pos_z' => 25,
+            'money' => 100,
+            'energy' => 100,
+            'hunger' => 100,
+            'thirst' => 100,
+            'state' => Character::STATE_AWAKE,
+            'education' => 0,
+            'is_online' => false,
+        ];
+    }
+
+    /**
+     * Character without an account (NPC child).
+     */
+    public function npc(): static
+    {
+        return $this->state(fn (array $attributes) => [
+            'user_id' => null,
+            'name' => fake()->firstName(),
+        ]);
+    }
+}

database/factories/CityFactory.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace Database\Factories;
+
+use App\Models\City;
+use Illuminate\Database\Eloquent\Factories\Factory;
+use Illuminate\Support\Str;
+
+/**
+ * @extends Factory<City>
+ */
+class CityFactory extends Factory
+{
+    /**
+     * Define the model's default state.
+     *
+     * @return array<string, mixed>
+     */
+    public function definition(): array
+    {
+        $name = fake()->unique()->city();
+
+        return [
+            'name' => $name,
+            'slug' => Str::slug($name).'-'.fake()->unique()->numberBetween(1, 9999),
+            'bounds_min_x' => -80,
+            'bounds_max_x' => 80,
+            'bounds_min_z' => -80,
+            'bounds_max_z' => 80,
+            'is_active' => false,
+            'expansions' => 0,
+        ];
+    }
+}

database/factories/UserFactory.php

@@ -31,6 +31,7 @@ class UserFactory extends Factory
             'password' => static::$password ??= Hash::make('password'),
             'remember_token' => Str::random(10),
             'role' => 'user',
+            'status' => 'active',
             'locale' => 'pt_BR',
             'is_active' => true,
         ];
@@ -56,12 +57,24 @@ class UserFactory extends Factory
         ]);
     }
 
+    /**
+     * Indicate that the account awaits administrator approval.
+     */
+    public function pending(): static
+    {
+        return $this->state(fn (array $attributes) => [
+            'status' => 'pending',
+            'is_active' => false,
+        ]);
+    }
+
     /**
      * Indicate that the account has been deactivated.
      */
     public function inactive(): static
     {
         return $this->state(fn (array $attributes) => [
+            'status' => 'banned',
             'is_active' => false,
         ]);
     }

database/migrations/2026_10_18_000100_add_status_to_users_table.php

@@ -0,0 +1,38 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Adds lifecycle status to users for admin approval gating.
+ *
+ * Statuses: "pending" (registered, waiting for admin), "active" (approved),
+ * "banned" (blocked). Existing rows are backfilled from is_active.
+ */
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::table('users', function (Blueprint $table): void {
+            $table->string('status', 20)->default('pending')->after('role')->index();
+        });
+
+        DB::table('users')->where('is_active', true)->update(['status' => 'active']);
+        DB::table('users')->where('is_active', false)->update(['status' => 'banned']);
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('users', function (Blueprint $table): void {
+            $table->dropColumn('status');
+        });
+    }
+};

database/migrations/2026_10_18_000200_create_cities_table.php

@@ -0,0 +1,42 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Creates the "cities" table.
+ *
+ * Each city owns a rectangular territory (bounds) used to generate the
+ * street layout, clamp movement and limit construction. Cities can be
+ * expanded or created by administrators as the platform grows.
+ */
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('cities', function (Blueprint $table): void {
+            $table->id();
+            $table->string('name', 120);
+            $table->string('slug', 120)->unique();
+            $table->decimal('bounds_min_x', 10, 2)->default(-80);
+            $table->decimal('bounds_max_x', 10, 2)->default(80);
+            $table->decimal('bounds_min_z', 10, 2)->default(-80);
+            $table->decimal('bounds_max_z', 10, 2)->default(80);
+            $table->boolean('is_active')->default(true)->index();
+            $table->unsignedInteger('expansions')->default(0);
+            $table->timestamps();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('cities');
+    }
+};

database/migrations/2026_10_18_000250_create_job_positions_table.php

@@ -0,0 +1,38 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Creates the "job_positions" table.
+ *
+ * Employment positions offered inside a city. Characters reference a job
+ * while working; the world ticker pays the salary while state=working.
+ */
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('job_positions', function (Blueprint $table): void {
+            $table->id();
+            $table->foreignId('city_id')->constrained('cities')->cascadeOnDelete();
+            $table->foreignId('store_id')->nullable()->constrained('stores')->nullOnDelete();
+            $table->string('title', 120);
+            $table->decimal('salary', 10, 2)->default(10);
+            $table->unsignedTinyInteger('requires_education')->default(0);
+            $table->timestamps();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('job_positions');
+    }
+};

database/migrations/2026_10_18_000300_create_characters_table.php

@@ -0,0 +1,55 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Creates the "characters" table.
+ *
+ * A character is the in-world avatar of a user (user_id nullable for NPC
+ * children). It stores position, survival needs, employment and family-relevant
+ * state that the world ticker updates continuously.
+ */
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('characters', function (Blueprint $table): void {
+            $table->id();
+            $table->foreignId('user_id')->nullable()->unique()->constrained('users')->nullOnDelete();
+            $table->foreignId('city_id')->constrained('cities')->cascadeOnDelete();
+            $table->string('name', 120);
+            $table->unsignedTinyInteger('skin')->default(1);
+            $table->unsignedTinyInteger('hair')->default(1);
+            $table->unsignedTinyInteger('shirt')->default(1);
+            $table->decimal('pos_x', 10, 2)->default(0);
+            $table->decimal('pos_y', 10, 2)->default(0);
+            $table->decimal('pos_z', 10, 2)->default(0);
+            $table->decimal('money', 12, 2)->default(100);
+            $table->unsignedTinyInteger('energy')->default(100);
+            $table->unsignedTinyInteger('hunger')->default(100);
+            $table->unsignedTinyInteger('thirst')->default(100);
+            $table->string('state', 20)->default('awake')->index();
+            $table->foreignId('job_id')->nullable()->constrained('job_positions')->nullOnDelete();
+            $table->foreignId('house_id')->nullable();
+            $table->unsignedTinyInteger('education')->default(0);
+            $table->boolean('is_online')->default(false);
+            $table->timestamp('last_tick_at')->nullable();
+            $table->timestamps();
+
+            $table->index(['city_id', 'state']);
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('characters');
+    }
+};

database/migrations/2026_10_18_000400_create_buildings_table.php

@@ -0,0 +1,46 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Creates the "buildings" table.
+ *
+ * Player-constructed structures (houses, etc.) placed on free terrain.
+ * Construction advances via the world ticker until is_complete.
+ */
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('buildings', function (Blueprint $table): void {
+            $table->id();
+            $table->foreignId('city_id')->constrained('cities')->cascadeOnDelete();
+            $table->foreignId('owner_character_id')->nullable()->constrained('characters')->nullOnDelete();
+            $table->string('type', 40)->default('house');
+            $table->string('name', 160)->nullable();
+            $table->decimal('pos_x', 10, 2);
+            $table->decimal('pos_z', 10, 2);
+            $table->decimal('width', 8, 2)->default(10);
+            $table->decimal('depth', 8, 2)->default(10);
+            $table->decimal('height', 8, 2)->default(5);
+            $table->boolean('is_complete')->default(false)->index();
+            $table->unsignedTinyInteger('build_progress')->default(0);
+            $table->timestamps();
+
+            $table->index(['city_id', 'type']);
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('buildings');
+    }
+};

database/migrations/2026_10_18_000500_create_relationships_table.php

@@ -0,0 +1,40 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Creates the "relationships" table.
+ *
+ * Social graph between characters: friends, spouses and parent-child links.
+ * For parent_child, character_a is the child and character_b is the parent.
+ */
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('relationships', function (Blueprint $table): void {
+            $table->id();
+            $table->foreignId('character_a_id')->constrained('characters')->cascadeOnDelete();
+            $table->foreignId('character_b_id')->constrained('characters')->cascadeOnDelete();
+            $table->string('type', 30);
+            $table->string('status', 20)->default('pending');
+            $table->timestamps();
+
+            $table->unique(['character_a_id', 'character_b_id', 'type']);
+            $table->index(['character_b_id', 'type', 'status']);
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('relationships');
+    }
+};

database/migrations/2026_10_18_000600_create_inventory_items_table.php

@@ -0,0 +1,37 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Creates the "inventory_items" table.
+ *
+ * Stackable item quantities owned by a character (food, water, materials, product).
+ */
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('inventory_items', function (Blueprint $table): void {
+            $table->id();
+            $table->foreignId('character_id')->constrained('characters')->cascadeOnDelete();
+            $table->string('item', 40);
+            $table->unsignedInteger('qty')->default(0);
+            $table->timestamps();
+
+            $table->unique(['character_id', 'item']);
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('inventory_items');
+    }
+};

database/migrations/2026_10_18_000700_create_transactions_table.php

@@ -0,0 +1,38 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Creates the "transactions" table.
+ *
+ * Audit trail of economic exchanges between characters and stores.
+ */
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('transactions', function (Blueprint $table): void {
+            $table->id();
+            $table->foreignId('from_character_id')->nullable()->constrained('characters')->nullOnDelete();
+            $table->foreignId('to_character_id')->nullable()->constrained('characters')->nullOnDelete();
+            $table->foreignId('store_id')->nullable()->constrained('stores')->nullOnDelete();
+            $table->string('item', 40);
+            $table->unsignedInteger('qty')->default(1);
+            $table->decimal('amount', 12, 2)->default(0);
+            $table->timestamps();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('transactions');
+    }
+};

database/migrations/2026_10_18_000900_create_character_messages_table.php

@@ -0,0 +1,37 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Creates the "character_messages" table.
+ *
+ * Persistent chat between characters (player-to-player or player-to-NPC).
+ */
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('character_messages', function (Blueprint $table): void {
+            $table->id();
+            $table->foreignId('from_character_id')->constrained('characters')->cascadeOnDelete();
+            $table->foreignId('to_character_id')->constrained('characters')->cascadeOnDelete();
+            $table->string('body', 1000);
+            $table->timestamps();
+
+            $table->index(['to_character_id', 'created_at']);
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('character_messages');
+    }
+};

database/migrations/2026_10_18_001000_add_hospitalized_until_to_characters_table.php

@@ -0,0 +1,34 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+/**
+ * Adds hospital admission tracking to characters.
+ *
+ * When a character is hit by a vehicle they are admitted for two game days
+ * (hospitalized_until). The world ticker releases them automatically.
+ */
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::table('characters', function (Blueprint $table): void {
+            $table->timestamp('hospitalized_until')->nullable()->after('last_tick_at')->index();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('characters', function (Blueprint $table): void {
+            $table->dropColumn('hospitalized_until');
+        });
+    }
+};

database/seeders/CityWorldSeeder.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace Database\Seeders;
+
+use App\Models\Building;
+use App\Models\Character;
+use App\Models\City;
+use App\Models\Job;
+use App\Models\Store;
+use App\Models\User;
+use Illuminate\Database\Seeder;
+
+/**
+ * Seeds the persistent world: default city, jobs and citizen characters.
+ *
+ * Backfills users.status for pre-existing accounts and ensures every active
+ * user has a character so the platform works after the status migration.
+ */
+class CityWorldSeeder extends Seeder
+{
+    /**
+     * Seed the world tables.
+     */
+    public function run(): void
+    {
+        $city = City::updateOrCreate(
+            ['slug' => 'city10'],
+            [
+                'name' => 'City10',
+                'bounds_min_x' => -80,
+                'bounds_max_x' => 80,
+                'bounds_min_z' => -80,
+                'bounds_max_z' => 80,
+                'is_active' => true,
+                'expansions' => 0,
+            ],
+        );
+
+        $bakery = Store::where('type', 'bakery')->orderBy('id')->first();
+        $market = Store::where('type', 'market')->orderBy('id')->first();
+
+        Job::updateOrCreate(
+            ['city_id' => $city->id, 'title' => 'Padeiro'],
+            ['store_id' => $bakery?->id, 'salary' => 12, 'requires_education' => 0],
+        );
+        Job::updateOrCreate(
+            ['city_id' => $city->id, 'title' => 'Operador de mercado'],
+            ['store_id' => $market?->id, 'salary' => 10, 'requires_education' => 0],
+        );
+        Job::updateOrCreate(
+            ['city_id' => $city->id, 'title' => 'Servidor público'],
+            ['salary' => 15, 'requires_education' => 30],
+        );
+        Job::updateOrCreate(
+            ['city_id' => $city->id, 'title' => 'Professor'],
+            ['salary' => 14, 'requires_education' => 60],
+        );
+
+        // City hospital: accident victims are admitted here for two game days.
+        Building::updateOrCreate(
+            [
+                'city_id' => $city->id,
+                'type' => Building::TYPE_HOSPITAL,
+            ],
+            [
+                'owner_character_id' => null,
+                'name' => 'Hospital Municipal',
+                'pos_x' => 60,
+                'pos_z' => -60,
+                'width' => 14,
+                'depth' => 12,
+                'height' => 8,
+                'is_complete' => true,
+                'build_progress' => 100,
+            ],
+        );
+
+        User::query()->where('is_active', true)->where('status', '!=', User::STATUS_ACTIVE)
+            ->update(['status' => User::STATUS_ACTIVE]);
+        User::query()->where('is_active', false)->where('status', User::STATUS_PENDING)
+            ->update(['status' => User::STATUS_BANNED]);
+
+        User::query()->where('status', User::STATUS_ACTIVE)->each(function (User $user) use ($city): void {
+            Character::ensureForUser($user, $city);
+        });
+    }
+}

database/seeders/DatabaseSeeder.php

@@ -24,6 +24,7 @@ class DatabaseSeeder extends Seeder
             LegalDocumentSeeder::class,
             UserSeeder::class,
             CityContentSeeder::class,
+            CityWorldSeeder::class,
         ]);
     }
 }