number-8

assets.md

Number 8 - Asset Requirements for Vite Project

Directory Structure

number-8/
├── public/             # Static assets that bypass Vite processing
│   ├── favicon.ico     # Site favicon
│   └── manifest.json   # PWA manifest
├── src/
│   ├── assets/         # Assets processed by Vite
│   │   ├── audio/      # Sound effects and music
│   │   ├── images/     # Game images
│   │   │   ├── cards/  # Card images
│   │   │   ├── ui/     # UI elements
│   │   │   └── backgrounds/ # Background images
│   │   └── fonts/      # Custom fonts
│   ├── components/     # React components
│   ├── hooks/          # Custom React hooks
│   ├── models/         # TypeScript interfaces and types
│   ├── store/          # Game state management
│   ├── utils/          # Helper functions
│   ├── App.tsx         # Main App component
│   └── main.tsx        # Entry point
├── tests/              # Test files
├── dist/               # Build output (generated)
└── [config files]      # Various configuration files

Asset Requirements Table

Asset	Format	Dimensions	Quantity	Specs	Description	Simpsons Reference
Card Faces	PNG/SVG	300x420px	48 unique designs	150 DPI, <100KB each	Character cards numbered 1-12 in 4 colors	Each number features a specific character (see mapping below)
Card Back	PNG/SVG	300x420px	1	150 DPI, <100KB	Branded card back	"Number 8" with musical notes
Wild Card	PNG/SVG	300x420px	1	150 DPI, <100KB	Special card	"A single plum, floating in perfume, served in a man's hat"
Skip Card	PNG/SVG	300x420px	1	150 DPI, <100KB	Special card	Ralph Wiggum with "I Choo-Choo-Choose to Skip You!"
Game Logo	SVG	600x200px	1	Vector, <50KB	Game title logo	"Number 8" in yellow Simpsons font with musical notes
Backgrounds	PNG/JPG	1920x1080px	4	<250KB each	Game screens	Springfield, Moe's Tavern, Krusty Burger, Power Plant
UI Buttons	SVG	200x80px	8 sets	Vector, <20KB each	Normal/hover/active states	Donut-shaped buttons, Duff beer tab, etc.
Phase Icons	SVG	100x100px	8	Vector, <15KB each	Icons for each phase	Mini illustrations of each phase theme
Character Avatars	PNG	128x128px	12	<30KB each	Player selection	Character headshots with transparent backgrounds
Audio: Phase Complete	MP3/OGG	N/A	8	<5s, <100KB each	Sound for completing each phase	Iconic quotes related to each phase
Audio: Card Actions	MP3/OGG	N/A	4	<1s, <50KB each	Draw, play, shuffle, discard	Homer's "Woo-hoo!", "D'oh!", etc.
Audio: UI Sounds	MP3/OGG	N/A	5	<1s, <50KB each	Button clicks, notifications	Various short Simpsons sounds
Audio: Background Music	MP3/OGG	N/A	2	60-90s loops, <1MB each	Menu and gameplay themes	Simpsons-inspired instrumental tracks
Custom Font	WOFF2/TTF	N/A	1 family	<100KB	Game text font	Similar to Simpsons font without copyright issues

Character-Number Mapping (Make 4 color variations of each)

Card Number	Character	Why It's Funny
1	Homer	"I'm Number One at the bowling alley!"
2	Marge	"Two minutes before Homer does something stupid again"
3	Bart	"Three-finger salute from the Butterfinger mascot"
4	Lisa	"Four-time winner of the school science fair"
5	Maggie	"Five cents was the price of her infamous pacifier"
6	Grampa Simpson	"Back in nineteen-dickety-six..."
7	Mr. Burns	"Seven is his lucky nuclear reactor number"
8	Barney Gumble	"Number 8! burp Number 8! burp" from Be Sharps audition
9	Moe Szyslak	"Nine years since his last date"
10	Krusty the Clown	"Channel 10 - where his show airs"
11	Ned Flanders	"Eleven Commandments he follows (added one about left-handed scissors)"
12	Chief Wiggum	"12 donuts in a dozen - his daily breakfast"

Phase Sound Effects

