來源維護者： SuperReaper1999 · 版本： 9e77b2226edc · 整理日期： 2026-10-12

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

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

Project Judas

Judas 是一款遊戲引擎。 它專為一類遊戲打造——從微小的平坦地形關卡，到行星與宇宙尺度、包含太空船、任意重力、地形、液體、氣體，以及行星、船艦與開放太空之間無縫轉換的世界——而且它刻意保持狹窄：它不打算與 Unity、Unreal 或 Godot 競爭。你將在下方遇到的星球、木板、太空船、地形、湖泊、大氣、火焰、門與其他物件，都是引擎的技術展示：用來驗證引擎能力的場景內容，而不是引擎本身，也不是「Judas 這款遊戲」。

渲染目標為 OpenGL 3.3 Core / GLSL 330。OpenGL 進入點透過 SDL 建立的上下文，使用隨附的 GLAD 2.0.8 OpenGL 3.3 Core 載入器載入；產生方式與授權來源記錄於 third_party/glad/README.md。

JUDAS 狀態：已準備好進行新功能開發

目前接受的檢查點：b7d7f4142b243cd57d9998f4952857e67e5d84a8
（Lastlight UI 與牆壁追擊）；M73 自有訊號已在
18650ba23c23eaaab0542d6e0055e33cc14d1049 接受。M74 編輯器時期動畫
重定向已暫時建立檢查點；人體動作驗證仍待進行。
請參閱重定向／設定檔參考以及一般
Retarget Lab 專案。
M72 桌面審查與原生 Windows VM 檢查已在其記錄範圍內完成。實體 Windows 硬體驗證仍未完成；M67 人工撰寫審查仍為暫時／延後狀態。M69 控制器接受度使用合成／VM 檢查；硬體手感尚未測試。
請從架構、JudasJS 與
文件維護開始。

M38 獨立匯出（已接受）： 專案設定可匯出可移動的 Linux Release 遊戲套件，包含其專案輸入、場景與已註冊的執行階段資源。
請參閱匯出工作流程與平台需求。

M33 次要攝影機（已接受）： 撰寫的攝影機可渲染至產生的紋理，
供一般場景材質取用。請參閱攝影機撰寫與示範。
操作者接受度已記錄；傳送門尚未實作。

FTFT1–9 已建立檢查點，且最終乾淨 Release 驗證已通過；請參閱
docs/STABILIZATION_STATUS.md。請參閱
docs/FTFT.md 以取得確切狀態與證據。並未暗示新的
里程碑標籤。完整高保真 M32 液體／固體耦合仍屬
未來研究，與近似生產模型分開。

歷史 FTFT9 基礎／保留的舊版 PBF 路徑： 它使用粒子／PBF 液體運動，搭配取樣的
近似流體靜力學／阻力、明確的幾何容器腔體，以及自訂
玩家游泳。外部碰撞與解析支撐具有不同歸屬；
不主張精確的外部液體／物體動量守恆。下方歷史
M24–M26 結果保留其原始範圍，並不描述此新
耦合。目前的行為證據與已接受的數值限制記錄於
帳本與最終閘門。

目前守恆液體使用 M54 儲存器／容器
與 M55 動態表面。數量與表面演化
具有不同歸屬；兩者皆不主張最終流體保真度。受保護的 P1 研究
仍分開進行。舊版粒子流體示範是一般已註冊
專案，具有平坦游泳池、徑向重力行星盆地、投擲
物體，以及可承載實際液體粒子的空幾何容器：

./build/judas projects/fluid_demo/fluid_demo.judasproj

使用 F1/F2 選擇兩個場景。歷史 FTFT/P1 固定裝置仍是證據，
不是目前的示範啟動器。

歷史 FTFT4 剛體物理結果（下方數值成本描述該閘門）：

動態 AABB 樹 broadphase，具備窮舉 oracle 覆蓋，包括
玩家掃掠。1,500 個靜止木箱：14.266 ms 中位數完整物理步進
在最新七次執行比較中；較舊的約 4 ms 結果
屬於較不穩健的幾何。
配對局部穩健基本幾何、保留的有號間隙與精確
局部錨點；累積的暖啟動接觸衝量、盒流形
與庫侖摩擦以提供持續支撐。
事件時間隔離撞擊，具備撰寫的回彈係數；刻意
非彈性的耦合／多重接觸撞擊。剩餘步進時間被
消耗。暫時錨定運動帳本保留動態／玩家查詢的往返
移動。低速／事件上限擷取與
有限解析度掠射 CCD 是明確近似。
通過目前引擎的計時、能量、堆疊、斜坡、平台、broadphase、
生命週期與幾何檢查。43 個生產套件與受保護的
非同步／持久化／重力／近遠整合檢查通過 FTFT4。

請參閱 FTFT4 結果以取得確切
預算、限制與成本。主動旋轉複合體與移動支撐
比舊端點／推測路徑成本更高；不主張廣泛加速。
較早的零重力停止、過早彈跳與能量增益失敗
仍保留為歷史證據，與通過的修復分開。

里程碑 31（已接受）——Judas 學會它不必等待。 昂貴的
獨立工作不再停止模擬／渲染執行緒：

工作系統（src/JobSystem.h）。有界工作池（數量衍生
自硬體，上限為 16；絕不每項工作一個執行緒，絕不 detached）
以 High/Normal/Low 優先級執行提交的工作，並具備公平規則，
使低優先工作被延遲但絕不餓死。工作具有控制代碼與
Queued/Running/Completed/Failed/Cancelled 狀態，會回報錯誤，可在
開始前取消（執行中亦可合作式取消），並在仍有未完成工作時
確定性關閉：佇列中的工作被取消，執行中的工作被等待，每個
工作者都被 join。
非同步檔案 IO（src/AsyncFile.h）。讀取請求以
Succeeded（位元組）、Failed（訊息）或 Cancelled 完成；工作者擁有其
自身參考，因此呼叫者可在任何時間丟棄請求。
非同步資源。 M30 ResourceManager 現在讓資源
經過 Unloaded → Queued → Loading → CpuReady → Ready。工作者讀取
並解碼（OBJ 解析、影像解碼）；只有 Pump() 在 GL 執行緒上
建立或銷毀 GPU 物件，每幀最多數次上傳。
請求絕不阻塞；呈現會繪製灰色佔位符，直到
資源 Ready（失敗時為洋紅色），並在資源抵達的該幀切換為真實網格。
重複請求會加入同一個進行中的載入；
已釋放或被取代的載入會依世代被拒絕，絕不
復活；被丟棄的需求（參考計數）會取消佇列中的載入。
預算與逐出。 常駐位元組會依資源估算；超過
可設定預算時，未被參考的 Ready 資源會依最近最少使用
優先逐出，被參考的絕不逐出；被逐出的資源只會
再次載入。
診斷。 Profiler 顯示工作者、佇列中／執行中／已完成／
失敗／已取消的工作、工作者使用率、資源載入中／就緒／
失敗、常駐位元組與預算、上傳、逐出、取消
與過期丟棄；Asset Browser 將每個資源顯示為 loading /
ready（含大小）/ FAILED（含原因）/ unloaded。

實測（judas_resource_stress，40 個合成真實資源，總計 137 MB
的 OBJ/PNG，微小遊戲場景播放中，Xvfb 下的軟體 GL，3 個工作者）：
非同步載入在 0.57 秒 wall time 內完成，最差主執行緒幀
為 29.6 ms，且沒有幀超過 33 ms；同樣 40 個載入在 M30 阻塞
路徑中花費 1.75 秒，40 幀中有 27 幀超過 33 ms，最差幀為
67.8 ms。工作本身並非免費（1.48 秒工作者 CPU）；主
執行緒只是不再等待全部完成。全部 31 個套件通過（新增：
judas_job_tests）；測試框架執行與參考位元組完全相同。
請參閱 docs/ARCHITECTURE.md，「里程碑 31」，
以了解歸屬法則、契約與限制。

里程碑 30（已接受）——Judas 學會真正用它自己
做遊戲。——Judas 學會真正用它自己
做遊戲。** 引擎現在具有真正的專案概念、穩定的資源身分、單一
資源管理器邊界，以及一個能在不碰引擎原始碼的情況下
製作小型遊戲的編輯器：

專案。 一款遊戲是一個目錄，內含 .judasproj 檔案，命名
專案、其啟動場景及其 Assets/Scenes/Saves 資料夾。執行階段
啟動專案（./build/judas my_game.judasproj）；編輯器建立、開啟與編輯專案
（File → New project / Open project / Project settings），並可將 Run project 作為獨立
執行階段程序執行。技術展示是一般專案
（judas_tech_demo.judasproj）；一款微小平坦遊戲隨附於
projects/tiny_game/。沒有任何引擎程式碼依專案而分支。
資源身分。 每個可匯入資源（.obj、.png/.jpg/.bmp/ .tga、.ttf）在 .judasmeta sidecar 中帶有 32 位十六進位
數字 id。場景以 id 參考網格與紋理（場景格式版本
3），因此在 Asset Browser 中重新命名或移動資源會保持每個
場景參考有效——由自動化測試證明，而非依檔名
猜測。缺少與損壞的資源會被回報，絕不猜測繞過。
資源管理器。 ResourceManager 是專案資源成為
GPU 資源的唯一位置：request → load → ready → cached → failed
→ released → reloaded，同步，GL 僅在 Renderer 內，撰寫資料中
沒有 GL 控制代碼。
可用的編輯器。 視埠 translate/rotate/scale gizmos（world/
local space、Ctrl 吸附、每次拖曳一個 undo 步驟）、Asset Browser
（依路徑匯入、重新命名／移動、缺少指示器、拖曳到
視埠或 inspector 欄位）、階層 rename/duplicate/
indicators、component editor registry 而非 inspector
switch、Project settings、引擎視覺化的 Debug 選單
（碰撞形狀、玩家膠囊與支撐、接觸、重力向量與區域、幀軸、光源、互動範圍、
生命週期／保真度、取樣地形法線、流體粒子、
大氣半徑）以及 Profiler 面板（幀時間、固定步進、
步進時間、物體、接觸、生命週期計數、繪製呼叫、三角形、
陰影 pass、光源、流體粒子、資源命中／未命中）。

全部 30 個 M30 測試套件通過（新的 judas_project_tests 涵蓋專案
格式、資源身分在重新命名／移動後仍有效、資源管理器
契約、兩個隨附專案的 project → startup scene → runtime、
gizmo 數學與 undo/redo、inspector 資料往返，以及
Edit/Play 分離）；經典與地形測試框架執行在近端與遠端世界
原點與 M27/M28 參考位元組完全相同。請參閱 docs/ARCHITECTURE.md，「里程碑
30」，以了解邊界、格式、證據與限制
（無 OS 檔案對話框、球體近似揀選、無物件父子關係、無
非同步載入）。

里程碑 29（已接受）——Judas 學會存在並不代表被完整
模擬。三項引擎能力，因為它們是
同一個問題而一起建構：

