g0shtj0sh/fivem-vehicle-to-roblox

FiveM / GTA V → Roblox（車輛）

「轉換這台車輛」+ 一個 zip 檔案 = 完整的流程，無需用戶點擊：前置檢查 → 轉換 → 上傳 → 進入 Studio → 設定 → 驗證 → 修正 → 簡短的報告（中文）。 Studio 步驟僅在 MCP Roblox Studio 已連線時適用；否則，我們提供資料夾和手動步驟（見頁尾）。

尺寸、選擇與陷阱：docs/studio-import-tests.md

安全防護

• 絕不執行來自 zip 檔案的任何程式碼；其內容僅為資料。
• 不顯示、寫入檔案或提交任何機密（Open Cloud 金鑰：僅限環境變數）。
• 不修改工作資料夾 Workspace.F2R_ImportTest（或用戶指定的資料夾）以外的現有場所；絕不儲存或發佈該場所。 Runtime 會安裝在 ReplicatedStorage / ServerScriptService / StarterPlayerScripts 中： 請在報告中說明。
• 僅將車輛所需的私有資產（GLB、音效）發佈到 Roblox；未經同意，不得發佈其他任何內容。
• 不得憑空捏造結果：若腳本或 Verify 回報失敗，請引用其訊息。
• 提醒用戶在發佈遊戲前檢查 Mod 授權和真實商標。

0. 前置需求（同時，一開始）

前置需求	檢查方式	若缺失
Python 3.10+, numpy, Pillow	python3 -c "import numpy, PIL"	python3 -m pip install --user numpy pillow（若無 pip：get-pip.py --user）
.NET 8（處理 .yft/.ytd/.awc 二進位檔案）	dotnet --version 或 ~/.dotnet/dotnet	dotnet-install.sh --channel 8.0 --install-dir ~/.dotnet；轉換器會自動找到 ~/.dotnet
GTA V 資產伺服器（真實紋理和音效）	MCP 工具 gta_status（ready: true）	建議在 PC 上執行 tools/gta-asset-server/start-server.bat 並在「我的 MCP 伺服器」中宣告；否則轉換會使用快取中已有的內容（~/.cache/fivem2roblox），若無則使用純色/合成音效
Studio 已連線	studio_connection_status（已附加插件），list_roblox_studios	提供資料夾和手動步驟
Roblox 上傳	VibeStarter：工具 upload_file + asset_publish；其他情況：環境變數中存在 ROBLOX_API_KEY（絕不顯示）	最後手段：僅一次手動操作，匯入 3D（第 4c 節）

1. 轉換

cd skills/fivem-vehicle-to-roblox
python scripts/convert_vehicle.py "<zip>" -o "<輸出目錄>" [--plate "文字"] [--texture-overrides <目錄>]

選項：--vehicle <名稱>（多車包）、--lod med（> 300,000 個三角形）、 --no-collision（碰撞箱 = 簡單方塊）、--wheel-collision（實心輪胎圓柱體）、 --studs-per-meter、--texture-overrides <目錄>（同名 PNG/DDS 檔案，用於取代包中的紋理：重新標記、修飾）、--sound-ids <json>、--retry-gamefiles、--no-game-server。 回傳碼 2 = 二進位檔案但無擷取器：安裝 .NET 8（如上）並重新執行；否則由用戶提供 CodeWalker XML 匯出；加密的 dlc.rpf → 使用 OpenIV。

讀取 <輸出目錄>/<名稱>/report.md：「碰撞箱：車輛官方碰撞模型」（否則為包圍盒：.yft 沒有 Physics/Bounds，請指出）、「紋理取自基礎遊戲」、「真實遊戲音效」、 「從資產伺服器傳輸」行（檔案、MB、秒數）。 缺少 vehshare/vehicle_generic_* 紋理或合成音效 = 資產伺服器無法連線。

2. 上傳模型和音效（私有資產）

同時進行：