Phase	Sound Clip	Max Length	File Size	Notes
1: Steamed Hams	"Steamed hams!"	2s	<75KB	Skinner saying it unconvincingly
2: Monorail Madness	"Monorail!"	3s	<90KB	Town chanting "Monorail!"
3: Canyonero 8	"Canyonero!"	2s	<80KB	Country-western jingle sound
4: You Don't Win Friends with Salad	"You don't win friends with salad!"	3s	<100KB	The conga line chant
5: Bart's Chalkboard	Chalk writing sound + "Ay caramba!"	2s	<75KB	Squeaky chalk plus catchphrase
6: Homer's Half-Assed Game Design	"D'oh!"	1s	<50KB	Classic Homer D'oh
7: Dental Plan! Lisa Needs Braces!	"Dental plan! Lisa needs braces!"	3s	<100KB	The hypnotic back-and-forth
8: Number 8!	"Number 8 burp Number 8 burp"	4s	<120KB	Barney's Be Sharps audition

Color Scheme

Color Name	Hex Code	Used For	Simpsons Reference
Simpson Yellow	#FED90F	Primary brand color	The iconic skin tone
Power Plant Green	#7BC142	Green cards	Nuclear waste glow
Duff Red	#ED1C24	Red cards	Duff beer cans
Marge Blue	#3A57A6	Blue cards	Marge's hair
Donut Pink	#F7A3CA	Highlights	Homer's favorite treat
Springfield Gray	#8B8989	UI backgrounds	Springfield's dreary sky
Kwik-E-Mart Teal	#00AEEF	Accents	Convenience store colors
Burns Manor Purple	#662D91	Special effects	Mr. Burns' sinister vibe

Special Asset Requirements

1. The "Number 8" Animation

   • Format: Sprite sheet (PNG) or JSON animation
   • Frames: 24 frames (12fps)
   • Size: 400x300px
   • Description: Barney singing "Number 8 burp" with musical notes
   • Used for: Phase completion celebration

2. "Single Plum" Wild Card Animation

   • Format: GIF or sprite sheet
   • Frames: 18 frames (6fps)
   • Size: 250x250px
   • Description: A plum floating in perfume in a man's hat with sparkle effects
   • Used for: Wild card play animation

3. "Woohoo!" Celebration

   • Format: Sprite sheet (PNG)
   • Frames: 12 frames (12fps)
   • Size: 300x300px
   • Description: Homer jumping with excitement
   • Used for: Game win animation

Asset Naming Convention

All assets should follow the convention: [category]-[subcategory]-[descriptor]-[variant].[extension]

Examples:

• card-red-homer-01.png
• audio-phase-number8.mp3
• ui-button-play-normal.svg
• background-moes-tavern.jpg

Special Notes

1. "Steamed Hams" Cards: The "Steamed Hams" phase cards should include subtle hamburger icons despite clearly being grilled.

2. "Single Plum" Wild Card: Should depict a single plum floating in perfume, served in a man's hat, exactly as Moe produces it in the episode.

3. Error Sound: When invalid moves are attempted, use the "Saxophone fail" sound from Lisa's saxophone practice.

4. Loading Screen: Should feature the iconic clouds and title sequence from the show's intro.

5. Card Discard Pile: Should resemble the Springfield Tire Fire, with cards looking slightly burned when discarded.

6. Animation for Skip Card: Should include Ralph's "I'm in danger" nervous smile when played.

7. Barney Card #8: Must feature Barney from his Be Sharps audition, clean-cut with his "Number 8 burp" musical performance.

Remember: The assets should be inspired by The Simpsons but distinct enough to avoid copyright issues. They should capture the humor and spirit of the show while being original artwork.

number8.md

Number 8 - Design Document

Project Overview

Project Name: Number 8
Tech Stack: Bun + React + TypeScript (strict) + Vite + Vitest
Description: A Simpsons-themed digital card game inspired by Phase 10, featuring 8 phases instead of 10. The game will include Simpsons-themed cards, phases, and references. Deployment: GitHub Pages with custom domain (number8.deanlofts.xyz)

Project Goals

1. Create a fun, playable card game with familiar phase-based gameplay
2. Use Simpsons references for theming and humor
3. Keep the game free of ads, microtransactions, and predatory monetization
4. Make it easily accessible online through GitHub Pages

Core Game Concept

