Scenario Slides Troubleshooting Guide

Common issues and solutions

Overview

This guide addresses common technical issues when using scenario slides for live sessions. Issues are organized by category for quick reference.

Quick navigation:

Browser Issues

Slides Won’t Load

Symptoms: Blank page, spinning loader, or error message when opening scenario HTML file.

Solutions:

  1. Try different browser:
    • Chrome → Firefox → Edge
    • Some extensions interfere with RevealJS
  2. Clear browser cache:
    • Chrome: Ctrl+Shift+Delete → Select “Cached images and files” → Clear
    • Firefox: Ctrl+Shift+Delete → Select “Cache” → Clear Now
    • Edge: Ctrl+Shift+Delete → Select “Cached images and files” → Clear
  3. Disable extensions temporarily:
    • Chrome: Menu → More Tools → Extensions → Toggle off all
    • Test slides again
    • Re-enable extensions one by one to identify culprit
  4. Update browser:
    • Help → About → Check for updates
    • Restart browser

Why this happens: Some browser extensions (ad blockers, privacy tools) interfere with JavaScript-heavy presentations like RevealJS.

Slides Display Incorrectly

Symptoms: Overlapping text, missing images, broken layouts.

Solutions:

  1. Reset browser zoom:
    • Ctrl+0 (zero) to reset to 100%
    • RevealJS is designed for 100% zoom
  2. Hard refresh:
    • Ctrl+F5 (Windows) or Cmd+Shift+R (Mac)
    • Forces browser to reload all assets
  3. Check browser console:
    • Press F12 → Console tab
    • Look for red error messages
    • Screenshot errors and report if persistent
  4. Test in incognito/private mode:
    • Rules out extension interference
    • File → New Incognito Window
    • Open slides again

Why this happens: Cached CSS or JavaScript from previous versions can conflict with current slides.

Speaker View Won’t Open

Symptoms: Pressing S does nothing, or new window opens but is blank.

Solutions:

  1. Check popup blocker:
    • Browser may be blocking speaker view popup
    • Allow popups for localhost or file:// URLs
    • Chrome: Address bar → Popups blocked icon → Always allow
  2. Try manual window management:
    • Click “Presenter Mode” link if visible in slides
    • Duplicate browser tab manually
    • Add ?showNotes=true to URL
  3. Restart browser:
    • Close all browser windows
    • Open browser fresh
    • Try S key again

Why this happens: Browser popup blockers treat speaker view as unwanted popup.

Display Problems

Wrong Content on Wrong Screen

Symptoms: Presenter view showing on projector, main presentation on laptop.

Solutions:

  1. Identify which window is which:
    • Advance slides with arrows on each window
    • Watch which one changes
  2. Drag windows to correct displays:
    • Click and drag presenter window to laptop screen
    • Click and drag main presentation to projector
    • Windows snap to displays automatically
  3. Make projector “primary display” if needed:
    • Windows: Right-click desktop → Display settings → Identify → Set projector as primary
    • Mac: System Preferences → Displays → Arrangement → Drag menu bar to projector icon
  4. Reopen speaker view after moving:
    • Close speaker view window
    • Press S again
    • Position correctly immediately

Why this happens: RevealJS follows window positioning, not automatic screen detection.

Projector Mirroring Instead of Extending

Symptoms: Laptop and projector show identical content, can’t separate presenter view from main presentation.

Solutions:

  • Windows:
    1. Press Win+P
    2. Select “Extend” (not “Duplicate”)
    3. Press S again for speaker view
    4. Position windows correctly
  • Mac:
    1. System Preferences → Displays
    2. Arrangement tab
    3. Uncheck “Mirror Displays”
    4. Press S again for speaker view
    5. Position windows correctly

Why this happens: Default display mode is often “duplicate” for presentations.

Projector Not Detected

Symptoms: Laptop doesn’t recognize external display.

Solutions:

  1. Check physical connection:
    • Reseat HDMI/DisplayPort/VGA cable
    • Try different cable if available
    • Try different port on laptop
  2. Force detection:
    • Windows: Win+P → Connect to wireless display → Detect
    • Mac: System Preferences → Displays → Detect Displays button
  3. Projector must be powered on:
    • Check projector power light
    • Select correct input source on projector (HDMI 1 vs 2, etc.)
  4. Driver issues (Windows):
    • Device Manager → Display adapters
    • Update display driver
    • Restart computer

Why this happens: Hardware handshake between devices can fail.

Display Resolution Issues

Symptoms: Slides appear stretched, compressed, or distorted on projector.

