BeatPlay

A lightweight, customizable rhythm game built with TypeScript and HTML5 Canvas.

Overview

BeatPlay is a 4-lane rhythm game where you hit notes in sync with music. It features precise timing detection, customizable charts, and an easy-to-extend architecture.

Features (MVP v0.1)

• ✅ 4-lane gameplay with tap notes
• ✅ High-precision timing engine (<10ms accuracy)
• ✅ Judgment system (Perfect/Great/Good/Miss)
• ✅ Combo and scoring system
• ✅ Web-based (runs in browser)
• ✅ TypeScript for type safety
• ✅ Modular, extensible architecture

Tech Stack

• Language: TypeScript
• Platform: Web (HTML5 Canvas)
• Audio: Web Audio API
• Build Tool: Vite
• Rendering: Canvas 2D API

Project Structure

BeatPlay/
├── src/
│   ├── engine/          # Core game systems
│   ├── gameplay/        # Gameplay logic
│   ├── rendering/       # Visual rendering
│   └── main.ts          # Entry point
├── assets/              # Songs, charts, images
├── docs/                # Documentation
└── package.json

Getting Started

Prerequisites

• Node.js (v18 or higher)
• npm or yarn

Installation

1. Clone or download this repository

2. Install dependencies:

npm install

3. Start development server:

npm run dev

4. Open your browser to http://localhost:3000

Build for Production

npm run build

The built files will be in the dist/ folder.

How to Play

• Use D, F, J, K keys for the 4 lanes (left to right)
• Hit notes as they reach the judgment line
• Aim for Perfect timing to maximize your score
• Build combos to increase your score multiplier

Controls

Key	Lane
D	Lane 1
F	Lane 2
J	Lane 3
K	Lane 4

Adding Custom Songs

1. Place your audio file in assets/songs/your-song/
2. Create a chart.json file with note data (see Chart Format below)
3. Load the song in your game code

Chart Format

{
  "metadata": {
    "title": "Song Name",
    "artist": "Artist Name",
    "bpm": 140,
    "offset": 0
  },
  "notes": [
    {
      "time": 1000,
      "lane": 0,
      "type": "tap"
    }
  ]
}

• time: Milliseconds from song start
• lane: 0-3 (left to right)
• type: "tap" (more types coming later)

Timing Windows

Judgment	Window	Points
Perfect	±30ms	100
Great	±60ms	75
Good	±100ms	50
Miss	>100ms	0

Development

Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm run preview - Preview production build
• npm run type-check - Check TypeScript types

Documentation

See the /docs folder for detailed documentation:

• PRD.md - Product requirements and features
• ARCHITECTURE.md - System architecture and tech decisions
• DESIGN.md - Game design and mechanics
• TODOS.md - Development roadmap
• LOGS.md - Development journal

Roadmap

Current Version: v0.1 (MVP)

• Basic project structure
• Core engine systems
• Complete gameplay implementation
• Demo songs and charts

Future Versions

• Long notes (holds)
• Visual effects and polish
• Song selection UI
• Results screen
• Chart editor
• Customizable themes
• More lanes (6, 7, etc.)
• Practice mode

Contributing

This is a personal project, but suggestions and feedback are welcome!

License

MIT License - feel free to use and modify for your own projects.

Credits

Built with TypeScript, Vite, and Web Audio API.

---

Note: This is an early MVP. Many features are still in development. Check docs/TODOS.md for the current development status.