可變模擬保真度。 每個動態物體都是持久實體，能以 Full 保真度（一般的即時物理物體）、Coarse 保真度（沒有物理物體；其姿態與速度是引擎資料，每步以低成本推進——已靜止的實體保持不動，自由飛行的實體在相同重力場下積分，沒有接觸），或 Dormant（沒有物體、沒有逐步工作，狀態精確保留）來表示。轉換會保留身分、姿態、線性與角速度；重建回 Full 時會從該狀態重建即時物體，沒有衝量，也沒有重複。
實體／世界生命週期。 Active（Full/Coarse）、Unloaded（Dormant）與 Destroyed 是不同的：卸載的實體會回來，銷毀的永遠不會。實體可以採用哪些保真度是一項能力（流體／大氣／燃燒／載具／複合內容僅限 Full）；它何時改變是場景選擇的策略。唯一隨附的策略是與玩家的距離；未設定策略的場景會讓每個實體保持 Full，且完全不觸及這一切。
持久化為基準 + 差異。 執行階段變更——實體被移動、銷毀或建立，門／開關被切換——會以小型 .judasstate 檔案儲存於未變更的基準場景之上，並在完整重新啟動後載入回來。場景檔案永遠不會被遊戲玩法改寫；刪除差異檔，原始基準就會回來。

在 1,500 個受管理木箱上測量：全部 Full（1,501 個物理物體）時每個固定步 343 ms，而使用距離策略（20 個物體：19 個 Full、41 個 Coarse、1,440 個 Dormant）時為 1.0 ms；將全部 1,500 個提升為 Full 耗費 0.65 ms。新場景：assets/scenes/fidelity_demo.judas（一排受管理木箱向遠處延伸、兩顆自由飛行的衛星、距離策略 25 m / 70 m）與 assets/scenes/flat_playground.judas（五十個實體、無策略——忽略這一切的小型傳統遊戲）。全部 29 個套件通過；經典測試框架與 M27 位元組完全相同。請參閱 docs/ARCHITECTURE.md, “Milestone 29,”，以了解模型、差異格式、測量結果與限制（流體／氣體／火焰／玩家／載具沒有簡化形式；粗略慣性運動沒有接觸；M29 暴露出一個既有的靜止潛變求解器假象）。

Milestone 28（已接受） 讓 Judas 成為具有真實場景、確定性版本化場景格式、場景驅動執行階段，以及 judas_editor 執行檔的引擎——請參閱下方的「Milestone 28 accepted baseline」。

快速開始

sudo apt install cmake libsdl2-dev libglm-dev build-essential   # Ubuntu/Debian
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j"$(nproc)"

./build/judas                                        # the project in the current directory (the tech demo), startup scene
./build/judas judas_tech_demo.judasproj              # the same, explicitly
./build/judas projects/tiny_game/tiny_game.judasproj # the tiny flat game
./build/judas assets/scenes/classic.judas            # one scene of the enclosing project
./build/judas_editor projects/tiny_game/tiny_game.judasproj   # editor: open a project
./build/judas_editor assets/scenes/classic.judas             # editor: open a scene (and its project)
./build/judas_editor                                 # editor: the project enclosing the working directory

專案與場景資料中的路徑是相對於專案根目錄（包含 .judasproj 的目錄），絕不是相對於工作目錄。唯一由引擎擁有的檔案，即 UI 字型 assets/fonts/DejaVuSans.ttf，會在其執行檔目錄旁、其父目錄、$JUDAS_ENGINE_ROOT，或工作目錄中找到——因此儲存庫下任何位置的建置樹都能從任何地方運作；若建置樹位於其他地方，請設定 JUDAS_ENGINE_ROOT=<repository>。

專案

專案是含有一個 .judasproj 檔案的目錄：

JudasProject 1
name "Tiny Game"
startup-scene "Scenes/main.judas"
assets-dir "Assets"
scenes-dir "Scenes"
saves-dir "Saves"

./build/judas 會播放啟動場景；F6/F7 世界狀態差異位於專案的 saves 目錄中。技術展示是儲存庫根目錄的 judas_tech_demo.judasproj（資產位於 assets/ 下，場景位於 assets/scenes/ 下，啟動場景為 terrain.judas）；小型遊戲是 projects/tiny_game/。編輯器的 File → New project 會建立目錄樹以及入門場景（地面、玩家起點、燈），並將其設為啟動場景；Project settings 會編輯名稱與啟動場景，並列出專案的場景；Run project 會以獨立程序啟動 ./build/judas ——如同玩家會啟動遊戲的方式，而不是編輯器的 Play。

資產以 id 參照。資產目錄中的每個資產檔案都有一個 sidecar：

Assets/models/beacon.obj
Assets/models/beacon.obj.judasmeta      JudasAssetMeta 1 / id "<32 hex>" / type mesh / source "..."

sidecar 會隨檔案移動，因此重新命名或移動資產（Asset Browser → Rename / move）不會改變任何場景。沒有 sidecar 的檔案會列為 untracked，直到被匯入或追蹤；沒有其檔案的 sidecar 會回報為 missing；重複的 id 與損毀的 sidecar 會列為 problems。不會從檔案名稱推測任何事。

非同步資源（M31）

資產會在背景載入：執行階段與編輯器請求資產、繼續模擬與繪製（網格仍在載入時顯示灰色預留位置方塊，失敗時顯示洋紅色），並在其 Ready 的那一幀切換到真實網格。工作執行緒負責讀取與解碼；只有 GL 執行緒會上傳，每幀最多兩個資源。JUDAS_RESOURCE_MODE=blocking 會還原同步的 M30 路徑（腳本化測試框架一律使用它）。Profiler（View → Profiler）會顯示工作與資源狀態；Asset Browser 會將每個資產顯示為 loading / ready / FAILED。

./build/judas_resource_stress [report.json]   # the M31 stress demonstration (needs a display; Xvfb is fine)

FTFT2 透過一般的 Application::Run 迴圈新增確定性的真實 GL 整合涵蓋範圍，包括取消、專案交接、常駐與關閉。較舊的腳本化測試框架仍是阻塞參考，而 M31 壓力工具是支援性的負載／效能證據。

python3 scripts/ftft2_validation.py  # builds; async integration, editor/runtime, production suites

需要 CMake/C++17、SDL2/GLM 開發套件、Python 3，以及可運作的 OpenGL 3.3 環境。測試執行器使用 SDL 離屏／Mesa 軟體 GL；晚於新完成的情況需要至少兩個硬體衍生的工作執行緒。請參閱 FTFT2 evidence，以了解確切範圍與限制。

場景

場景是純文字檔。標頭會指明格式與版本；settings 帶有場景範圍的值；每個 object 區塊都有明確、永不重複使用的 id、名稱、變換，以及它使用的任何元件：

JudasScene 3
settings
  name "Classic abuse chamber"
  world-origin 0 0 0
  sun-direction 0.4 0.7 0.35
  sun-color 1 0.98 0.92
  ambient 0.16 0.17 0.19
  fluid-scale 1
  next-id 26
end

object 2 "Planet A"
  position 0 0 0
  rotation 1 0 0 0
  scale 1 1 1
  render sphere
  render.radius 20
  render.color 0.3 0.45 0.35
  ...                            (a mesh render carries render.mesh-asset "<id>"
                                  and render.texture-asset "<id>" — asset ids, never paths)
  body static sphere
  body.radius 20
  ...
  gravity radial 9.81
  gravity.region sphere 26
end

寫入器發出的每個欄位，讀取器都要求——不會有任何欄位被默默預設。儲存是確定性的（物件依場景順序、固定鍵順序、最短精確小數），因此場景檔案在版本控制下能乾淨地 diff。完整文法與每個元件的欄位在 docs/ARCHITECTURE.md, “Milestone 28, Scene file format.”

隨附場景（assets/scenes/）：

File	Content
`terrain.judas`	M25–M27 地形行星：湖泊、大氣、太空船、燃料塊（預設執行階段場景）
`terrain_rotated.judas`	相同內容，但行星旋轉 47°（先前的 `JUDAS_TERRAIN_ROTATED`）
`terrain_atmospheric_pass.judas`	駕駛員已附加，飛船位於 M26 解析遠地點（先前的 `JUDAS_ATMOSPHERIC_PASS`）
`terrain_atmospheric_pass_rotated.judas`	上述兩者
`classic.judas`	雙行星與木板的濫用測試室，包含 M24 杯子、軌道物體、門、開關、樓梯、斜坡、信標
`classic_fluid_rotated.judas`	經典場景，包含 M24 旋轉流體站重力區域
`classic_fluid_zero.judas`	經典場景，包含零重力流體站區域
`fidelity_demo.judas`	M29：平坦地面、60 個向 240 m 遠處延伸的受管理木箱、兩顆自由飛行的衛星、距離策略（Full ≤ 25 m、Coarse ≤ 70 m、Dormant 更遠）
`flat_playground.judas`	M29：小型傳統案例——小地圖上的五十個實體、無策略、沒有任何受管理項目
`rigid_stability.judas`	M32：乾剛體接觸——等長箱堆疊、數種尺寸的鬆散箱、20° 斜坡上有高摩擦箱保持不動與低摩擦箱滑動、一個球體
`broadphase_stress.judas`	M32： 1,500 個木箱，全部為 Full 剛體（無保真度策略），排列成網格並帶有幾個堆疊——負載下 profiler 的 broadphase 線條

M28 之前的環境開關仍可在從儲存庫根目錄無引數啟動時運作，並從專案的 scenes 目錄選取這些檔案：JUDAS_CLASSIC_DEMO=1、JUDAS_FLUID_GRAVITY=rotated|zero、JUDAS_ATMOSPHERIC_PASS=1、JUDAS_TERRAIN_ROTATED=1。明確的 ./build/judas 或 ./build/judas <scene> 引數會優先於所有這些。JUDAS_WORLD_OFFSET（far 或 x,y,z）仍會覆寫場景撰寫的世界原點。

隨附場景由 ./build/judas_scene_author assets/scenes projects/tiny_game/Scenes（tools/SceneAuthor.cpp）產生。重新產生會覆寫已提交的檔案，且不再忠實於它們。序列化器現在也會將較後面的欄位以其預設值寫出，而產生器早於後續的場景編輯：FTFT9（1b3a134）直接將流體腔加入 classic.judas、classic_fluid_rotated.judas 與 classic_fluid_zero.judas 中的兩個杯子，因此重新產生會移除它們。請將已提交的場景視為真相來源，僅在刻意為之時重新產生。裸跑此工具時，它會印出用法且不寫入任何內容。

編輯器

./build/judas_editor [project.judasproj | scene.judas] 會開啟專案（及其啟動場景）或其外層專案內的場景。編輯模式有專用的中央場景檢視、可調整大小的階層／檢閱器側欄，以及底部的資產瀏覽器。執行 Play 會保留正常全視窗的執行階段檢視。請參閱 editor guide 與 making a game by hand。

