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
2026-10-17 21:46:23 -03:00
parent 79d12fa2f4
commit 79ce2a1825
132 changed files with 11809 additions and 1036 deletions
@@ -0,0 +1,38 @@
+<?php
+
+namespace App\Http\Controllers\Web;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+use Illuminate\View\View;
+
+/**
+ * Account lifecycle screens for registration approval.
+ */
+class AccountController extends Controller
+{
+    /**
+     * Show the wait screen for pending registrations.
+     */
+    public function pending(Request $request): View|RedirectResponse
+    {
+        $user = $request->user();
+
+        if ($user === null) {
+            return redirect()->route('login');
+        }
+
+        if ($user->status === 'active') {
+            return redirect()->route('dashboard');
+        }
+
+        if ($user->status === 'banned') {
+            auth()->guard('web')->logout();
+            $request->session()->invalidate();
+
+            return redirect()->route('login')->withErrors(['email' => __('auth.disabled')]);
+        }
+
+        return view('auth.pending');
+    }
+}
@@ -0,0 +1,65 @@
+<?php
+
+namespace App\Http\Controllers\Web\Admin;
+
+use App\Http\Controllers\Controller;
+use App\Models\Character;
+use App\Models\User;
+use Illuminate\Http\RedirectResponse;
+use Illuminate\Http\Request;
+use Illuminate\View\View;
+
+/**
+ * Administrator management of citizen accounts.
+ *
+ * Lists registered users, approves pending registrations (which creates the
+ * in-world character) and bans accounts that must not enter the platform.
+ */
+class CitizenAdminController extends Controller
+{
+    /**
+     * List all citizens with their approval status.
+     */
+    public function index(Request $request): View
+    {
+        abort_unless($request->user()?->isAdmin(), 403);
+
+        $users = User::query()
+            ->with('character:id,user_id,name,city_id')
+            ->orderByDesc('created_at')
+            ->paginate(20);
+
+        return view('admin.citizens.index', [
+            'users' => $users,
+        ]);
+    }
+
+    /**
+     * Approve a pending citizen and ensure their character exists.
+     */
+    public function approve(Request $request, User $user): RedirectResponse
+    {
+        abort_unless($request->user()?->isAdmin(), 403);
+
+        $user->forceFill(['status' => User::STATUS_ACTIVE, 'is_active' => true])->save();
+        Character::ensureForUser($user);
+
+        return redirect()->route('admin.citizens.index')
+            ->with('status', __('admin.citizens.approved'));
+    }
+
+    /**
+     * Ban a citizen so they can no longer authenticate.
+     */
+    public function ban(Request $request, User $user): RedirectResponse
+    {
+        abort_unless($request->user()?->isAdmin(), 403);
+
+        abort_if((int) $user->id === (int) $request->user()->id, 422, __('admin.citizens.cannot_ban_self'));
+
+        $user->forceFill(['status' => User::STATUS_BANNED, 'is_active' => false])->save();
+
+        return redirect()->route('admin.citizens.index')
+            ->with('status', __('admin.citizens.banned'));
+    }
+}
@@ -0,0 +1,73 @@
+<?php
+
+namespace App\Http\Controllers\Web\Admin;
+
+use App\Http\Controllers\Controller;
+use App\Models\City;
+use Illuminate\Http\RedirectResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Str;
+use Illuminate\View\View;
+
+/**
+ * Administrator management of city territories.
+ *
+ * Supports creating new cities and expanding the bounds of existing ones
+ * so the playable map can grow over time.
+ */
+class CityAdminController extends Controller
+{
+    /**
+     * List all cities with expansion controls.
+     */
+    public function index(Request $request): View
+    {
+        abort_unless($request->user()?->isAdmin(), 403);
+
+        return view('admin.cities.index', [
+            'cities' => City::query()->orderBy('id')->get(),
+        ]);
+    }
+
+    /**
+     * Create a new city territory.
+     */
+    public function store(Request $request): RedirectResponse
+    {
+        abort_unless($request->user()?->isAdmin(), 403);
+
+        $data = $request->validate([
+            'name' => ['required', 'string', 'max:120'],
+        ]);
+
+        City::create([
+            'name' => $data['name'],
+            'slug' => Str::slug($data['name']).'-'.uniqid(),
+            'bounds_min_x' => -80,
+            'bounds_max_x' => 80,
+            'bounds_min_z' => -80,
+            'bounds_max_z' => 80,
+            'is_active' => false,
+            'expansions' => 0,
+        ]);
+
+        return redirect()->route('admin.cities.index')
+            ->with('status', __('admin.cities.created'));
+    }
+
+    /**
+     * Expand a city's territory by one grid step.
+     */
+    public function expand(Request $request, City $city): RedirectResponse
+    {
+        abort_unless($request->user()?->isAdmin(), 403);
+
+        if (! $city->expand()) {
+            return redirect()->route('admin.cities.index')
+                ->withErrors(['city' => __('admin.cities.max_expansions')]);
+        }
+
+        return redirect()->route('admin.cities.index')
+            ->with('status', __('admin.cities.expanded'));
+    }
+}
@@ -45,7 +45,17 @@ class AuthController extends Controller

        $user = Auth::user();

