From 3bb2968dcbeb7ca3c21b44ffad77fefbf5a9dba2 Mon Sep 17 00:00:00 2001
From: Wiwi Kuan <wiwi@noreply.localhost>
Date: Wed, 6 May 2026 02:20:31 +0000
Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=20README.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 128 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 126 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index ec9a4cd..bc844eb 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,127 @@
-# Hoops
+# 🏀 Hoops
 
-投籃遊戲！
\ No newline at end of file
+一個可以直接嵌入 Docusaurus 部落格文章的瀏覽器投籃小遊戲。純 Canvas 繪製，不依賴任何遊戲引擎，音效也是用 Web Audio API 即時合成的。
+
+---
+
+## 玩法
+
+**按住（空白鍵 / 滑鼠 / 觸控）→ 放開**，就投出去了。
+
+時機點很重要。太早放、太晚放都會偏掉。
+
+### 模式
+
+| 模式 | 說明 |
+|------|------|
+| **限時模式** | 60 秒內盡量投，結束後顯示得分 |
+| **練習模式** | 不限時，隨便投 |
+
+標題畫面可以用鍵盤 `1` / `2` 選模式，或直接點按鈕。
+
+### 鍵盤快捷鍵
+
+| 按鍵 | 動作 |
+|------|------|
+| `Space` 按住 / 放開 | 蓄力 / 投籃 |
+| `1` / `2` | 在標題畫面選模式 |
+| `Esc` | 練習模式中回主畫面 |
+
+---
+
+## 遊戲機制
+
+### 蓄力與投籃時機
+
+按住後球會隨著一個 sine 曲線跳起來，跳到頂點附近有一個非常短暫的「完美時機窗口」（`PERFECT_WINDOW_T`，預設約 28% 的跳躍週期）。在這個窗口內放開，球幾乎會完美飛進。
+
+偏離完美時機越多，球就會往偏斜方向飄去——偏早往一個方向飄，偏晚往另一個方向。偏移量由 `SHOT_DRIFT_VEL` 和 `SHOT_DRIFT_ANGLE` 控制。
+
+即使在完美時機內放開，也有一點點微小的隨機浮動（`PERFECT_JITTER_VEL` / `PERFECT_JITTER_ANGLE`），所以每一球都不會完全一樣。
+
+### 物理碰撞
+
+- **籃框（rim）**：兩端各有一個圓形碰撞體，球打到會彈開（`RESTITUTION_RIM`）
+- **籃板（backboard）**：從籃框後緣延伸出去，可以打板得分
+- **連接臂**：rim 後緣到籃板之間的細臂，也有碰撞偵測
+- **球與球**：多顆球同時在空中會互相彈開（`RESTITUTION_BALL`）
+
+---
+
+## 在 Docusaurus 裡使用
+
+### 1. 把檔案放進去
+
+將 `Hoops3.jsx` 複製到你的 Docusaurus 專案中，例如：
+
+```
+src/components/Hoops3.jsx
+```
+
+### 2. 在 MDX 文章裡引入
+
+Docusaurus 的部落格文章支援 MDX，可以直接 import React component：
+
+```mdx
+---
+title: 投籃遊戲
+---
+
+import Hoops from '@site/src/components/Hoops3';
+
+<Hoops />
+```
+
+### 3. 自訂參數（選用）
+
+可以透過 `config` prop 調整遊戲設定：
+
+```mdx
+<Hoops config={{
+  GAME_DURATION: 30,
+  PERFECT_TOLERANCE: 0.01,
+}} />
+```
+
+所有可用的參數及預設值：
+
+| 參數 | 預設值 | 說明 |
+|------|--------|------|
+| `GAME_DURATION` | `60` | 限時模式秒數 |
+| `COOLDOWN` | `0.5` | 兩球之間的間隔（秒） |
+| `JUMP_DURATION` | `0.5` | 跳躍動畫總時長（秒） |
+| `JUMP_HEIGHT_RATIO` | `0.25` | 跳躍高度（相對畫面寬度） |
+| `PERFECT_WINDOW_T` | `0.28` | 完美時機的位置（0~1，跳躍週期的幾成） |
+| `PERFECT_TOLERANCE` | `0.001` | 完美時機的容許誤差（越大越好投） |
+| `MAX_DRIFT_T` | `0.35` | 最大飄移對應的時機偏差 |
+| `GRAVITY_RATIO` | `5` | 重力強度（相對畫面寬度） |
+| `BALL_RADIUS_RATIO` | `0.03` | 球的大小（相對畫面寬度） |
+| `RESTITUTION_RIM` | `0.75` | 籃框彈性係數 |
+| `RESTITUTION_BOARD` | `0.75` | 籃板彈性係數 |
+| `RESTITUTION_BALL` | `0.7` | 球與球碰撞彈性係數 |
+| `SHOT_TARGET_TIME` | `0.75` | 球飛到籃框的目標時間（秒） |
+| `SHOT_DRIFT_VEL` | `0.4` | 時機偏差造成的速度飄移量 |
+| `SHOT_DRIFT_ANGLE` | `0.6` | 時機偏差造成的角度飄移量 |
+| `BALL_IMG_SRC` | `null` | 自訂球的圖片 URL（不設就用預設橘球） |
+
+---
+
+## 作弊
+
+程式在 `window.__hoops` 上掛了一個物件，讓你可以直接從 DevTools Console 竄改遊戲狀態。
+
+**把 Perfect 容許範圍設到 999（基本上每球都完美）：**
+
+```javascript
+window.__hoops.CONFIG.PERFECT_TOLERANCE = 999
+```
+
+設完之後，不管什麼時候放開，都算完美時機。
+
+---
+
+## 注意事項
+
+- 鍵盤監聽加了 IntersectionObserver：捲出畫面後空白鍵不會被遊戲吃掉，翻頁還是翻頁
+- 觸控裝置用 `setPointerCapture` 處理，不會干擾頁面上的其他連結點擊
+- Canvas 的 Console 會輸出每一球的時機資訊，方便 debug
\ No newline at end of file