Three.js Card Game Demo

Overview

This is an AI-assisted demonstration project exploring the intersection of artificial intelligence and 3D web development. Using Claude Code and Test-Driven Development (TDD), this project showcases how AI can help build interactive 3D spaces with Three.js. The goal is to create an immersive card game environment while documenting the AI-driven development process.

Current Status: Story 1 Implementation - Basic Scene Setup & Performance Monitoring

What Was Implemented

Core Features

• ✅ Three.js project with TypeScript configuration
• ✅ Basic 3D scene with camera, renderer, and lighting
• ✅ FPS counter/stats display for performance monitoring
• ✅ WebGL renderer with performance optimization flags
• ✅ Ambient and directional lighting
• ✅ Responsive canvas that fills the viewport
• ✅ 60 FPS baseline performance capability

Test-Driven Development

All functionality was implemented following strict TDD principles:

• Tests written first
• Implementation to make tests pass
• Comprehensive test coverage (36 tests, 100% passing)

Project Structure

/home/maxwell/ai.three.js.demo/
├── index.html              # Main HTML entry point with FPS display
├── package.json            # Project dependencies and scripts
├── tsconfig.json          # TypeScript configuration
├── vite.config.ts         # Vite build and test configuration
└── src/
    ├── main.ts            # Application entry point
    ├── Scene.ts           # Three.js scene management class
    ├── Scene.test.ts      # Scene unit tests (18 tests)
    ├── FPSCounter.ts      # FPS monitoring class
    ├── FPSCounter.test.ts # FPS counter unit tests (18 tests)
    └── test-setup.ts      # WebGL mocking for tests

Key Components

Scene Class (/home/maxwell/ai.three.js.demo/src/Scene.ts)

Manages the Three.js scene, camera, renderer, and lighting:

• Camera: PerspectiveCamera with 75° FOV, positioned at (0, 5, 10)
• Renderer: WebGLRenderer with antialiasing and high-performance settings
• Lighting:
  • Ambient light (0xffffff, intensity 0.6)
  • Directional light (0xffffff, intensity 0.8) at position (5, 10, 7.5)
• Responsive: Automatically handles window resize
• Performance: Optimized pixel ratio (max 2x)

FPSCounter Class (/home/maxwell/ai.three.js.demo/src/FPSCounter.ts)

Real-time performance monitoring:

• Tracks frames per second (FPS)
• Measures frame time in milliseconds
• Smooths readings using 60-frame rolling average
• Updates DOM display every second
• Provides immediate calculation for testing

Running the Project

Development Server

npm run dev

Opens at http://localhost:3000 with hot reload

Run Tests

npm test           # Watch mode
npm test -- --run  # Single run
npm run test:ui    # Visual test UI

Build for Production

npm run build

Output in /dist directory

Preview Production Build

npm run preview

Test Results

All 36 tests pass successfully:

FPSCounter Tests (18 tests)

• Initialization and element references
• FPS calculation and accuracy
• Frame time measurement
• DOM updates and formatting
• Performance under load
• Resource cleanup

Scene Tests (18 tests)

• Scene and camera initialization
• WebGL renderer configuration
• Lighting setup (ambient + directional)
• Camera positioning
• Responsive canvas resizing
• Render loop management
• Resource disposal

Performance Targets

✅ 60 FPS Baseline: Scene maintains 60 FPS with basic setup

• Optimized WebGL renderer settings
• Efficient pixel ratio management
• Proper resource cleanup

Technologies Used

• Three.js (v0.180.0) - 3D graphics library
• TypeScript (v5.9.3) - Type-safe JavaScript
• Vite (v7.1.12) - Build tool and dev server
• Vitest (v4.0.4) - Unit testing framework
• jsdom - DOM environment for testing

Acceptance Criteria Status

All acceptance criteria from Story 1 have been met:

• ✅ FPS meter visible on screen
• ✅ Scene renders at consistent 60 FPS capability
• ✅ TypeScript compilation works without errors
• ✅ All tests pass (36/36)
• ✅ Production build successful

Next Steps

Story 1 is complete. The foundation is ready for:

• Story 2: Table and Environment Setup
• Story 3: Camera System with Player POV Switching
• Additional stories as defined in the technical specification

Development Decisions

Testing Approach

• Used TDD methodology throughout
• Created comprehensive WebGL mocks for headless testing
• Separated test files from production build
• Achieved full test coverage of core functionality

Architecture Choices

• Separated Scene and FPSCounter into distinct, testable classes
• Used dependency injection pattern for DOM elements
• Implemented proper cleanup methods for resource management
• Followed TypeScript strict mode best practices

Performance Optimizations

• Limited pixel ratio to 2x for retina displays
• Used high-performance WebGL context
• Implemented efficient FPS calculation with rolling average
• Proper disposal of Three.js resources

File Paths Summary

All implementation files with absolute paths:

Source Files:

• /home/maxwell/ai.three.js.demo/src/main.ts
• /home/maxwell/ai.three.js.demo/src/Scene.ts
• /home/maxwell/ai.three.js.demo/src/FPSCounter.ts

Test Files:

• /home/maxwell/ai.three.js.demo/src/Scene.test.ts
• /home/maxwell/ai.three.js.demo/src/FPSCounter.test.ts
• /home/maxwell/ai.three.js.demo/src/test-setup.ts

Configuration Files:

• /home/maxwell/ai.three.js.demo/tsconfig.json
• /home/maxwell/ai.three.js.demo/vite.config.ts
• /home/maxwell/ai.three.js.demo/package.json

HTML:

• /home/maxwell/ai.three.js.demo/index.html