476 lines
17 KiB
Markdown
476 lines
17 KiB
Markdown
# Escape from Jail Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** Add a Bust Out mechanic to the jail page — spend 1000 cash, roll against a dexterity+speed formula, succeed to escape or fail to extend your sentence by 1.5×.
|
||
|
||
**Architecture:** A new `JailService` holds all bust-out logic (mirrors the existing `HealthService::revive()` pattern). A new `JailController` handles the HTTP action. The existing jail view gains a Bust Out card with a CSRF form. No new database migrations.
|
||
|
||
**Tech Stack:** Laravel 11, PHP 8.2, Blade templating, Eloquent ORM, Laravel Sail (Docker). All `artisan` commands must be run via `./vendor/bin/sail artisan`.
|
||
|
||
## Global Constraints
|
||
|
||
- Project runs in **Laravel Sail** — all `php artisan` commands must use `./vendor/bin/sail artisan`
|
||
- Dark crime theme: Tailwind classes `bg-syndicate-*`, `text-crime-*`, `bg-crime-*`, `text-yellow-*` — match the existing jail page colour palette (yellow for jail, not purple/green)
|
||
- Services are instantiated with `new` in controllers — no DI container injection (see existing `CharacterController`, `GymController`)
|
||
- No PHPUnit in this project — manual verification via `./vendor/bin/sail artisan tinker` and browser testing only
|
||
- Flash messages use `session()->flash('success', ...)` / `session()->flash('error', ...)`; displayed via existing layout partials
|
||
- CSRF required on all POST forms (`@csrf`)
|
||
- Routes file: `routes/game.php`
|
||
|
||
---
|
||
|
||
## File Map
|
||
|
||
| Action | File |
|
||
|--------|------|
|
||
| Modify | `config/game.php` — add two keys to `jail` block |
|
||
| Create | `app/Services/Game/JailService.php` |
|
||
| Create | `app/Http/Controllers/Game/JailController.php` |
|
||
| Modify | `routes/game.php` — add bust-out route and pass new vars to jail view |
|
||
| Modify | `resources/views/game/jail.blade.php` — add Bust Out card |
|
||
|
||
---
|
||
|
||
### Task 1: Config + JailService
|
||
|
||
**Files:**
|
||
- Modify: `config/game.php` (lines 81–86)
|
||
- Create: `app/Services/Game/JailService.php`
|
||
|
||
**Interfaces:**
|
||
- Produces:
|
||
- `JailService::bustOut(Character $character): array{success: bool, message: string}`
|
||
- `JailService::sendToJail(Character $character, int $seconds): void`
|
||
- `JailService::releaseFromJail(Character $character): void`
|
||
- `JailService::calculateBustOutChance(Character $character): float` (returns 0.0–1.0)
|
||
|
||
- [ ] **Step 1: Add two config keys to the `jail` block in `config/game.php`**
|
||
|
||
Open `config/game.php`. The existing `jail` block is at lines 81–86:
|
||
|
||
```php
|
||
// Jail system configuration
|
||
'jail' => [
|
||
'sentence_length' => 3600,
|
||
'breakout_chance' => 0.05,
|
||
'breakout_cost' => 1000,
|
||
'sentence_multiplier' => 1.5,
|
||
'bust_out_stat_multiplier' => 0.003, // per combined dex+speed point
|
||
'bust_out_max_chance' => 0.80, // cap at 80%
|
||
],
|
||
```
|
||
|
||
Replace the existing block (4 keys) with the 6-key version above.
|
||
|
||
- [ ] **Step 2: Verify config is readable**
|
||
|
||
```bash
|
||
./vendor/bin/sail artisan tinker
|
||
```
|
||
|
||
In the tinker prompt:
|
||
```php
|
||
config('game.jail.bust_out_stat_multiplier'); // expect 0.003
|
||
config('game.jail.bust_out_max_chance'); // expect 0.8
|
||
exit
|
||
```
|
||
|
||
- [ ] **Step 3: Create `app/Services/Game/JailService.php`**
|
||
|
||
```php
|
||
<?php
|
||
|
||
namespace App\Services\Game;
|
||
|
||
use App\Models\Character;
|
||
|
||
class JailService
|
||
{
|
||
/**
|
||
* Calculate bust-out success chance for a character (0.0 to 1.0).
|
||
*/
|
||
public function calculateBustOutChance(Character $character): float
|
||
{
|
||
$base = config('game.jail.breakout_chance', 0.05);
|
||
$multiplier = config('game.jail.bust_out_stat_multiplier', 0.003);
|
||
$cap = config('game.jail.bust_out_max_chance', 0.80);
|
||
|
||
return min($cap, $base + ($character->dexterity + $character->speed) * $multiplier);
|
||
}
|
||
|
||
/**
|
||
* Attempt to bust out of jail.
|
||
*
|
||
* Deducts breakout_cost cash regardless of outcome.
|
||
* On success: releases character immediately.
|
||
* On failure: multiplies remaining sentence by sentence_multiplier.
|
||
*
|
||
* @return array{success: bool, message: string}
|
||
*/
|
||
public function bustOut(Character $character): array
|
||
{
|
||
$cost = config('game.jail.breakout_cost', 1000);
|
||
|
||
if ($character->money < $cost) {
|
||
return [
|
||
'success' => false,
|
||
'message' => 'You need $' . number_format($cost) . ' to attempt a bust-out.',
|
||
];
|
||
}
|
||
|
||
$character->money -= $cost;
|
||
$successRate = $this->calculateBustOutChance($character);
|
||
$roll = random_int(0, 9999) / 10000;
|
||
|
||
if ($roll <= $successRate) {
|
||
$this->releaseFromJail($character);
|
||
$character->save();
|
||
|
||
return [
|
||
'success' => true,
|
||
'message' => "You escaped! You're free.",
|
||
];
|
||
}
|
||
|
||
// Failure: extend sentence
|
||
$multiplier = config('game.jail.sentence_multiplier', 1.5);
|
||
$remaining = max(0, $character->in_jail_until->diffInSeconds(now()));
|
||
$extended = (int) ceil($remaining * $multiplier);
|
||
|
||
$character->in_jail_until = now()->addSeconds($extended);
|
||
$character->save();
|
||
|
||
$newReleaseTime = $character->in_jail_until->diffForHumans();
|
||
|
||
return [
|
||
'success' => false,
|
||
'message' => "Bust failed — your sentence was extended to {$newReleaseTime}.",
|
||
];
|
||
}
|
||
|
||
/**
|
||
* Send a character to jail for the given number of seconds.
|
||
*/
|
||
public function sendToJail(Character $character, int $seconds): void
|
||
{
|
||
$character->status = 'in_jail';
|
||
$character->in_jail_until = now()->addSeconds($seconds);
|
||
$character->save();
|
||
}
|
||
|
||
/**
|
||
* Release a character from jail immediately.
|
||
*/
|
||
public function releaseFromJail(Character $character): void
|
||
{
|
||
$character->status = 'active';
|
||
$character->in_jail_until = null;
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 4: Smoke-test the service in tinker**
|
||
|
||
```bash
|
||
./vendor/bin/sail artisan tinker
|
||
```
|
||
|
||
```php
|
||
use App\Services\Game\JailService;
|
||
use App\Models\Character;
|
||
|
||
$svc = new JailService();
|
||
|
||
// Fake a character with known stats
|
||
$char = new Character(['dexterity' => 5, 'speed' => 5]);
|
||
$chance = $svc->calculateBustOutChance($char);
|
||
// expect: 0.05 + (5+5)*0.003 = 0.08
|
||
echo $chance; // 0.08
|
||
|
||
$char2 = new Character(['dexterity' => 50, 'speed' => 50]);
|
||
echo $svc->calculateBustOutChance($char2); // 0.35
|
||
|
||
$char3 = new Character(['dexterity' => 100, 'speed' => 100]);
|
||
echo $svc->calculateBustOutChance($char3); // 0.8 (capped)
|
||
exit
|
||
```
|
||
|
||
- [ ] **Step 5: Commit**
|
||
|
||
```bash
|
||
git add config/game.php app/Services/Game/JailService.php
|
||
git commit -m "feat: add JailService and bust-out config keys"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 2: JailController + Route
|
||
|
||
**Files:**
|
||
- Create: `app/Http/Controllers/Game/JailController.php`
|
||
- Modify: `routes/game.php`
|
||
|
||
**Interfaces:**
|
||
- Consumes:
|
||
- `JailService::bustOut(Character): array{success: bool, message: string}` (Task 1)
|
||
- `JailService::calculateBustOutChance(Character): float` (Task 1)
|
||
- Produces:
|
||
- Route `game.jail.bust-out` (POST `/game/jail/bust-out`)
|
||
- Updated jail view route passes `$bustOutChance` and `$bustOutCost` to the view
|
||
|
||
- [ ] **Step 1: Create `app/Http/Controllers/Game/JailController.php`**
|
||
|
||
```php
|
||
<?php
|
||
|
||
namespace App\Http\Controllers\Game;
|
||
|
||
use App\Http\Controllers\Controller;
|
||
use App\Services\Game\JailService;
|
||
use Illuminate\Http\RedirectResponse;
|
||
use Illuminate\Http\Request;
|
||
|
||
class JailController extends Controller
|
||
{
|
||
protected JailService $jailService;
|
||
|
||
public function __construct()
|
||
{
|
||
$this->jailService = new JailService();
|
||
}
|
||
|
||
/**
|
||
* Attempt to bust out of jail.
|
||
*/
|
||
public function bustOut(Request $request): RedirectResponse
|
||
{
|
||
$character = $request->user()->character;
|
||
|
||
if (!$character || !$character->isInJail()) {
|
||
return redirect()->route('game.dashboard');
|
||
}
|
||
|
||
$result = $this->jailService->bustOut($character);
|
||
|
||
if ($result['success']) {
|
||
return redirect()->route('game.dashboard')
|
||
->with('success', $result['message']);
|
||
}
|
||
|
||
return redirect()->route('game.jail')
|
||
->with('error', $result['message']);
|
||
}
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: Add the bust-out route and update the jail GET route in `routes/game.php`**
|
||
|
||
The existing jail route group starts at line 81:
|
||
|
||
```php
|
||
// Jail route (for when character is in jail)
|
||
Route::middleware(['auth'])->group(function () {
|
||
Route::get('/game/jail', function () {
|
||
$character = auth()->user()->character;
|
||
if (!$character || !$character->isInJail()) {
|
||
return redirect()->route('game.dashboard');
|
||
}
|
||
$releaseTime = $character->in_jail_until ? $character->in_jail_until->diffForHumans() : 'unknown';
|
||
$bustOutChance = (int) round((new \App\Services\Game\JailService())->calculateBustOutChance($character) * 100);
|
||
$bustOutCost = config('game.jail.breakout_cost', 1000);
|
||
return view('game.jail', compact('character', 'releaseTime', 'bustOutChance', 'bustOutCost'));
|
||
})->name('game.jail');
|
||
|
||
Route::post('/game/jail/bust-out', [\App\Http\Controllers\Game\JailController::class, 'bustOut'])
|
||
->name('game.jail.bust-out');
|
||
});
|
||
```
|
||
|
||
Replace the existing jail group (lines 81–91 of `routes/game.php`) with the block above.
|
||
|
||
- [ ] **Step 3: Verify routes are registered**
|
||
|
||
```bash
|
||
./vendor/bin/sail artisan route:list --name=game.jail
|
||
```
|
||
|
||
Expected output includes two rows:
|
||
```
|
||
GET /game/jail game.jail
|
||
POST /game/jail/bust-out game.jail.bust-out
|
||
```
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add app/Http/Controllers/Game/JailController.php routes/game.php
|
||
git commit -m "feat: add JailController and bust-out route"
|
||
```
|
||
|
||
---
|
||
|
||
### Task 3: Jail View — Bust Out Card
|
||
|
||
**Files:**
|
||
- Modify: `resources/views/game/jail.blade.php`
|
||
|
||
**Interfaces:**
|
||
- Consumes (variables passed from the route closure, Task 2):
|
||
- `$character` — Character model (has `->money`)
|
||
- `$releaseTime` — string, e.g. "in 45 minutes"
|
||
- `$bustOutChance` — int (percentage, e.g. 8 for 8%)
|
||
- `$bustOutCost` — int (e.g. 1000)
|
||
- `$bustOutCost` formatted with `number_format()` in the view
|
||
|
||
- [ ] **Step 1: Replace `resources/views/game/jail.blade.php` with the updated version**
|
||
|
||
```blade
|
||
@extends('layouts.game')
|
||
|
||
@section('title', 'Jail')
|
||
|
||
@section('game-content')
|
||
<div class="max-w-2xl mx-auto space-y-4">
|
||
|
||
{{-- Flash messages --}}
|
||
@if(session('success'))
|
||
<div class="bg-green-900/30 border border-green-700 text-green-300 rounded-lg px-4 py-3 text-sm">
|
||
{{ session('success') }}
|
||
</div>
|
||
@endif
|
||
@if(session('error'))
|
||
<div class="bg-red-900/30 border border-red-700 text-red-300 rounded-lg px-4 py-3 text-sm">
|
||
{{ session('error') }}
|
||
</div>
|
||
@endif
|
||
|
||
<div class="bg-syndicate-800 border border-syndicate-700 rounded-lg">
|
||
<div class="p-8 text-center">
|
||
<div class="mb-6">
|
||
<span class="text-6xl">🚔</span>
|
||
</div>
|
||
|
||
<h1 class="font-display text-2xl font-bold text-gray-100 mb-4">You're in Jail</h1>
|
||
<p class="text-gray-400 mb-6 text-sm">Your character has been arrested and is currently serving time.</p>
|
||
|
||
{{-- Status card --}}
|
||
<div class="bg-yellow-900/20 border border-yellow-800 rounded-lg p-6 mb-6 text-left">
|
||
<h3 class="font-display text-base font-semibold text-yellow-300 mb-3">Your Status</h3>
|
||
<div class="space-y-2 text-sm">
|
||
<div class="flex justify-between">
|
||
<span class="text-gray-400">Status</span>
|
||
<span class="text-yellow-400 font-medium">In Jail</span>
|
||
</div>
|
||
<div class="flex justify-between">
|
||
<span class="text-gray-400">Release Time</span>
|
||
<span class="text-gray-200 font-medium">{{ $releaseTime }}</span>
|
||
</div>
|
||
<div class="flex justify-between">
|
||
<span class="text-gray-400">Cash on Hand</span>
|
||
<span class="text-gray-200 font-medium">${{ number_format($character->money) }}</span>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
{{-- Bust Out card --}}
|
||
<div class="bg-syndicate-700 border border-syndicate-600 rounded-lg p-6 mb-6 text-left">
|
||
<h3 class="font-display text-base font-semibold text-gray-100 mb-1">Bust Out</h3>
|
||
<p class="text-gray-400 text-xs mb-4">Spend cash for a chance to escape early. Failure extends your sentence.</p>
|
||
|
||
<div class="space-y-2 text-sm mb-4">
|
||
<div class="flex justify-between">
|
||
<span class="text-gray-400">Success Chance</span>
|
||
<span class="text-yellow-400 font-medium">{{ $bustOutChance }}%</span>
|
||
</div>
|
||
<div class="flex justify-between">
|
||
<span class="text-gray-400">Cost</span>
|
||
<span class="text-gray-200 font-medium">${{ number_format($bustOutCost) }}</span>
|
||
</div>
|
||
<div class="flex justify-between">
|
||
<span class="text-gray-400">On Failure</span>
|
||
<span class="text-red-400 font-medium">Sentence × 1.5</span>
|
||
</div>
|
||
</div>
|
||
|
||
@if($character->money >= $bustOutCost)
|
||
<form action="{{ route('game.jail.bust-out') }}" method="POST">
|
||
@csrf
|
||
<button type="submit"
|
||
class="w-full flex items-center justify-center px-6 py-3 bg-yellow-700 hover:bg-yellow-600 text-white font-medium rounded-lg transition">
|
||
<span class="mr-2">🔓</span>
|
||
Bust Out ({{ $bustOutChance }}% chance)
|
||
</button>
|
||
</form>
|
||
@else
|
||
<button type="button" disabled
|
||
title="You need ${{ number_format($bustOutCost) }} to attempt a bust-out"
|
||
class="w-full flex items-center justify-center px-6 py-3 bg-syndicate-600 text-gray-500 font-medium rounded-lg cursor-not-allowed">
|
||
<span class="mr-2">🔒</span>
|
||
Not Enough Cash
|
||
</button>
|
||
@endif
|
||
</div>
|
||
|
||
<div class="space-y-4">
|
||
<p class="text-sm text-gray-600">Or wait for your sentence to complete automatically.</p>
|
||
|
||
<a href="{{ route('game.dashboard') }}"
|
||
class="inline-flex items-center text-gray-500 hover:text-gray-300 transition text-sm">
|
||
<svg class="w-4 h-4 mr-1" fill="none" stroke="currentColor" viewBox="0 0 24 24">
|
||
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 19l-7-7 7-7" />
|
||
</svg>
|
||
Back to Dashboard
|
||
</a>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
@endsection
|
||
```
|
||
|
||
- [ ] **Step 2: Verify the jail page renders**
|
||
|
||
In a browser (or via `curl`), navigate to `/game/jail` while logged in with a jailed character. Confirm:
|
||
- Status card shows release time and cash on hand
|
||
- Bust Out card shows correct % and cost
|
||
- If character has ≥ $1,000: button is active (yellow), form submits to `game.jail.bust-out`
|
||
- If character has < $1,000: button is disabled, grey, shows tooltip
|
||
|
||
To temporarily put a character in jail for testing:
|
||
```bash
|
||
./vendor/bin/sail artisan tinker
|
||
```
|
||
```php
|
||
use App\Models\Character;
|
||
$c = Character::first();
|
||
$c->status = 'in_jail';
|
||
$c->in_jail_until = now()->addHour();
|
||
$c->save();
|
||
exit
|
||
```
|
||
|
||
Then visit `/game/jail`.
|
||
|
||
- [ ] **Step 3: Test the full bust-out flow**
|
||
|
||
With the jailed character, click "Bust Out":
|
||
- **Success path:** You are redirected to `/game` with a green "You escaped! You're free." flash.
|
||
- **Failure path:** You stay on `/game/jail` with a red "Bust failed — your sentence was extended to..." flash and the release time has increased.
|
||
|
||
Verify cash was deducted in both cases:
|
||
```bash
|
||
./vendor/bin/sail artisan tinker
|
||
```
|
||
```php
|
||
use App\Models\Character;
|
||
Character::first()->money; // should be 1000 less than before
|
||
exit
|
||
```
|
||
|
||
- [ ] **Step 4: Commit**
|
||
|
||
```bash
|
||
git add resources/views/game/jail.blade.php
|
||
git commit -m "feat: add bust-out card to jail page"
|
||
``` |