Repo ↗ · 原始 README ↗ · 文件包（Markdown／授權）

封面參考（原作）： A Story About My Uncle · 原作宣傳圖，由 IGDB 提供。圖片版權屬原權利人，供辨識原作使用，不代表此重寫／模組專案的實際畫面。

來源維護者： bailo167 · 版本： 088b91731e2e · 整理日期： 2026-10-12

文件授權： MIT · LICENSE · 本文形式： README 翻譯

下文為來源 README 的繁中翻譯，由 Kirikirin 使用 AI 輔助整理；功能、完成度與測試結果均為原作者描述，本站未逐項實機驗證。圖片改為來源連結，指令與技術識別保留原文。

ASAMU-decomp

[README 圖片：CI](https://github.com/bailo167/ASAMU-decomp/actions/workflows/ci.yml)
README 圖片：status: pre-alpha
README 圖片：platforms: Windows | Linux | macOS
README 圖片：license: MIT OR Apache-2.0

一個以 Rust 和 Bevy 從零開始撰寫的《A Story About My Uncle》開源引擎重製版，可從你合法擁有的遊戲副本中遊玩原版遊戲的關卡。

README 圖片：ASAMU-decomp 以第一人稱執行 AG-StarHaven 關卡：前景中的抓鉤手套、木製走道、粉色樹木以及雲海之上的漂浮島嶼

此重製版正在執行 <code>AG-StarHaven</code>，資料從合法擁有的遊戲副本在本機匯入。
更多截圖

非官方專案。 與 Gone North Games 或 Coffee Stain Studios 無任何關聯、背書或聯繫。
此儲存庫包含任何原版受著作權保護的遊戲資產、程式碼或資料。若要使用，你需要自己合法
擁有的《A Story About My Uncle》副本；匯入器會從你的安裝在本機轉換資料。

這是什麼

ASAMU-decomp 是遊戲引擎與規則的淨室重實作：一個建構於
Bevy 之上的全新原生執行階段，外加一個匯入器，用於讀取原始 Steam
安裝的 Unreal Engine 3 封裝，並在你的機器上將其轉換為執行階段可載入的格式（glTF、DDS、Ogg 和 JSON，以及一些我們自有的原始緩衝區，用於 BSP 幾何和光照圖）。它是透過逆向工程合法擁有的
副本所建構，每個還原的遊戲玩法數值都記錄了其來源。

它不是模組、包裝器、注入器或原版執行檔的修補副本，且不隨附任何遊戲內容。沒有你自己的副本時，你會得到一個小型灰色測試關卡；有了它，你就能在現代跨平台引擎中執行遊戲自身的關卡、
腳本、角色和音效。

此專案處於pre-alpha 階段。很多功能已經可用；限制也同樣直白地列出。

目前狀態

匯入你自己的副本後，以下功能目前可用：

領域 可執行的內容
關卡 全部七張故事地圖皆可載入其幾何、擺設和串流子關卡：Workshop、Paradise Cave、Beautiful City、Dark Cave、Star Haven、Ice Cave（含 The Core）以及 Epilogue。
移動 原版引擎 pawn 物理的移植（行走、墜落、飛行、踏步、煞車），由從遊戲自身資料還原的數值驅動：行走和衝刺速度、加速度、空中控制、可放開的跳躍、落地。
抓鉤與能力 抓鉤（瞄準、範圍、拉引、所有放開規則、有限次數、充能水晶）、強力跳躍和火箭靴，移植自原版的腳本行為。
關卡腳本 Kismet（遊戲的視覺化腳本）的直譯器：12 張隨附地圖使用的全部 97 種 sequence object（3,207 個已放置物件），外加用於移動平台、過場攝影機和計時事件的 Matinee 軌道。
碰撞 對轉換後關卡幾何和 BSP 的三角形碰撞、移動平台碰撞、觸發和擊殺體積、檢查點。
渲染 靜態網格、近似材質、原版烘焙光照圖、帶動畫的蒙皮角色、粒子系統、貼花、水和植被、高度霧、關卡的色彩分級和泛光。
角色 Maddie、村民、Dark Cave 蠕蟲、收集品和故事可互動物件，以及帶動畫的第一人稱手部。
音訊 音效提示、環境音、帶字幕的旁白，以及自適應音樂系統。
遊戲外殼 主選單、章節選擇、暫停和設定；存檔和進度；遊戲的 14 種語言文字；帶獎牌的時間挑戰（如同原版，需完成遊戲後解鎖）；鍵盤/滑鼠和遊戲手把，使用原版綁定（選單需要鍵盤或滑鼠；遊戲手把路徑有測試涵蓋，但尚未用真實控制器試過）。
戰役路徑 每個關卡的腳本化出口會通往下一關，從 Workshop 到 Epilogue，可在自動化執行中完成。
平台 每次推送都會在 Windows、Linux 和 macOS（Apple silicon）上建置，並進行 Intel-macOS 編譯檢查；函式庫和工具 crate 的測試在三者上皆會執行。

目前限制

  • 行為一致性尚未量測。 移動、抓鉤和能力是從還原的數值和規格移植而來，但尚未與原版遊戲的錄影逐 tick 比較。錄製器和比較工具已存在，第一批錄影於 2026 年 10 月製作，而第一次重播就出現分歧；目前找到的原因是工具限制和未解問題，尚未歸類為模擬差異（docs/PARITY.md）。在這些數字出現之前，任何「玩起來像原版」的說法都不會被視為已驗證。
  • 沒有人從頭到尾玩過。 上述的戰役鏈是由自動化執行證明的，該執行會跳至每個關卡的出口觸發器。這顯示腳本化轉場可運作，而非每條路線都能手動通行。
  • 渲染是近似值。 材質被簡化為標準 PBR 模型，光照圖失去其方向性細節，某些效果（霧體積、動態模糊、環境光遮蔽）不會繪製，且少數材質仍顯示為平面佔位符。光照和色彩可能與原版有明顯差異。
  • 某些腳本化物件永遠不會出現。 初始隱藏、之後由關卡腳本顯示的道具和平台（六張地圖中共 13 個）尚未繪製。
  • 原版的選單和 HUD 未被重現。 它們是 Scaleform 影片；目前以功能性替代品代替。教學美術、標題標誌和工作人員名單影片使用佔位符。
  • 僅驗證了一種遊戲版本： macOS Steam build 1822049。定位器知道 Windows 安裝的預期佈局，匯入器也會嘗試轉換，但從未在 Windows 安裝上執行過。
  • 原版的存檔無法匯入。 此重製版保有自己的存檔。
  • 尚無封裝發行版。 發行管線已存在但尚未執行；目前你需從原始碼建置。

已知的遊戲玩法差異列於 docs/PARITY.md，未解的整合和渲染
缺口列於 docs/INTEGRATION.md（第 10 節）。

沙盒（實驗性）

asamu --sandbox 會在重製版之上開啟一個實驗室：在遊玩時變更移動和能力參數、
凍結和單步執行時間、保留記憶體內存檔狀態、傳送、觀看速度、跳躍和擺盪讀數，並在兩個手工製作的測試競技場中試用全部功能。這是我們自己的工具（crates/asamu-sandbox 和應用程式的選用功能），
不是原版的行為，且它顯示或記錄的任何內容都不是一致性的證據。它將存檔保留在
記憶體中，絕不觸碰忠實遊戲的存檔、進度或時間挑戰紀錄，且可被編譯排除；一個防護
測試套件會檢查，經歷未變更 Sandbox 工作階段的遊戲與未經歷者位元完全相同。這是
第一版，有自動化測試和無人截圖涵蓋，但尚未手動使用：
docs/SANDBOX.md。

快速開始

你需要一個 Rust 工具鏈 以及透過 Steam 安裝的《A Story About My Uncle》。

git clone https://github.com/bailo167/ASAMU-decomp
cd ASAMU-decomp
cargo build --release -p asamu -p asamu-import

# Convert your copy (found through Steam; read-only; about a minute and 2.3 GB on your disk)
cargo run --release -p asamu-import -- all

# Play one level directly (progress is kept in memory only)
cargo run --release -p asamu -- --level AG-Workshop

若要使用磁碟上的存檔進入主選單，請以匯入器的輸出資料夾執行 asamu --converted <folder>，且不加
--level（該資料夾由匯入器印出；Playing 列出了預設值）。不加選項的 asamu
會啟動內建測試關卡，不需要遊戲資料。
Linux 需要先安裝一些系統套件，且匯入器有其他安裝位置的選項：
請見 Building 和 Playing。

轉換後的資料是受著作權保護的遊戲資料。它會留在你機器上的資料夾中；請勿分享。

運作方式

flowchart LR
    install["Your legitimate copy<br/>(Steam install, read-only)"]
    importer["<b>asamu-import</b><br/>UE3 package reader + converters"]
    data["Converted data<br/>glTF · DDS · Ogg · JSON<br/>(stays on your machine)"]
    runtime["<b>asamu</b><br/>Rust / Bevy runtime"]
    install --> importer --> data --> runtime

匯入器（以及開發者工具 asamu-inspect）是唯一會讀取 Unreal Engine 3 封裝的部分。執行階段
從不連結封裝讀取器：它載入轉換後的格式，且從不定位或讀取安裝。

flowchart TB
    subgraph imp["Importer (runs once, on your machine)"]
        ue3["asamu-ue3<br/>package reader · LZO · objects · bytecode<br/>meshes · textures · Kismet · Matinee"]
        import["asamu-import<br/>12 conversion stages"]
        ue3 --> import
    end
    subgraph rt["Runtime"]
        assets["asamu-assets<br/>scenes · materials · audio graphs · particles"]
        world["asamu-world<br/>collision · volumes · checkpoints · movers"]
        player["asamu-player<br/>pawn physics · grapple · abilities"]
        kismet["asamu-kismet<br/>Kismet + Matinee interpreter"]
        game["asamu-game<br/>frame order · NPCs · saves · time trial"]
        app["apps/asamu (Bevy)<br/>rendering · audio · UI · input"]
        world --> game
        player --> game
        kismet --> game
        game --> app
        assets --> app
    end
    import -. "converted data" .-> assets
    import -. "converted data" .-> world
    import -. "converted data" .-> kismet

模擬（asamu-player、asamu-world、asamu-kismet、asamu-game）是確定性的，並在沒有
渲染器的情況下以固定步長執行，這正是它能在 CI 中測試並與原版比較的原因。
Architecture 有詳細說明。

技術亮點

  • 遊戲的腳本封裝就藏在顯眼之處。 磁碟上沒有 ASAMU.u：cooker 將其合併
    到 Startup.upk，其中封裝 asamu 持有全部 172 個遊戲類別。唯一的原生 ASAMU 程式碼是一個
    設定管理器；抓鉤是一個 UnrealScript 武器，執行於原版引擎的 pawn 物理之上。
  • 全部 42 個隨附的 UE3 封裝皆可解析（檔案版本 868；其中 38 個壓縮封裝從 LZO1X 區塊解壓縮），
    使用從零撰寫並與獨立實作交叉檢查的讀取器。70,946 個腳本物件和 2,521 個類別預設
    物件解碼，每個位元組皆有交代。
  • 全部 12,801 個已編譯腳本的位元碼解碼器（12,511 個函式、211 個狀態和 79 個帶有
    類別層級程式碼的類別），其 token 表與執行檔相符。
  • 在可證明之處精確解碼資產： 全部 1,512 個靜態網格從其解碼欄位逐位元組重新編碼；
    8,920 個材質和 30,284 個已放置 actor 與獨立解碼器一致。
  • 從未剝離符號的二元檔還原原生物理。 macOS 執行檔仍帶有約 135,000 個
    符號，這使得撰寫引擎 pawn 移動的詳細規格並從中移植成為可能。與執行中遊戲的一致性尚未量測。
  • 每個遊戲玩法常數都有出處。 地面速度 440、跳躍速度 1000、抓鉤範圍 5000：執行階段中的每個數值
    都引用其來自的類別預設、設定檔或原生程式碼，且若它們漂移，測試會失敗。
  • 原版遊戲的唯讀一致性錄製器： 一個用於 Windows 版本的記憶體讀取錄製器，它
    製作了第一批錄影（每幀的位置、速度、視角和抓鉤狀態），以及一個用於
    Rosetta 下 macOS 版本的 LLDB 腳本，它通過其附加和佈局檢查，但尚未錄製任何追蹤。這些
    錄影會透過重製版重播並比較。
  • 儲存庫中沒有遊戲資料，由工具強制執行。 CI 中的衛生檢查會拒絕遊戲檔案格式、二進位
    負載和私人路徑，並標記反編譯器輸出；匯入器是資料到達執行階段的唯一途徑。

證據及其主張的信心標籤，位於
docs/reverse-engineering/（34 份文件）。

截圖

以下全部都是重製版，渲染從合法擁有的副本在本機匯入的資料。
README 圖片：Star Haven：雲海之上的木製碼頭、一座冰山和漂浮岩石 README 圖片：Beautiful City：一座爬滿藤蔓的石拱門、一條燈籠照亮的階梯，以及帶發光符文的漂浮島嶼
AG-StarHaven AG-BeautifulCity
README 圖片：Beautiful City：洞穴村莊內的市集攤位和一棵盛開的樹 README 圖片：第一人稱視角的 Star Haven，帶有抓鉤手套
AG-BeautifulCity 中的村莊市集 第一人稱，帶有轉換後的手套和替代 HUD

平台

平台 目標 狀態
Windows x86_64-pc-windows-msvc 每次推送皆在 CI 中建置；函式庫和工具測試會執行
Linux x86_64-unknown-linux-gnu 每次推送皆在 CI 中建置；函式庫和工具測試會執行
macOS（Apple silicon） aarch64-apple-darwin 每次推送皆在 CI 中建置；函式庫和工具測試會執行；開發機器
macOS（Intel） x86_64-apple-darwin 在 CI 中進行編譯檢查

CI 證明程式碼在每個系統上都能編譯，且不需要遊戲資料的函式庫與工具測試皆通過；
應用程式的 Sandbox 測試也會在 Linux 上的 CI 中執行。應用程式的其他測試，以及每個會讀取遊戲資料的測試，僅
在開發機器上執行。在 Windows
與 Linux 上實際遊玩尚未經過手動測試。

進度

目前里程碑： M11 — 完整遊戲/劇情路徑（核心遊玩內容、Kismet 劇情腳本、NPC、音訊、選單與存檔皆已連接；已開始對照原版錄影衡量一致性）

以下「已實作」表示程式碼存在並通過自身的測試。「已驗證」則另行計算：對於格式、
資產與匯入器項目，結果是對照原版的資料或另一份獨立撰寫的解碼器進行檢查；對於工具項目，該檢查在 CI 中執行通過；對於碰撞，我們的查詢與暴力破解
預言機一致。沒有任何項目是對照執行中遊戲的行為進行驗證，且遊玩項目在
一致性比較通過之前都維持未驗證。

README 圖片：由 progress/progress.toml 產生的進度矩陣

類別 項目 已實作 + 已驗證 已驗證 進行中 完成度 已驗證 %
二進位逆向工程 8 8 4 0 100% 50%
符號 7 7 4 0 100% 57%
UE3 封裝 10 10 9 0 100% 90%
壓縮 6 6 6 0 100% 100%
物件 6 6 5 0 100% 83%
UnrealScript 8 8 6 0 100% 75%
Kismet 6 6 3 0 100% 50%
地圖 7 7 6 0 100% 85%
資產 10 10 10 0 100% 100%
玩家 10 10 0 0 100% 0%
沿桿滑行 8 8 0 0 100% 0%
世界 13 13 0 0 100% 0%
渲染 12 12 1 0 100% 8%
音訊 5 5 0 0 100% 0%
存檔/進度 5 5 0 0 100% 0%
匯入器 7 7 5 0 100% 71%
平台 5 5 0 0 100% 0%
測試 10 9 3 1 90% 30%
Sandbox（非原版） 7 5 0 2 71% 0%
總計 150 147 62 3 98% 41%

百分比由 tools/progress-gen 從
progress/progress.toml 中列舉的項目計算而得：完成度 = (已實作 + 已驗證) / 總數，取整數下限。
已驗證另行回報。狀態定義見 CLAUDE.md。

工作區

路徑 用途
apps/asamu Bevy 執行檔：渲染、音訊、UI、輸入
crates/asamu-core 共用數學、單位、座標慣例、確定性三角函式
crates/asamu-player 確定性、無渲染的 pawn 物理、沿桿滑行、能力與軌跡格式
crates/asamu-world 關卡場景、碰撞、體積、檢查點、世界物件
crates/asamu-kismet Kismet 與 Matinee 解譯器
crates/asamu-game 影格順序、關卡腳本主機、NPC、存檔、計時挑戰
crates/asamu-sandbox Sandbox 模型（實驗性，我們的）：參數疊加、工作階段指令、時間控制、存檔狀態、測試競技場
crates/asamu-assets 轉換後資料的執行階段檢視：場景、材質、音訊圖、粒子
crates/asamu-ue3 遊戲 UE3 封裝世代的防禦性讀取器（僅匯入器與檢查工具）
tools/asamu-import 將原版安裝轉換為使用者本機資料（asamu-import all）
tools/asamu-locate, asamu-inventory 尋找 Steam 安裝；其檔案的淨化清單
tools/asamu-inspect, asamu-symbols 檢查封裝與地圖；分類原版執行檔的符號
tools/asamu-trace, trace-recorder 錄製原版遊戲（唯讀）並與重製版比較
tools/progress-gen, repo-hygiene 進度矩陣產生器；拒絕將遊戲資料與逆向工程傾印提交至版本庫

文件

法律範圍

本專案僅散布獨立撰寫的程式碼、工具、測試、格式文件與淨化後的中繼資料
（雜湊、計數、解釋結構所需的名稱）。它絕不散布原版執行檔、
封裝、地圖、貼圖、網格、音訊、視訊或反編譯程式碼。見 docs/LEGAL.md。

本 README 中的螢幕截圖顯示重製版執行從自有副本於本機轉換而來的資料；
收錄這些截圖是為了說明本專案。

程式碼以 MIT 或 Apache-2.0 雙重授權；見 LICENSE。A Story About My Uncle 及其所有
資產為其各自擁有者的財產。

授權與來源聲明

原始 README 與翻譯沿用 MIT 授權；本次修改為繁中翻譯、連結與排版調整。可修改的 Markdown、原始 README、LICENSE 與 NOTICE 收錄於頂部文件包。原作遊戲內容與商標不因此獲得授權。

LICENSE

ASAMU-decomp is dual-licensed under either of

  * MIT License (below), or
  * Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0)

at your option. This license covers only the code, tooling, tests and
documentation written for this project. It grants no rights whatsoever to
"A Story About My Uncle" or any of its assets, which remain the property of
their respective owners and are not included in this repository.

-------------------------------------------------------------------------------
MIT License

Copyright (c) 2026 ASAMU-decomp contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.