Rolling Around

一個可愛的 3D 滾球收集遊戲，使用 Three.js + TypeScript + Vite 打造。從一顆 1 公尺的糖果球出發，穿過商店收集物品、吞下羊群與房屋，長大後把城市和山岳一起捲走！

遊戲玩法

• 吃得下比你小的東西：物件體積小於球的 60% 就會黏上球，球隨之長大
• 撞到太大的東西會彈開，高速撞上去還會把剛黏上的東西撞掉
• 連擊：1.4 秒內連續吞食會累積連擊，音效一路往上爬音階，成長加成最高 +30%
• 收集圖鑑：家具、商品、植物、動物、車輛、建築與地景，第一次吃到會標記「新發現」
• 沒有上限：球可以一直長大，從街邊的小球一路滾到捲走整片城市與山岳
• 稱號：小彈珠 → 雪球 → 滾石 → 推土球 → 城鎮吞噬者 → 摩天巨球 → 怪獸級 → 天災級 → 小行星 → 移山巨球 → 大陸吞噬者 → 月球級 → 行星級 → 恆星級 → 星系級 → 宇宙之球
• 長按衝刺：按住 Shift 加速 1.6 倍，消耗體力條（約 3 秒用完），用光要喘一下才能再衝
• 道具：磁吸（把附近小東西吸過來）、衝刺（速度 ×1.7）、巨大化（體積 +25%）
• 小動物會逃跑：當你大到能吃掉牠們時，綿羊、鴨子、路人會慌張地跳著逃走

模式

模式	說明
限時挑戰	4 分鐘內滾到最大，結束時顯示成績、圖鑑與最佳紀錄
自由滾動	沒有時間限制，暫停畫面可看目前的圖鑑

操作方式

按鍵	功能
W / A / S / D 或 方向鍵	滾動
滑鼠移動（點畫面鎖定）/ Q / E	轉動視角
空白鍵	跳躍
Shift（按住）	衝刺（消耗體力）
P / Esc	暫停 / 繼續
M	背景音樂開關

手機與平板：左半邊拖曳滾動、右半邊滑動轉視角；右下角點「跳躍」、按住「衝刺」，可多指一起操作。右上角可暫停、看圖鑑，並在暫停畫面切換音樂。支援橫直向與瀏海／底部手勢區域；暫停、切換背景或轉向會清掉觸控輸入。

世界與畫面

• 無限程序生成的世界，區塊隨球的大小放大（100 → 400 → 1600 → 6400 公尺，之後每級再放大 4 倍、沒有上限），大球也看得到完整地平線
• 每局隨機安排街區，同一局的配置固定：商店有商品與家具、住宅有郵筒、農場有牲畜、公園有樹木與長椅；道路與斑馬線跨區塊相接，車輛沿車道、行人沿人行道活動
• 建築有前後門，可以進去收集物品，進入時屋頂會隱藏以看清室內；牆壁與屋頂都有碰撞，球長大後能吞下整棟空心建築
• 七種建築：住宅、麵包店、咖啡館、穀倉、倉庫、公寓與辦公大樓；屋頂、招牌、門面、高度與室內物品各有不同，圖鑑也能分別收集
• 隨成長從生活街區、高樓街區擴展到城市與山岳；保留原本物件，再加入適合目前尺度的目標，不在大地圖撒放巨型糖果
• 大尺度街區分成小建築、高樓和城市／山岳三段；剛升級就有能吃的物件，大地標也能在下次世界升級前吞下，小建築不會藏在地標的碰撞範圍內
• PBR 光影：軟陰影、天空環境光、亮面糖果球、會反射天空的流動水面、陽光反光的光暈；日夜循環（一天 4 分鐘）、星空、隨機降雨（雨天地面更滑）
• 真實手感：起步煞車俐落、轉彎有抓地力、陡坡會往下滾、落地會彈一下；掉進水裡會濺起水花、浮在水面滑行並留下漣漪
• 球再大也一樣好操控：100 公尺之後速度、跳躍與重力跟著球等比放大，巨球不會變成慢動作
• 電腦跑不動時會自動切換效能模式（關光暈、降解析度與陰影）
• 程序化背景音樂與音效，全部由 Web Audio API 即時合成：有空間殘響與立體聲定位，滾動聲會隨草地 / 水面變化，白天有鳥叫、晚上有蟲鳴

技術棧

• Three.js — 3D 渲染引擎
• TypeScript — 型別安全
• Vite — 開發與建置
• Web Audio API — 程序化音效與音樂

本地開發

npm install      # 安裝依賴
npm run dev      # 啟動開發伺服器
npm test         # 遊戲公式單元測試
npm run build    # 建置生產版本
npm run preview  # 預覽生產版本

部署資訊

本專案部署於 Render 靜態網站服務：

• 線上網址：https://katamari-web-game.onrender.com/
• 建置指令：npm run build
• 發布目錄：dist

專案結構

rolling-around/
├── src/
│   ├── main.ts              # 程式進入點
│   ├── rules.ts             # 遊戲公式（速度、跳躍、體力、吃的判定、稱號、生成密度）
│   ├── GameManager.ts       # 主循環、模式、碰撞、連擊、計分
│   ├── Engine.ts            # 渲染器、相機、光照
│   ├── Player.ts            # 玩家球體、物理、黏附物件
│   ├── WorldManager.ts      # 無限區塊、地形、物件生成與移動
│   ├── worldLayout.ts       # 固定種子街區配置、用途與建築碰撞公式
│   ├── Buildings.ts         # 空心建築、共用幾何與屋頂剖視
│   ├── ObjectFactory.ts     # 物件型錄與道具
│   ├── WeatherSystem.ts     # 天空、日夜、天氣
│   ├── AudioManager.ts      # 音效與背景音樂
│   ├── Effects.ts           # 粒子、水花、漣漪
│   ├── materials.ts         # 共用材質與程序化貼圖
│   ├── HUD.ts               # 介面、暫停 / 結算畫面、圖鑑
│   └── TouchControls.ts     # 觸控操作
├── tests/rules.test.ts      # 單元測試
├── index.html
└── style.css

注意事項

• 需要支援 WebGL 的瀏覽器（建議 Chrome、Edge、Firefox、Safari 最新版）
• 音效需要點擊開始按鈕後才會啟動（瀏覽器限制）
• 支援 prefers-reduced-motion 無障礙設定

授權

MIT License