Update CSS file paths and enhance tutorial system

- Changed CSS file paths in index.html and show.html.erb to reflect new directory structure under public/break_escape. - Added a new tutorial.css file with styles tailored for the tutorial system, ensuring a cohesive pixel-art aesthetic. - Enhanced the tutorial manager to track player interactions, including clicks to move and inventory item usage, improving the tutorial experience for new players. - Updated tutorial steps to dynamically include objectives based on the current scenario. Files modified: - index.html: Updated CSS links. - show.html.erb: Updated CSS links. - tutorial.css: New styles for the tutorial system. - player.js: Added notifications for player actions. - tutorial-manager.js: Enhanced logic for tracking tutorial progress and objectives. - interactions.js: Added notifications for inventory interactions.
2026-02-20 13:50:46 +00:00 · 2026-01-19 09:54:15 +00:00
parent b7223af010
commit 5c28743144
13 changed files with 1174 additions and 104 deletions
--- a/docs/TUTORIAL_STYLE_COMPARISON.md
+++ b/docs/TUTORIAL_STYLE_COMPARISON.md
@@ -0,0 +1,259 @@
+# Tutorial Style Comparison - Before & After
+
+## Quick Reference Guide
+
+### Tutorial Prompt Modal
+
+| Property | Before | After | Reason |
+|----------|--------|-------|--------|
+| Overlay Background | `rgba(0, 0, 0, 0.85)` | `transparent` | Keep game visible |
+| Overlay Pointer Events | Normal | `pointer-events: none` | Allow clicks through |
+| Overlay Z-Index | `10000` | `1400` | Below minigames (1500+) |
+| Modal Background | `linear-gradient(135deg, #1a1a2e 0%, #16213e 100%)` | `rgba(0, 0, 0, 0.95)` | Match game's solid dark backgrounds |
+| Modal Pointer Events | Normal | `pointer-events: all` | Re-enable for modal |
+| Border Radius | `12px` | `0` (removed) | Pixel-art aesthetic |
+| Box Shadow | Basic shadow with inner glow | Enhanced: `0 0 30px rgba(0, 255, 136, 0.4)` | Stronger accent color glow |
+| Inner Glow | Inline style | `::before` pseudo-element | Better separation of concerns |
+| Title Font Size | `20px` | `20px` (kept) | Good size maintained |
+| Title Letter Spacing | None | `1px` | Better readability |
+| Body Font Size | `20px` | `22px` | Improved readability |
+| Body Bottom Margin | `25px` | `30px` | Better spacing |
+
+### Tutorial Panel
+
+| Property | Before | After | Reason |
+|----------|--------|-------|--------|
+| Overlay Background | `rgba(0, 0, 0, 0.4)` | `transparent` | Keep game visible |
+| Overlay Z-Index | `9999` | `1400` | Below minigames (1500+) |
+| Panel Background | `linear-gradient(135deg, #1a1a2e 0%, #16213e 100%)` | `rgba(0, 0, 0, 0.95)` | Consistency with other panels |
+| Border Radius | `12px` | `0` (removed) | Pixel-art aesthetic |
+| Bottom Position | `20px` | `100px` | More clearance above inventory |
+| Max Height | None | `calc(100vh - 120px)` | Prevent going off screen |
+| Overflow | Hidden | `auto` with scrollbar | Handle tall content |
+| Box Shadow | Basic shadow | Enhanced double shadow | Better depth |
+| Inner Glow | Inline style | `::before` pseudo-element | Better implementation |
+
+### Buttons (Primary)
+
+| Property | Before | After | Reason |
+|----------|--------|-------|--------|
+| Border Radius | `6px` | `0` (removed) | Sharp corners |
+| Box Shadow | Single shadow on hover | Layered 3D effect | Better depth perception |
+| Hover Transform | `translateY(-2px)` | `translateY(-2px)` (kept) | Good interaction |
+| Active State | None | `translateY(0px)` with adjusted shadow | Button press feedback |
+| Letter Spacing | None | `1px` | Better readability |
+
+### Buttons (Secondary)
+
+| Property | Before | After | Reason |
+|----------|--------|-------|--------|
+| Background | `transparent` | `rgba(0, 0, 0, 0.5)` | More visible |
+| Color | `#888` | `#aaa` | Better contrast |
+| Hover Color | `#aaa` | `#fff` | Stronger feedback |
+| Box Shadow | None | `0 2px 0 #222` | Depth effect |
+
+### Progress Indicator
+
+| Property | Before | After | Reason |
+|----------|--------|-------|--------|
+| Font Size | `18px` | `20px` | Better visibility |
+| Letter Spacing | `1px` | `2px` | More emphasis |
+| Text Shadow | None | `0 0 8px rgba(0, 255, 136, 0.5)` | Accent glow |
+
+### Skip Button
+
+| Property | Before | After | Reason |
+|----------|--------|-------|--------|
+| Border | `1px solid #444` | `2px solid #444` | Consistent with game |
+| Border Radius | `4px` | `0` (removed) | Pixel-art aesthetic |
+| Font Size | `16px` | `18px` | Better readability |
+| Letter Spacing | None | `1px` | Consistency |
+| Text Transform | None | `uppercase` | Better emphasis |
+| Hover Background | None | `rgba(255, 107, 107, 0.1)` | Better feedback |
+| Hover Box Shadow | None | `0 0 10px rgba(255, 107, 107, 0.3)` | Red glow warning |
+
+### Tutorial Title
+
+| Property | Before | After | Reason |
+|----------|--------|-------|--------|
+| Font Size | `16px` | `18px` | Better hierarchy |
+| Margin Bottom | `12px` | `15px` | Better spacing |
+| Letter Spacing | None | `1px` | Consistency |
+
+### Tutorial Instruction
+
+| Property | Before | After | Reason |
+|----------|--------|-------|--------|
+| Font Size | `20px` | `22px` | Better readability |
+| Line Height | `1.5` | `1.5` (kept) | Good value |
+
+### Objective Box
+
+| Property | Before | After | Reason |
+|----------|--------|-------|--------|
+| Border Left | `3px solid #00ff88` | `4px solid #00ff88` | More prominent |
+| Border Radius | `4px` | `0` (removed) | Pixel-art aesthetic |
+| Padding | `10px 15px` | `12px 16px` | Better spacing |
+| Animation | None | `objective-pulse` (2s infinite) | Draw attention |
+| Completed State | None | `.completed` class with green | Visual feedback |
+
+### Objective Label (strong)
+
+| Property | Before | After | Reason |
+|----------|--------|-------|--------|
+| Font Size | `12px` | `13px` | Slightly larger |
+| Margin Bottom | `5px` | `8px` | Better spacing |
+| Text Transform | None | `uppercase` | Emphasis |
+| Letter Spacing | None | `1px` | Consistency |
+
+### Objective Text
+
+| Property | Before | After | Reason |
+|----------|--------|-------|--------|
+| Font Size | `18px` | `20px` | Better readability |
+| Line Height | None | `1.4` | Better multi-line |
+
+### Tutorial Actions
+
+| Property | Before | After | Reason |
+|----------|--------|-------|--------|
+| Border Top | None | `2px solid #444` | Visual separation |
+| Padding Top | None | `15px` | Better spacing |
+
+### Continue Button
+
+| Property | Before | After | Reason |
+|----------|--------|-------|--------|
+| Border Radius | `6px` | `0` (removed) | Pixel-art aesthetic |
+| Box Shadow | Single on hover | Layered 3D effect | Better depth |
+| Letter Spacing | None | `1px` | Consistency |
+| Text Transform | None | `uppercase` | Emphasis |
+
+## New Features Added
+
+### 1. Completion State
+```css
+.tutorial-objective.completed {
+    border-left-color: #4ade80;
+    background: rgba(74, 222, 128, 0.1);
+    animation: none;
+}
+```
+Visual feedback when objectives are completed.
+
+### 2. Objective Pulse Animation
+```css
+@keyframes objective-pulse {
+    0%, 100% {
+        border-left-color: #00ff88;
+        box-shadow: 0 0 5px rgba(0, 255, 136, 0.3);
+    }
+    50% {
+        border-left-color: #00cc6a;
+        box-shadow: 0 0 15px rgba(0, 255, 136, 0.5);
+    }
+}
+```
+Draws attention to current objective.
+
+### 3. Focus States
+```css
+.tutorial-btn:focus,
+.tutorial-next:focus,
+.tutorial-skip:focus {
+    outline: 3px solid #00ff88;
+    outline-offset: 3px;
+}
+```
+Accessibility for keyboard navigation.
+
+### 4. Reduced Motion Support
+```css
+@media (prefers-reduced-motion: reduce) {
+    /* All animations disabled */
+}
+```
+Respects user accessibility preferences.
+
+### 5. High Contrast Mode
+```css
+@media (prefers-contrast: high) {
+    /* Enhanced borders and shadows */
+}
+```
+Better visibility for users with visual needs.
+
+## Color Palette Used
+
+| Color | Hex | Usage |
+|-------|-----|-------|
+| Primary Accent | `#00ff88` | Borders, titles, primary buttons |
+| Primary Accent Dark | `#00cc6a` | Button hover/active states |
+| Primary Accent Darker | `#00aa55` | Deep shadow effects |
+| Success Green | `#4ade80` | Completion indicators |
+| Warning Red | `#ff6b6b` | Skip button hover |
+| Text Primary | `#fff` | Main text |
+| Text Secondary | `#e0e0e0` | Body text |
+| Text Tertiary | `#aaa` | Secondary buttons |
+| Border Standard | `#444` | Dividers, inactive borders |
+| Border Light | `#666` | Hover states |
+| Background Dark | `rgba(0, 0, 0, 0.95)` | Panel backgrounds |
+| Background Overlay | `rgba(0, 0, 0, 0.85)` | Full-screen overlays |
+
+## Typography Scale
+
+| Element | Font | Size (Desktop) | Size (Mobile) |
+|---------|------|----------------|---------------|
+| Modal Title | Press Start 2P | 20px | 16px |
+| Panel Title | Press Start 2P | 18px | 14px |
+| Button Text | Press Start 2P | 12px | 10px |
+| Objective Label | Press Start 2P | 13px | 11px |
+| Progress Text | VT323 | 20px | 18px |
+| Body Text | VT323 | 22px | 20px |
+| Instruction Text | VT323 | 22px | 20px |
+| Objective Text | VT323 | 20px | 18px |
+| Skip Button | VT323 | 18px | 16px |
+
+## Spacing System
+
+| Property | Desktop | Mobile |
+|----------|---------|--------|
+| Modal Padding | 30px | 20px |
+| Panel Padding | 20px 25px | 15px 18px |
+| Button Padding (Primary) | 12px 24px | 10px 16px |
+| Objective Padding | 12px 16px | 10px 12px |
+| Section Gap | 15px | 12px |
+| Button Gap | 15px | 10px |
+
+## Animation Timing
+
+| Animation | Duration | Easing | Purpose |
+|-----------|----------|--------|---------|
+| fadeIn | 0.3s | ease-in | Overlay appearance |
+| slideDown | 0.4s | ease-out | Modal entrance |
+| slideUp | 0.4s | ease-out | Panel entrance |
+| objective-pulse | 2s | ease-in-out (infinite) | Draw attention |
+| hover transitions | 0.2s | ease | Button interactions |
+
+## Summary of Changes
+
+- ✅ Removed all border-radius for pixel-art aesthetic
+- ✅ Replaced gradients with solid dark backgrounds
+- ✅ **Removed dark overlay** - game stays fully visible
+- ✅ **Proper z-index layering** - tutorial below minigames (1400 vs 1500)
+- ✅ **Pointer events management** - clicks pass through overlay
+- ✅ **Screen positioning** - max-height prevents going off top of screen
+- ✅ **Smart content handling** - scrollable if content is too tall
+- ✅ **Conditional steps** - objectives step skipped if scenario has none
+- ✅ Added 3D depth to buttons with layered shadows
+- ✅ Increased font sizes for better readability
+- ✅ Added letter-spacing for consistency
+- ✅ Enhanced hover and active states
+- ✅ Added pulsing animation to objectives
+- ✅ Implemented completion visual feedback
+- ✅ Added accessibility features (focus, reduced-motion, high-contrast)
+- ✅ Improved mobile responsiveness
+- ✅ Better positioning relative to game HUD
+- ✅ Consistent color palette with rest of game
+- ✅ Added inner glow effects with pseudo-elements
+
--- a/docs/TUTORIAL_UI_IMPROVEMENTS.md
+++ b/docs/TUTORIAL_UI_IMPROVEMENTS.md
@@ -0,0 +1,225 @@
+# Tutorial UI Improvements
+
+## Overview
+
+The tutorial system UI has been significantly improved to match BreakEscape's established design language and provide a more polished, cohesive experience for new players.
+
+## Design Language Alignment
+
+The tutorial system now consistently uses:
+
+- **Dark backgrounds**: `rgba(0, 0, 0, 0.95)` for modals/panels (matching other UI elements)
+- **Transparent overlays**: No dark screen overlay - game remains visible
+- **Sharp corners**: No border-radius (pixel-art aesthetic)
+- **2px borders**: Using `#444` for standard borders, `#00ff88` for accented elements
+- **Typography**: 
+  - `Press Start 2P` for headers and titles
+  - `VT323` for body text and instructions
+- **Accent color**: `#00ff88` (cyan-green) for primary actions and highlights
+- **Secondary colors**: 
+  - `#4ade80` for completion/success states
+  - `#ff6b6b` for warnings/skip actions
+- **Z-index hierarchy**: Tutorial at 1400, below minigames (1500+) and dialogue systems
+
+## Key Improvements
+
+### 1. Visual Consistency
+
+**Before**: Tutorial used gradients and rounded corners that didn't match the game's pixel-art aesthetic.
+
+**After**: 
+- Removed rounded corners completely
+- Replaced gradients with solid dark backgrounds
+- Added subtle inner glow effects using `::before` pseudo-elements
+- Consistent border styling with `#00ff88` accent color
+
+### 2. Enhanced Buttons
+
+**Improved button styling with:**
+- 3D depth effect using layered box-shadows
+- Proper active states that respond to clicks
+- Better hover animations with translateY transforms
+- Color consistency with the game's primary accent color
+
+### 3. Tutorial Panel Positioning
+
+**Changed**: Panel now sits at `bottom: 90px` to properly clear the inventory bar (80px height)
+
+**Why**: Prevents overlap with the game's HUD elements while maintaining visibility
+
+### 4. Visual Feedback
+
+**Added animations:**
+- Pulsing border effect on objective box (using `objective-pulse` animation)
+- Completion state with color change to green (`#4ade80`)
+- Smooth transitions between states
+
+**JavaScript enhancements:**
+- Added `.completed` class when objectives are finished
+- Visual indicator shows immediately when player completes a step
+- Player must click "Continue" after completing each step (no auto-advance)
+- All steps now track real player actions (movement, running, interaction, click-to-move, inventory clicks)
+- Inventory step teaches players to click items like the Notepad to access notes
+- Final "Objectives" step shows Continue button immediately for player to proceed at their pace
+- **Smart step detection**: Objectives step automatically skipped if scenario has no objectives
+- Gives players complete control over tutorial pacing
+
+### 5. Typography Improvements
+
+**Enhanced readability:**
+- Increased font sizes: 
+  - Body text: `20px` → `22px`
+  - Progress indicator: `18px` → `20px`
+  - Titles: Added consistent `letter-spacing: 1px`
+- Better text shadows on accent color elements
+- Improved line-height for multi-line text
+
+### 6. Accessibility
+
+**Added support for:**
+
+- **Keyboard navigation**: 
+  - Visible focus states with 3px solid outlines
+  - Proper tab order through interactive elements
+
+- **Reduced motion**: 
+  - Respects `prefers-reduced-motion` media query
+  - Disables all animations and transforms when requested
+
+- **High contrast mode**: 
+  - Increases border widths to 3px
+  - Enhances box-shadows for better visibility
+  - Bolds important text
+
+### 7. Mobile Responsiveness & Screen Positioning
+
+**Improved mobile experience:**
+- Adjusted font sizes for smaller screens
+- Reduced padding and margins appropriately
+- Maintained proper spacing above inventory on mobile
+- Buttons scale better on touch devices
+- Max width set to 95% for better edge spacing
+
+**Screen positioning improvements:**
+- Panel positioned at `bottom: 100px` (was 90px) for better clearance
+- Added `max-height: calc(100vh - 120px)` to prevent panel going off top of screen
+- Added scrollable content with styled scrollbar if panel content is too tall
+- Works on all screen sizes and orientations
+
+### 8. Polish & Details
+
+**Small touches that matter:**
+- Inner glow effect on modals using `::before` pseudo-element
+- Colored left borders on objective boxes (matching notification system)
+- Better box-shadow layering for depth perception
+- Smooth slide-up and slide-down animations
+- Proper z-index layering (1400 for tutorial, below minigames at 1500+)
+- **No dark overlay** - game remains fully visible during tutorial
+- **Pointer events management** - clicks pass through overlay to game
+
+## File Changes
+
+### `/public/break_escape/css/tutorial.css`
+- Complete redesign of all tutorial system styles
+- Added accessibility media queries
+- Improved animations and transitions
+- Better mobile responsive breakpoints
+
+### `/public/break_escape/js/systems/tutorial-manager.js`
+- Added completion class toggling for visual feedback
+- Enhanced step showing logic
+- Auto-advance steps show completed state immediately
+
+## Testing
+
+A dedicated test file has been created at `/test-tutorial-ui.html` that allows you to:
+
+1. Preview the tutorial prompt modal
+2. See active tutorial steps
+3. View completed tutorial steps
+4. Test responsive behavior
+5. Verify accessibility features
+
+**Usage:**
+```bash
+# Open in browser
+open test-tutorial-ui.html
+
+# Or use keyboard shortcuts:
+# Press 1: Show prompt modal
+# Press 2: Show active tutorial step
+# Press 3: Show completed tutorial step
+```
+
+## Design Patterns Matched
+
+The tutorial system now matches these existing BreakEscape patterns:
+
+1. **Objectives Panel** (`objectives.css`):
+   - Similar header structure with borders
+   - Consistent color scheme
+   - Matching font usage
+
+2. **Notifications** (`notifications.css`):
+   - Colored left borders for status
+   - Similar animation patterns
+   - Consistent typography
+
+3. **HUD Elements** (`hud.css`):
+   - Proper z-index layering
+   - Pixel-art rendering
+   - Consistent positioning
+
+4. **Modals** (`modals.css`):
+   - Dark backgrounds with proper opacity
+   - Border styling
+   - Button patterns
+
+## Browser Compatibility
+
+Tested and working in:
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+- Mobile browsers (iOS Safari, Chrome Mobile)
+
+## Future Enhancements
+
+Potential improvements for future iterations:
+
+1. Sound effects for step completion
+2. Animated checkmarks or icons
+3. Progress bar at bottom of panel
+4. Keyboard shortcut hints for desktop tutorial steps
+5. Touch gesture animations for mobile steps
+6. Multi-language support with proper text scaling
+
+## Tutorial Flow
+
+**Player-controlled progression:**
+1. Player completes an objective (e.g., moves with WASD, clicks to move)
+2. Objective box turns green with "✓ COMPLETED" indicator
+3. "Continue →" button appears
+4. Player clicks Continue when ready to proceed
+5. No forced auto-advance - player controls pacing for all steps
+
+**Desktop Tutorial Steps:**
+1. Movement (WASD) - Tracks keyboard movement
+2. Running (Shift+WASD) - Tracks running state
+3. Interaction (E key) - Tracks interaction events
+4. Alternative Movement (Click) - Tracks click-to-move
+5. Inventory (Click Notepad) - Tracks inventory item clicks
+6. Objectives Panel - Continue button shows immediately (only if scenario has objectives)
+
+**Mobile Tutorial Steps:**
+1. Movement (Tap) - Tracks tap-to-move
+2. Interaction (Tap objects) - Tracks interaction events
+3. Inventory (Tap Notepad) - Tracks inventory item clicks
+4. Objectives Panel - Continue button shows immediately (only if scenario has objectives)
+
+**Note:** The Objectives step is automatically skipped if the current scenario doesn't define any objectives.
+
+## Summary
+
+The tutorial system now provides a cohesive, polished experience that matches BreakEscape's pixel-art aesthetic while maintaining excellent usability and accessibility. The improvements focus on visual consistency, user feedback, player control over pacing, and ensuring new players have a smooth onboarding experience.
+