-        if (! $user->is_active) {
+        if ($user->status === User::STATUS_PENDING) {
+            Auth::logout();
+            $request->session()->invalidate();
+            $request->session()->regenerateToken();
+
+            return redirect()->route('login')->withErrors([
+                'email' => __('auth.pending'),
+            ]);
+        }
+
+        if ($user->status === User::STATUS_BANNED || ! $user->is_active) {
            Auth::logout();
            $request->session()->invalidate();
            $request->session()->regenerateToken();
@@ -89,8 +99,9 @@ class AuthController extends Controller
            'email' => $data['email'],
            'password' => $data['password'],
            'role' => User::ROLE_USER,
+            'status' => User::STATUS_PENDING,
            'locale' => $data['locale'] ?? 'pt_BR',
-            'is_active' => true,
+            'is_active' => false,
        ]);

        Auth::login($user);
@@ -0,0 +1,72 @@
+<?php
+
+namespace App\Http\Controllers\Web;
+
+use App\Http\Controllers\Controller;
+use App\Models\Character;
+use App\Models\CharacterMessage;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+
+/**
+ * Persistent chat between world characters.
+ */
+class CharacterChatController extends Controller
+{
+    /**
+     * List messages exchanged with another character (newest last).
+     */
+    public function index(Request $request, Character $character): JsonResponse
+    {
+        $me = Character::ensureForUser($request->user());
+
+        $messages = CharacterMessage::query()
+            ->where(function ($q) use ($me, $character): void {
+                $q->where('from_character_id', $me->id)->where('to_character_id', $character->id);
+            })
+            ->orWhere(function ($q) use ($me, $character): void {
+                $q->where('from_character_id', $character->id)->where('to_character_id', $me->id);
+            })
+            ->orderBy('id')
+            ->limit(100)
+            ->get()
+            ->map(fn (CharacterMessage $m) => [
+                'from' => (int) $m->from_character_id,
+                'body' => $m->body,
+                'at' => $m->created_at?->toIso8601String(),
+            ]);
+
+        return response()->json([
+            'me' => $me->id,
+            'them' => $character->id,
+            'messages' => $messages,
+        ]);
+    }
+
+    /**
+     * Send a chat message to another character.
+     */
+    public function send(Request $request, Character $character): JsonResponse
+    {
+        $me = Character::ensureForUser($request->user());
+
+        if ((int) $character->id === (int) $me->id) {
+            return response()->json(['message' => __('city.social_self')], 422);
+        }
+
+        $data = $request->validate([
+            'body' => ['required', 'string', 'max:1000'],
+        ]);
+
+        $message = CharacterMessage::create([
+            'from_character_id' => $me->id,
+            'to_character_id' => $character->id,
+            'body' => $data['body'],
+        ]);
+
+        return response()->json([
+            'message' => __('city.chat_sent'),
+            'id' => $message->id,
+        ]);
+    }
+}
@@ -0,0 +1,496 @@
+<?php
+
+namespace App\Http\Controllers\Web;
+
+use App\Http\Controllers\Controller;
+use App\Models\Building;
+use App\Models\Character;
+use App\Models\City;
+use App\Models\InventoryItem;
+use App\Models\Job;
+use App\Models\Transaction;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+
+/**
+ * Player-driven world actions: position sync and lifecycle verbs.
+ *
+ * Every action targets the authenticated user's own character only and
+ * respects city bounds and inventory/money rules from the design spec.
+ */
+class CityActionController extends Controller
+{
+    public const BUILD_MATERIALS = 50;
+
+    /**
+     * Persist the caller's character position (throttled from the viewer).
+     */
+    public function position(Request $request): JsonResponse
+    {
+        $character = $this->ownCharacter($request);
+        $character->releaseIfHospitalStayOver();
+        $data = $request->validate([
+            'pos_x' => ['required', 'numeric'],
+            'pos_z' => ['required', 'numeric'],
+        ]);
+
+        if ($character->isHospitalized()) {
+            return response()->json([
+                'message' => __('city.hospital_bed'),
+                'pos_x' => $character->pos_x,
+                'pos_z' => $character->pos_z,
+                'state' => $character->state,
+                'hospitalized_until' => $character->hospitalized_until?->toIso8601String(),
+            ]);
+        }
+
+        $city = $character->city;
+        $x = max((float) $city->bounds_min_x, min((float) $city->bounds_max_x, (float) $data['pos_x']));
+        $z = max((float) $city->bounds_min_z, min((float) $city->bounds_max_z, (float) $data['pos_z']));
+
+        $character->forceFill([
+            'pos_x' => $x,
+            'pos_z' => $z,
+            'pos_y' => 0,
+            'is_online' => true,
+        ])->save();
+
+        return response()->json([
+            'pos_x' => $character->pos_x,
+            'pos_z' => $character->pos_z,
+            'state' => $character->state,
+            'hospitalized_until' => null,
+        ]);
+    }
+
+    /**
+     * Dispatch a named world action for the caller's character.
+     */
+    public function handle(Request $request, string $action): JsonResponse
+    {
+        $character = $this->ownCharacter($request);
+        $character->releaseIfHospitalStayOver();
+
+        // Traffic accidents are always accepted, even from the hospital bed.
+        if ($action === 'accident') {
+            return $this->accident($character);
+        }
+
+        if ($character->isHospitalized()) {
+            return response()->json([
+                'message' => __('city.hospital_blocked'),
+                'hospitalized_until' => $character->hospitalized_until?->toIso8601String(),
+                'character' => $this->characterData($character),
+            ], 422);
+        }
+
+        return match ($action) {
+            'eat' => $this->eat($character),
+            'drink' => $this->drink($character),
+            'sleep' => $this->sleep($character),
+            'wake' => $this->wake($character),
+            'work' => $this->work($character),
+            'stop-work' => $this->stopWork($character),
+            'study' => $this->study($character),
+            'buy' => $this->buy($request, $character),
+            'sell' => $this->sell($request, $character),
+            'build' => $this->build($request, $character),
+            'apply-job' => $this->applyJob($request, $character),
+            default => response()->json(['message' => __('city.action_unknown')], 422),
+        };
+    }
+
+    /**
+     * Admit the character to the hospital after a vehicle collision.
+     *
+     * Stays two game days (Character::HOSPITAL_STAY_SECONDS).
+     */
+    private function accident(Character $character): JsonResponse
+    {
+        if ($character->isHospitalized()) {
+            return response()->json([
+                'message' => __('city.hospital_already'),
+                'hospitalized_until' => $character->hospitalized_until?->toIso8601String(),
+                'character' => $this->characterData($character),
+            ]);
+        }
+
+        [$x, $z] = $character->admitToHospital();
+
+        return response()->json([
+            'message' => __('city.hospital_hit'),
+            'hospitalized_until' => $character->hospitalized_until?->toIso8601String(),
+            'character' => $this->characterData($character),
+            'bed' => ['pos_x' => $x, 'pos_z' => $z],
+        ]);
+    }
+
+    /**
+     * Resolve the character owned by the authenticated user.
+     */
+    private function ownCharacter(Request $request): Character
+    {
+        $user = $request->user();
+        abort_unless($user !== null, 401);
+
+        return Character::ensureForUser($user);
+    }
+
+    /**
+     * Consume one food ration and restore hunger.
+     */
+    private function eat(Character $character): JsonResponse
+    {
+        if (! $this->consume($character, InventoryItem::ITEM_FOOD, 1)) {
+            return response()->json(['message' => __('city.no_food')], 422);
+        }
+
+        $character->hunger = min(100, (int) $character->hunger + 40);
+        $character->save();
+
+        return $this->characterPayload($character);
+    }
+
+    /**
+     * Consume one water ration and restore thirst.
+     */
+    private function drink(Character $character): JsonResponse
+    {
+        if (! $this->consume($character, InventoryItem::ITEM_WATER, 1)) {
+            return response()->json(['message' => __('city.no_water')], 422);
+        }
+
+        $character->thirst = min(100, (int) $character->thirst + 40);
+        $character->save();
+
+        return $this->characterPayload($character);
+    }
+
+    /**
+     * Lie down to sleep (requires a completed house).
+     */
+    private function sleep(Character $character): JsonResponse
+    {
+        if ($character->state === Character::STATE_SLEEPING) {
+            return $this->characterPayload($character);
+        }
+
+        if ($character->house_id === null || ! $character->house?->is_complete) {
+            return response()->json(['message' => __('city.no_house')], 422);
+        }
+
+        $character->state = Character::STATE_SLEEPING;
+        $character->save();
+
+        return $this->characterPayload($character);
+    }
+
+    /**
+     * Leave the sleeping state.
+     */
+    private function wake(Character $character): JsonResponse
+    {
+        if ($character->state === Character::STATE_SLEEPING) {
+            $character->state = Character::STATE_AWAKE;
+            $character->save();
+        }
+
+        return $this->characterPayload($character);
+    }
+
+    /**
+     * Start working (requires employment).
+     */
+    private function work(Character $character): JsonResponse
+    {
+        if ($character->job_id === null) {
+            return response()->json(['message' => __('city.no_job')], 422);
+        }
+
+        $character->state = Character::STATE_WORKING;
+        $character->save();
+
+        return $this->characterPayload($character);
+    }
+
+    /**
+     * Stop working or studying.
+     */
+    private function stopWork(Character $character): JsonResponse
+    {
+        if (in_array($character->state, [Character::STATE_WORKING, Character::STATE_STUDYING], true)) {
+            $character->state = Character::STATE_AWAKE;
+            $character->save();
+        }
+
+        return $this->characterPayload($character);
+    }
+
+    /**
+     * Study at the city school (requires a school building type presence or job city school).
+     */
+    private function study(Character $character): JsonResponse
+    {
+        $hasSchool = Building::query()
+            ->where('city_id', $character->city_id)
+            ->whereIn('type', ['school', Building::TYPE_HOUSE])
+            ->exists();
+
+        $hasCivicSchool = Building::query()
+            ->where('city_id', $character->city_id)
+            ->where('type', 'school')
+            ->exists();
+
+        // City10 ships with a public school implied by the "Professor" job city.
+        if (! $hasCivicSchool && ! $hasSchool) {
+            $hasSchool = true;
+        }
+
+        if (! $hasSchool) {
+            return response()->json(['message' => __('city.no_school')], 422);
+        }
+
+        $character->state = Character::STATE_STUDYING;
+        $character->save();
+
+        return $this->characterPayload($character);
+    }
+
+    /**
+     * Accept an open job position in the character's city.
+     */
+    private function applyJob(Request $request, Character $character): JsonResponse
+    {
+        $data = $request->validate([
+            'job_id' => ['required', 'integer', 'exists:job_positions,id'],
+        ]);
+
+        $job = Job::query()->findOrFail($data['job_id']);
+        if ((int) $job->city_id !== (int) $character->city_id) {
+            return response()->json(['message' => __('city.job_other_city')], 422);
+        }
+
+        if ((int) $character->education < (int) $job->requires_education) {
+            return response()->json(['message' => __('city.job_education')], 422);
+        }
+
+        $character->job_id = $job->id;
+        $character->state = Character::STATE_AWAKE;
+        $character->save();
+
+        return $this->characterPayload($character);
+    }
+
+    /**
+     * Buy items from the city market using money.
+     */
+    private function buy(Request $request, Character $character): JsonResponse
+    {
+        $data = $request->validate([
+            'item' => ['required', 'in:food,water,materials,product'],
+            'qty' => ['required', 'integer', 'min:1', 'max:50'],
+            'price' => ['required', 'numeric', 'min:0.01', 'max:1000'],
+        ]);
+
+        $total = round($data['price'] * $data['qty'], 2);
+        if ($character->money < $total) {
+            return response()->json(['message' => __('city.no_money')], 422);
+        }
+
+        DB::transaction(function () use ($character, $data, $total): void {
+            $character->money = $character->money - $total;
+            $character->save();
+            $this->grant($character, $data['item'], (int) $data['qty']);
+            Transaction::create([
+                'from_character_id' => $character->id,
+                'item' => $data['item'],
+                'qty' => (int) $data['qty'],
+                'amount' => $total,
+            ]);
+        });
+
+        return $this->characterPayload($character);
+    }
+
+    /**
+     * Sell inventory items for money.
+     */
+    private function sell(Request $request, Character $character): JsonResponse
+    {
+        $data = $request->validate([
+            'item' => ['required', 'in:food,water,materials,product'],
+            'qty' => ['required', 'integer', 'min:1', 'max:50'],
+            'price' => ['required', 'numeric', 'min:0.01', 'max:1000'],
+        ]);
+
+        if (! $this->consume($character, $data['item'], (int) $data['qty'])) {
+            return response()->json(['message' => __('city.no_inventory')], 422);
+        }
+
+        $total = round($data['price'] * $data['qty'], 2);
+        DB::transaction(function () use ($character, $data, $total): void {
+            $character->money = $character->money + $total;
+            $character->save();
+            Transaction::create([
+                'to_character_id' => $character->id,
+                'item' => $data['item'],
+                'qty' => (int) $data['qty'],
+                'amount' => $total,
+            ]);
+        });
+
+        return $this->characterPayload($character);
+    }
+
+    /**
+     * Start constructing a house on free terrain.
+     */
+    private function build(Request $request, Character $character): JsonResponse
+    {
+        $data = $request->validate([
+            'pos_x' => ['required', 'numeric'],
+            'pos_z' => ['required', 'numeric'],
+            'name' => ['nullable', 'string', 'max:120'],
+        ]);
+
+        $city = $character->city;
+        $x = (float) $data['pos_x'];
+        $z = (float) $data['pos_z'];
+
+        if (! $city->contains($x, $z)) {
+            return response()->json(['message' => __('city.out_of_bounds')], 422);
+        }
+
+        if (! $this->consume($character, InventoryItem::ITEM_MATERIALS, self::BUILD_MATERIALS)) {
+            return response()->json(['message' => __('city.no_materials')], 422);
+        }
+
+        $width = 10;
+        $depth = 10;
+        $overlaps = Building::query()
+            ->where('city_id', $city->id)
+            ->get()
+            ->contains(function (Building $b) use ($x, $z, $width, $depth): bool {
+                $minX = (float) $b->pos_x - (float) $b->width / 2;
+                $maxX = (float) $b->pos_x + (float) $b->width / 2;
+                $minZ = (float) $b->pos_z - (float) $b->depth / 2;
+                $maxZ = (float) $b->pos_z + (float) $b->depth / 2;
+
+                return ($x + $width / 2) > $minX && ($x - $width / 2) < $maxX
+                    && ($z + $depth / 2) > $minZ && ($z - $depth / 2) < $maxZ;
+            });
+
+        if ($overlaps) {
+            return response()->json(['message' => __('city.site_taken')], 422);
+        }
+
+        $building = Building::create([
+            'city_id' => $city->id,
+            'owner_character_id' => $character->id,
+            'type' => Building::TYPE_HOUSE,
+            'name' => $data['name'] ?? ($character->name."'s house"),
+            'pos_x' => $x,
+            'pos_z' => $z,
+            'width' => $width,
+            'depth' => $depth,
+            'height' => 5,
+            'is_complete' => false,
+            'build_progress' => 0,
+        ]);
+
+        return response()->json([
+            'message' => __('city.build_started'),
+            'building' => [
+                'id' => $building->id,
+                'pos_x' => $building->pos_x,
+                'pos_z' => $building->pos_z,
+                'progress' => $building->build_progress,
+            ],
+            'character' => $this->characterData($character->fresh()),
+        ]);
+    }
+
+    /**
+     * Grant inventory quantity (upsert).
+     */
+    private function grant(Character $character, string $item, int $qty): void
+    {
+        $row = InventoryItem::query()
+            ->where('character_id', $character->id)
+            ->where('item', $item)
+            ->first();
+
+        if ($row) {
+            $row->qty = (int) $row->qty + $qty;
+            $row->save();
+
+            return;
+        }
+
+        InventoryItem::create([
+            'character_id' => $character->id,
+            'item' => $item,
+            'qty' => $qty,
+        ]);
+    }
+
+    /**
+     * Consume inventory quantity when available.
+     */
+    private function consume(Character $character, string $item, int $qty): bool
+    {
+        $row = InventoryItem::query()
+            ->where('character_id', $character->id)
+            ->where('item', $item)
+            ->first();
+
+        if ($row === null || (int) $row->qty < $qty) {
+            return false;
+        }
+
+        $row->qty = (int) $row->qty - $qty;
+        $row->save();
+
+        return true;
+    }
+
+    /**
+     * Standard character JSON payload for action responses.
+     */
+    private function characterPayload(Character $character): JsonResponse
+    {
+        return response()->json([
+            'message' => __('city.action_ok'),
+            'character' => $this->characterData($character),
+        ]);
+    }
+
+    /**
+     * Character attributes exposed to the client.
+     *
+     * @return array<string, mixed>
+     */
+    private function characterData(Character $character): array
+    {
+        $character->loadMissing('inventory', 'job');
+
+        return [
+            'id' => $character->id,
+            'name' => $character->name,
+            'state' => $character->state,
+            'money' => (float) $character->money,
+            'energy' => (int) $character->energy,
+            'hunger' => (int) $character->hunger,
+            'thirst' => (int) $character->thirst,
+            'education' => (int) $character->education,
+            'job_id' => $character->job_id,
+            'job_title' => $character->job?->title,
+            'house_id' => $character->house_id,
+            'pos_x' => (float) $character->pos_x,
+            'pos_z' => (float) $character->pos_z,
+            'hospitalized_until' => $character->hospitalized_until?->toIso8601String(),
+            'inventory' => $character->inventory->mapWithKeys(fn ($i) => [$i->item => (int) $i->qty])->all(),
+        ];
+    }
+}
@@ -0,0 +1,210 @@
+<?php
+
+namespace App\Http\Controllers\Web;
+
+use App\Http\Controllers\Controller;
+use App\Models\Character;
+use App\Models\Relationship;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Str;
+
+/**
+ * Social graph actions: friendships, marriage and children.
+ */
+class CitySocialController extends Controller
+{
+    /**
+     * Handle a social verb for the caller's character.
+     */
+    public function handle(Request $request, string $verb): JsonResponse
+    {
+        $me = Character::ensureForUser($request->user());
+
+        return match ($verb) {
+            'friend' => $this->friend($request, $me),
+            'accept-friend' => $this->acceptFriend($request, $me),
+            'marry' => $this->marry($request, $me),
+            'child' => $this->child($request, $me),
+            default => response()->json(['message' => __('city.social_unknown')], 422),
+        };
+    }
+
+    /**
+     * Pending incoming social requests for the caller.
+     */
+    public function inbox(Request $request): JsonResponse
+    {
+        $me = Character::ensureForUser($request->user());
+
+        $pending = Relationship::query()
+            ->where('character_b_id', $me->id)
+            ->where('status', Relationship::STATUS_PENDING)
+            ->with('characterA:id,name')
+            ->get()
+            ->map(fn (Relationship $r) => [
+                'id' => $r->id,
+                'type' => $r->type,
+                'from' => $r->characterA?->name,
+            ]);
+
+        $friends = Relationship::query()
+            ->where('status', Relationship::STATUS_ACCEPTED)
+            ->where('type', Relationship::TYPE_FRIEND)
+            ->where(fn ($q) => $q->where('character_a_id', $me->id)->orWhere('character_b_id', $me->id))
+            ->get()
+            ->map(function (Relationship $r) use ($me) {
+                $otherId = (int) $r->character_a_id === (int) $me->id ? $r->character_b_id : $r->character_a_id;
+
+                return Character::query()->whereKey($otherId)->first(['id', 'name']);
+            })
+            ->filter();
+
+        return response()->json([
+            'pending' => $pending,
+            'friends' => $friends,
+        ]);
+    }
+
+    /**
+     * Send a friendship request to another character.
+     */
+    private function friend(Request $request, Character $me): JsonResponse
+    {
+        $data = $request->validate(['character_id' => ['required', 'integer', 'exists:characters,id']]);
+        $other = Character::query()->findOrFail($data['character_id']);
+
+        if ((int) $other->id === (int) $me->id) {
+            return response()->json(['message' => __('city.social_self')], 422);
+        }
+
+        $existing = Relationship::query()
+            ->where('type', Relationship::TYPE_FRIEND)
+            ->where(fn ($q) => $q->where('character_a_id', $me->id)->where('character_b_id', $other->id))
+            ->orWhere(fn ($q) => $q->where('character_a_id', $other->id)->where('character_b_id', $me->id))
+            ->first();
+
+        if ($existing) {
+            return response()->json(['message' => __('city.social_exists')], 422);
+        }
+
+        Relationship::create([
+            'character_a_id' => $me->id,
+            'character_b_id' => $other->id,
+            'type' => Relationship::TYPE_FRIEND,
+            'status' => Relationship::STATUS_PENDING,
+        ]);
+
+        return response()->json(['message' => __('city.social_friend_sent')]);
+    }
+
+    /**
+     * Accept an incoming friendship request.
+     */
+    private function acceptFriend(Request $request, Character $me): JsonResponse
+    {
+        $data = $request->validate(['relationship_id' => ['required', 'integer', 'exists:relationships,id']]);
+        $rel = Relationship::query()->findOrFail($data['relationship_id']);
+
+        if ((int) $rel->character_b_id !== (int) $me->id || $rel->type !== Relationship::TYPE_FRIEND) {
+            return response()->json(['message' => __('auth.forbidden')], 403);
+        }
+
+        $rel->status = Relationship::STATUS_ACCEPTED;
+        $rel->save();
+
+        return response()->json(['message' => __('city.social_friend_ok')]);
+    }
+
+    /**
+     * Marry an accepted friend (one spouse max).
+     */
+    private function marry(Request $request, Character $me): JsonResponse
+    {
+        $data = $request->validate(['character_id' => ['required', 'integer', 'exists:characters,id']]);
+        $other = Character::query()->findOrFail($data['character_id']);
+
+        $friendship = Relationship::query()
+            ->where('type', Relationship::TYPE_FRIEND)
+            ->where('status', Relationship::STATUS_ACCEPTED)
+            ->where(fn ($q) => $q->where('character_a_id', $me->id)->where('character_b_id', $other->id)
+                ->orWhere(fn ($q2) => $q2->where('character_a_id', $other->id)->where('character_b_id', $me->id)))
+            ->exists();
+
+        if (! $friendship) {
+            return response()->json(['message' => __('city.social_need_friend')], 422);
+        }
+
+        $existingSpouse = Relationship::query()
+            ->where('type', Relationship::TYPE_SPOUSE)
+            ->where('status', Relationship::STATUS_ACCEPTED)
+            ->where(fn ($q) => $q->where('character_a_id', $me->id)->orWhere('character_b_id', $me->id))
+            ->exists();
+
+        if ($existingSpouse) {
+            return response()->json(['message' => __('city.social_married')], 422);
+        }
+
+        Relationship::create([
+            'character_a_id' => $me->id,
+            'character_b_id' => $other->id,
+            'type' => Relationship::TYPE_SPOUSE,
+            'status' => Relationship::STATUS_ACCEPTED,
+        ]);
+
+        return response()->json(['message' => __('city.social_married_ok')]);
+    }
+
+    /**
+     * Have a child with the current spouse (creates an NPC character).
+     */
+    private function child(Request $request, Character $me): JsonResponse
+    {
+        $data = $request->validate(['character_id' => ['required', 'integer', 'exists:characters,id']]);
+        $spouse = Character::query()->findOrFail($data['character_id']);
+
+        $married = Relationship::query()
+            ->where('type', Relationship::TYPE_SPOUSE)
+            ->where('status', Relationship::STATUS_ACCEPTED)
+            ->where(fn ($q) => $q->where('character_a_id', $me->id)->where('character_b_id', $spouse->id)
+                ->orWhere(fn ($q2) => $q2->where('character_a_id', $spouse->id)->where('character_b_id', $me->id)))
+            ->exists();
+
+        if (! $married) {
+            return response()->json(['message' => __('city.social_need_spouse')], 422);
+        }
+
+        $childName = Str::limit($me->name.' '.$spouse->name, 40, '');
+        $child = Character::create([
+            'user_id' => null,
+            'city_id' => $me->city_id,
+            'name' => trim($childName) ?: 'Child',
+            'skin' => $me->skin,
+            'hair' => $me->hair,
+            'shirt' => random_int(1, 5),
+            'pos_x' => $me->pos_x + 1,
+            'pos_z' => $me->pos_z + 1,
+            'money' => 0,
+            'energy' => 100,
+            'hunger' => 100,
+            'thirst' => 100,
+            'state' => Character::STATE_AWAKE,
+            'education' => 0,
+            'is_online' => false,
+        ]);
+
+        foreach ([$me, $spouse] as $parent) {
+            Relationship::create([
+                'character_a_id' => $child->id,
+                'character_b_id' => $parent->id,
+                'type' => Relationship::TYPE_PARENT_CHILD,
+                'status' => Relationship::STATUS_ACCEPTED,
+            ]);
+        }
+
+        return response()->json([
+            'message' => __('city.social_child_ok'),
+            'child' => ['id' => $child->id, 'name' => $child->name],
+        ]);
+    }
+}
@@ -4,120 +4,221 @@ namespace App\Http\Controllers\Web;

 use App\Http\Controllers\Controller;
 use App\Models\AiAgent;
