Code_of_Conquest/docs/PLAYSCREEN.md

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

# 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

/* 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

<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)

<div hx-get="/play/session/{id}/job/{job_id}"
     hx-trigger="load delay:1s"
     hx-swap="innerHTML">

Cascade Refresh (after action completes)

<!-- 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