# quantum-physics-lab-game

**Repository Path**: code01/quantum-physics-lab-game

## Basic Information

- **Project Name**: quantum-physics-lab-game
- **Description**: **量子物理实验室** 是一款教育类游戏，通过互动游戏玩法教授量子力学的核心概念。玩家将穿越三个沉浸式关卡，每个关卡都会介绍一种基本的量子现象：概率分布、叠加态和纠缠态。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-11
- **Last Updated**: 2026-03-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Quantum Physics Laboratory Game

A dual-implementation educational quantum physics laboratory game. Players learn about, detect, and collect quantum energy to ultimately escape the laboratory. The game includes complete Python (Pygame) and JavaScript (Canvas) versions, suitable for classroom demonstrations, self-study, and science exhibitions.

## Game Levels and Mechanics

### Level 1: Quantum Probability Distribution and Energy Collection
- **Learning Objectives**: Understand quantum randomness and probability distribution (Gaussian distribution), and the concept of measurement-induced collapse.
- **Mechanics**:
  1. Study quantum randomness materials at the computer desk to unlock the **Quantum Detector**.
  2. Carry the detector while moving in the laboratory to reveal quantum dots (distributed according to Gaussian distribution σ=60).
  3. After unlocking the **Quantum Observer**, approach the high-density center to collect energy (closer to center = higher probability, faster energy collection).
  4. Once energy reaches 100%, the door automatically opens. Exit through the top passage.

### Level 2: Quantum Superposition and the Cost of Observation
- **Learning Objectives**: Understand quantum superposition states and how observation affects the system.
- **Mechanics**:
  1. Turn off the main room light to cause the deterministic door to enter a superposition state (both open and closed).
  2. In the darkness, use a **flashlight** as an observation tool to shine on the door, causing it to collapse to a deterministic state (50% probability open, 50% closed). If it collapses to closed, move the flashlight away to restore the superposition state and try again.
  3. **The Cost of Observation**: Enemies representing random interference appear in the darkness and move toward the player.
  4. Enemy Weakness: Enemies directly illuminated by the flashlight temporarily stop moving. Players can use a heatmap of enemy spawn locations to avoid high-probability danger zones or proactively freeze enemies.
  5. Pass through the door after it collapses to "open".

### Level 3: Quantum Entanglement
- **Learning Objectives**: Understand quantum entanglement (state correlation, "spooky action at a distance").
- **Mechanics**:
  1. Door A (entrance) is in superposition, Door B (exit) is in a closed state.
  2. Pick up the **Quantum Entanglement Revealer** to expose the entangled energy beam between the two doors.
  3. The two doors' states are linked and opposite: if Door A collapses to open, Door B must be closed; if Door A collapses to closed, Door B must be open.
  4. **Goal**: Use the flashlight to continuously shine on Door A, causing it to collapse to "closed" state. Due to entanglement, Door B will inevitably switch to "open" state.
  5. Escape through Door B and successfully exit the laboratory!

---

## Game Versions and Running Instructions

This project uses dual-version development, maintaining completely consistent game content and physics logic:
- **Python Version**: Built with Pygame, runs as a native desktop application.
- **Web Version**: Built with pure JavaScript + HTML5 Canvas, no build tools required, runs directly in browser, supports mobile controls (virtual joystick).

### 1. Running the Web Version (JavaScript / Canvas)
The Web version includes all three levels and supports responsive design (keyboard controls on PC, joystick on Pad/mobile).

Start the local server using Bun:
```sh
bun run server.ts
```
Then open your browser to: `http://localhost:3000`

> Default starts at Level 1. You can switch levels with additional parameters:
> - Level 1: `http://localhost:3000/?level=1`
> - Level 2: `http://localhost:3000/?level=2`
> - Level 3: `http://localhost:3000/?level=3`

### 2. Running the Python Version (Pygame)
The Python version includes a main menu interface and level transitions, providing a native application experience.

Run the main program using the `uv` environment manager:
```sh
uv run main.py
```
*In the main menu, you can select any unlocked level or switch between Chinese and English interfaces.*

You can also run individual levels (for debugging):
```sh
uv run src_python/level1_quantum_game.py
uv run src_python/level2_quantum_game.py
uv run src_python/level3_quantum_game.py
```

### 3. Docker Deployment (Recommended for Server Environments)
You can use Docker to quickly build and launch the Web version server.

**Standard Startup**:
```sh
docker compose up --build -d
```
Once the container is running, access `http://localhost:3000` in your browser.

**Version-tracked Startup (Recommended)**:
```sh
bun run docker:up
```
This command automatically fetches the latest Git Commit Hash as the Docker image tag and starts it, facilitating version management.

---

## Project Directory Structure

Game logic is clearly separated into independent modules, making it easy to teach and extend.

```text
.
├── src_python/                   # Python Native Implementation (Pygame)
│   ├── main_menu.py              # Main menu and level selection
│   ├── game_manager.py           # Game progress and save data
│   ├── language_manager.py       # i18n multi-language system
│   ├── level1_quantum_game.py    # Level 1 game logic
│   ├── level2_quantum_game.py    # Level 2 game logic
│   ├── level3_quantum_game.py    # Level 3 game logic
│   └── level_transition.py       # Level transition/summary screen
├── src_web/                      # Web Implementation (JS + Canvas)
│   # Web entry point ├── index.html               , switches levels via URL parameters
│   ├── game_manager.js           # Web state management
│   ├── language_manager.js       # Web multi-language support
│   ├── level1_quantum_game.js    # Level 1 logic (corresponds to Python version)
│   ├── level2_quantum_game.js    # Level 2 logic
│   ├── level3_quantum_game.js    # Level 3 logic
│   └── level_transition.js       # Web level transition screen
├── assets/                       # Core resource files (audio, video, sprites)
├── main.py                       # Python client entry point
├── server.ts                     # Web version local server (Bun-based)
├── pyproject.toml / uv.lock      # Python dependency management
├── package.json / bun.lock       # Node/Bun dependency management
└── Dockerfile / compose.yaml     # Containerization configuration
```

## Current Development Status

| Feature Module | Python/Pygame | JavaScript/Canvas (Web) |
|---------------|---------------|------------------------|
| **Level 1: Probability Distribution** | ✅ Complete | ✅ Complete |
| **Level 2: Superposition** | ✅ Complete | ✅ Complete |
| **Level 3: Quantum Entanglement** | ✅ Complete | ✅ Complete |
| **Multi-language Support (Chinese/English)** | ✅ Complete | ⏳ Partial Support (In Progress) |
| **Cross-platform Adaptation (Joystick/Touch)** | - (PC Native) | ✅ Complete |

## Future Update Plans (TODO)

### Web Version Development

#### User Feedback
- [ ] Character walks off the screen edge and cannot get back
- [x] Link navigation doesn't work, requires manual input
- [x] Cannot pick up items under the desk, must go to top of desk
- [x] First level video should be changed to PPT - video requires replaying if accidentally moved
- [ ] Should support tablet gameplay
- [ ] Level 2 enemy movement speed is too fast, need to add speed limit
- [ ] Game guidance is insufficient - need to add Level 1 gameplay explanation similar to Level 2
- [ ] Add on-screen control instructions for Level 1 (like Level 2)
- [ ] Level 2 gameplay hint text switches too fast - change to left/right arrow key paging, auto-exit after last page
- [ ] Complete English version of learning materials