{"id":50853290,"url":"https://github.com/timcsy/4-cube-puzzle","last_synced_at":"2026-06-14T16:04:51.336Z","repository":{"id":363526521,"uuid":"1263734569","full_name":"timcsy/4-cube-puzzle","owner":"timcsy","description":"立體四方塊 4 Cube Puzzle：國中科展的現代互動重製（TypeScript + Three.js + C++）","archived":false,"fork":false,"pushed_at":"2026-06-09T08:41:44.000Z","size":2913,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T10:13:02.809Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://timcsy.github.io/4-cube-puzzle/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/timcsy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-09T08:10:28.000Z","updated_at":"2026-06-09T08:44:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/timcsy/4-cube-puzzle","commit_stats":null,"previous_names":["timcsy/4-cube-puzzle"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/timcsy/4-cube-puzzle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timcsy%2F4-cube-puzzle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timcsy%2F4-cube-puzzle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timcsy%2F4-cube-puzzle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timcsy%2F4-cube-puzzle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/timcsy","download_url":"https://codeload.github.com/timcsy/4-cube-puzzle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timcsy%2F4-cube-puzzle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34326258,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-14T16:04:50.407Z","updated_at":"2026-06-14T16:04:51.323Z","avatar_url":"https://github.com/timcsy.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 立體四方塊 · 4 Cube Puzzle（現代重製版）\n\n\u003e 國中科展研究《方塊圓舞曲─探討立體四方塊解法》的現代化重製。\n\u003e 原始研究：**張頌宇、謝荏全、蕭亦淳**。\n\n把一份用 Dev-C++、Visual Basic、PhotoImpact、Freehand 完成的國中科展，\n重寫成今天的樣子：**TypeScript 解法引擎 + Three.js 互動 3D 視覺化 + 現代 C++ + Markdown 文件**。\n\n🎮 **線上試玩 → https://timcsy.github.io/4-cube-puzzle/**\n\n![立體四方塊](docs/images/model-1.jpg)\n\n## 這是什麼遊戲？\n\n四個正方體，每面用兩條對角線切成 4 個三角形，塗紅(R)/黃(Y)/藍(B)。\n遊戲提供 **13 種立體圖形**玩法，要把四個方塊拼成指定形狀，\n並讓所有**相接面的三角形顏色彼此相等**。詳見 [研究背景](docs/01-研究背景.md)。\n\n## 專案結構\n\n```\n4-cube-puzzle/\n├── docs/                  研究文件（Markdown + 圖片）\n│   ├── 01-研究背景.md\n│   ├── 02-方塊與規則.md\n│   ├── 03-解法演算法.md\n│   ├── 04-十三種圖形.md\n│   └── 05-顏色排列研究.md\n├── web/                   互動 3D 視覺化（Vite + TypeScript + Three.js）\n│   ├── src/solver.ts        解法引擎（忠實重現原始 C++ 暴力窮舉）\n│   ├── src/geometry.ts      方塊 24 三角形的 3D 幾何\n│   ├── src/assembly.ts      依約束把四方塊組裝成立體外型\n│   ├── src/shapes.ts        全 88 種形狀的列舉 + 約束生成 + 等角縮圖（圖形拼圖核心）\n│   ├── src/study.ts         顏色排列頁：套組設定 + 88 形狀研究（展開圖 / 3D 預覽）\n│   ├── src/cubeset.ts       515,780 種套組產生器（編號 / 分步自訂、生成方塊資料）\n│   └── public/data/puzzle-data.json   四方塊資料 + 13 圖形約束 + 解答數\n└── color-study/           顏色排列研究（現代 C++，解出當年算不完的問題）\n    ├── color_study.cpp      排列數：24 面如何排到四方塊（792,238,080）\n    ├── combinations.cpp     組合數：本質不同的設計（515,780，Burnside）\n    └── legacy/              2011 原始程式 + 忠實重寫（紀念）\n```\n\n## 研究文件\n\n1. [研究背景](docs/01-研究背景.md) — 遊戲由來（MacMahon 1920s → Scott Nelson 1971 → ThinkFun）、研究動機與脈絡。\n2. [方塊與規則](docs/02-方塊與規則.md) — 方塊塗色、相接邊同色規則、座標與資料模型。\n3. [解法演算法](docs/03-解法演算法.md) — 暴力窮舉與剪枝，如何重現原始 C++ 的解。\n4. [十三種圖形](docs/04-十三種圖形.md) — 13 個官方圖形與各自的排列數 / 解法數。\n5. [顏色排列研究](docs/05-顏色排列研究.md) — 24 面如何排到四方塊、515,780 種設計、可全玩套組與 88 形狀的完整分析。\n\n## 快速開始\n\n\u003e **線上試玩**：\u003chttps://timcsy.github.io/4-cube-puzzle/\u003e\n\u003e （push 到 GitHub 後，於 repo *Settings → Pages → Source* 選「GitHub Actions」即會由\n\u003e [`.github/workflows/deploy.yml`](.github/workflows/deploy.yml) 自動部署。）\n\n### 互動 3D 網頁\n\n```bash\ncd web\nnpm install\nnpm run dev      # 開發伺服器\n# 或 npm run build \u0026\u0026 npm run preview\n```\n\n瀏覽器內分兩大區塊：\n\n- **圖形拼圖**：四顆方塊能拼出的**全部 88 種形狀**（面接觸或邊接觸都算相連、鏡像分開；官方 13 個標 ★），\n  選任一形狀即以當前套組**即時求解**。內含兩種子模式——\n  - *看解答*：瀏覽每一組解、即時 3D 組裝、旋轉縮放觀察相貼面如何對齊。\n  - *試玩*：自己旋轉 / 交換方塊，動手解解看。\n- **顏色排列**：顏色排列研究的結果與 24 個不同的面，並可從 **515,780 種「方塊套組」**中\n  用編號或分步自訂選一組（預覽展開圖 / 3D，附四類推薦套組），「套用」後即作用於**圖形拼圖**（兩邊共用同一套組，解答數即時重算）。\n\n### 顏色排列研究（C++）\n\n```bash\ncd color-study\ng++ -O2 -std=c++17 -o color_study color_study.cpp \u0026\u0026 ./color_study      # 排列數 792,238,080\ng++ -O2 -std=c++17 -o combinations combinations.cpp \u0026\u0026 ./combinations   # 組合數 515,780\n```\n\n## 13 個官方圖形的解答數\n\n這裡的「**排列數**」＝程式窮舉出的**所有**合法排法——把「4 顆方塊放哪個位置」（4! 種）與「各自轉到哪個朝向」（24⁴ 種）都算進去。本引擎 13 個圖形全部算得出，每組解也都能在「圖形拼圖」分頁逐一瀏覽。\n\n| 圖形 | 難度 | 排列數 | ｜ | 圖形 | 難度 | 排列數 |\n|:---:|:---:|---:|:---:|:---:|:---:|---:|\n| 一 | 初 | 40 | ｜ | 八 | 高 | 44 |\n| 二 | 初 | 3,400 | ｜ | 九 | 高 | 54 |\n| 三 | 中 | 134 | ｜ | 十 | 高 | 36 |\n| 四 | 中 | 63,296 | ｜ | 十一 | 高 | 186 |\n| 五 | 中 | 8 | ｜ | 十二 | 高 | 496 |\n| 六 | 高 | 4 | ｜ | 十三 | 高 | 8 |\n| 七 | 高 | 48 | ｜ | | | |\n\n\u003e 難度為原研究分級：初級＝1、2；中級＝3、4、5；高級＝6～13。\n\u003e 原始報告另對少數圖形做了「對稱化簡」（扣掉圖形本身對稱造成的重複解），例如圖形一 40→**20**、圖形二 3,400→**1,700**。\n\u003e 本重製版可重現原報告所有已公布數字。詳見 [十三種圖形](docs/04-十三種圖形.md)。\n\n## 重點發現（延伸研究）\n\n當年算不完的問題，這次用現代工具往下挖了好幾層（完整推導與資料見 [顏色排列研究](docs/05-顏色排列研究.md)）：\n\n- **24 面全不同的設計共 515,780 種**（含擺向的排列數 792,238,080），由 Burnside 軌道計數得出。\n- **能拼出全部 13 圖形的「可全玩」套組只有 2,904 種** ＝ 484 個色置換軌道 ＝ **242 個本質手性對**；\n  隨機套組約 99.5% 會卡在圖形五。\n- **四顆方塊其實能拼出 88 種形狀**（面接觸或邊接觸都算相連、鏡像分開），官方 13 個只是其中人工挑選。\n  原始 2011 套組能解開其中 **87 / 88**，唯一卡住的是「**對角雙柱**」（2×2×2 對角兩條直立方塊，自鏡像、鏡射也救不了）。\n- 在「圖形拼圖」分頁可直接玩到全部 88 種形狀並即時求解。\n\n## 與當年的對照\n\n| | 2011 原版 | 現代重製版 |\n|---|---|---|\n| 解法計算 | Dev-C++ / VS2010 暴力窮舉 | TypeScript（瀏覽器內即時運算） |\n| 立體呈現 | Visual Basic 生成器（單向版／旋轉版） | Three.js 寫實 3D，可組裝、旋轉 |\n| 圖形製作 | PhotoImpact / Freehand 10 | 程式即時產生幾何 |\n| 顏色排列研究 | 36 層迴圈跑 3³⁶，跑不完 | 各方塊獨立枚舉 + 組合，毫秒解出（排列數 792,238,080、組合數 515,780） |\n| 報告 | Word / PDF | Markdown |\n\n### 當年的「立體四方塊生成器」\n\n解法算出來只是數字，要「看見」它還得自己畫。當年用 **Visual Basic** 寫了一支\n「立體四方塊生成器」把每組解立體呈現，前後做了兩代：**單向版**，以及改用八個方向呈現的**旋轉版**。\n[docs](docs/04-十三種圖形.md) 裡那些立體透視圖，就是它產出的。\n本重製版的 Three.js 視覺化，正是這支程式的現代接班人。\n\n![2011 原始 Visual Basic 生成器](docs/images/original-generator.png)\n\n## 授權與致謝\n\n研究內容與圖片版權屬原作者所有。本重製版為教育與保存目的之現代化改寫。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimcsy%2F4-cube-puzzle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimcsy%2F4-cube-puzzle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimcsy%2F4-cube-puzzle/lists"}