編輯器動作	操作方式
環顧四周	按住滑鼠右鍵並移動滑鼠
平移場景視圖	在視埠中按住滑鼠中鍵並拖曳；移動會跟隨視平面與最近的焦距深度；放開或 `Escape` 結束拖曳
縮放場景視圖	在視埠中滾動滑鼠滾輪；向上滾動靠近，向下滾動遠離目前焦距；面板捲動不會移動攝影機
飛行	按住右鍵時：`W`/`A`/`S`/`D`、`E` 向上、`Q` 向下、`Shift` 加速
選取	左鍵點擊視埠中可見的圖元/網格幾何，包括巢狀物件，或在 Hierarchy 中點擊它
聚焦選取項目	`F`，或 Hierarchy → Focus
移動 / 旋轉 / 縮放	`W` / `E` / `R` 選取操作器；拖曳紅色/綠色/藍色握把（箭頭、環、方塊）；`X` 切換區域/世界空間；按住 `Ctrl`（或 Edit → Snap）以吸附 0.5 m / 15° / 0.25；一次拖曳為一個復原步驟
建立物件	Create 選單：空物件、靜態/動態方塊或球體、網格、點/聚光燈、門、重力區域、玩家起始點（置於攝影機前方 8 m）；或從 Asset Browser 拖曳網格到視埠
重新命名 / 複製	雙擊 Hierarchy 列（或右鍵 → Rename）；`Ctrl+D`、Hierarchy → Duplicate，或右鍵 → Duplicate（新的 id，置於原始物件之後）
刪除 / 重新排序	`Delete`、Hierarchy → Delete，或右鍵選單（Move up / Move down — 順序是作者資料：較早的重力區域優先）
Hierarchy 指示器	將滑鼠停留在列上可查看元件字母與穩定身分；`(!)` 標示缺少或未知的網格；暫停的執行階段檢視會顯示 `[Full]`/`[Coarse]`/`[Dormant]`/`[destroyed]` 狀態
編輯	Inspector：名稱、變換、每個元件的欄位（每種元件類型一個編輯器，來自註冊表；Add component… / Remove）、資產欄位為下拉選單或拖放目標，並附上誠實的狀態列（未知 id、檔案缺少）
場景範圍數值	工具列 Scene 或 View → Scene settings：名稱、世界原點、太陽、環境光、流體比例、保真度策略
資產	Asset Browser（View 選單）：每個受追蹤的資產及其類型、路徑、狀態與 id；Import 依路徑將檔案匯入資產目錄（由引擎自身的載入器驗證）；選取 → Rename / move、Remove；Track 未追蹤的檔案；問題會列出；將列拖曳到視埠或 inspector 欄位上
專案	File → New project…、Open project…、Project settings（名稱、啟動場景、場景清單 — 雙擊開啟）、Run project
除錯檢視	Debug 選單切換：碰撞形狀、玩家膠囊 + 支撐、接觸、重力向量 + 區域、畫面軸、燈光、互動範圍、生命週期/保真度、取樣地形法線、流體粒子、大氣半徑 — 在 Edit（作者資料）與 Play（即時）中繪製
效能分析器	View → Profiler：畫面毫秒 / FPS（滾動）、每畫面固定步數、最後一步毫秒、即時/動態剛體、接觸、實體數量、繪製呼叫、三角形、陰影階段、動態燈光、除錯線、流體粒子與表面/求解時間、資源數量與命中/未命中/失敗
復原 / 重做	`Ctrl+Z` / `Ctrl+Y`（Edit 選單）— 操作器/共享欄位手勢與建立/複製/刪除/重新排序會分組；某些特殊 inspector 控制項會提交每次變更
儲存 / 開啟	`Ctrl+S`、File → Save scene / Save scene as… / Open scene…（路徑欄位相對於專案根目錄；無作業系統對話框）；未儲存的場景替換/關閉會提供 Save、Discard 或 Cancel
Play scene	工具列 Play 或 `F5`：作者場景會以其專案腳本/舊版相容性策略具現化；編輯輸入邊緣會先清除
播放期間	現代專案提供自己的暫停/輸入策略；歷史相容性可保留 M13 選單。暫停檢視為唯讀。
Stop	Stop 或 `F5`：執行階段世界會被丟棄，作者場景完全保持原樣
Run project	在編輯器二進位檔旁以獨立程序啟動 `./build/judas` ，並載入啟動場景

Play 期間所做的執行階段變更（拋出的板條箱、燒掉的燃料、移動的水）
永遠不會寫回場景；M29 世界狀態差異會寫入專案的 saves 目錄。
「將執行階段狀態套用到場景」是可能的未來功能，不是 M30 的功能。

物件父子關係、作業系統檔案對話框、網格精確揀選、非同步
載入與資產烹製管線刻意不屬於 M30 —
請參閱 docs/ARCHITECTURE.md，「Milestone 30,
Deliberately not implemented.」

生命週期、保真度與持久性（M29）

場景中的每個動態剛體都是具有穩定 id 的 持久實體
（其場景物件 id；執行階段建立的實體會從另一個高位範圍取得 id）。在任何時刻，它都處於一種 保真度：

保真度	物理剛體	每步工作	狀態儲存於
Full	是	一般模擬	`PhysicsWorld`
Coarse	否	已靜止：無；慣性：在重力下進行一次低成本積分，無接觸	實體記錄
Dormant	否	無 — 對其而言時間已凍結	實體記錄

以及一種 生命週期 狀態：Active（Full 或 Coarse）、Unloaded
（Dormant）或 Destroyed（永久）。場景可透過剛體的 Managed 旗標讓實體加入自動管理，並在 Scene 面板中選擇策略（Fidelity policy: distance，附帶 Full 與 Coarse
半徑）。若無策略，則永遠不會有任何項目被降級。編輯器的 Inspector
會在播放時顯示所選實體的持久 id、生命週期、保真度、粗略運動種類與重建次數，並附有 Force Full /
Coarse / Dormant 除錯按鈕；HUD 會顯示計數。

持久性 是相對於未變更基準場景的差異：

按鍵	動作
`Z`	在玩家前方建立一個持久板條箱
`Y`	永久摧毀目標（或持有）的可揀選實體
`F6`	儲存世界狀態差異（`saves/<scene>.judasstate`）
`F7`	刪除它 — 下次啟動即為原始基準

執行階段（以及編輯器的 Play）會自動套用 saves/<scene>.judasstate
（若存在）（JUDAS_WORLD_STATE= 覆寫，
JUDAS_WORLD_STATE=none 停用）。差異只記錄：已移動的實體
（姿勢 + 速度）、已摧毀、已建立（其完整定義），
以及門/開關狀態。FTFT1 存檔使用格式 2，並帶有標準作者場景資料的版本化 SHA-256
指紋。僅憑場景名稱永遠不會授權載入。ID、物件順序、變換、元件、資產 ID 與作者設定必須相符；註解、空白與數字拼寫則無關緊要。
格式錯誤/不相容的存檔會在任何即時世界變更之前被拒絕。
舊版第 1 版存檔無法驗證，會在不變更檔案的情況下被拒絕；
請在開始新存檔前明確封存或刪除其中一個。基準
.judas 檔案永遠不會被遊戲玩法寫入。這是嚴格的場景相容性，
不是遷移或外部資產位元組的雜湊。請參閱 FTFT ledger。

Milestone 28 已接受基準

M28 建立了真實場景（src/Scene.h）、.judas 場景檔案
格式（src/SceneSerialization.h；嚴格、確定性、版本化 — 現在在 M29 的兩項新增後為
第 2 版）、場景驅動的執行階段
（RuntimeWorld、Simulation、WorldPresentation、GameSession、
InteractivePlay），將 Application.cpp 從 2,404 行縮減為約 120
行協調程式碼，以及 Dear ImGui judas_editor，並具有明確的
Edit/Play 分離。操作員已接受 M28；它是 main 上的提交 57e69a0。
M28 可攜性修正（glm::glm 以及
glm::glm-header-only）仍然有效。

目前熱學範圍（FTFT8）

有限可燃塗層使用溫度、燃料與取樣氧化劑；沒有控制反應的燃燒計時器。大氣是開放式指定
儲庫，火焰/煙霧形狀是視覺輸出，不是守恆氣體 CFD。
熱學材料也可在沒有行星/大氣元件的普通場景中運作：
無大氣意味著真空輻射與零氧化劑。

被動配對/儲庫熱交換在剛性係數下受到限制，因此其
顯式步進不會超過取樣溫度。配對的兩端
接收相同的傳遞，診斷會暴露任何限制。化學與
加熱器輸入分開計算。這是具有固定載體質量/熱容量且無輻射遮蔽的近似熱學模型，
不是詳細化學。請參閱方法與獨立檢查。

Milestone 27 已接受基準

M27 新增： 地形太空船上的三個普通可揀選剛體方塊
帶有有限可燃塗層。它們的溫度、剩餘
燃料、燃燒率、熱輸出與局部氧化劑供應是固定步進
熱學狀態。按住 C 為玩家局部視線框架所攜帶的 18 kW 點加熱器供電。
其輻射能量透過幾何攔截到達每個方塊；沒有 Ignite 指令。一旦方塊夠熱，
大氣氧化劑允許燃料受限的反應釋放
熱。剩餘燃料使用雙精度，因此微小的稀薄空氣燃燒仍會
消耗可解釋其釋放熱量的質量。成對輻射
可加熱附近的第二個方塊；較遠的第三個
方塊測試僅靠鄰近不會傳播火勢。這些仍是可用 G 拾取並以 H 投擲的物理
剛體。太空船可使用普通接觸與推力將
它們帶入稀薄大氣或真空。

火需要 M26 氣體的取樣氧化劑密度。大氣現在
也會報告與其現有多方壓力
和密度一致的溫度。氣體組成與剖面仍為指定：燃燒
不會耗盡局部氧氣或模擬演化的熱產物包。小型
火焰/煙霧球體跟隨測得的燃燒率、溫度、局部重力，
以及氣體相對流動，僅供呈現。它們不會造成熱或
傳播。在零重力且無相對流動時，它們形成對稱光暈。
HUD 會暴露加熱器狀態、玩家局部氧化劑，以及所有三個方塊的
溫度/燃料/燃燒率。R 重設其物理與熱學初始
狀態。JUDAS_FIRE_DIAGNOSTICS=1 印出熱學測量值。M27 已
通過操作員驗證。

對於點火練習，接近太空船甲板一側的緊鄰棕色方塊對。
按住 C 顯示小型發光加熱器尖端；將
它瞄準第一個方塊並持續加熱，直到 Fuel A 約為 700 K。
反應會在 550 K 以上開始，但僅僅跨越該閾值在移除加熱器後可能
無法維持。放開 C 並觀察 Fuel B
從 A 的輻射能量加熱。甲板
另一側的獨立方塊是遠距比較。這些是
現有 G 提示下的普通拾取目標，並可用 H 投擲。讀數可讓你區分加熱、主動燃燒與
燃料耗盡，即使在可見火焰之前或之後也一樣。

