純前端的《天堂 Lineage》裝備強化模擬遊戲。Vue 3 + Babylon.js 2.5D 等角場景 + localStorage，無後端、無建置步驟，所有
.html直接在瀏覽器執行。
重現《天堂 Lineage》裝備強化（精煉）系統的瀏覽器遊戲模擬器。玩家在 2.5D 等角地城場景中走動、與歐林 NPC 互動，購買卷軸、強化武器與防具、出售裝備換取天幣，體驗高等級精煉的機率刺激。
設計目標：
- 完整模擬原版精煉手感（機率、爆炸、安定值）
- 純靜態檔案部署，無需任何後端、無需建置步驟
- 機率資料與程式邏輯分離，便於客製化私服規則
- 3D 場景的「邏輯／呈現」徹底分離，導航邏輯可被 Node 單元測試
僅需 Node.js 與現代瀏覽器（Chrome / Edge / Firefox）。
| 平台 | 方式 |
|---|---|
| 跨平台 | node start.cjs（解析動態 port、啟動 server 後自動開瀏覽器） |
| Windows | 直接雙擊 start.bat |
| macOS / Linux | chmod +x start.sh && ./start.sh |
npx serve .
# 然後在瀏覽器開啟伺服器顯示的 http://localhost:<port>務必透過 HTTP 開啟，不要用
file://。assets/data/refine_rates.json是執行期fetch的，file://會觸發 CORS，機率會默默降級成程式內建預設值。serve.json已設no-store避免開發時快取。（3D 場景的
nav3d.js/scene3d.js以 classic<script>全域載入，連file://都能跑；唯獨上述 JSON fetch 需要 HTTP。）
- 伺服器啟動後瀏覽器自動導向
login.html - 輸入角色名稱完成登入，進入主遊戲
lineage.html
lineage-refine/
│
├── index.html # 入口，自動轉址 → login.html
├── login.html # 登入頁
├── lineage.html # 主遊戲（Vue 3 app + 遊戲迴圈 + 3D 場景黏合層）
├── setting.html # 歐林 NPC 配置（可獨立開啟，亦被主遊戲以 iframe 嵌入）
├── cash_pay.html # 天幣儲值
├── refine_table.html # 精煉機率查詢表（新分頁）
├── logout.html # 登出片尾動畫
│
├── assets/
│ ├── js/
│ │ ├── nav3d.js # 純導航邏輯（無 DOM、無 Babylon，可被 Node 測試）
│ │ ├── scene3d.js # 純 Babylon 呈現層
│ │ └── credits.js # 登出片尾名單資料
│ └── data/
│ └── refine_rates.json # 精煉機率設定（執行期 fetch，可獨立調整）
│
├── start.cjs # 跨平台啟動腳本（動態 port + 自動開瀏覽器）
├── start.bat # Windows 一鍵啟動
├── start.sh # macOS / Linux 一鍵啟動
├── serve.json # serve 設定（no-store 防快取）
│
├── static/ # 背景圖、BGM（login / game / logout）
├── lineage_jpg/ # 遊戲場景圖素材
│
├── tests/
│ └── nav3d.test.mjs # nav3d.js 的 Node 單元測試（10 項）
│
└── docs/ # 中文設計文件
├── 01_game_vision.md ~ 08_ui_graphics.md
└── adr/ # 架構決策紀錄
├── 0001-babylon-3d-isometric-scene.md
└── 0002-rebuild-navigation-in-3d.md
index.html
└─→ login.html 輸入角色名稱登入
└─→ lineage.html 主遊戲（需登入，否則跳回 login）
├─⊞ setting.html 歐林配置（以 iframe 嵌入，3D 場景保留在背後）
├─→ cash_pay.html 天幣儲值（驗證登入）
├─→ refine_table.html 機率查詢（新分頁）
└─→ logout.html 登出片尾
所有頁面在 onMounted 檢查 localStorage 的 lineage_player.loggedIn，未登入則強制跳回 login.html。
設定頁特例：lineage.html 的「⚙ 配置」以 iframe 嵌入 setting.html（不跳頁，3D 場景保留在背後）。setting.html 偵測自己是否被嵌入（window.self !== window.top）：嵌入時用 postMessage（lineage-setting-saved / lineage-setting-live）與父頁溝通做即時預覽與存檔後關閉；獨立開啟時則維持整頁跳轉行為。
| 項目 | 技術 |
|---|---|
| 前端框架 | Vue 3（CDN 載入，Composition API，無建置步驟） |
| 3D 場景 | Babylon.js（CDN）— 正交相機 2.5D 等角 |
| 樣式 | 純 CSS3（Flexbox / Grid） |
| 資料儲存 | localStorage（純前端，無後端） |
| 機率設定 | assets/data/refine_rates.json（執行期 fetch） |
| 測試 | Node 內建 test runner（node --test） |
無任何建置工具：所有 .html 直接在瀏覽器執行，Vue 3 與 Babylon.js 從 CDN 載入。新增邏輯請使用純瀏覽器相容 JS，不可引入 TypeScript、JSX 或 ES module bundler。
3D 場景相依以 classic <script> 載入，順序固定：Babylon CDN → assets/js/nav3d.js → assets/js/scene3d.js → 頁面內 inline app。nav3d.js / scene3d.js 各為 IIFE，只掛 globalThis.Nav3D / globalThis.Scene3D。
3D 場景刻意拆成「邏輯／呈現／黏合」三層，責任分明：
- 無 DOM、無 Babylon，因此能被
tests/nav3d.test.mjs以 Node import 測試。 TILEMAP是地圖的唯一真值來源：A* 導航網格與 3D 牆面幾何都由它生成。改地圖只改這個字串陣列。- 圖例：
#牆.地板S起點O歐林C營火t火把P柱子。
- 圖例：
- 提供：
walkable()、A*findPath()（含視線平滑）、canStep()碰撞、座標轉換logicToWorld/worldToLogic。 - 無物理引擎（見
docs/adr/0002）：碰撞用射線／網格判定。
createScene(canvas, opts)回傳sceneApi：setPlayer、setOlin、setNavPath、setCameraMode、setBrightness、dispose。- 正交相機（2.5D 等角，俯角鎖定）；
cameraMode為'fixed'|'rotatable'。 - 多盞點光源（火把／營火）逐像素打光，放大時是效能熱點。
- 持有世界座標
(wx, wy)，logicLoop每幀以nav3d算移動／尋路，再透過sceneApi餵位置給scene3d。 - 移動採 delta-time：
_moveStep = SPEED × dtFactor，FPS 起伏時實際速度不變（夾上限避免穿牆）。
座標系：邏輯像素 (wx, wy)（以 TILE_PX=40 的 tilemap 為準）對上 Babylon 世界單位（WORLD_SCALE=0.04、地圖以原點為中心、邏輯南方 = -Z），兩者以 logicToWorld / worldToLogic 互轉。
所有遊戲狀態存於 localStorage：
{
"name": "Tiger",
"gold": 10000000,
"server": "s1",
"loggedIn": true,
"loginTime": 1718000000000,
"invSize": 100
}invSize＝背包容量（預設 100，向歐林購買每次 +100 格花 1000 萬天幣，上限 1000）。
背包陣列（長度＝lineage_player.invSize，初始 100 格），陣列索引即格子位置：
[
{ "id": "w001", "name": "長劍", "type": "weapon", "enhance": 5 },
{ "id": "s001", "name": "祝福卷軸", "type": "scroll_weapon", "scrollType": "blessed" },
null
]物品 type 可為：weapon / armor / scroll_weapon / scroll_armor / 消耗品
{
"maxEnhLevel": 20,
"brightness": 70,
"cameraMode": "fixed",
"priceConfig": {
"weapon": { "1": 1000, "5": 5000, "10": 50000 },
"armor": { "1": 800, "5": 4000 },
"twdRate": 100
}
}寫
lineage_config時務必用...prev展開保留既有欄位，避免不同頁互相覆寫（例如cameraMode被設定頁以外的頁面洗掉）。
精煉核心邏輯詳見 docs/06_refine_system.md。機率資料與程式分離，存於 assets/data/refine_rates.json（執行期 fetch，失敗則用內建預設值）。
{
"scroll_bonus": { "normal": 0, "blessed": 20, "cursed": 40 },
"weapon": {
"safe_level": 6,
"rates": [
{ "from": 0, "to": 1, "base": 100, "safe": true },
{ "from": 6, "to": 7, "base": 77, "safe": false }
]
},
"armor": {
"safe_level": 4,
"rates": [ "..." ]
}
}base：基礎成功率（0–100，支援小數）safe：安定範圍內成功率固定 100%，不受卷軸加成影響- 卷軸
scroll_bonus直接疊加到base，並 clamp 至 100
| 類型 | 安定範圍 |
|---|---|
| 武器 | +0 ~ +5（safe_level = 6） |
| 防具 | +0 ~ +3（safe_level = 4） |
每次強化費用 = 500 × 2^(當前等級) 天幣
| 卷軸 | 成功 | 失敗 |
|---|---|---|
| 普通 | +1 | 裝備消失 |
| 祝福 | 50% +1 / 50% +2 | 裝備消失 |
| 詛咒 | -1（+40% 成功率加成） | 必爆炸 |
背包工具列勾選「整批衝裝」後，點武器／防具卷軸開啟三階段視窗（詳見 docs/adr/0003）：
- 待處理：載入背包中所有同類裝備，點選／SHIFT 範圍多選。
- 指定等級：下拉選 +1 ~ 最高強化上限（
maxEnhLevel）。 - 衝裝處理：輪巡逐件精煉（拉霸式高亮，間隔可在設定頁「衝裝動畫毫秒」調 100/200/500/1000ms，預設 100，衝裝中調整即時生效），每次嘗試消耗 1 張同變體卷軸、免強化費；機率與單把精煉相同（安定範圍 100%，失敗爆裝化為粉末）。過程逐次記錄在視窗內訊息框，主訊息記錄只收最後總結。卷軸用盡即中止。結束顯示總結，「回到背包」收回存活裝備。視窗 RWD：寬屏一行 10 格、窄屏 5 格（
docs/adr/0004）。
詛咒卷軸不可用於整批（成功會降級，永遠衝不到目標）；祝福 +2 跳級會 clamp 在目標等級。
- Babylon.js 正交相機 2.5D 地城，玩家點地走動、A* 自動尋路、與歐林 NPC 互動。
- 火把／營火點光源、亮度可調（
brightness）、相機可鎖定或旋轉（cameraMode）。 - 內建小地圖（minimap）。
- 初始 100 格（5 欄），可向歐林購買擴充（+100 格／1000 萬天幣，上限 1000 格），支援依類型 / 名稱 / 強化等級排序
- 強化裝備顯示格式統一為「+N 名稱」（如
+10 大馬士革刀） - 鐵鎚模式：點卷軸啟動 → 再點裝備格即自動強化，適合批量操作
- 整批衝裝：工具列勾選後點卷軸，多選裝備一次衝到指定等級（見上方精煉系統）
- 右鍵快速操作：直接強化 / 直接出售
可設定各強化等級的牌價與玩家自訂售價、最高強化等級、亮度、相機模式。以 iframe 嵌入主遊戲做即時預覽。
預設匯率 1 TWD = 100 Gold。
顏色標示各階段機率（綠 100% / 黃 ≥44% / 橘 ≥11% / 紅 ≤5%），並標示機率來源是 JSON 或內建預設。
nav3d.js 為純邏輯，可在 Node 直接測試：
node --test tests/nav3d.test.mjs # 10 項全部應通過測試涵蓋 tilemap 解析、walkable、A* findPath、canStep 碰撞、logicToWorld / worldToLogic 往返等。
天堂沙漠風格主題，所有頁面共享同一組 CSS 變數：
--gold: #c8a84b /* 主要金色 */
--gold2: #f0d060 /* 亮金 / 標題 */
--panel: #150e06 /* 深色面板背景 */
--border: #6a4420 /* 面板邊框 */
--text: #e8d5a0 /* 內文 */
--red: #cc2222
--green: #22aa44強化結果動畫：成功（黃金光環 + 粒子）、失敗（紅色飄散）、爆炸（旋轉縮放爆炸）。
Vue 範本閃現防護：
#app保留v-cloak（搭配[v-cloak]{display:none}與#preboot靜態載入層），避免掛載前{{ }}原始範本外露。
- 不可有建置步驟：只能寫純瀏覽器相容 JS。
nav3d.js必須維持「無 DOM、無 Babylon」：否則無法被 Node 測試、破壞邏輯／呈現分離。nav3d.js/scene3d.js以 classic<script>全域載入，載入順序固定（見技術架構）。- 務必透過 HTTP 開啟，否則
refine_rates.json的 fetch 會 CORS 降級。
詳見 CLAUDE.md、CONTEXT.md（場景／相機統一詞彙）與 docs/adr/。
- 角色選擇系統（採用 Babylon 的主因之一，見
docs/adr/0001） - 裝備圖鑑系統
- 稀有武器掉落
- 強化統計分析
- 雲端存檔
- 世界排行榜
MIT — 僅供學習、研究及遊戲系統設計展示用途。