12 KiB
選舉小鎮 — 架構總覽
以台灣選舉為舞台的網頁遊戲。主要玩法是選戰卡牌:用政府開放資料建出真實的選民結構當底盤,8 週出牌拉票,最後開票夜一區一區翻過來。 外圍有政治生涯(里長一路選到總統)、政策島、小遊戲、捏人物與服裝店、歷屆參選人資料庫。
本文件寫的是 2026-10-28 程式碼的實際狀態。舊的設計文件(十週行程版、多人連線、舊架構等)描述的東西已刪除或沒有做, 已經移除;程式註解裡提到的 docs/02、04–09、11–13、15–17、21 指的就是這些舊文件,原文在 2026-10-28 的備份裡。
全貌
政府開放資料、中選會、Wikidata
│
▼
backend/data/pipeline(Python)──► backend/data/build/
├─ packs/ 資料包:村里人口、選民群、歷史得票、地圖
├─ scenarios/ 劇本:真實候選人與得票,加上 calibration.json
├─ people/ records.json(歷屆參選人)、genders.json、slogans.json
└─ council/ 議員選區
│ ▲
│ apps/sim 校準 ─────┘(舊十週引擎讓 AI 對打,寫 calibration.json)
▼
backend/packages ──► backend/apps/server(Fastify,REST /api)──► web(React + Vite)
│ │
data/runs/<局>.json 瀏覽器 localStorage
(每一局卡牌的存檔) (進度、生涯、外觀、設定)
兩個程式庫
| 程式庫 | 內容 | 規則 |
|---|---|---|
backend/ |
pnpm workspace:規則、伺服器、校準工具、Python 資料管線 | 所有結算都在這裡 |
web/ |
React 19 + Vite;3D 小鎮用 three.js | 只依賴 @election2026/protocol,不含遊戲規則 |
前端拿到的是伺服器算好的「玩家視角」,自己不算票。改畫面不用動後端,改規則不用動前端。
後端套件
| 套件 | 做什麼 | 誰用 |
|---|---|---|
packages/protocol |
前後端契約:Zod 定義(資料包、劇本、卡牌的請求與回應、參選人資料)、頭像部件目錄、政黨清單;pnpm schema 產生 JSON Schema 給 Python 驗證 |
全部,包括前端 |
packages/rogue |
選戰卡牌的規則:純函式,狀態可序列化,同一個種子同一局 | server、sim |
packages/engine |
選民模型(docs/03),加上舊的十週選戰引擎 | rogue 開局用選民模型;十週引擎只給 sim |
packages/content |
十週引擎的行動、事件、記者堵麥、議題;手工劇本;自創角色 | server、rogue、sim |
packages/scenarios |
劇本目錄:手工劇本+管線產生的全台劇本,套上校準值 | server、sim |
packages/pack-loader |
從磁碟讀取並驗證資料包、劇本、標語、性別 | server、sim |
apps/server |
Fastify API,速率限制;卡牌每一局放記憶體(最多 200 局)並寫到 data/runs/ |
前端 |
apps/sim |
校準(calibrate-local.ts)、回測、平衡報告(卡牌、生涯、政黨、大絕招、里長) |
開發者 |
rogue 裡面
| 檔案 | 內容 |
|---|---|
setup.ts、local.ts |
開局:用選民模型算各區(或各里)底盤與地區特色;local.ts 是里長、議員關 |
archetypes.ts |
候選人特色(docs/25):本命區算法、六種類型的技能/弱點/專屬牌(類型由伺服器依中選會紀錄或出身決定) |
rules.ts |
createRun、endWeek、choose、ultimate,以及從 cards.ts 轉出的 playCard:每個動作回傳新的狀態 |
state.ts |
RunState、TOTAL_WEEKS = 8、存檔版本 SAVE_VERSION 與 migrateRun |
data.ts、cards.ts |
牌的資料與效果 |
rival.ts |
對手每週的意圖與行動;每局抽的對手規則(docs/25);落後時急起直追(docs/26) |
battle.ts |
本週戰場:每週要搶的一區(docs/26) |
overtime.ts、pledges.ts |
趕場(體力用完翻牌庫頂,翻到負面狀態牌就翻車)、政見支票(第 1 週開跑記者會,開票夜兌現或跳票)(docs/27) |
tides.ts、calibration.ts |
歷史形勢的全國風向表(apps/sim rogue-tides)、逐張地圖的對手強度校準(apps/sim rogue-calibrate) |
route.ts、scenes.ts、content.ts |
每週結束的「下一站」(含地方派系談判、下下週的門)、辯論/民調/黑函週(週次每局隨機)、堵麥與地方抉擇 |
advisors.ts、feats.ts、meta.ts、ultimate.ts、mechanics.ts |
幕僚、成就、生涯能力與政策、大絕招、逆風等級(ASC_RULES,docs/26) |
view.ts |
給前端的玩家視角(含每張手牌打在每一區的預估) |
tutorial.ts、bots.ts |
新手教學;模擬玩家(平衡報告用) |
API
| 路由 | 用途 |
|---|---|
GET /api/health |
健康檢查 |
GET /api/scenarios |
劇本清單(候選人、能力值、查證過的標語、數字出處) |
GET /api/scenarios/list |
劇本清單的畫面版(首頁、選人畫面用,只留畫面用到的欄位,docs/27) |
GET /api/packs/:packId/topology |
地圖 |
GET /api/rogue/catalog |
目錄:牌、幕僚、事件、成就、逆風等級、生涯能力、政策島建築(圖鑑、生涯、政策島用) |
POST /api/rogue/runs |
開一局:劇本、候選人、種子、逆風、勢均力敵、每日一戰、自創角色、生涯帶過來的東西、里長/議員關 |
POST /api/rogue/tutorial |
開新手教學 |
GET /api/rogue/runs/:id、/area |
這一局的玩家視角、地圖範圍 |
GET /api/rogue/villages/:scenarioId |
里長關選里用 |
POST /api/rogue/runs/:id/play、/end-week、/choose、/ultimate、/rush、/overtime |
出牌、結束這週、選下一站、大絕招、加開行程、趕場(docs/27) |
GET /api/people、/api/people/:id |
歷屆參選人與客觀資歷分數(records.json) |
前端
web/src/App.tsx 是 hash 路由;首頁和卡牌一開始就載入,其他畫面用到才下載。
資料夾(web/src/game/) |
畫面 |
|---|---|
home、start |
首頁、會動的 3D 選戰小鎮 |
rogue |
卡牌大廳、一局、開票夜、結果圖卡、圖鑑與成就、政治生涯 |
career |
任期小遊戲(質詢、審預算…) |
island |
政策工坊與政策島 |
minigames |
掃街握手、造勢、看板等小遊戲 |
creator、shop、art |
捏人物、服裝店、頭像繪製(部件目錄,docs/24) |
people |
歷屆參選人 |
board3d、stage、news、audio、ui、hud |
3D 棋盤、地圖、新聞台、音樂音效、共用元件、設定 |
../viewer、../map |
資料檢視器(開發用:資料檢視器、美術總覽、頭像對照、部件檢查只有 pnpm dev 打得開,正式版不打包) |
玩家進度沒有帳號,存在瀏覽器 localStorage(鍵都以 tongsuan. 開頭:卡牌進度與完成度、生涯、政策島、外觀與小鎮幣、自創角色、小遊戲紀錄、設定)。
載入:index.html 內嵌載入畫面(不等任何下載),首頁等 3D 小鎮搭好才淡出(src/splash.ts);three.js 和一局卡牌的畫面用到才下載;
3D 小鎮依實際每秒張數自動降畫質,偵測到沒有顯示卡(軟體繪圖)直接用最低畫質。正式版用 pnpm start(建置後 vite preview),比 pnpm dev 小三倍以上;API 回應由伺服器壓縮(@fastify/compress)。
素材:web/public/assets/ 是 CC0/OFL 素材(逐檔記在 LICENSES.md);字型切成 unicode-range 小片、3D 模型 meshopt 壓縮、音樂 Opus,重做的腳本在 art/(docs/27);web/public/cards/ 是卡牌插圖,用 art/ 裡的腳本產生;頭像部件是原創 SVG,放在 backend/packages/protocol/art/avatar/,pnpm avatar:build 轉成程式碼。
一局卡牌怎麼跑
- 前端
POST /api/rogue/runs。伺服器從劇本目錄找劇本,讀資料包(同一份快取),rogue/setup.ts用選民模型算出各區底盤,createRun產生初始狀態。 - 每個動作(出牌、結束這週、選下一站)都是
rules.ts的純函式:舊狀態 → 新狀態。伺服器存起來(記憶體+data/runs/<id>.json),回傳view.ts算好的玩家視角。 - 種子決定一切:同一個種子、同樣的選擇就是同一局。每日一戰的種子由日期算出,「挑戰朋友」連結帶著種子。
資料管線
backend/data/pipeline,指令是 election-data(安裝方式見 backend/README.md):
| 指令 | 產出 |
|---|---|
pack --county <代碼> |
資料包:村里人口與 30 個選民群、歷史得票、村里屬性、地圖(--before 做回測用的資料包) |
local --year、races --year |
縣市長、總統、區域立委劇本(候選人層級得票和中選會核對) |
donations |
政治獻金(劇本的錢) |
records |
歷屆參選人與資歷分數、議員選區 |
parties |
歷屆政黨清單(也寫 protocol/src/parties.ts) |
python -m election_data.genders |
候選人性別(給頭像) |
資料來源與授權見 docs/10;每個資料包的 sources.json 列出來源、版本與擷取日期。
測試與檢查
cd backend && pnpm typecheck && pnpm test # 協定、引擎、內容、卡牌、劇本、伺服器
cd web && pnpm typecheck && pnpm test && pnpm build
cd backend/data/pipeline && .venv/bin/pytest && .venv/bin/ruff check src tests
原則
- 規則只在後端,前端只依賴協定。
- 規則是純函式、狀態可序列化,同一個種子可以重現(測試、存檔、挑戰朋友都靠這點)。
- 內容是資料:牌、事件、幕僚、劇本都是資料檔,新增內容不改規則。
- 真實資料、真實人物有界線:不用照片、不用 AI 畫真人、不捏造真人引述、AI 控制的真實人物不用奧步(docs/14)。
文件
| 文件 | 內容 |
|---|---|
| 03-voter-model.md | 選民模型:選民群、投票公式、參數、校準 |
| 10-data-sources.md | 資料來源、授權、已查證的法規(部分資料源只是研究,文件開頭有說明) |
| 14-legal-and-ethics.md | 真實人物、政黨、選舉期間的法律與倫理界線 |
| 18-feedback-backlog.md | 使用者回饋與改版紀錄(歷史紀錄;程式註解的「18 第 N 項」指這裡) |
| 19-classic-battles.md | 歷史劇本:1996–2024 總統、2014 縣市長怎麼做出來的 |
| 20-campaign-slogans.md | 真實候選人的競選標語與出處 |
| 22-rogue-v2.md | 選戰卡牌:玩法、機制、平衡 |
| 23-career-and-meta.md | 政治生涯、政策島、小遊戲、歷屆參選人與資歷分數 |
| 24-avatar-shop-plan.md | 紙娃娃部件目錄、畫風、服裝店;附開放真錢前的法規整理 |
| 25-gameplay-v3.md | 選戰卡牌第三版:本命區、類型技能、完成度(已做);流派、對手規則、隨機行事曆、難度(規格) |
| 26-gameplay-v4.md | 選戰卡牌第四版:桌遊機制研究、本週戰場、加開行程、急起直追、逆風階梯重排、各項設定的平衡 |
| 27-gameplay-v5-and-assets.md | 選戰卡牌第五版:趕場(推運氣)、政見支票;資源瘦身(字型切片、3D 模型壓縮、音樂、劇本清單),首頁 8.7 MB → 1.6 MB |
| appendix-1994-original.md | 1994 年原作《臺灣模擬選戰》的拆解紀錄 |