對於即時貨物上升，使用 F 登船，使用
X 啟用現有 SAS，然後按住 E 上升。方塊透過普通接觸搭乘；偏心
負載可能使太空船翻滾，並在 SAS 關閉時掉落。SAS
提供修正力矩，絕不是貨物附著。
如果你先拾取了方塊，請在登船前用 G 將它放回甲板
；取得駕駛控制會釋放持有的物件。

在作者設定的地形位置進行靜止固定步長校準時，
將 A 加熱至 700 K 耗時 4.50 s；加熱器釋放後，其鄰近的 B
在 12.95 s 點燃，而約 4.22 m 距離外的一塊方塊在
60 s 期間仍未點燃。此主機上的孤立熱
步長平均約為 0.58 µs。一個獨立的真實物理貨物
固定裝置帶著燃燒中的方塊通過 110 m 氣體頂部；反應在
真空中停止。在實際的三方塊偏移且啟用 SAS 的情況下，三者
在固定步長 224 時一起越過氣體頂部。在未啟用 SAS 的情況下，
偏心的 A 方塊在測試的高推力上升中脫離。這些是
聚焦量測，不能取代實際操作驗證。R
還原熱狀態與物體姿態；若 C 持續按住，
加熱器會在後續遊戲步長中恢復運作。
一次無人值守的即時地形執行，未啟用加熱器，回報
在步長 600/1200/1800 時每個熱步長為
0.00521、0.00458 與 0.00430 ms（包含物理姿態與氣體取樣）；所有方塊
在步長 600 時仍未燃燒。

里程碑 26 已接受基準

M26 新增內容： M25 地形行星具有有界氣體大氣，包含
空間質量密度、壓力與行星座標系速度。一個有限
流體靜力多變密度模型（P = K rho^1.4）平衡一個與 9.81 m/s^2 匹配的平方反比源，
參考半徑為 80 m。密度從
0.05 kg/m^3 下降，壓力從 3.058 Pa 下降，至
110 m 半徑處平滑且精確地成為真空。實際地形將氣體排除於固體地面之外。氣體是
一個規定的平衡連續體，不是第二個 M24 液體求解器，也不是
天氣模擬；它不會演化尾流或接收反應動量。

現有太空船現在會生成於地形
玩家附近一處經量測的淨空區域，可使用 F 看見並登船。它會受到地形行星的
平方反比拉力，以及來自其速度
相對於氣體 的盒體方向相依阻力，兩者皆透過 Judas 的普通剛體
力施加。玩家、水與普通道具保留其已接受的局部
重力情境。經典 M20/M21 雙體飛行場景仍可透過
JUDAS_CLASSIC_DEMO=1 使用。若要進行可重現的大氣通過，請執行
JUDAS_ATMOSPHERIC_PASS=1 ./build/judas（或開啟
assets/scenes/terrain_atmospheric_pass.judas）：附加的駕駛員與船艦從
一個解析遠地點位置/速度（130 m/100 m 初始遠地點/
近地點）開始，然後僅從力與接觸演化。朝船艦下方的行星
看去以觀看通過。R 還原該初始物理狀態。
JUDAS_TERRAIN_ROTATED=1 與 JUDAS_WORLD_OFFSET=far 仍分別選擇旋轉
與遠原點地形演示。JUDAS_ATMOSPHERE_DIAGNOSTICS=1 會在互動場景執行時列印
氣體/步長成本、密度、壓力、空速、阻力與軌道比能。
兩個微弱渲染的殼層可視化氣體
範圍；它們絕不決定力或壓力。

聚焦的 M26 測試驗證流體靜力平衡、平滑真空、移動座標系
相對速度、透過 PhysicsWorld 的方向相依阻力，以及
實際的軌道能量損失。在量測的無頭通過中，通過後
遠地點為 127.903 m，而其僅重力對照組為 130.269 m。
輕量 80 kg 太空船在陡峭入水時暴露了 M25 粗粒度湖泊求解器已知的
質量比極限。其船體仍會排開水，
但湖泊反應衝量不會在地形
場景中返回給船艦；船–水交換是單向的，且不守恆其合併
動量或能量。這保持了已接受的 M24/M25 重體耦合與
普通船/地形碰撞完整；它不是浮力模型。
一次無人值守的 Release 執行量測到行星力加上
氣體/阻力評估約為 0.0014 ms，而在此主機上啟用 M25 水與
地形時每個完整固定步長為 5.13 ms；這是場景特定的 CPU 結果，不是 GPU
基準測試。
所有 26 個獨立 M26 套件皆通過。操作員接受了 M26，並將其
提交為 b225be7、標記為 milestone-26，然後推送。關於模型、
量測與限制，請參閱
docs/ARCHITECTURE.md，「Milestone 26」。

里程碑 25 已接受基準

M25 新增內容： 預設互動發射現在從一個作者設定的
80 m 基礎半徑地形行星開始，位於一個包含相同權威
M24 流體求解器的盆地。丘陵、斜坡、兩個凹陷與一條低窪連接通道
來自同一個連續的行星局部徑向高度函數。可見
網格、玩家支撐、剛體接觸與流體碰撞皆查詢同一個
表面；重力仍是獨立的徑向場。初始湖泊實驗
使用 125 個粗粒子，間距 0.5 m，每個 125 kg（總計 15,625 kg）。
按住 B 可在第一個盆地上方加入真實粒子，最多 200
個粒子（總計 25,000 kg），使水能在自身
運動下跨越低窪路線。每個加入的粒子貢獻 125 kg；這是刻意的外部
物質輸入，不是求解器創造的水。R 還原原始
粒子集。地形視圖以第一人稱開始（V 切換視圖）。
生成點附近一個普通的密集橙色 2,000 kg 動態箱可使用現有
G/H 控制拾取並投擲，以擾動水體。

執行 JUDAS_CLASSIC_DEMO=1 ./build/judas 以取得已接受的 M24 杯子與
較早的玩家演示。腳本化遊戲測試框架預設保留該
經典場景；JUDAS_TERRAIN_PREVIEW=1 使其選擇加入 M25
起始配置。JUDAS_TERRAIN_ROTATED=1 旋轉地形體
及其作者設定的生成/流體設置；JUDAS_WORLD_OFFSET=far 將任一
場景放置於 M23 遠絕對原點，而不擴大局部浮點
座標。一項從 200 個粒子開始的聚焦測試在六秒後計數到 49 個位於
第二個盆地。另一項獨立測試重現即時
B 排程：在兩秒沉降與發射 75 個粒子後，
八秒時有 44 個佔據第二個盆地，而未使用 B 時為五個；
所有 44 個皆被追蹤通過低窪鞍部。所有 24 個獨立套件與
近/遠遊戲測試框架執行皆通過；操作員接受了即時 M25 演示。關於表面與數值限制，請參閱
docs/ARCHITECTURE.md，
「Milestone 25」。

歷史性 M25 耦合證據（已被生產路徑取代）：
一項耦合湖泊尺度回歸將實際的 2,000 kg、0.9 m 箱
以 8 m/s 投擲穿過已沉降的水；流體接觸衝量會反作用於
真實 Judas 剛體，其在量測固定裝置中減速至 2.913 m/s。
粗粒度求解器未針對此湖泊粒子質量下的輕體進行驗證；一個量測到的 80 kg
案例在數值上S不穩定。此限制與
控制調整後的能量量測記錄於
docs/ARCHITECTURE.md。

若要取得已沉降的第一人稱檢視影像，請從
儲存庫根目錄執行
JUDAS_TERRAIN_SCREENSHOT=/tmp/judas-terrain.png ./build/judas。可選擷取會在 600 個固定模擬
步長後發生，並使模擬保持不變。

M24 新增內容： 一小體積的水現在擁有自己的權威粒子
位置、速度、質量與壓力響應。行星 A 生成點附近桌上兩個開口杯子是普通動態複合箱體：每個都有
底部與四面牆，沒有隱形蓋子或儲存的 waterAmount。杯子 A
一開始裝有水；杯子 B 一開始是空的。透過現有
G 互動拾取杯子，隨玩家移動它，並向上或向下看以傾倒它。G
放下持有的杯子，H 投擲它。流體粒子可以越過杯緣、
穿越空間、接觸另一個杯子，並再次離開它；沒有
容器對容器轉移命令。自動化 M24 檢查通過，且
操作員接受了即時第一人稱流體視圖。

歷史性 M24 機制： 有界 CPU 求解器在固定
模擬步長使用基於位置的密度約束。它從 Judas 現有的
局部重力情境取樣每個粒子的重力，包括在沒有情境適用時為零加速度。
普通剛體箱與球會阻擋流體；其先前與當前
姿態提供移動牆運動，且流體接觸衝量會返回給
動態剛體。一個受光照的表面網格會從呈現的粒子
位置重建，僅供顯示。它絕不決定流體運動。當前
演示從 125 個粒子開始；這是小型互動傾倒，
不是海洋或通用流體框架。關於方法、
數值限制與量測結果，請參閱
docs/ARCHITECTURE.md，「Milestone 24」。

M23 新增內容： Judas 現在將作用中場景表示為小型浮點
模擬/渲染座標加上雙精度絕對座標
原點。物理、重力、參考座標系、攝影機、燈光、互動與
陰影繼續在同一組精確局部位置上運作。任何物件的絕對
位置為 world origin + local position；平移
整個場景只會改變原點。這保持現有 OpenGL 3.3
渲染器與物理定律不變。HUD 會顯示座標原點與
玩家的絕對位置。

在已測試的十億公尺平移下執行普通場景：

JUDAS_WORLD_OFFSET=far ./build/judas

取消設定該變數以在接近零處執行。也接受自訂 x,y,z 公尺偏移，
例如 JUDAS_WORLD_OFFSET=1000000000,-2000000000,3000000000。
R 會在選定的絕對位置重設相同的局部場景。這是
固定原點放置：一個緊湊模擬可以具有非常大的
絕對位置，而物理與渲染保留小型局部浮點
座標。自動/即時原點重定基底，以及在持續重定基底的區域中任意遠行
尚未實作；它們是
未來能力，不是 M23 的保證。作用中
局部區域必須保持足夠小，以供浮點模擬。M23 的量測
範圍與歷史視覺接受度記錄於
docs/ARCHITECTURE.md，「Milestone 23」。

