273 lines
10 KiB
Markdown
273 lines
10 KiB
Markdown
# Production Play Screen Implementation Plan
|
|
|
|
## Overview
|
|
|
|
Create a new production play screen at `templates/game/play.html` with a 3-column layout optimized for immersive gameplay, separate from the dev console.
|
|
|
|
## Layout Structure
|
|
|
|
```
|
|
+-------------+------------------------+------------------+
|
|
| LEFT | MIDDLE | RIGHT |
|
|
| (280px) | (1fr flex) | (320px) |
|
|
+-------------+------------------------+------------------+
|
|
| Character | Location Header | [History] |
|
|
| - Name/Lv | - Name, Type, Turn # | [Quests] |
|
|
| - HP/MP | Ambient Details | [NPCs] |
|
|
| - Stats | ---------------- | [Map] |
|
|
| ---------- | DM Response Area | |
|
|
| Actions | (main narrative) | Each accordion |
|
|
| [Free] | | independently |
|
|
| [Premium] | | refreshable |
|
|
| [Elite] | | |
|
|
| ---------- | | |
|
|
| [Talk NPC] | | |
|
|
| [Travel] | | |
|
|
+-------------+------------------------+------------------+
|
|
```
|
|
|
|
## Files to Create
|
|
|
|
### Templates
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `templates/game/play.html` | Main 3-column layout |
|
|
| `templates/game/partials/character_panel.html` | Left: actions + character stats |
|
|
| `templates/game/partials/narrative_panel.html` | Middle: DM response + location |
|
|
| `templates/game/partials/sidebar_history.html` | Right accordion: turn history |
|
|
| `templates/game/partials/sidebar_quests.html` | Right accordion: active quests |
|
|
| `templates/game/partials/sidebar_npcs.html` | Right accordion: NPCs at location |
|
|
| `templates/game/partials/sidebar_map.html` | Right accordion: discovered locations |
|
|
| `templates/game/partials/job_polling.html` | Job status polling partial |
|
|
| `templates/game/partials/travel_modal.html` | Travel destination modal |
|
|
| `templates/game/partials/npc_chat_modal.html` | NPC dialogue modal |
|
|
|
|
### CSS
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `static/css/play.css` | All play screen styles |
|
|
|
|
### Flask Views
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `app/views/game_views.py` | New blueprint for production game routes |
|
|
|
|
### Modify
|
|
| File | Change |
|
|
|------|--------|
|
|
| `app/__init__.py` | Register `game_bp` blueprint |
|
|
|
|
## Flask Routes
|
|
|
|
```python
|
|
# Main routes
|
|
GET /play/session/<session_id> # Main play screen
|
|
GET /play/session/<id>/character-panel # Refresh character stats
|
|
GET /play/session/<id>/narrative # Refresh narrative
|
|
GET /play/session/<id>/history # Refresh history accordion
|
|
GET /play/session/<id>/quests # Refresh quests accordion
|
|
GET /play/session/<id>/npcs # Refresh NPCs accordion
|
|
GET /play/session/<id>/map # Refresh map accordion
|
|
|
|
# Action routes
|
|
POST /play/session/<id>/action # Submit action -> job polling
|
|
GET /play/session/<id>/job/<job_id> # Poll job status
|
|
|
|
# Modal routes
|
|
GET /play/session/<id>/travel-modal # Get travel modal
|
|
POST /play/session/<id>/travel # Execute travel
|
|
GET /play/session/<id>/npc/<npc_id>/chat # Get NPC chat modal
|
|
POST /play/session/<id>/npc/<npc_id>/talk # Send message to NPC
|
|
```
|
|
|
|
## CSS Theme
|
|
|
|
```css
|
|
/* Dark fantasy theme matching existing */
|
|
--play-bg-primary: #1a1a2a;
|
|
--play-bg-secondary: #2a2a3a;
|
|
--play-border: #4a4a5a;
|
|
|
|
/* Action tiers */
|
|
--action-free: #3b82f6; /* Blue */
|
|
--action-premium: #8b5cf6; /* Purple */
|
|
--action-elite: #f59e0b; /* Gold */
|
|
|
|
/* Resource bars */
|
|
--hp-bar-fill: #ef4444;
|
|
--mp-bar-fill: #3b82f6;
|
|
```
|
|
|
|
## Action Button Organization
|
|
|
|
**Free Tier (Blue):**
|
|
1. Ask Locals for Information (town/tavern)
|
|
2. Explore the Area (wilderness/dungeon)
|
|
3. Search for Supplies (any) - 2 turn cooldown
|
|
4. Rest and Recover (town/tavern/safe) - 3 turn cooldown
|
|
|
|
**Premium Tier (Purple):**
|
|
5. Investigate Suspicious Activity (any)
|
|
6. Follow a Lead (any)
|
|
7. Make Camp (wilderness) - 5 turn cooldown
|
|
|
|
**Elite Tier (Gold):**
|
|
8. Consult Ancient Texts (library/town) - 3 turn cooldown
|
|
9. Commune with Nature (wilderness) - 4 turn cooldown
|
|
10. Seek Audience with Authorities (town) - 5 turn cooldown
|
|
|
|
## HTMX Patterns
|
|
|
|
### Action Submission
|
|
```html
|
|
<button hx-post="/play/session/{id}/action"
|
|
hx-vals='{"action_type":"button","prompt_id":"ask_locals"}'
|
|
hx-target="#narrative-content"
|
|
hx-indicator="#loading"
|
|
hx-disabled-elt="this">
|
|
```
|
|
|
|
### Job Polling (1s interval)
|
|
```html
|
|
<div hx-get="/play/session/{id}/job/{job_id}"
|
|
hx-trigger="load delay:1s"
|
|
hx-swap="innerHTML">
|
|
```
|
|
|
|
### Cascade Refresh (after action completes)
|
|
```html
|
|
<!-- Hidden triggers in dm_response.html -->
|
|
<div hx-get="/play/session/{id}/history" hx-target="#accordion-history" hx-trigger="load" hidden></div>
|
|
<div hx-get="/play/session/{id}/npcs" hx-target="#accordion-npcs" hx-trigger="load" hidden></div>
|
|
```
|
|
|
|
## Responsive Design
|
|
|
|
- **Desktop (>1024px):** 3-column grid
|
|
- **Tablet (768-1024px):** 2-column, left sidebar as slide-out drawer
|
|
- **Mobile (<768px):** Single column, right sidebar as bottom sheet
|
|
|
|
## Implementation Approach: Visual First
|
|
|
|
Build complete UI with mock/sample data first, then wire up real API calls. This allows rapid iteration on layout and styling before integrating backend.
|
|
|
|
### Phase 1: Complete Visual Layout with Mock Data
|
|
1. Create `game_views.py` with main route using hardcoded mock data
|
|
2. Create `play.html` base template with 3-column grid
|
|
3. Create `play.css` with all styles (theme, grid, components)
|
|
4. Register blueprint
|
|
5. Build all visual components with sample content:
|
|
- Left: Character panel with mock stats/actions
|
|
- Middle: Narrative panel with sample DM text
|
|
- Right: All 4 accordions with mock entries
|
|
|
|
### Phase 2: Interactive Components (No API)
|
|
1. Accordion toggle functionality (JavaScript)
|
|
2. Modal open/close (travel + NPC chat)
|
|
3. Action button states (hover, disabled, loading simulation)
|
|
4. Collapsible ambient details
|
|
5. Responsive breakpoints
|
|
|
|
### Phase 3: Wire Up API Integration ✅ COMPLETE (Nov 24, 2025)
|
|
1. ✅ Replace mock data with real API calls in Flask view
|
|
2. ✅ Implement job polling for actions
|
|
3. ✅ Wire up travel modal to `/api/v1/travel`
|
|
4. ✅ Wire up NPC chat to `/api/v1/npcs/{id}/talk`
|
|
5. ✅ Add HTMX refresh triggers for accordions
|
|
6. ✅ Wire up equipment modal with real character data
|
|
|
|
### Phase 4: Polish
|
|
- Error handling states
|
|
- Loading indicators
|
|
- Empty state messages
|
|
- Accessibility (ARIA labels, keyboard nav)
|
|
|
|
## Critical Reference Files
|
|
|
|
1. `public_web/templates/dev/story_session.html` - HTMX patterns, job polling
|
|
2. `public_web/app/views/dev.py` - Flask view patterns, API client usage
|
|
3. `public_web/static/css/main.css` - Theme variables, base styles
|
|
4. `api/app/data/action_prompts.yaml` - All 10 action definitions
|
|
5. `api/app/api/sessions.py` - Session API response formats
|
|
|
|
## API Endpoints Used
|
|
|
|
All endpoints already exist:
|
|
- `GET /api/v1/sessions/{id}` - Session state (updated to include `character_id`)
|
|
- `POST /api/v1/sessions/{id}/action` - Submit action
|
|
- `GET /api/v1/sessions/{id}/history` - Conversation history
|
|
- `GET /api/v1/jobs/{id}/status` - Poll job status
|
|
- `GET /api/v1/characters/{id}` - Character data
|
|
- `GET /api/v1/npcs/at-location/{id}` - NPCs at location
|
|
- `POST /api/v1/npcs/{id}/talk` - Talk to NPC
|
|
- `GET /api/v1/travel/available` - Available destinations
|
|
- `POST /api/v1/travel` - Travel to location
|
|
|
|
---
|
|
|
|
## Implementation Notes (Phase 3)
|
|
|
|
### Session Creation from Characters Page
|
|
|
|
Added the ability for players to create game sessions directly from `/characters`:
|
|
|
|
**Files Modified:**
|
|
- `public_web/app/views/character_views.py`
|
|
- Updated `list_characters()` to fetch user sessions via `GET /api/v1/sessions` and map them to characters
|
|
- Added new route `POST /characters/<character_id>/play` (`create_session`) that creates a session and redirects to play screen
|
|
|
|
- `public_web/templates/character/list.html`
|
|
- Added sessions section showing active sessions per character (up to 3 displayed)
|
|
- Added "Continue Playing" button (resumes latest session)
|
|
- Added "New Session" button (creates new session)
|
|
- Added "Start Adventure" button for characters without sessions
|
|
- Added CSS for session badges (turn number, status indicator)
|
|
|
|
### Play Screen API Integration
|
|
|
|
**Files Modified:**
|
|
- `public_web/app/views/game_views.py`
|
|
- Removed all mock data constants
|
|
- Added helper functions:
|
|
- `_get_user_tier(client)` - Gets user subscription tier
|
|
- `_build_location_from_game_state(game_state)` - Builds location dict from session
|
|
- `_build_character_from_api(char_data)` - Transforms API character response with robust defaults
|
|
- Updated all routes to use real API calls:
|
|
- `play_session` - Main play screen
|
|
- `character_panel` - Character stats refresh
|
|
- `narrative_panel` - Narrative content refresh
|
|
- `history_accordion`, `quests_accordion`, `npcs_accordion`, `map_accordion` - Sidebar refreshes
|
|
- `take_action` - Submit actions to API, return job polling partial
|
|
- `poll_job` - Poll job status, handle NPC dialogue vs story responses
|
|
- `equipment_modal`, `travel_modal`, `npc_chat_modal` - Modal data loading
|
|
- `do_travel`, `talk_to_npc` - Execute travel and NPC dialogue
|
|
|
|
**New Template:**
|
|
- `public_web/templates/game/partials/npc_dialogue_response.html` - Displays NPC dialogue from job polling results
|
|
|
|
### API Changes
|
|
|
|
**Files Modified:**
|
|
- `api/app/api/sessions.py`
|
|
- Updated `get_session_state()` to include `character_id` and `status` in response
|
|
- This was required because the play screen needs to know which character to load
|
|
|
|
### CSS Fixes
|
|
|
|
**Files Modified:**
|
|
- `public_web/static/css/play.css`
|
|
- Increased `max-width` from 1800px to 2400px for wider screens
|
|
- Changed middle column from `1fr` to `minmax(500px, 1fr)` to ensure minimum width
|
|
- Fixed NPC tags overflow:
|
|
- Added `flex-wrap: wrap` to `.npc-tags`
|
|
- Added `overflow: hidden` and `max-height: 3.5em`
|
|
- Added `white-space: nowrap` to `.npc-tag`
|
|
|
|
### Bug Fixes
|
|
|
|
1. **Character data showing "Unknown"** - Fixed `_build_character_from_api()` to always return complete dict with sensible defaults even when API data is empty or incomplete
|
|
|
|
2. **API not returning character_id** - Updated `api/app/api/sessions.py` to include `character_id` in session state response
|
|
|
|
3. **NPC tags overflow** - Fixed CSS to wrap tags and hide overflow
|