Solutions:

  1. Use native resolution:
    • RevealJS slides are 1280x720 (16:9 aspect ratio)
    • Set projector to 720p or 1080p
    • Avoid 4:3 aspect ratios
  2. Adjust scaling:
    • Windows: Display settings → Scale → 100%
    • Mac: System Preferences → Displays → Scaled → Default
  3. Let projector auto-adjust:
    • Most projectors have “Auto” button
    • Press to optimize image

Why this happens: Resolution mismatch between laptop output and projector input.

Navigation Issues

Arrow Keys Don’t Advance Slides

Symptoms: Pressing left/right arrows does nothing.

Solutions:

  1. Click presentation window:
    • Browser focus might be on different window
    • Click anywhere on presentation
    • Try arrows again
  2. Check if stuck slide:
    • Some slides have incremental content
    • Keep pressing → to reveal all items
    • Then advance to next slide
  3. Refresh if completely stuck:
    • Press F5 to reload
    • Navigate back to where you were
    • Continue session

Why this happens: Browser window focus determines which element receives keyboard input.

Can’t Navigate Past Certain Slide

Symptoms: Arrows stop working at specific slide.

Solutions:

  1. Check for incremental content:
    • Slide may have multiple bullet points revealing one by one
    • Keep pressing → until all content visible
    • Then → again advances to next slide
  2. Use overview mode:
    • Press ESC to see all slides
    • Click desired slide to jump to it
    • Press ESC again to return to presentation
  3. Skip problematic slide:
    • Navigate to slide before
    • Press page down (not arrow)
    • Or use overview mode to jump past

Why this happens: Incremental lists require multiple → presses before advancing slides.

Player-Safe Mode Not Hiding IM Slides

Symptoms: Pressing P doesn’t activate player-safe mode, or mode activates but IM slides still visible.

Note: This feature will be implemented in Phase 1 of Issue #78. If you’re reading this before implementation:

Temporary solution:

  • Manually navigate carefully
  • Skip IM-only slides (marked with colored borders)
  • Use overview mode (ESC) to see which slides to skip

After Phase 1 implementation:

  • Press P to toggle mode
  • Banner should appear confirming activation
  • Arrow keys automatically skip IM-only slides

Why this happens: Feature not yet implemented (as of Phase 0 documentation).

State Persistence Issues

Checkboxes Not Saving

Symptoms: Session state tracker checkboxes reset when browser refreshes.

Solutions:

  1. Enable localStorage in browser:
    • Chrome: Settings → Privacy and security → Cookies → Allow all
    • Firefox: Options → Privacy & Security → Custom → Cookies → Allow
    • Don’t use “Block all cookies”
  2. Don’t use private/incognito mode:
    • Private browsing doesn’t persist localStorage
    • Use normal browser window
  3. Check browser console:
    • F12 → Console
    • Look for localStorage errors
    • May indicate permissions issue
  4. Fallback to paper tracking:
    • Print scenario planning sheet
    • Check boxes manually with pen
    • Low-tech but reliable

Why this happens: Browsers block localStorage in private mode or strict privacy settings.

Scratchpad Notes Disappear

Symptoms: IM notes typed into scratchpad vanish when navigating slides or refreshing browser.

Solutions:

  1. Same as checkbox solutions above (localStorage required)

  2. Export notes before closing:

    • Select all text in scratchpad (Ctrl+A)
    • Copy (Ctrl+C)
    • Paste into external document (Notepad, Google Docs)
    • Save externally

  3. Take external notes as backup:

    • Use physical notebook
    • Use separate note-taking app
    • Don’t rely solely on scratchpad

Why this happens: Same localStorage issues as checkboxes.

State Persists When You Want Fresh Start

Symptoms: Previous session’s checkboxes and notes still present when starting new session.

Solutions:

  1. Use “Clear” button:
    • Navigate to Session State slide (IM-only)
    • Click “Clear” or “Reset” button
    • Confirms before clearing
  2. Clear localStorage manually:
    • F12 → Console
    • Type: localStorage.clear()
    • Press Enter
    • Refresh page (F5)
  3. Use different browser:
    • Each browser has separate localStorage
    • Chrome session ≠ Firefox session
    • Quick way to keep sessions separate
  4. Use incognito for disposable sessions:
    • State won’t persist anyway
    • Good for testing or demo runs

Why this happens: localStorage is designed to persist indefinitely until explicitly cleared.

Performance Issues

Slides Lag or Stutter

Symptoms: Animations choppy, slow response to arrow keys, browser feels sluggish.