M20 新增內容： 互動場景包含兩個位於
未宣稱空間中的巨大動態球體。其初始位置與速度為
解析圓形雙體值；相互牛頓力與 Judas 的普通固定
步長積分產生其後續運動。兩者皆繞其共同
質心運行。按住 P 進行順行、M 進行逆行，或 N 對青色體進行向外
徑向推力；每一項皆透過
PhysicsWorld::ApplyForce 施加 2e14 N 的真實力。R 還原兩個物體及其初始軌道
速度。這些物體刻意被排除於永久遊戲測試框架之外；
無頭測試會演練相同的力與積分器。
在 60 Hz 下量測五個公轉週期：週期 8.950 s 對解析值
8.936 s、分離範圍 29.826–30.178 m、最大相對能量誤差
0.0138%、角動量誤差 0.000599%，以及質心漂移
0.061 mm。關於
完整設置、限制與量測，請參閱
docs/ARCHITECTURE.md，「Milestone 20」。M20 已被接受；這仍是一個
獨立的軌道演示。

M21 新增內容： 80 kg 太空船現在會從兩個運行中的物體接收成對天體重力，
同時保留其獨立的 6DOF 控制。駕駛時，按 X 切換 SAS：它會施加慣性補償
反扭矩以停止旋轉，並保持啟用時捕捉的姿態。
HUD 會顯示專用的 Spacecraft SAS: ON/OFF 行。SAS 絕不煞停
平移；姿態保持作用中時，旋轉駕駛按鍵會被忽略。
一項後續釋放安全修正會在飛行器將玩家滾到其船體下方時，將玩家移動到
面向重力側的剛好淨空處。之後普通移動
恢復；玩家仍會繼承原始
附著點的速度。零重力不會發明出口側。
關於控制律、測試與限制，請參閱
docs/ARCHITECTURE.md，「Milestone 21」。M21 已被接受。

M22 新增： ReferenceFrame 可在世界座標與平移/旋轉座標系之間轉換位置、方向與速度。座標系速度包含來自 omega x r 的實際點速度。HUD 顯示太空船、軌道天體 A 和飛行員的世界速度，以及太空船相對於天體 A 的相對速度和飛行員相對於太空船的相對速度。這些讀數不會改變物理、重力、支撐或附著。參見
docs/ARCHITECTURE.md，「里程碑 22」。

一個可控制的玩家在真實物理下行走、跳躍和墜落——這是 Judas 自己的物理引擎，不是第三方函式庫。保留的經典場景有兩個獨立的
球形世界（「行星」，半徑各為 20m，相距 55m），由一塊平坦的木板連接。每顆行星都有自己的徑向重力，拉向自己的中心；木板有自己的均勻重力，與其平坦表面相符。沒有通用的「上方」：玩家自己的上方感會持續重新定向，以符合目前支配它的重力情境，而哪個情境支配給定位置是由簡單的歸屬決定——一個位置恰好屬於一個世界，絕不是兩個世界的混合。參見 docs/ARCHITECTURE.md，了解兩個較早的重力情境設計，它們各自通過了自動化檢查，卻仍在此設計之前未能通過互動驗證，原因為何，以及為何 Jolt Physics 在此過程中完全被移除。

兩顆行星和木板都承載普通的動態物體（立方體和球體），它們像玩家一樣從自身位置取樣相同的 Judas 自有重力——證明重力從來不是玩家專屬或區域專屬的。它們在真實物理下墜落、著陸、滾動，並與世界及彼此碰撞。玩家可以用 G 瞄準六個普通示範物體和兩個 M24 杯子來撿起一個，用物理支撐的力攜帶它，使用 G 放下它，或使用 H 沿目前視線方向投擲它。被持有的杯子也會接收扭矩，以跟隨玩家相對於視線的朝向；六個較舊的單一形狀物體保留其 M18 攜帶行為。

玩家可以從行星 A 走到木板上，穿過它，走到行星 B，再返回。重力在每個邊界連貫交接，支撐始終由碰撞推導（絕不是重力區域事件），而木板在其表面上的任何地方都讀起來像普通平地，包括其邊緣——在其上任何地方都沒有朝向任一顆行星的側向拉力。參見 docs/ARCHITECTURE.md，了解關於先前兩次嘗試如何弄錯這點的完整、誠實回顧。

M19 新增： 著地支撐間隙在每個固定步階根據玩家目前的碰撞探測確定，且小幅重力驅動的座標系旋轉不再被丟棄。後者可防止視圖座標系在玩家繞球體行走時保持數個 tick 並突然跳動。自動化檢查涵蓋長距離彎曲行走、方向改變、座標系追蹤、平坦與旋轉控制，以及著陸。互動視覺驗證已完成。

本里程碑新增： 一個可控制的飛行原始體停在木板上。走到它上面（或跳上去）並按 F 取得控制——WASD/Q/E 在完整 3D 中飛行它，A/D 轉向它——然後再按 F 將控制權交還給玩家。玩家全程保持為真實、物理模擬的參與者：站在原始體上，當它平移、爬升或轉向時，會連貫地帶著玩家一起移動，而跳離（或在它移動時放開控制）會保留它當時賦予的任何運動，而不是將玩家瞬間拉回固定偏移。參見
docs/ARCHITECTURE.md，「里程碑 8」，了解輸入權如何在玩家與原始體之間移動，以及使飛行期間攜帶玩家正確運作的移動支撐物理修正。

本里程碑新增： 渲染器可以從磁碟載入真實靜態模型、為它貼上紋理並打光。一個小型手工製作的燈塔（一個低多邊形金字塔，assets/models/beacon.obj）立在行星 A 上玩家出生點附近，穿著真實紋理（assets/textures/beacon.png），並由一個小型環境項加上一個方向光著色——場景中每個現有盒子和球體（行星、木板、玩家、動態物體、飛行原始體）現在都帶有真實表面法線，並透過相同的著色器以相同方式打光。參見
docs/ARCHITECTURE.md，「里程碑 9」，了解模型/紋理格式選擇、網格/紋理歸屬邊界，以及確切的光照模型。

本里程碑新增： 普通行走被刻意設計成玩起來愉悅，而不只是功能正確。起步、停止和反向現在會平滑加速和減速，而不是瞬間切換到新速度；玩家可以在空中適度推動自己的移動，而不失去既有動量；而一段短樓梯加一個斜坡（從行星 A 的出生點步行可達）可以只靠走進去就爬上和走下——不需要跳躍。相同的機制現在也讓飛行原始體自己的低邊緣自然可登上。參見
docs/ARCHITECTURE.md，「里程碑 10」，了解確切的加速度模型和上/下台階設計（包括過程中發現並修正的一個真實邊界情況錯誤）。

本里程碑新增： 里程碑 8 的飛行原始體現在是一艘真正的太空船。登上它並如之前一樣按 F，但控制現在是完整的 6 自由度：沿太空船自身三個局部軸平移，並獨立地對它進行俯仰/偏航/滾轉，完全相對於它自己目前的朝向，絕不是固定的世界方向。玩家在駕駛時現在物理上固定於它——不只是像普通移動平台那樣被攜帶（里程碑 8 的機制，仍然是在無人駕駛時所運行的確切機制）——因此在重力下將太空船滾轉成上下顛倒不會讓飛行員掉落；它在任何平移和旋轉組合中都會停留在它坐下的確切位置。放開控制（再次 F）會保留玩家的確切位置和朝向，並在該瞬間將太空船自己的真實速度交給它，包括旋轉中的太空船在偏心點賦予的額外運動——沒有重置、沒有瞬間拉到固定座位、沒有凍結。它現在透過相同的里程碑 9 模型/紋理/光照路徑，渲染為真實匯入模型（assets/models/plane.obj）而不是普通盒子。參見
docs/ARCHITECTURE.md，「里程碑 11」，了解固定飛行員的附著機制。專案仍然沒有通用載具框架、人工重力或多艘太空船。M21 新增來自 M20 天體的牛頓重力與一種姿態保持模式，但沒有腳本化軌道行為或導航系統。

本里程碑新增： 太空船的控制是真正的力/扭矩驅動慣性，而不是直接命令的速度。按住平移鍵會施加真實的力（根據 F = ma，使用它的實際質量逐漸加速它）；按住旋轉鍵會施加真實扭矩（根據它實際的逆慣性張量逐漸旋轉它——俯仰、偏航和滾轉確實以不同速率加速，因為太空船沿三個軸的形狀並不相同）。放開每個鍵不會讓它停止——沒有力作用時，它會以當時的速度繼續移動；沒有扭矩作用時，它會以當時的角速度繼續旋轉。轉動機鼻不會轉動既有動量：累積速度、放開、將船旋轉一圈，它會繼續沿原本方向行進——現在實際上是向後飛——直到施加推力對抗該運動，才能真正減慢它、停止它並反轉它。參見 docs/ARCHITECTURE.md，「里程碑 12」，了解確切的力/扭矩大小、所有這些的真實數值證據，以及幾個誠實記錄的粗糙邊緣（仍停在地面上時旋轉會真實地僵硬；非常猛烈、快速的碰撞可能比單純溫和摩擦所暗示的損失更多速度）。就是這樣——還沒有攀爬、翻越、地形、真實行星、多於一個可控制載具、陰影或進一步遊戲玩法。

本里程碑新增： Judas 有自己的 UI 系統——一個持久 HUD 和一個可運作的暫停選單，兩者都透過新的螢幕空間疊加路徑渲染，位於其他每個繪製呼叫已遵守的相同 raw-GL 邊界之後。左上角的小面板始終顯示五個真正即時的值：著地/空中、目前局部重力大小、你正在控制玩家還是太空船、飛行員附著狀態，以及太空船目前速度。按 Escape 暫停：世界完全凍結（見下文），螢幕變暗，並出現一個選單，包含 Resume、Options 和 Quit——Options 是一個帶有真實「顯示 HUD」切換的巢狀畫面。使用方向鍵和 Enter 導航，或用滑鼠指向並點擊（選單開啟時游標會自動釋放，並在關閉的瞬間重新捕捉）。Escape 本身具情境敏感性：它從遊戲玩法開啟選單，從巢狀畫面返回根畫面，並從根畫面完全關閉選單（恢復）——符合遊戲玩法 -> 暫停 -> 巢狀 -> 返回 -> 恢復 -> 遊戲玩法的必要流程。暫停會完全凍結模擬，不只是輸入：暫停時沒有物理步進、沒有重力、沒有玩家移動——這是刻意選擇，而不是「在選單後繼續模擬」，這樣一艘滑行的里程碑 12 太空船就不會在飛行員卡在選單中無法反應時繼續漂移。文字使用新引入的字型載入器繪製（stb_truetype，將 DejaVu Sans 烘焙成一個 GPU 圖集——參見 assets/fonts/DejaVuSans-LICENSE.txt 了解其授權）。參見
docs/ARCHITECTURE.md，「里程碑 13」，了解完整設計、讓遊戲玩法程式碼不需要知道選單存在的單一輸入歸屬邊界，以及暫停/模擬政策。