Number 8 is a card game where players work through 8 sequential phases, each requiring specific card combinations. The first player to complete all phases wins. The game mechanics follow Phase 10's core gameplay, but with Simpsons-themed elements and references, including the iconic "Number 8" burp sequence from the Simpsons.

Game Elements

Cards

• Numbered Cards: 96 cards (1-12 in four colors, two of each)
• Wild Cards: 8 cards that can represent any number/color
• Skip Cards: 4 cards that allow players to skip another player's turn
• Theming: Each card will feature Simpsons characters and references

Phases

1. Steamed Hams - 2 sets of 3 cards
2. Monorail Madness - 1 run of 4 + 1 set of 3
3. Canyonero 8 - Run of 8 cards
4. You Don't Win Friends with Salad - 7 cards of one color
5. Bart's Chalkboard - 3 sets of 2
6. Homer's Half-Assed Game Design - 1 set of 4 + 1 run of 4
7. Dental Plan! Lisa Needs Braces! - 2 sets of 4
8. Number 8! Number 8! - 1 set of 5 + 1 run of 3

Game Modes

• Single Player: Play against 1-5 AI opponents
• Local Multiplayer: Pass-and-play with friends (2-6 players)

Visual Design

Aesthetic

• Color Palette: Based on Simpsons colors (yellow, blue, red, green)
• Style: Cartoonish, vibrant, and clean
• UI Elements: Simpsons-themed buttons, backgrounds, and fonts

Screen Layouts

Main Menu

• Game logo (Number 8 with Simpsons styling)
• Play buttons (Single Player, Local Multiplayer)
• Options button (sound, difficulty, etc.)
• Credits/About button

Game Setup

• Player name input
• Number of players/AI selection
• AI difficulty setting
• Start game button

Game Board

• Player hand area (bottom)
• Discard pile and draw deck (center)
• Phase display (top)
• Other players' status (sides/top)
• Current phase requirements display

Phase Completion Screen

• Celebratory animation
• "Number 8" sound clip
• Next phase preview

UI Flow

1. Main Menu → Game Setup → Game Board
2. In Game Board:
   • Draw card
   • Play cards to complete phase or add to others' phases
   • Discard card
   • End turn
3. Game continues until a player completes all 8 phases
4. Game Over Screen → Main Menu or Play Again

Game Mechanics

Turn Structure

1. Draw one card (from deck or discard pile)
2. Option to play phase if not already completed
3. Option to add to others' completed phases
4. Discard one card
5. Next player's turn

Phase Rules

• Players must complete phases in order
• Once a phase is completed, players can add to their own or others' phase cards
• Skip cards prevent a player from taking their turn
• Wild cards can be used as any card needed to complete a phase

Scoring

• First to complete all phases wins
• Optional: scoring based on cards left in hand when someone wins

AI System Design

AI Difficulty Levels

• Easy (Ralph Wiggum): Makes basic moves, often discards useful cards
• Medium (Homer Simpson): Competent but makes occasional mistakes
• Hard (Lisa Simpson): Strategic, prioritizes phase completion efficiently

AI Behavior

• Card evaluation (which cards to keep vs. discard)
• Phase completion strategy
• Defensive play (using skip cards strategically)
• Each AI has a Simpsons character personality affecting play style

Sound Design

Sound Effects

• Card shuffling and dealing
• Card playing/drawing
• Phase completion ("Number 8!" sound)
• Skip card effect
• Game win celebration

Music

• Simpsons-inspired background music
• Menu music vs. gameplay music

Technical Architecture

State Management

• Global game state
• Player hands and phase progress
• Turn management
• Card deck and discard pile

Data Models

• Card model (type, value, color, etc.)
• Player model (hand, current phase, etc.)
• Phase model (requirements, validation logic)
• Game state model (tracking overall game progress)

Component Structure

• Game board component
• Card component
• Player hand component
• Phase display component
• Turn indicator component

Development Approach

Phase 1: Core Game Logic

• Card mechanics (deck, hands, drawing, discarding)
• Phase validation rules
• Turn management
• Win condition checking

Phase 2: User Interface

• Game board layout
• Card rendering and interaction
• Phase display and validation
• Player controls

Phase 3: AI Implementation

• AI player logic
• Difficulty levels
• Character personalities

Phase 4: Theming & Polish