Solutions:

  1. Close unnecessary tabs:
    • Browser resources shared across all tabs
    • Close email, social media, etc.
    • Keep only slides open
  2. Close other applications:
    • Check Task Manager (Ctrl+Shift+ESC on Windows)
    • Close memory-intensive apps
    • Especially video conferencing if not needed
  3. Reduce browser zoom:
    • Ctrl+0 to reset to 100%
    • Lower zoom = better performance
  4. Lower display resolution temporarily:
    • Windows: Display settings → Resolution → 1280x720
    • Mac: System Preferences → Displays → Scaled → Lower resolution
    • Only during session if needed
  5. Upgrade hardware:
    • RevealJS is graphics-intensive
    • Older laptops may struggle
    • Consider newer laptop for smoother experience

Why this happens: RevealJS uses CSS3 animations and transitions that require graphics processing.

Browser Freezes or Crashes

Symptoms: Browser becomes unresponsive, shows “Page Unresponsive” dialog.

Solutions:

  1. Immediate:
    • Click “Wait” if browser offers option
    • Give it 30 seconds to recover
  2. If doesn’t recover:
    • Force quit browser (Alt+F4 or Cmd+Q)
    • Reopen browser
    • Reopen slides
    • Navigate back to current position
  3. Prevention:
    • Update browser to latest version
    • Update graphics drivers
    • Close resource-heavy applications before session
  4. Fallback:
    • Have scenario cards printed as backup
    • Can continue session without slides if needed

Why this happens: Insufficient RAM or graphics processing power for RevealJS.

Recovery Procedures

Full Session Recovery After Crash

If browser crashes mid-session:

  1. Reopen browser immediately
  2. Reopen scenario slides HTML file
  3. Press S for speaker view
  4. Position windows correctly
  5. Press P for player-safe mode
  6. Use overview mode (ESC) to find your position:
    • Look for last slide you remember showing
    • Click to jump there
  7. Resume session with brief acknowledgment to players:
    • “Technical hiccup, we’re back where we were…”
    • Continue facilitation

Session state may be lost depending on localStorage persistence.

Recovering from Showing IM Slide to Players

If players accidentally see IM-only slide:

  1. Advance immediately (press → quickly)
  2. Acknowledge briefly:
    • “Oops, that was my facilitator notes”
    • “Please ignore that last screen”
  3. Don’t dwell on it - move forward confidently
  4. Most players won’t process spoilers that quickly anyway
  5. Enable player-safe mode (P) if not already enabled

Damage control:

  • Unlikely to meaningfully spoil session
  • Players focused on their investigations, not reading fast enough
  • Worst case: One clue revealed early - adjust facilitation accordingly

Emergency Backup Plan

If technology fails completely:

  1. Have scenario cards printed as backup
  2. Narrative facilitation without slides:
    • Read scenario hook from planning doc
    • Describe NPCs verbally
    • Track clues on whiteboard or paper
    • Players imagine malmon instead of seeing card
  3. Low-tech = still effective - story is what matters

Prevention:

  • Always have scenario planning doc available (digital or printed)
  • Test technology before players arrive
  • Have backup presentation on USB drive
  • Know scenario well enough to improvise if needed

When to Ask for Help

These issues might require technical support:

  • Persistent browser crashes after trying solutions above
  • Hardware incompatibility (projector won’t connect after all troubleshooting)
  • localStorage completely non-functional in all browsers
  • Slides render completely broken in all browsers

Where to get help:

Quick Reference: Most Common Issues

Issue Quick Fix
Slides won’t load Try different browser, clear cache
Wrong window on projector Drag windows to correct screens
Arrow keys don’t work Click presentation, try again
Lost speaker view Press S to reopen
Theme toggle not working Press T key or click theme button (top right)
Checkboxes don’t save Enable localStorage, don’t use incognito
Projector mirroring Win+P → Extend (Windows) or uncheck Mirror (Mac)
Browser crash Reopen browser, reopen slides, use ESC to find position
Accidentally showed IM slide Advance quickly, acknowledge, enable player-safe mode

Prevention Best Practices

Before every session:

  1. ✅ Test technology 15 minutes before players arrive
  2. ✅ Verify display connection working
  3. ✅ Run through first few slides to confirm navigation
  4. ✅ Have scenario planning doc accessible as backup
  5. ✅ Know where “most common issues” table is in this guide

During session:

  1. ✅ Enable player-safe mode before projecting
  2. ✅ Keep this troubleshooting guide open on phone or second device
  3. ✅ Stay calm if issues arise - players won’t notice brief hiccups
  4. ✅ Have water nearby to pause naturally while recovering

The best troubleshooting is prevention through testing and preparation.