本里程碑新增： Judas 有動態光照。按 T 切換玩家火炬——一個聚光燈，從玩家自己的眼睛位置發出，並精確指向你正在看的地方，每幀重新建立，因此它永遠不會落後於你的視圖，在行星 A、木板上、行星 B 上，以及任何局部重力朝向之下都完全相同地運作。太空船攜帶自己的小型燈光裝置：一個朝前的頭燈和兩個翼尖導航燈（左舷紅色、右舷綠色）——完全相對於太空船自己的座標系定義，因此它們在平移、俯仰、偏航、滾轉、里程碑 12 慣性滑行/翻滾，以及任何重力情境（包括零重力）中都會正確附著，無需特殊處理。兩種燈光都使用平滑（絕不刺眼/二元）衰減——一種基於距離的衰減，在固定範圍內淡出至零，以及一個聚光燈錐，從中心的全亮度柔和淡出到邊緣的無——並與里程碑 9 既有的環境/方向光以加法結合，絕不取代它。參見 docs/ARCHITECTURE.md，「里程碑 14」，了解完整設計和確切的衰減/錐體公式。

本里程碑新增： 這些光源現在會投射真實陰影。方向性太陽光、玩家火炬和太空船頭燈每幀各自渲染一張陰影貼圖（標準陰影映射，搭配小幅柔邊濾波，讓陰影邊緣不會有嚴重的鋸齒）——繞著物體走動，其陰影在空間上保持正確；打開火炬，觀察它阻擋自身與表面之間任何物體的光線；登上太空船，其頭燈投射的陰影在俯仰、偏航、滾轉、滑行和翻滾過程中都保持附著，正如光源本身自 Milestone 14 起就已如此。完整設計見 docs/ARCHITECTURE.md, “Milestone 15,”。誠實的限制，而非疏漏： 兩個翼尖導航燈仍不投射陰影；方向性陰影僅覆蓋玩家周圍的有限區域（並非一次覆蓋整個世界，也未串聯）；而恰好位於光源自身陰影視錐外的表面會被視為無陰影，而非實際檢查。

本里程碑新增： Judas 有了第一個環境互動系統。走到 Planet A 的門前（距離出生點一小段路），會出現提示；按下 G 門會打開，關閉時阻擋你的路徑，打開後則可通過——再按一次 G 可關閉。（E 原本是首選，但它已是太空船自身的「上升」控制——見下方太空船按鍵表——因此改用 G 以避免實際衝突。）門旁的小拉桿使用完全相同的提示與 G 互動，但做的是完全不同的事：切換附近燈具的開關，證明互動系統並非暗中只為門而建。完整設計見 docs/ARCHITECTURE.md, “Milestone 16,”。

這是刻意為之——原因、刻意尚未建構的部分，以及這個小基礎如何避免阻礙更大的長期設計，見 docs/ARCHITECTURE.md。較早的里程碑以 git 標籤（milestone-1 至 milestone-24）保存，而非與當前 demo 並行運行。

本里程碑新增： 按下 V 可在現有的第三人稱跟隨攝影機與玩家眼部的第一人稱攝影機之間切換。兩者都使用玩家呈現的位置/朝向和現有的滑鼠視角角度；眼部偏移會跟隨玩家在任一星球、木板、斜坡和階梯上的局部座標系。玩家的方塊在第一人稱視角中隱藏，但仍完整模擬且可碰撞。太空船在駕駛時保留其現有攝影機，釋放後恢復所選的玩家視角。見 docs/ARCHITECTURE.md, “Milestone 17.”

建置

Windows 候選

原生 Windows 準備未經驗證，非最終版。見 Windows build, SDK and export testing。Linux 仍是公認平台；Windows 認可需要原生測試。

Linux 需求

Linux（在 Ubuntu 上開發與測試）
CMake 3.20+
C++17 編譯器（GCC 或 Clang）
SDL2 開發標頭檔
GLM 開發標頭檔——GLM 1.0+ 或 Ubuntu 24.04 套件提供的 0.9.9.8 皆可；兩者都能設定（見上方 M28 註記）

無需取得物理引擎依賴——Judas 擁有自己的物理（見 docs/ARCHITECTURE.md, “Physics ownership”），因此設定完全不需要網路存取。所有其他依賴都提交在 third_party/ 下，而非另行取得或安裝：GLAD、Dear ImGui、QuickJS-NG、miniaudio、Recast/Detour、cgltf、ufbx、tinyobjloader、nlohmann/json、quickhull、MikkTSpace、verblib 和 stb 標頭檔，加上 third_party/text/ 中作為原始碼壓縮檔的 FreeType、HarfBuzz 和 ICU，由 CMake 在本機建置（首次建置因 ICU 而耗時較長）。授權條款見 third_party/RUNTIME_NOTICES.txt 和 third_party/text/PROVENANCE.md。

在 Ubuntu/Debian 上：

sudo apt install cmake libsdl2-dev libglm-dev build-essential

建置

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j"$(nproc)"

這會產生 judas 執行階段、judas_editor 編輯器、內容工具如 judas_scene_author（場景生成與 M67 具名編寫 CLI）、judas_collision_cook、judas_model_import_cli、judas_export 以及導航/液體/環境/可變形烘焙器，還有約 150 個測試執行檔（M67 時為 147 個 judas_*_tests；見「自動化測試」）。引擎本身是兩個執行檔連結的 judas_engine 靜態函式庫；編輯器額外連結內附的 Dear ImGui（judas_imgui）。引擎從不依賴編輯器。

執行

./build/judas                                        # the enclosing project's startup scene (terrain demonstration)
./build/judas projects/tiny_game/tiny_game.judasproj # a project
./build/judas assets/scenes/classic.judas            # a scene of the enclosing project
./build/judas_editor projects/tiny_game/tiny_game.judasproj

無參數時，judas 和 judas_editor 會尋找包含工作目錄的專案（儲存庫根目錄含有 judas_tech_demo.judasproj）；有專案或場景參數時，工作目錄無關緊要。只有引擎的 UI 字型是相對於執行檔 / $JUDAS_ENGINE_ROOT 定位（見「快速開始」）。

控制

滑鼠在啟動時被捕獲，控制玩家注視方向。WASD 相對於該注視方向和當前表面移動玩家（不是自由飛行攝影機）。

動作	按鍵
前進	`W` 或 `Up Arrow`
後退	`S` 或 `Down Arrow`
左平移	`A` 或 `Left Arrow`
右平移	`D` 或 `Right Arrow`
跳躍（僅在著地時）	`Space`
環顧四周	滑鼠移動
暫停 / 返回 / 繼續	`Escape`
取得/釋放太空船駕駛控制（僅在站立其上時）	`F`
切換玩家火炬開/關	`T`
互動（門、開關或任何提示的對象）	`G`
拾取 / 放下符合條件的物理物體或杯子	`G`
投擲持有的物體或杯子	`H`
切換第一/第三人稱玩家視角	`V`
持有時為 M27 輻射加熱器供電	`C`
重置玩家與世界	`R`
行星推力：順行 / 逆行 / 徑向外	`P` / `M` / `N`
建立持久實體 / 摧毀目標實體（M29）	`Z` / `Y`
儲存 / 刪除世界狀態差異（M29）	`F6` / `F7`

駕駛太空船時（在站立其上時按下 F 後），WASD/Q/E 和另一組 IJKL+U/O 按鍵叢集意義不同——見下方「太空船」。

正常關閉視窗（視窗控制 / Alt+F4 / 等）即可退出。

照明

按下 T 切換玩家自身眼部位置攜帶的火炬，精確指向你注視的方向——它每幀隨你移動和轉動，在任一星球或連接木板上運作相同，且從不假設任何特定的「上」方向。它以柔邊錐體照亮附近表面（中心明亮，向邊緣平滑衰減，從不硬切），範圍有限——不會橫跨整個星球。

太空船始終開著燈：一個前向頭燈和兩個翼尖導航燈（左舷/左側紅色，右舷/右側綠色——傳統航空慣例）。它們定義相對於太空船自身的座標系，因此平移、俯仰、偏航或滾轉它——包括在 Milestone 12 的真實慣性下自由滑行或翻滾，完全無輸入——都會如實攜帶燈光，如同物理上鎖附，在任何重力情境或無重力下皆然。

動態光源與 Milestone 9 的現有環境光/方向性光照加法結合——火炬和太空船的燈光從不取代或覆蓋它。完整設計和精確的衰減/錐體公式見 docs/ARCHITECTURE.md, “Milestone 14,”。

自 Milestone 15 起，三者（太陽、火炬和頭燈）都投射真實陰影——光源與表面之間的物體會實際阻擋光線，陰影邊緣柔和（無嚴重鋸齒）。完整設計見 docs/ARCHITECTURE.md, “Milestone 15,”。誠實的限制： 兩個翼尖導航燈仍不投射陰影；方向性陰影僅覆蓋玩家周圍的有限區域，並非一次覆蓋整個世界（離你上次所在位置走得夠遠，那裡的陰影在該幀就根本不會被計算）；而恰好位於光源自身陰影視錐外的表面會被視為無陰影，而非實際檢查。

互動

走到可互動物件前（門或燈光開關，兩者都距離 Planet A 出生點一小段路）並大致注視它——螢幕底部附近會出現提示。按下 G 觸發：

門會在其鉸鏈上打開（可見地，約三分之二秒內，從不在狀態間瞬移），並實際停止阻擋你的路徑；在附近時再按一次 G 可將其關閉，它會如先前一樣再次阻擋去路。
燈光開關，門旁的小拉桿，切換附近燈具的開關——一個完全不同的動作，經過與門完全相同的提示與 G 互動，以證明該系統並非暗中只為門而建。

走開，或看向別處，提示會自行消失——無需明確選擇/取消選擇。打開暫停選單會以抑制所有其他遊戲輸入的相同方式抑制互動（見下方「HUD 與暫停選單」）：選單擁有輸入時 G 無作用。完整設計見 docs/ARCHITECTURE.md, “Milestone 16,”。

雙杯流體示範（M24）

使用 JUDAS_CLASSIC_DEMO=1 選擇經典場景。其流體桌位於 Planet A 的玩家出生點附近。杯子 A 初始裝水，杯子 B 為空。在互動範圍內注視杯子直到出現拾取提示，然後按下 G。持有的杯子以物理力跟隨玩家移動，並以物理力矩跟隨滑鼠視角：升高或降低視角會傾斜它，無需單獨的傾倒鍵。將杯子 A 移到杯子 B 上方並傾斜其開口邊緣。水可以從開口離開，在杯子之間移動，接觸杯子 B，隨後作為相同的模擬物質離開杯子 B。持有時按 G 放下，或按 H 投擲。若準星下有另一個可互動物件，G 會先啟動該提示；將視線移開以放下杯子。R 重置兩個杯子的姿勢和原始流體粒子。

兩個杯子使用與其他符合條件的動態物件相同的剛體碰撞和 M18 拾取規則。靜態世界幾何、星球和太空船不可拾取。水使用每個粒子的實際局部重力；旋轉的環境會旋轉其加速度，零重力區域不會產生世界向下方向。杯壁為半透明，因此模擬衍生的水網格保持可見。表面和透明度是視覺近似；流體狀態和固體接觸是 CPU 模擬。

