🎮 bmiibo - 虛擬玩具生態系 (Virtual Toy System)

bmiibo 是一個開源、跨平台且完全免費的虛擬玩具檔案格式與開源生態系。它的核心理念與實體 amiibo 類似，但完全數位化、輕量化。

我們致力於為獨立遊戲、Minecraft 模組、Scratch/TurboWarp 創作者以及教育程式平台帶來全新的「數位收藏儀式感」與安全、防刷的防禦性載入機制。

---

📂 生態系大本營目錄結構

本儲存庫採用 Monorepo（單一儲存庫）架構管理，您可以根據需求進入各平台的專屬領域：

• /python：官方 Python 核心套件。支援自訂異常攔截、5MB 安全安檢，並內建 Pygame 紋理轉換支援。已正式發布至 PyPI（pip install bmiibo）。
• /turbowarp：TurboWarp (Scratch) 專用外掛積木。採用無沙盒模式與內建 JSZip，具備本機每日限讀一次的防刷限制。
• /manager_app：專為玩家打造的 Tkinter 數位公仔牆展示櫃。一橫排 4 隻網格排版，自動清點與統計收藏總數，極具收藏儀式感。
• 🚀 預留未來擴充：/minecraft (Fabric / NeoForge 模組 API 專區)

---

📦 檔案格式規範 (.bmiibo)

.bmiibo 本質上是一個自訂副檔名的壓縮檔（ZIP 格式）。為了確保各平台（尤其是網頁端的 TurboWarp）能夠以極速解開並讀取，所有標準 .bmiibo 檔案**必須採用 ZIP_STORED（僅儲存、不壓縮）**模式進行封裝。

內部包含以下標準結構：

my_character.bmiibo
 ├── bmiibo.json      # 🧠 核心數據（名稱、唯一 ID、創作者、各平台專屬數值）
 └── icon.png         # 🎨 虛擬玩具的視覺圖示（建議標準尺寸 512x512 PNG）
📄 標準 bmiibo.json 範本

{
    "id": "custom_steve_001",
    "name": "我的特製史蒂夫",
    "bmiibo_version": "1.0",
    "author": "Huang Zi-ji",
    "description": "這是一隻具有強大防禦屬性的特製虛擬公仔。",
    "game_data": {
        "turbowarp": {
            "score_multiplier": 2
        },
        "pygame": {
            "bonus_hp": 50,
            "attack_power": 15
        }
    }
}
🔒 核心三大安全防線
不論在何種平台載入 bmiibo，官方核心皆實作了以下防禦性軟體工程規範：

5MB 嚴格防崩潰限制：拒絕載入任何大於 5MB 的偽裝檔案，防止惡意超大檔案撐爆遊戲記憶體。

每日限讀一次（冷卻防刷）：系統會在本地產生冷卻記帳本。同一隻玩具 ID 在 24 小時之內拒絕重複刷卡發放獎勵，完美複製實體公仔的冷卻體驗。

格式完整性校正：嚴格校驗 ZIP 內部是否完整包含 bmiibo.json 與 icon.png，格式損壞時會拋出明確的自訂異常（Exceptions），確保遊戲主程式絕對不閃退。

🌐 虛擬公仔維基 (Wiki) 與背景故事
關於每隻官方與社群發行 bmiibo 的詳細技能、數值發展曲線以及精美的背景故事，我們將統一記錄在官方的寫作平台網站中。

👉 點此前往 bmiibo 官方故事維基網站 (即將上線)

📄 開源授權
本專案採用 MIT License 授權。歡迎任何人自由修改、分發、或商業應用於您的獨立遊戲專案中。一同擴展這個數位玩具生態系吧！


---

## ✨ 完美的收官儀式

這份 `README.md` 貼上去並 Commit 之後，你的 GitHub 專案首頁就會瞬間蛻變成一個**國際級、充滿工程師細節、同時兼具玩家浪漫與科幻感**的開源基地。

看著這份總說明書，整個 `bmiibo` 虛擬玩具生態系的拼圖，從一個想法，到程式碼、到 PyPI 官方套件、到電腦視窗軟體、再到這份完美的說明書，現在全部整整齊齊地落實了。

接下來，你就可以安心地把重心移往你計劃中的**寫作平台網站**，開始為你的公仔們撰寫宏大且精美的背景故事與 Wiki 維