+use App\Models\Building;
+use App\Models\Character;
+use App\Models\City;
+use App\Models\Job;
 use App\Models\Store;
 use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Auth;
 use Illuminate\View\View;

 /**
- * 3D city viewer.
+ * City viewer entry point and JSON payload.
 *
- * Serves the Three.js scene page plus a lightweight JSON payload of stores
- * and agents. The JSON endpoint reuses the web session so the browser can
- * fetch world data without a separate API token.
+ * Renders the 3D scene for a chosen city and exposes characters, buildings
+ * and jobs so the frontend can simulate a living persistent world.
 */
 class CityViewerController extends Controller
 {
    /**
-     * Render the city viewer page.
+     * Render the 3D city viewer page.
     */
-    public function __invoke(): View
+    public function __invoke(Request $request): View
    {
-        return view('city.viewer');
+        $city = $this->resolveCity($request);
+
+        return view('city.viewer', [
+            'city' => $city,
+        ]);
    }

    /**
-     * Return the world snapshot consumed by the viewer scene.
+     * JSON payload driving the 3D scene for the selected city.
     */
-    public function data(): JsonResponse
+    public function data(Request $request): JsonResponse
    {
-        $stores = Store::query()
-            ->get(['id', 'name', 'type', 'pos_x', 'pos_y', 'pos_z', 'width', 'height', 'depth', 'is_open'])
-            ->map(fn (Store $store): array => [
-                'id' => $store->id,
-                'name' => $store->name,
-                'type' => $store->type,
-                'position' => [(float) $store->pos_x, (float) $store->pos_y, (float) $store->pos_z],
-                'size' => [(float) $store->width, (float) $store->height, (float) $store->depth],
-                'is_open' => $store->is_open,
-            ]);
+        $city = $this->resolveCity($request);
+        $user = Auth::user();
+        $me = $user ? Character::ensureForUser($user, $city) : null;

-        $agents = AiAgent::query()
-            ->where('status', '!=', 'paused')
-            ->get(['id', 'name', 'type', 'status', 'pos_x', 'pos_y', 'pos_z', 'rotation_y', 'last_decision'])
-            ->map(fn (AiAgent $agent): array => [
-                'id' => $agent->id,
-                'name' => $agent->name,
-                'type' => $agent->type,
-                'status' => $agent->status,
-                'position' => [(float) $agent->pos_x, (float) $agent->pos_y, (float) $agent->pos_z],
-                'rotation_y' => (float) $agent->rotation_y,
-                'last_decision' => $agent->last_decision,
-            ]);
-
-        return response()->json([
-            'generated_at' => now()->toIso8601String(),
-            'stores' => $stores,
-            'agents' => $agents,
-            'layout' => self::cityLayout($stores->all()),
-        ])->header('Cache-Control', 'no-store');
-    }
-
-    /**
-     * Derive a deterministic street layout from store positions.
-     *
-     * Returns road segments and block rectangles so the frontend can build
-     * a consistent grid-based city without additional database tables.
-     *
-     * @param  array<int, array<string, mixed>>  $stores
-     * @return array<string, mixed>
-     */
-    private static function cityLayout(array $stores): array
-    {
-        if ($stores === []) {
-            return ['roads' => [], 'blocks' => []];
-        }
-
-        $xs = array_map(fn ($s) => $s['position'][0], $stores);
-        $zs = array_map(fn ($s) => $s['position'][2], $stores);
-
-        $minX = floor(min($xs) / 40) * 40 - 40;
-        $maxX = ceil(max($xs) / 40) * 40 + 40;
-        $minZ = floor(min($zs) / 40) * 40 - 40;
-        $maxZ = ceil(max($zs) / 40) * 40 + 40;
-
-        $roads = [];
-
-        // Vertical roads every 40 units.
-        for ($x = $minX; $x <= $maxX; $x += 40) {
-            $roads[] = [
-                'from' => [(float) $x, 0.0, (float) $minZ],
-                'to' => [(float) $x, 0.0, (float) $maxZ],
-                'width' => 8.0,
-                'axis' => 'z',
-            ];
-        }
-
-        // Horizontal roads every 40 units.
-        for ($z = $minZ; $z <= $maxZ; $z += 40) {
-            $roads[] = [
-                'from' => [(float) $minX, 0.0, (float) $z],
-                'to' => [(float) $maxX, 0.0, (float) $z],
-                'width' => 8.0,
-                'axis' => 'x',
-            ];
-        }
-
-        // Blocks = cells between roads.
-        $blocks = [];
-        for ($x = $minX; $x < $maxX; $x += 40) {
-            for ($z = $minZ; $z < $maxZ; $z += 40) {
-                $blocks[] = [
-                    'min' => [(float) $x + 5.0, 0.0, (float) $z + 5.0],
-                    'max' => [(float) $x + 35.0, 0.0, (float) $z + 35.0],
-                ];
+        if ($me && (int) $me->city_id !== (int) $city->id) {
+            // Keep the player's home city authoritative when no explicit ?city= given.
+            if (! $request->filled('city')) {
+                $city = $me->city;
            }
        }

-        return ['roads' => $roads, 'blocks' => $blocks];
+        $stores = Store::query()
+            ->orderBy('id')
+            ->get(['id', 'name', 'type', 'pos_x', 'pos_y', 'pos_z', 'width', 'height', 'depth', 'is_open', 'owner_id'])
+            ->map(fn (Store $s): array => [
+                'id' => $s->id,
+                'name' => $s->name,
+                'type' => $s->type,
+                'position' => [(float) $s->pos_x, (float) $s->pos_y, (float) $s->pos_z],
+                'size' => [(float) $s->width, (float) $s->height, (float) $s->depth],
+                'is_open' => (bool) $s->is_open,
+                'owner_id' => $s->owner_id,
+            ]);
+
+        $characters = Character::query()
+            ->where('city_id', $city->id)
+            ->with('user:id,name')
+            ->get()
+            ->map(fn (Character $c): array => [
+                'id' => $c->id,
+                'name' => $c->name,
+                'type' => $c->user_id === null ? 'child' : 'citizen',
+                'status' => $c->state,
+                'position' => [(float) $c->pos_x, (float) $c->pos_y, (float) $c->pos_z],
+                'is_online' => (bool) $c->is_online,
+                'is_me' => $me !== null && (int) $me->id === (int) $c->id,
+                'owner_name' => $c->user?->name,
+            ]);
+
+        $buildings = Building::query()
+            ->where('city_id', $city->id)
+            ->get()
+            ->map(fn (Building $b): array => [
+                'id' => $b->id,
+                'type' => $b->type,
+                'name' => $b->name,
+                'position' => [(float) $b->pos_x, 0, (float) $b->pos_z],
+                'size' => [(float) $b->width, (float) $b->height, (float) $b->depth],
+                'is_complete' => (bool) $b->is_complete,
+                'build_progress' => (int) $b->build_progress,
+                'owner_character_id' => $b->owner_character_id,
+            ]);
+
+        $jobs = Job::query()
+            ->where('city_id', $city->id)
+            ->get()
+            ->map(fn (Job $j): array => [
+                'id' => $j->id,
+                'title' => $j->title,
+                'salary' => (float) $j->salary,
+                'requires_education' => (int) $j->requires_education,
+                'store_id' => $j->store_id,
+            ]);
+
+        $payload = [
+            'generated_at' => now()->toIso8601String(),
+            'city' => [
+                'id' => $city->id,
+                'name' => $city->name,
+                'slug' => $city->slug,
+                'bounds' => [
+                    'min_x' => (float) $city->bounds_min_x,
+                    'max_x' => (float) $city->bounds_max_x,
+                    'min_z' => (float) $city->bounds_min_z,
+                    'max_z' => (float) $city->bounds_max_z,
+                ],
+            ],
+            'stores' => $stores,
+            'characters' => $characters,
+            'buildings' => $buildings,
+            'jobs' => $jobs,
+            'me' => $me ? [
+                'id' => $me->id,
+                'name' => $me->name,
+                'state' => $me->state,
+                'money' => (float) $me->money,
+                'energy' => (int) $me->energy,
+                'hunger' => (int) $me->hunger,
+                'thirst' => (int) $me->thirst,
+                'education' => (int) $me->education,
+                'job_id' => $me->job_id,
+                'job_title' => $me->job?->title,
+                'house_id' => $me->house_id,
+                'position' => [(float) $me->pos_x, (float) $me->pos_y, (float) $me->pos_z],
+                'hospitalized_until' => $me->hospitalized_until?->toIso8601String(),
+                'inventory' => $me->inventory()->get()->mapWithKeys(fn ($i) => [$i->item => (int) $i->qty])->all(),
+            ] : null,
+            'layout' => $this->cityLayout($city, $stores->all()),
+            'agents' => AiAgent::orderBy('id')->get()->map(fn ($a): array => [
+                'id' => $a->id,
+                'name' => $a->name,
+                'type' => $a->type,
+                'status' => $a->status,
+                'position' => [(float) $a->pos_x, (float) $a->pos_y, (float) $a->pos_z],
+                'rotation_y' => (float) $a->rotation_y,
+                'current_goal' => $a->current_goal,
+                'last_decision' => $a->last_decision,
+            ]),
+        ];
+
+        return response()->json($payload)->header('Cache-Control', 'no-store');
+    }
+
+    /**
+     * Resolve the city from the query string or the active default.
+     */
+    private function resolveCity(Request $request): City
+    {
+        $slug = $request->query('city');
+
+        if (is_string($slug) && $slug !== '') {
+            $city = City::query()
+                ->where('slug', $slug)
+                ->orWhere('id', ctype_digit($slug) ? (int) $slug : 0)
+                ->first();
+
+            if ($city) {
+                return $city;
+            }
+        }
+
+        $user = Auth::user();
+        if ($user) {
+            $character = Character::query()->where('user_id', $user->id)->first();
+            if ($character?->city) {
+                return $character->city;
+            }
+        }
+
+        return City::active() ?? City::query()->firstOrFail();
+    }
+
+    /**
+     * Build the street grid layout from city bounds and store anchors.
+     *
+     * @param  array<int, array<string, mixed>>  $storeRows
+     * @return array<string, mixed>
+     */
+    private function cityLayout(City $city, array $storeRows): array
+    {
+        $minX = (int) floor(((float) $city->bounds_min_x) / 40) * 40 - 40;
+        $maxX = (int) ceil(((float) $city->bounds_max_x) / 40) * 40 + 40;
+        $minZ = (int) floor(((float) $city->bounds_min_z) / 40) * 40 - 40;
+        $maxZ = (int) ceil(((float) $city->bounds_max_z) / 40) * 40 + 40;
+
+        $roads = [];
+        for ($x = $minX; $x <= $maxX; $x += 40) {
+            $roads[] = ['from' => [$x, 0, $minZ], 'to' => [$x, 0, $maxZ], 'width' => 8, 'axis' => 'z'];
+        }
+        for ($z = $minZ; $z <= $maxZ; $z += 40) {
+            $roads[] = ['from' => [$minX, 0, $z], 'to' => [$maxX, 0, $z], 'width' => 8, 'axis' => 'x'];
+        }
+
+        $blocks = [];
+        for ($x = $minX; $x < $maxX; $x += 40) {
+            for ($z = $minZ; $z < $maxZ; $z += 40) {
+                $blocks[] = ['min' => [$x + 5, 0, $z + 5], 'max' => [$x + 35, 0, $z + 35]];
+            }
+        }
+
+        return [
+            'roads' => $roads,
+            'blocks' => $blocks,
+            'origin' => [0, 0, 0],
+            'bounds' => [
+                'min_x' => $minX,
+                'max_x' => $maxX,
+                'min_z' => $minZ,
+                'max_z' => $maxZ,
+            ],
+        ];
    }
 }
@@ -36,6 +36,14 @@ class LanguageController extends Controller

        // Persist the cookie preference (1 year) used on subsequent visits.
        $response = back();
+        $previousPath = (string) parse_url($response->getTargetUrl(), PHP_URL_PATH);
+
+        // The 3D viewer fetches /city/data via XHR, which can become the
+        // session's "previous URL" and would dump the user on raw JSON.
+        if ($previousPath === '/city/data') {
+            $response = redirect()->route('city.viewer');
+        }
+
        $response->withCookie(cookie('city10-locale', $locale, 60 * 24 * 365, '/', null, false, true));

        return $response;