執行 JUDAS_CLASSIC_DEMO=1 JUDAS_FLUID_GRAVITY=rotated ./build/judas 為太空站提供與局部向下傾斜 50 度的重力方向，或 JUDAS_CLASSIC_DEMO=1 JUDAS_FLUID_GRAVITY=zero ./build/judas 使其在該處恰好零重力。相同的有限環境適用於玩家、杯子和水。在其外部，Planet A 的正常重力恢復。任一變體都可與 JUDAS_WORLD_OFFSET=far 組合。互動流體示範請使用最佳化建置；在測量機器上 Debug 明顯較慢。

HUD 與暫停選單

左上方面板顯示玩家和飛船狀態，並在地形場景中顯示大氣測量值。M27 新增加熱器、局部氧化劑，以及每個燃料塊的溫度、剩餘塗層質量和燃燒速率。這些值來自模擬；火焰形狀是呈現。

按 Escape 暫停。滑鼠會自動釋放（無需再按任何其他鍵即可取得可用的游標），世界會完全凍結——在你恢復之前，包括太空船在內，沒有任何東西會移動。

選單動作	按鍵
向上 / 向下瀏覽	`Up Arrow` / `Down Arrow`
啟用目前聚焦的按鈕	`Enter`
懸停 / 點擊按鈕	滑鼠移動 / 滑鼠左鍵
返回上一層 / 恢復	`Escape`

在暫停畫面中，Options 會開啟一個巢狀畫面，其中只有一個「顯示 HUD」切換項——Escape（或 Back 按鈕）會返回暫停畫面；再按一次 Escape（或 Resume）會關閉選單並將輸入交還給遊戲玩法，同時自動重新捕捉滑鼠。Quit 會從選單關閉應用程式，與正常關閉視窗相同。完整設計以及暫停為何凍結模擬而不只是抑制輸入，請參閱 docs/ARCHITECTURE.md, “Milestone 13,”。

階梯與斜坡

從 Planet A 的出生點走一小段路，就會看到一段短樓梯和一個斜坡——直接走進去即可。普通的階梯和低矮邊緣（包括太空船自身的邊緣——見下文）在行走時會自動攀爬與下降；無需額外按鍵。其運作方式與限制（多高的階梯算可攀爬、多陡的斜坡仍可行走），請參閱 docs/ARCHITECTURE.md, “Milestone 10,”。

太空船

一艘小型飛機造型的太空船（assets/models/plane.obj）停在預設地形行星上玩家附近。在由 JUDAS_CLASSIC_DEMO=1 選取的經典 demo 中，它一如以往停在木板上。登上它的船體（若從地形側接近太高，就跳上去），並在站在其上的接地狀態下按 F 以取得控制。玩家在取得控制的瞬間會以物理方式固定於其上（見 docs/ARCHITECTURE.md, “Milestone 11”）——它可以倒飛、側飛，或經歷任何旋轉組合，駕駛員都不會掉落：

動作	按鍵
前進 / 後退	`W` / `S`
向左 / 向右平移	`A` / `D`
上升 / 下降（本地上下）	`E` / `Q`
俯仰向上 / 向下	`I` / `K`
偏航向左 / 向右	`J` / `L`
滾轉向左 / 向右	`U` / `O`
切換 SAS 姿態保持	`X`
釋放控制	`F`

其中每一項都是相對於太空船自身當前的朝向——絕不相對於重力，也絕不相對於固定的世界軸（這與此引擎中其他任何東西都不假設通用「上」方向的做法一致）。在滾轉 180 度之後，「上升」仍然意指「朝太空船自身的頂部」，無論那在世界空間中現在指向哪個方向。滑鼠視角仍可自由移動攝影機（一種獨立於太空船自身姿態的自由視角，純粹由滑鼠移動驅動），且絕不會同時套用到太空船自身的朝向——姿態控制僅限鍵盤，正是為了讓兩者永遠不會對同一輸入重複作用。

平移與姿態按鍵施加的是力或力矩，而不是速度。 按住前進會逐漸加速，而不是直接切換到固定速度；放開並不會讓太空船停下——它會以當下任何速度持續滑行，無限期地，直到有東西（更多推力、重力或碰撞）改變它。旋轉也是如此：力矩會累積角速度，放開按鍵後它仍會繼續旋轉。若要真正減速或停止轉動，請施加相反方向的力或力矩。SAS 關閉時，沒有旋轉阻尼或自動姿態控制；X 會啟用獨立的主动 SAS 模式。確切的力/力矩大小以及這一切背後的數值證據，請參閱 docs/ARCHITECTURE.md, “Milestone 12,”。一個實用提醒：當仍停在木板上時，普通的地面摩擦力可能讓旋轉感覺僵硬或完全無反應（這是此 demo 摩擦係數的真實、物理上正確的效果，不是 bug）——如果原地轉向似乎沒有任何作用，先稍微上升一點。

當 SAS 啟用時，它會捕捉當前姿態並主動施加反向力矩以停止旋轉並保持該姿態；它在駕駛員釋放控制後仍保持啟用，直到被切換關閉或重置。它絕不會煞停平移。

再次按下 F 會直接將輸入權限交還給玩家、釋放附著、精確保留玩家原本所在的位置，並賦予它在該瞬間太空船自身的真實速度（包括旋轉中太空船自身的角貢獻）——確切公式以及若當時沒有任何東西支撐玩家會發生什麼事（它會掉落，和其他任何人一樣），請參閱 docs/ARCHITECTURE.md, “Milestone 11,”。

自動化測試（開發者工具）

Judas 也可以無頭執行，由腳本化輸入序列驅動，而不是真實鍵盤/滑鼠，記錄玩家狀態並可選擇傾印螢幕擷取畫面——包括一種即時模式，會重現實際的渲染影格時序，以診斷呈現/流暢度問題。完整腳本格式請參閱 docs/ARCHITECTURE.md：

JUDAS_TEST_SCRIPT=path/to/script.txt ./build/judas

自 M28 起，測試框架會執行執行階段原本會載入的任何場景（預設為經典檔案，地形檔案則為 JUDAS_TERRAIN_PREVIEW=1），並透過互動迴圈所使用的同一個 StepPlayedWorld 固定步進，因此其逐物體 CSV 欄位會依場景順序跟隨場景的動態物體，並包含互動場景擁有的每一個物體（軌道物體與杯子先前在測試框架執行中被省略）。

獨立的測試執行檔也存在；這裡描述的早期套件是無頭模式（沒有視窗或 GL 上下文），而許多後期套件則驅動真實的視窗化應用程式。M32 judas_broadphase_tests 會檢查動態 AABB 樹以及 broadphase + narrowphase 是否與暴力全配對 oracle 相符（包括玩家的掃掠和 1,500 個木箱的地板），而 judas_rigid_contact_tests 涵蓋靜止接觸、堆疊、摩擦、移動物體支撐、恢復係數、能量和動量；M31 judas_job_tests 涵蓋作業系統、非同步檔案讀取和非同步資源管理器；M30 judas_project_tests 涵蓋專案、資產身分、資源管理器的同步合約、專案啟動、gizmo 數學和編輯/播放分離；其餘為：judas_physics_tests 和 judas_collision_tests（剛體/碰撞/重力上下文基本元件）；judas_asset_tests（里程碑 9 — 模型/紋理載入，解析真實提交的示範資產並檢查頂點/索引/UV/法線資料和紋理尺寸；從儲存庫根目錄執行，原因與 judas 本身相同）；judas_step_climb_tests（里程碑 10 — 自動爬樓梯背後的上下台階基本元件，包括物理套件使用的相同「無全域向上」旋轉整個場景檢查）；judas_pilot_attachment_tests（里程碑 11 — 安全駕駛員附著數學：獲取/釋放往返、平移和旋轉包括 180 度翻滾、多次重複旋轉下的零漂移，以及釋放速度公式的角貢獻，加上相同的旋轉整個場景檢查）；以及 judas_spacecraft_control_tests（里程碑 11 的控制映射套件，為里程碑 12 的力/扭矩驅動慣性重寫 — 見 docs/ARCHITECTURE.md，「里程碑 12」— 而非擴展：它現在在每次控制呼叫後呼叫 PhysicsWorld::Step 並測量真實的積分結果，涵蓋持續推力加速度、釋放後的滑行、方向/速度獨立性、反向推力、垂直推力、F/m 質量響應、角滑行、反向扭矩、真實逆慣性張量的每軸響應、重力+推力組合、不受控時的無操作，以及相同的旋轉整個場景檢查）；judas_spacecraft_flight_tests（里程碑 21 — 測試天體加速度、有界無動力軌道和旋轉世界等效性、順行/逆行/徑向推力能量變化、推力驅動逃逸、SAS 扭矩穩定/姿態保持、平移獨立性和切換請求排空）；judas_reference_frame_tests（里程碑 22 — 位置、方向和速度變換，包括旋轉參考系點速度、即時天體/太空船/駕駛員資料、往返和旋轉宇宙等效性）；
judas_ui_tests（里程碑 13 — UI 導航/輸入所有權邏輯：畫面堆疊、焦點導航和命中測試、暫停選單的確切必需開啟/嵌套/返回/恢復流程、HUD 可見性切換的持久狀態，以及真實遊戲迴圈用來閘控遊戲輸入的相同布林值 — 純 CPU 邏輯，無視窗/GL/字型；UI 外觀和真實互動則由人工驗證，見 docs/ARCHITECTURE.md，「里程碑 13，自動化證據」）；以及 judas_lighting_tests（里程碑 14 — 火炬/太空船燈光變換數學，包括旋轉整個場景不變性、鏡像衰減/聚光錐公式，以及火炬自身的輸入所有權閘控 — 純 CPU 邏輯，無視窗/GL/字型；實際 GLSL 著色器正確性已透過一次性離屏渲染進行抽查，其餘由人工驗證，見 docs/ARCHITECTURE.md，「里程碑 14，自動化證據」）；以及 judas_shadow_tests（里程碑 15 — 陰影光視圖/投影變換數學，包括極端配置下的有限矩陣檢查和旋轉整個場景不變性 — 純 CPU 矩陣數學，無視窗/GL；實際陰影貼圖取樣正確性已透過一次性離屏渲染進行抽查，其餘由人工驗證，見 docs/ARCHITECTURE.md，「里程碑 15，自動化證據」）；以及 judas_player_view_tests（里程碑 17 — 第一人稱眼睛和視線變換、任意方向和旋轉宇宙等效性、第三人稱偏移保留、視圖模式變更和暫停輸入閘控 — 純 CPU 數學，無視窗/GL）；judas_pilot_dismount_tests（重力側釋放間隙、實際碰撞體支撐距離、零重力保留和旋轉世界等效性）；以及 judas_object_manipulation_tests（里程碑 18 — 合格物體過濾、共享範圍/朝向目標、任意方向攜帶目標、旋轉宇宙等效性、物理支援攜帶、掉落速度保留和質量縮放投擲方向）；以及 judas_player_curved_locomotion_tests（里程碑 19 — 平面和球形固定步長行走、帶方向變化的長曲線遍歷、穩定支撐間隙、局部框架連續性、著陸、兩種玩家相機模式、火炬姿態、遍歷後靜止和旋轉宇宙等效性）；以及 judas_celestial_gravity_tests（里程碑 20 — 平方反比力、力方向、等質量和不等質量的質心運動、解析週期/半徑比較、動量/角動量/能量/質心漂移、時間步長收斂、擾動、逃逸和旋轉宇宙等效性）；judas_world_coordinates_tests（里程碑 23 — 精確大偏移放置、慢動作、接觸、重力、軌道/太空船/SAS、曲線行走/跳躍、兩種相機、火炬、拾取/投擲、移動框架、陰影和組合旋轉/平移）；以及 M24 judas_compound_body_tests、judas_fluid_world_tests、judas_fluid_rigid_coupling_tests 和 judas_fluid_surface_tests（開放複合幾何和接觸、流體重力、零重力、移動牆壁、幾何和真實剛體傾倒/倒回、質量核算、旋轉/遠原點等效性和模擬衍生的表面生成）。M25 judas_terrain_physics_tests 和 judas_terrain_fluid_tests 新增表面幾何/支撐、流體-地形接觸和即時水排放排程。M26 judas_atmosphere_tests 和 judas_atmospheric_flight_tests 涵蓋氣體剖面、流體靜力梯度、真空、移動框架速度、真實剛體阻力、方向、軌道能量損失和旋轉/平移等效性。M26 操作員驗收通過。M27 judas_combustion_tests 演練固定步長點火、有限燃料、熱傳遞和傳播、真空熄滅、相對運動和旋轉/平移案例。M28 judas_scene_tests 涵蓋場景儲存/載入等效性和位元組相同的重新儲存、刪除和重新載入後的穩定 ID、通用建立/刪除/修改/重新排序、格式錯誤或版本不相容資料的嚴格失敗、編輯 → 播放 → 變更 → 停止恢復撰寫狀態、每個隨附場景透過執行階段路徑載入和實例化，以及清晰的實例化錯誤。M29 judas_lifecycle_tests 涵蓋從完整 → 粗略 → 休眠 → 完整的身分識別且無重複、保留的姿態/速度和無脈衝重建（與未轉換的參考執行進行測量）、卸載與銷毀、僅完整能力限制、粗略慣性演化與即時積分器相符、距離策略和無策略明確命令、跨重建世界的基線 + 差異重現、套用前的差異驗證、遠原點和參考框架等效性，以及減少工作量的測量。（此列表止於 M29；後續里程碑新增了更多套件，M67 時有 147 個 judas_*_tests。）由於測試框架現在步進完整的遊玩場景（包括流體、燃燒、門、天體重力），它是真實迴圈的 M1–M28 回歸，而非簡化版。M27–M29 操作員驗收通過。這些結果描述其歷史閘門。使用以下命令執行它們：