• Simpsons visual themes and assets
• Sound effects and music
• Animations and transitions
• UI refinement

Phase 5: Testing & Deployment

• Game balance testing
• Bug fixing
• Performance optimization
• Deployment to GitHub Pages

Testing Strategy

• Unit Tests: Game logic functions, state management
• Integration Tests: Game flow, phase completion
• Playability Testing: Real player feedback

Post-Launch Plans

• Potential custom phase editor
• Additional Simpsons-themed events and cards
• Optional online multiplayer (if demand exists)
• Mobile-optimized version

Success Criteria

1. Game is fully playable with all 8 phases
2. AI opponents provide meaningful challenge
3. Simpsons theme is well-integrated and humorous
4. Game is free of bugs that impact playability
5. Successfully deployed to GitHub Pages at number8.deanlofts.xyz

This design document provides a comprehensive blueprint for building Number 8 without diving into implementation details, focusing instead on the game's concept, mechanics, and overall design approach.

requirements.md

Number 8 - Requirements Document

1. Introduction

1.1 Purpose

This document outlines the functional and non-functional requirements for "Number 8," a digital card game inspired by Phase 10 with Simpsons theming. It serves as the definitive reference for development and quality assurance.

1.2 Project Scope

Number 8 is a web-based card game that features 8 sequential phases with Simpsons-themed elements. It will be developed using Bun, React, TypeScript, Vite, and Vitest, and deployed on GitHub Pages at number8.deanlofts.xyz.

1.3 Target Users

• Fans of card games seeking a non-predatory alternative to commercial options
• Simpsons enthusiasts who appreciate references to the show
• Casual gamers looking for a turn-based card game experience
• Players of all ages (no age-restricted content)

2. Functional Requirements

2.1 Core Game Mechanics

2.1.1 Card System

• REQ-C1: The game shall include 108 total cards:
  • 96 numbered cards (1-12 in four colors, two of each)
  • 8 wild cards (can substitute for any card)
  • 4 skip cards (make a player lose their turn)
• REQ-C2: Each card shall display a distinct Simpsons-related visual theme
• REQ-C3: Cards must be drawn from a deck or discard pile
• REQ-C4: Players must discard one card at the end of each turn

2.1.2 Phase System

• REQ-P1: The game shall include 8 sequential phases, each with unique Simpsons-themed names
• REQ-P2: Each phase shall require specific card combinations:
  • Phase 1 ("Steamed Hams"): 2 sets of 3 cards
  • Phase 2 ("Monorail Madness"): 1 run of 4 + 1 set of 3
  • Phase 3 ("Canyonero 8"): Run of 8 cards
  • Phase 4 ("You Don't Win Friends with Salad"): 7 cards of one color
  • Phase 5 ("Bart's Chalkboard"): 3 sets of 2
  • Phase 6 ("Homer's Half-Assed Game Design"): 1 set of 4 + 1 run of 4
  • Phase 7 ("Dental Plan! Lisa Needs Braces!"): 2 sets of 4
  • Phase 8 ("Number 8! Number 8!"): 1 set of 5 + 1 run of 3
• REQ-P3: Players must complete phases in sequential order
• REQ-P4: A player must play all required cards for a phase in a single turn to complete it
• REQ-P5: After completing their current phase, a player can add cards to their own or others' phase cards

2.1.3 Game Flow

• REQ-F1: Each player turn shall consist of:
  1. Drawing one card
  2. Playing cards (optional)
  3. Discarding one card
• REQ-F2: The first player to complete all 8 phases wins the game
• REQ-F3: A new round begins immediately after a player wins
• REQ-F4: Skip cards cause the targeted player to miss their next turn
• REQ-F5: Game state must persist if browser is refreshed or closed accidentally

2.2 Game Modes

2.2.1 Single Player

• REQ-S1: The game shall support playing against 1-5 AI opponents
• REQ-S2: AI opponents must support at least three difficulty levels
• REQ-S3: Each AI shall have a distinct Simpsons character personality

2.2.2 Local Multiplayer

• REQ-M1: The game shall support 2-6 human players in pass-and-play mode
• REQ-M2: Transitions between players must include a "hand-off" screen to prevent seeing others' cards
• REQ-M3: The game shall allow a mix of human and AI players

2.3 User Interface

2.3.1 Game Layout

