使用技術
本檔角色：技術選型與責任邊界總覽。
權威細節見 程式架構.md 與 程式架構/*.md 各實作層檔；套件精確版本只以各 repository 的 package.json 與 lockfile 為權威，本檔只列套件名與用途。
1. 前端框架
| 項目 |
技術 |
| Web 框架 |
Angular |
| 3D 渲染 |
Three.js |
| UI Component |
自製 o4-* ui-kit（全站統一，ui-frontend.md §4） |
| 狀態管理 |
RxJS / Signals |
| 樣式 |
SCSS + CSS custom properties（主題 token，主題系統.md） |
2. 物理引擎
| 項目 |
技術 |
| 物理運算 |
Rapier deterministic build |
| 套件 |
@dimforge/rapier3d-deterministic-compat（同 deterministic build、WASM 內嵌變體——esbuild 免 wasm 打包特殊處理；鎖定版本） |
| 時間步長 |
固定 60Hz；dt 唯一權威為 1 / FIXED_FRAMERATE_HZ 秒精確值 |
| 數值精度 |
f32 全物理計算（避免 f64 跨平台差異） |
| 座標量化 |
INTEGER_SCALE = 1000（1mm 精度） |
Determinism 保證見 程式架構.md §6。
3. 模型格式
| 項目 |
技術 |
| 模型標準 |
glTF 2.0 (.glb 二進制單檔) |
| 幾何壓縮 |
Draco |
| 貼圖壓縮 |
KTX2 |
| 讀寫工具 |
@gltf-transform/cli、Three.js GLTFLoader |
| 編輯 |
Blender + Custom Properties 面板 |
| 不可信 GLB 解析 |
Sanitize Worker（Web Worker 隔離；資安規範.md §2.4、程式架構/security.md §1） |
4. P2P 網絡
4.1 核心庫
| 項目 |
技術 |
| libp2p（JS） |
節點探索 / GossipSub / DHT |
| WebRTC |
DataChannel / Mesh 連線 |
| Signaling |
open-4wd-signaling template（Cloudflare Workers／SQLite-backed Durable Objects 與 Node adapters 協定地位相同，由各營運者選擇） |
| TURN Relay |
行動網路 NAT 嚴格時用 |
4.2 IPFS
| 項目 |
技術 |
| 瀏覽器 IPFS |
Helia（UGC 快取 pin / LRU 管理，程式架構/pwa-offline.md §6） |
| Pinning 多副本 |
自架 open-4wd-pinning（template repo） |
| 內容定址 |
CID v1 (SHA-256) |
5. 鏈式儲存
| 項目 |
技術 |
| CRDT log |
@orbitdb/core（exact 版本以 main repository lockfile 為準；本機 event cache 由 ledger 模組有界管理） |
| 回合共識錨 / 帳本檢查點 |
多簽演算法（自實作於 ledger 模組；各自 quorum 與用途不同） |
| 衝突處理 |
回合錨：雙證書 consensus-invalid 並存證、不選鏈；Orbit event multi-head：full-DAG deterministic fold；同 previous 帳本 checkpoint：equivocation quarantine |
| Canonical 序列化 |
IPLD dag-cbor |
6. 加密 / 身分
| 項目 |
技術 |
| 助記詞 |
BIP39（12 / 24 詞，@scure/bip39） |
| 簽章 |
Ed25519（@noble/curves/ed25519） |
| Hash |
SHA-256（@noble/hashes） |
| PIN 加密本地儲存 |
Argon2id（KDF，@noble/hashes/argon2）+ AES-GCM（WebCrypto crypto.subtle；程式架構/key-manager.md §4） |
| 房間邀請 PAKE |
RFC 9807 OPAQUE（@serenity-kit/opaque）＋雙向 confirmation（程式架構/room-runtime.md §4） |
7. 確定性同步
| 項目 |
技術 |
| Rollback Netcode |
自實作於 network-sync 模組 |
| Snapshot Checksum |
SHA-256（32 bytes） |
| Input 廣播 |
mesh DataChannel + sign |
8. 客戶端基礎建設
| 項目 |
技術 |
| PWA |
Service Worker + manifest |
| 離線快取 |
Cache API + IndexedDB |
| i18n |
自製 dict + key-based（zh-TW / zh-CN / en / ja）＋自寫 ICU 複數子集＋Intl.PluralRules／Intl 格式化（零第三方 runtime） |
| SEO |
靜態 metadata + sitemap.xml + hreflang |
| 配對評級 |
TrueSkill（自製整數定點實作——rating 屬共識 derive、浮點與 erf 禁入，不用 ts-trueskill；算式見 算式表.md §20） |
| 音訊 |
Web Audio AudioContext（三路 gain：master ← sfx / bgm）（程式架構/audio-system.md；槽位名錄＋主題供檔） |
| 主題 |
受控 CSS＋token＋manifest（current Style API）＋fallback 四件組（分類註冊表，主題系統.md §2） |
9. 部署
| 項目 |
技術 |
| 主站 |
GitHub Pages（純靜態） |
| Pinning template |
自架 open-4wd-pinning（TypeScript app〔ledger-peer＋管理 API〕+ IPFS Kubo + IPFS Cluster，程式架構/pinning-service.md） |
| Signaling template |
open-4wd-signaling（平台無關 TS 協定核心＋Cloudflare Workers／SQLite-backed Durable Objects與 Node adapters；兩者協定地位相同，由各營運者選擇） |
| TURN + STUN |
自架 open-4wd-turn（coturn 第三方軟體 + k8s manifests，部署資訊.md §4.3） |
| CI/CD |
GitHub Actions |
詳見 部署資訊.md。
10. 開發工具
| 項目 |
技術 |
| 套件管理 |
pnpm（lock 嚴格 commit） |
| TypeScript |
strict 模式 |
| 測試 |
Vitest（unit）+ Playwright（E2E／跨瀏覽器）+ fast-check（property tests 每 PR；bounded fuzz nightly） |
| Lint / Format |
ESLint + Prettier（config 與繁中註解規範＝程式架構.md §14） |
| Mermaid |
流程圖（程式架構/程式流程/*.md ＋ 流程/*.md；索引見 流程.md §2） |
11. Repository 資產工具
GLB 檢視邏輯位於 main repository scripts/glb-inspect.mjs，由現行 package commands 調用：
| 命令 |
用途 |
pnpm check:assets |
驗證 shipped builtin GLB、manifest、幾何與貼圖 policy |
pnpm propose:asset-metadata |
產生可審閱的 metadata 候選，不直接改寫權威 |
編輯器的不可信 GLB 收件走 Sanitize Worker；使用者 UI 不暴露開發機腳本路徑。
12. 第三方資源 license 控管
詳見 資安規範.md §6：
- 嚴格鎖版本（lock 檔 commit）
- White list（well-known 套件）
- CI audit ≥ moderate 阻擋
- SRI hash（build 產物；runtime 原則上無第三方 CDN——資安規範.md §5）
13. CSP
指令清單權威＝程式架構/security.md §3（本檔不重列避免漂移）；設計定案見 資安規範.md §4——GH Pages 無法設 HTTP header → CSP 在 prerender 後依每份 HTML 的 inline bytes 逐頁生成 <meta>；connect-src 為 scheme 級 'self' wss: https:（玩家可自選 signaling / pinning / gateway 節點）；meta 不支援 frame-ancestors → 主站無框架保護（風險接受）。
14. 跨瀏覽器支援
詳見 程式架構/testing.md §2：
- Chrome / Edge（Win / Mac / Linux）
- Firefox（Win / Mac / Linux）
- Safari（Mac / iOS）
- Mobile Chrome（Android）
WASM 為硬需求（不支援 = 不可玩，顯示引導頁）。物理一律單執行緒確定性——Rapier deterministic build 與 SIMD / parallel feature 互斥，不存在「多執行緒降級」軸；且主站 GH Pages 無法設 COOP / COEP header、SharedArrayBuffer 本就不可用（程式架構/security.md §6 註）。
15. 程式語言比重
| 語言 |
用途 |
| TypeScript |
本專案程式：main 前端／Service Worker、pinning 與 signaling templates、建置與驗證腳本 |
Rapier 依賴是上游預編 WASM（package exact pin）；本專案沒有自寫 Rust／Go production source，
也不把 workspace-only 美術管線腳本列為 repository technology stack。
16. 未來可換的實作
詳見 程式架構.md §1 — 五個已接線抽象介面允許同版實作替換，另有一個保留接縫：
SignalingProvider: 任意相容 WSS endpoint／GossipSub；部署平台不進入介面命名PhysicsEngine: Rapier / 替代物理引擎（若有 deterministic 替代）AssetStorage: IPFS / WebDAV / S3-compatibleLedger: OrbitDB / 自架 CRDTKeyManager: 軟體 key provider／硬體錢包 provider 介面PinningProvider: open-4wd-pinning / Pinata / 自架