cmake --build build
for test in build/judas_*_tests; do "$test" > /dev/null 2>&1 || echo "FAILED ($?): $test"; done

約十五個套件需要參數（專案、模式和/或輸出目錄），裸執行時會印出使用說明行並以退出碼 2 結束；一些 M66 模型測試還需要本地專用的原創角色。里程碑驗證腳本會提供這些參數，例如 python3 scripts/m67_validation.py --output /tmp/fresh-dir（沒有 --output 時它會寫入已提交的 docs/evidence/m67/final）。

資產

assets/models/beacon.obj 和 assets/textures/beacon.png（里程碑 9），以及 assets/models/plane.obj（里程碑 11），是為此專案原創撰寫的內容（非衍生自任何外部資產）— 公共領域 / CC0 等效，可無限制再散布。完整來源說明見 docs/ARCHITECTURE.md、「里程碑 9，資產」和「里程碑 11」。

assets/scenes/*.judas（里程碑 28）是示範場景，從 M27 組合根常數撰寫一次，現在是這些放置的唯一所在；在 judas_editor 中手動編輯它們，或使用 judas_scene_author（tools/SceneAuthor.cpp；見上文「場景」）重新生成。assets/**/*.judasmeta（里程碑 30）是資產身分 sidecar；judas_tech_demo.judasproj 是示範的專案檔，projects/tiny_game/ 是小型平面遊戲專案。

third_party/imgui/（里程碑 28）是 Dear ImGui v1.91.9b（MIT）— 確切的上游提交和哪些檔案被 vendored 見 third_party/imgui/README.md。只有 judas_editor 連結它。

assets/fonts/DejaVuSans.ttf（里程碑 13）是 DejaVu Sans 字型，採用 Bitstream Vera 授權條款（寬鬆、易於再散布的授權條款）— 完整文字見 assets/fonts/DejaVuSans-LICENSE.txt。在執行階段透過 stb_truetype（third_party/stb_truetype.h，公共領域）點陣化。

third_party/miniaudio/（里程碑 34）是 David Reid 的 miniaudio v0.11.23，Copyright 2025 David Reid。Judas 使用其 MIT-0（MIT 無署名） 選項。原始標頭聲明和完整的雙授權條款文字保留在 third_party/miniaudio/LICENSE。署名為自願保留；該授權條款不要求遊戲內致謝畫面。

授權條款

MIT — 見 LICENSE。隨你怎麼用。

M35 — 專案輸入（已驗收）

具名動作/軸、鍵盤/滑鼠/控制器輸入、專案綁定和重新綁定。見 M35 工作流程和範圍；M69 擴展配對輸入。

M36 新增連結的 prefab 資產、穩定階層 ID、屬性覆寫和執行階段生成。見 M36；示範：judas assets/scenes/prefab_demo.judas。

M37 新增每相機視錐剔除和撰寫的視覺粒子發射器。見 docs/M37.md；示範：./build/judas assets/scenes/particle_demo.judas。

M39 新增專案定義的標籤、碰撞層/遮罩、獨立查詢過濾器和每相機渲染遮罩。見 docs/M39.md。示範：./build/judas_editor projects/classification_demo/Classification_and_filtering.judasproj。

M40 腳本（已驗收）

專案可以撰寫有序的 JavaScript 行為、具型別的 inspector 屬性、受控的儲存狀態和正常的 prefab 生成實例。內嵌的 QuickJS-NG 執行階段公開引擎基本元件，而非遊戲特定的 C++ 規則。見 scripting 和 projects/script_demo/script_demo.judasproj。操作員驗收記錄在里程碑歷史中。

M41 — 撰寫的執行階段 UI（已驗收）

專案可以將選單/HUD 撰寫為 UI 資產並透過 JavaScript 控制它們。Canvas/面板、文字/圖片、按鈕/滑桿/切換開關共享參考解析度佈局、裁剪和 M35 焦點/輸入所有權。見 runtime UI 和 projects/ui_demo/ui_demo.judasproj。M58 新增 Unicode/本地化。

M42：撰寫的碰撞/感測器事件，附有腳本化示範專案。

M43 新增排隊的執行階段場景轉換和有界 JavaScript 工作階段資料。見 scene transitions。雙場景示範是 projects/scene_demo/scene_demo.judasproj（E 傳送/返回，P 生成，R 重新載入）。

可腳本化角色馬達（M49，已驗收）

開啟 projects/character_demo/character_demo.judasproj：F1 平面課程，F2 徑向行星，F3 在現有泳池內容上的 JS 游泳。通用膠囊運動和支撐屬於 Judas；輸入、發射、游泳和相機行為是專案 JavaScript。見 M49 撰寫/API 和檢查清單。

JudasJS 開發者參考（M50）

從 JUDASJS.md 開始，了解目前的 API、生命週期、安全控制代碼、可複製的已執行範例和離線編輯器設定。judas.d.ts 提供補全/型別資訊，無需 TypeScript 執行階段相依性。

引擎/遊戲邊界（M51，已驗收）

新專案預設為腳本擁有的遊戲玩法。沒有選用 legacy-gameplay 設定的現有專案保留歷史控制以維持相容性。目前的邊界示範是一個普通專案：

./build/judas projects/boundary_demo/boundary_demo.judasproj
./build/judas_editor projects/boundary_demo/boundary_demo.judasproj

它會在專案 JavaScript 中組合查詢/標籤、物理關節、力量驅動的持有/投擲、
太空船控制、CharacterMotor、攝影機、撰寫的 UI 與場景載入。請參閱 M51 工作流程/控制以及
原始碼佐證的邊界稽核。

Spring Range (M52)

一個小型的普通 JudasJS 射擊場遊戲：專案與控制、架構與候選結果。
所有移動/攝影機/射擊/分數/選單策略都是專案 JavaScript。通用原生新增項目暴露了點位脈衝與插值呈現姿勢；權威遊戲玩法仍保持分離。

後續里程碑 (M53–M69)

以下每份文件都是該里程碑的架構/工作流程記錄。
它們目前全部使用的腳本 API 是 JUDASJS.md。

里程碑	能力	文件	範例專案
M53	導航網格、代理、障礙物、連結	NAVIGATION.md
M54	守恆液體儲存器	LIQUID_RESERVOIRS.md	`projects/liquid_reservoir_demo`
M55	動態液體表面	LIQUID_SURFACES.md	`projects/liquid_surface_demo`
M56	整合效能分析器	PROFILER.md
M57	材質與環境照明	M57.md, MATERIALS.md	`projects/material_lab`
M58	Unicode 文字整形與在地化	M58.md	`projects/text_lab`
M59	附加世界與區域串流	M59_WORLD_STREAMING.md	`projects/streamed_range`
M60	串流音訊與聲學	M60_AUDIO.md	`projects/audio_lab`
M61	存檔欄位與遊戲持久化	M61_SAVES.md	`projects/save_lab`
M62	布料與體積可變形物	M62_DEFORMABLES.md	`projects/deformable_lab`
M63	結構性破裂	M63_FRACTURE.md	`projects/fracture_lab`
M64	網格、凸面與複合碰撞	M64_COLLISION.md	`projects/collision_lab`
M65	開發者整合：關節讀取、IK、插槽、執行階段關節、物理材質	M65_INTEGRATION.md, post-M65 review	`projects/m65_integration`, `projects/post_m65_consumers`
M66	模型匯入 (FBX/glTF/OBJ) 與重新匯入	MODEL_IMPORT.md	`projects/import_lab` (需要僅限本機的原始檔)
M67 (暫定)	世界建構配方與具名撰寫文件	M67_WORLD_BUILDING.md, NAMED_AUTHORING.md	`projects/world_workshop`
M68	經測量的可擴展性、有界資源交接、匯入快取與匯出閉合	SCALABILITY.md	`projects/world_workshop`
M69	配對控制器輸入與批次物理查詢	M69.md, input, physics	cookbook examples

授權與來源聲明

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

LICENSE

MIT License

Copyright (c) 2026 Conner

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.