• REQ-U1: The interface shall display:
  • Current player's hand
  • Discard pile
  • Draw pile
  • All players' current phase status
  • Current phase requirements
  • Turn indicator
• REQ-U2: The UI must be responsive and work on both desktop and mobile browsers
• REQ-U3: Cards must be clearly distinguished by color and number

2.3.2 User Actions

• REQ-A1: Players must be able to:
  • Draw cards (from deck or discard pile)
  • Select multiple cards to play for a phase
  • View phase requirements
  • Discard a card
  • Add to existing phase cards
  • Use skip cards

2.3.3 Feedback Systems

• REQ-FB1: The game shall provide feedback for:
  • Valid/invalid card combinations
  • Phase completion
  • Game status (who's winning, current player, etc.)
  • Error states (illegal moves)
  • Win conditions

2.4 Simpsons Theming

• REQ-T1: All phases shall be named after Simpsons references
• REQ-T2: Cards shall feature Simpsons characters or references
• REQ-T3: Sound effects shall include Simpsons quotes when appropriate
• REQ-T4: The "Number 8" burp sequence shall play when completing a phase

3. Non-Functional Requirements

3.1 Performance

• REQ-NF1: The game shall load fully within 3 seconds on standard broadband connections
• REQ-NF2: Card animations must run at 60fps
• REQ-NF3: The application must function without performance degradation for sessions lasting up to 2 hours

3.2 Usability

• REQ-NF4: The game shall be playable without prior instructions for users familiar with card games
• REQ-NF5: Touch targets must be at least 44x44 pixels for mobile users
• REQ-NF6: First-time users shall be offered an optional tutorial
• REQ-NF7: Text must have a minimum contrast ratio of 4.5:1 for accessibility

3.3 Reliability

• REQ-NF8: The game shall auto-save progress after each player's turn
• REQ-NF9: The system shall recover from browser crashes or refresh with minimal loss of progress
• REQ-NF10: Game rules must be enforced 100% of the time to prevent cheating or errors

3.4 Security and Privacy

• REQ-NF11: The game shall not collect personal information beyond local storage needs
• REQ-NF12: No external API calls shall be made that could compromise user privacy
• REQ-NF13: The application must not include tracking or analytics that identify individual users

3.5 Technical Requirements

• REQ-NF14: The game shall be built with Bun, React, TypeScript (strict mode), Vite, and Vitest
• REQ-NF15: All components must be thoroughly tested using Vitest
• REQ-NF16: The codebase must follow established coding standards and maintain >80% test coverage
• REQ-NF17: The application must work in the latest versions of Chrome, Firefox, Safari, and Edge
• REQ-NF18: The application must deploy successfully to GitHub Pages

3.6 Ethical Requirements

• REQ-NF19: The game shall be completely free of ads, in-app purchases, or monetization schemes
• REQ-NF20: The game must not employ dark patterns or psychological manipulation tactics
• REQ-NF21: The game shall respect fair use of Simpsons references without infringing on copyright

4. Constraints and Assumptions

4.1 Constraints

• The game must deploy and function entirely from GitHub Pages
• Development time should be optimized for core gameplay over excessive visual polish
• Project will not include online multiplayer in its initial release

4.2 Assumptions

• Users will have at least 1024x768 screen resolution
• Users will have JavaScript enabled
• Browser local storage will be available for game state persistence

5. Acceptance Criteria

5.1 Game Functionality

• All 8 phases function correctly with proper validation
• AI opponents play intelligently according to their difficulty level
• Cards can be drawn, played, and discarded according to rules
• Game properly detects and declares a winner

5.2 User Experience

• Tutorial effectively explains gameplay to new users
• UI is intuitive with clear feedback for all player actions
• Simpsons theme enhances rather than detracts from gameplay
• Game is enjoyable and challenging at all AI difficulty levels

5.3 Technical Performance

• Game loads and performs well across specified browsers
• No game-breaking bugs or crashes present
• Mobile interface is usable on both phones and tablets
• Application successfully deploys to number8.deanlofts.xyz

6. Future Considerations

The following features are not required for initial release but may be considered for future development:

• Online multiplayer functionality
• Custom phase creator
• Additional Simpsons-themed game modes
• Achievements and statistics tracking
• Additional card packs with more Simpsons references