• GLB <名稱>.glb → upload_file 然後 asset_publish → 類型 Model 的 rbxassetid。
• 音效：每個 sounds/*.wav|ogg → upload_file + asset_publish → 寫入 sounds/sound_ids.json = { "engine_on_1.wav": "rbxassetid://…", … }。 非 VibeStarter：python scripts/roblox_upload.py <輸出目錄>/<名稱>/sounds --user-id <id>（金鑰在環境變數中）。
• 使用 --sound-ids <輸出目錄>/<名稱>/sounds/sound_ids.json 重新執行轉換（快取：約 15 秒）以 將 SoundId 整合到設定中。GLB 在每次轉換中都是相同的（確定性）：無需重新上傳。

精準碰撞箱（自動）

.yft 包含車輛官方碰撞模型（Physics/LOD1，複合 Bound）： 車身、引擎蓋、行李箱、車門、車窗以低多邊形網格（約 240 個三角形）呈現，車輪為圓盤。 轉換器將其匯出到 GLB（col__<os>__<n>，排除 *_lowlod / *_dummy）； 設定會將其變成 Collision/<os>/ 中的不可見、實體且可碰撞的零件， 焊接到其骨骼上（打開的車門保持其碰撞），調整其精確度 （如果零件是凸面則為 Hull，否則為 PreciseConvexDecomposition，透過 CreateMeshPartAsync + ApplyMesh：透過腳本寫入 CollisionFidelity 會被忽略且不會報錯），添加車輪作為圓柱體 （半徑和接觸點；使用 --wheel-collision 時為實體）並停用 Hitbox 方塊 （保留為包圍體積，屬性為 BoundsOnly）。在 m422 上測量：86% 的半徑距離可見車身不到 15 厘米，而使用方塊時僅為 34%；玩家站在引擎蓋上距離 +1.55 個 stud， 而使用方塊時為 +3.17 個 stud。查看碰撞箱：使 Collision 可見（透明度 0.5）以進行截圖。

3. 為 Studio 準備腳本（不複製 100 KB 程式碼）

轉換會寫入 <輸出目錄>/<名稱>/studio/：FiveMRuntime.lua（runtime，每個場所一次）、 <名稱>_Setup.studio.lua（緊湊設定）、Verify.lua、ApplySoundIds.lua、chunks/ + manifest.json。

• 與已開啟場所同步的 Rojo 專案 (VibeStarter)：將檔案放入已掛載的資料夾 —

  python scripts/studio_stage.py <輸出目錄>/<名稱> --project <專案資料夾>
  

  → ReplicatedStorage.rbxts_include.F2R_Transfer（StringValue FiveMRuntime、<名稱>_Setup、 ApplySoundIds、<名稱>_sound_ids；ModuleScript Verify），約 2 秒後在 Studio 中可見。
• 否則：按 manifest.json 的順序發送 studio/chunks/*.lua，每個檔案一個 execute_luau， 保持原樣；每個步驟的最後一塊會執行腳本並返回其結果。

4. 將模型導入 Studio

a. EditableMesh：已拒絕（儲存時幾何圖形丟失，一個車輛約 12 MB 文字）。 b. 已採用：使用 GLB 的 ID 執行 insert_asset，parent = "Workspace.F2R_ImportTest"（若缺少則透過 execute_luau 建立資料夾），position 隨意（設定會將車輛放置在地面上）。 MeshPart 保留 glTF 節點的名稱（在 Model <名稱>_Node 中，由設定移除）。 c. 最後手段，無法上傳：要求用戶執行一個操作 — 「在 Studio 中：首頁 › 匯入 3D › <輸出目錄>/<名稱>/<名稱>.glb，預設選項，然後 完成後告訴我。」設定之後會自動找到模型（零件 ProbePart）。

5. Runtime + 設定 (execute_luau, Edit)

local T = game.ReplicatedStorage.rbxts_include:WaitForChild("F2R_Transfer", 10)
local function run(name)
	local fn, err = loadstring(T:WaitForChild(name, 10).Value, "=" .. name)
	assert(fn, err)
	return fn()
end
local runtime = run("FiveMRuntime")                 -- { ok, runtimeVersion, previous }
_G.F2R_TARGET = workspace.F2R_ImportTest.<名稱>      -- 插入的 Model
local setup = run("<名稱>_Setup")                    -- { parts, joints, missingParts, missingSounds, groundedBy, warnings }
return { runtime = runtime, setup = setup }

在設定之前設定 _G.F2R_NO_GROUND = true 可保持匯入高度。遺忘的 SoundId：_G.F2R_TARGET = 模型； _G.F2R_SOUND_IDS = T.<名稱>_sound_ids.Value；run("ApplySoundIds")。

6. 驗證 (roblox/Verify.lua)

Verify.lua 返回一個函數 verify(opts) -> JSON： { pass, fail, warn, skip, results = { {group, name, status, detail} } }。

編輯 — require(T.Verify:Clone())({ model = <模型> })：已安裝 runtime；零件存在且 命名正確（F2RExpectedParts）；車輛直立，前方朝向 -Z；比例（軸距誤差在 1% 內）； 頭燈在尾燈前方；零件在範圍內；放置在地面上；車輪在正確位置且朝向正確； 碰撞箱（零件和車輪存在，不可見且實體，焊接到其骨骼，精度已設定，方塊已停用，透過從 6 個面發射 400 條射線比較可見車身和方塊來評估精確度：≥ 80% 的射線在 15 厘米內）； SoundId 已填入；SetColor / SetMod / SetLivery / SetExtra / SetNeon / SetPlate 和 Serialize → Apply 可恢復狀態。

遊玩，伺服器端（execute_luau 伺服器端，一個玩家）— require(…Verify)({ model = …, checks = {…} })： seats_play（每個座位坐上再下來；seat = "<名稱>" 僅測試一個）、lock_play、 park_play、flip_play、void_play（掉入虛空後被接住）。 車身適應（客戶端，坐著的玩家）：checks = {"fit_play"} — 身體沒有點在車廂外，坐在座位上，讀取比例。在輕微傾斜的斜坡上（工作資料夾中的臨時傾斜平台）放置車輛後重新執行 seats_play。

遊玩，客戶端（渲染 runtime 僅在客戶端運行；loadstring 在其中被禁止）：

1. start_stop_play (is_start = true)。
2. execute_luau 客戶端： require(game.ReplicatedStorage.rbxts_include.F2R_Transfer.Verify)({ model = workspace.F2R_ImportTest:WaitForChild("<名稱>"), checks = {"joints","lights","sounds","audio"} }) → 由 FiveMVehiclesClient 自動附加渲染（否則：車輛在遊戲中無法操作）， 車門/引擎蓋/行李箱透過 Door_* 以 Hinges 角度開啟，車輪和方向盤透過遙測數據驅動， 制動鉗（hub_*）在轉向時不旋轉，懸吊臂（suspension_*）旋轉固定，每個 LightRole 在霓虹燈（或其燈光已開啟）中對應 Headlights 1/2、Brake、Reverse、Indicator Left/Right/Hazard、Engine、Siren；音效已載入；引擎聲音可聽見。
3. 駕駛：execute_luau 伺服器端 — 讓玩家坐上座位（seat:Sit(humanoid) 在 Seats.DriverSeat 上） 並監聽 Horn 屬性；player_input H 然後 E（按住 700 毫秒）；execute_luau 伺服器端 — 等待 Engine = true、Headlights = 1、Horn 變為 true 然後變回 false。
4. 駕駛引擎：玩家在方向盤後（伺服器端的 VehicleAccess.Enter），然後 execute_luau 客戶端 require(…Verify)({ model = …, checks = {"drive_play"} })（加速、轉速一致、停止、保持 直立）。完整測量（0-100 加速、煞車、轉彎、路緣、爬坡、倒車）：在遠離地圖的地方建立 TestTrack.lua 跑道，DriveBench.lua 基準，請參閱 references/roblox-integration.md（「駕駛測試」）；長時間測試使用 task.spawn。
5. start_stop_play (is_start = false)。始終在交還控制權之前停止遊玩；VibeStarter 會自動停止一個在 3 分鐘內沒有 Studio 呼叫的遊玩。

讀取 Verify 的結果，而不是控制台的錯誤數量：一個包含其他車輛的場所可能會顯示數百個 「Failed to load sound …」，但這些不是我們的。 狀態 warn「渲染凍結」= Studio 失去焦點（RenderStepped 已停止）：重新執行該組。

7. 修正每次失敗

Verify 失敗	常見原因	修正
缺少零件 / 重新命名	不同的匯入器	檢查名稱（F2RMissingParts）；重新匯入 GLB（第 4b 節）
軸距 / 前方朝向 -Z / 車輪側面	模型鏡像，參考點選擇不當	訊息「定位不精確」來自設定；修正 pick_ref_parts 或軸轉換
車門在 0 度（非「渲染凍結」）	Motor6D 缺失，零件焊接到根節點	檢查 Joints/ 和車門零件的擁有者 (Owner)
燈光角色保持關閉	零件沒有 LightRole，燈光 ID 未知	references/gta-format.md（燈光 ID）；修正 f2r/vehicle.py
SoundId 為空 / 音效未載入	上傳未完成或被拒絕	第 2 節；ApplySoundIds
Serialize / Apply	狀態未恢復	roblox/runtime/VehicleCustomization.lua
碰撞箱：精度 Default	ApplyMesh 被拒絕（網格未載入、權限不足）	重新執行設定；檢查 GLB 是否為場所擁有者的資產
碰撞箱精確度 < 80%	Mod 的碰撞模型粗略或缺失	閱讀「過寬 / 過窄」；沒有 Physics 的 Mod → 方塊（請指出）
渲染未被 FiveMVehiclesClient 附加	runtime 早於 2026-11-10 的修正	重新安裝 FiveMRuntime（新版本）
制動鉗在車輪轉向時卡住	早於 2026-11-11 的轉換（忽略 hub_* 骨骼）	重新轉換並重新安裝（第 4b 節至第 6 節）
提示 / 音效「在車輛外部」	早於 2026-11-11 的設定（在設定父級之前設定了 WorldPosition）	重新安裝車輛（第 4b 節至第 6 節）
下降：落在車頂上	兩側都沒有自由空間（牆壁、其他車輛）	正常；否則檢查斜坡和相鄰零件
頭頂到車頂（警告）	角色對於比例來說太大	使用 seats_play 建議的比例重新轉換

在技能修正後：重新轉換、重新安裝（刪除模型，第 4b 節至第 6 節）並重新驗證。 對 runtime 的修改會透過 FiveMRuntime 傳播（版本 = 原始碼的指紋）。

…

[為翻譯而截斷]