Roblox 預告片
SK=<此技能資料夾路徑>。此技能的核心任務：「錄製它、讓它看起來像是我在玩、然後剪輯它。」
每個遊戲的檔案都存放在 <game>/trailer/ 資料夾中：shots.json、clips/、out/。腳本都是通用的，而每個遊戲特有的名稱（標籤、Remote、提示文字、物品 ID）都定義在 shots.json 中。
基本規則（請先閱讀）
- 它會錄製使用者的真實螢幕畫面。 在開始錄製前，先在聊天中告知使用者保持 Studio 在最前方且不被遮擋，將滑鼠移出遊戲視圖，在您說完成之前請勿碰觸電腦，並獲得他們的同意。僅錄製校準過的視口區域。使用
record.py clean刪除測試和無效的片段。絕對不要使用-C（游標）參數。 - Studio 禮儀：為此使用一個 Studio MCP 伺服器（針對社群版的
robloxstudio伺服器編寫，而非內建的 Roblox_Studio）。在開始測試之前，先檢查沒有其他 Agent 正在使用 Studio。在編輯模式下匯入工具包，使用完後移除它，並且絕對不要儲存含有此工具包的 Place。 - 誠實原則：Roblox 拒絕顯示遊戲未擁有功能、強化圖形或廣告宣稱的影片。在鏡頭前安排實際會發生的結果（例如為一個 Take 強制機率、授予一個道具）是允許的。偽造遊戲無法做到的事情則是不允許的；請改為重新安排鏡頭（請參閱範例中的 Gold→Rainbow 蒙太奇）。
- 不使用電腦使用功能。 所有操作都透過 MCP eval 呼叫、Python 和 ffmpeg 執行。
- 保持卡片和文字簡潔（「主題無雜訊」：工具上不要有額外雜訊）。遊戲本身的 UI 就是最好的文字。
工作流程
1. 規劃
閱讀 references/shot-list-template.md。根據遊戲的 GAME.md、FINISHED.md 和原始碼，撰寫鏡頭表格（前 2-3 秒的鉤子、核心循環、稀有時刻、社交互動、基地/進度、一個額外系統、標題卡、僅供社交用的行動呼籲），並在錄製前先展示給使用者看。然後撰寫 <game>/trailer/shots.json（架構請參考 references/luau-api.md；可從 assets/shots.template.json 或 references/example.shots.json 開始，後者為完整範例）。執行 python3 $SK/scripts/build_kit.py list --shots <shots.json> 可以統計原始素材的總時長。
2. 遊戲操作視角與電影運鏡（Luau）
scripts/TrailerDriver.luau負責在測試客戶端上執行一個鏡頭：傳送到起始姿勢、停用鍵盤控制、行走路徑點（使用 Humanoid:MoveTo、尋路、跳躍、人類抖動）、轉向目標、按下 ProximityPrompts（InputHoldBegin/End）、呼叫 Remote 或 Bindable，並在提示或遊戲事件發生時切換攝影機。它的玩家攝影機是一個帶有滑鼠般的延遲跟隨、晃動和輕微掃視的效果。遊戲 HUD 在遊戲操作鏡頭中保持開啟，在電影鏡頭中關閉；Roblox 頂部列、CoreGui 和游標始終關閉。每次執行前都會先停止前一次執行，並在事後恢復所有設定。scripts/CameraRig.luau提供電影運鏡預設：推軌/曲線/飛越、貝茲曲線、環繞、吊臂、推進、甩鏡（含動態模糊）以及靜態。所有運鏡皆透過 TweenService 曲線進行緩動，並具有可設定的持續時間。- 將它們匯入 Studio：
build_kit.py rbxmx→ 匯入ReplicatedStorage（編輯模式）→ 開始測試 → 使用eval_client_runtime發送build_kit.py call --shot ID。如果鏡頭需要設定，請先使用eval_server_runtime執行build_kit.py server --shot ID。詳細說明和完整動作列表請參閱references/luau-api.md。
3. 錄製
請參閱 references/recording.md。簡而言之：先執行 record.py calibrate 一次（驅動程式會將視口渲染為青色，腳本會自動找到它），然後針對每個鏡頭執行 record.py shot ID --start-ms <startsAtMs> --dur <dur>。它會等待驅動程式排程的開始時間，錄製前導、鏡頭和結尾，僅捕捉視口區域，並儲存精確的修剪偏移量。如果螢幕錄製不可用，record.py stitch 可以將儲存的 capture_screenshot 幀轉換為片段。
4. 剪輯
請參閱 references/editing.md。執行 edit.py build --cut roblox --format landscape 可製作用於上傳至 Roblox 的版本（最長 30 秒，1080p60 H.264，不含行動呼籲）。執行 --cut social --format both 可同時製作 16:9 與 9:16 版本。文字使用 Pillow 繪製，因為 Homebrew 的 ffmpeg 可能沒有 drawtext 功能。如果系統未安裝 Fredoka One 字型，請在使用者同意後下載至 assets/fonts/；否則會以 Arial Rounded Bold 作為替代。
5. 品質檢查
錄製後執行 qa.py clips --shots ...；剪輯後執行 qa.py final <mp4> --roblox。它會檢查掉幀、黑畫面、凍結畫面、Studio UI 邊緣、游標標誌以及 Roblox 的限制，並產生一份 contact sheet。使用 Read 功能打開這份 sheet 並仔細檢查：可能會有遺漏的 Studio 面板、游標或錯誤的 HUD 狀態。然後將剪輯成果（路徑加上 sheet）展示給使用者，並記錄修改意見以進行重新剪輯。重新剪輯只需要執行 edit.py。
6. 清理
停止測試，刪除 ReplicatedStorage.TrailerKit，執行 record.py clean --out <trailer> --shots <shots.json>，並刪除 <trailer>/build/ 資料夾。保留 clips/（原始素材）和 out/ 資料夾。
參考文件對照表
| 檔案 | 何時閱讀 |
|---|---|
references/shot-list-template.md | 規劃階段；將 GAME.md 轉換為鏡頭 |
references/luau-api.md | 撰寫 shots.json；驅動程式和攝影機腳本 API；目標、動作、觸發器、預設 |
references/recording.md | 第一次錄製前；校準、同步、備援方案、雙人鏡頭 |
references/editing.md | 剪輯區塊、轉場、卡片、字型和表情符號、音訊、直式影片 |
references/roblox-video-specs.md | Roblox 上傳限制與內容規則，附帶參考來源 |
references/worked-example.md + example.shots.json | 完整工作範例（一個寵物孵化轉蛋遊戲，「🥚 Pet Roll」） |
腳本對照表
| 腳本 | 用途 |
|---|---|
scripts/TrailerDriver.luau、scripts/CameraRig.luau | 執行時期（客戶端） |
scripts/build_kit.py | 產生 rbxmx 工具包、eval 程式碼片段、內聯 payload 備援、伺服器端程式碼片段、鏡頭列表 |
scripts/record.py（record.sh 包裝器） | 視窗管理、校準、錄製一個鏡頭、拼接、清理 |
scripts/edit.py | 建立剪輯、預覽卡片、列出字型 |
scripts/qa.py | 片段與最終檢查、contact sheet |
scripts/check_luau.sh | 使用預先包含 Roblox 全域變數的檔案進行 luau-analyze 分析（無需安裝 Roblox 類型定義即可運作） |
修改腳本後請進行驗證：執行 python3 -m py_compile $SK/scripts/*.py 以及 $SK/scripts/check_luau.sh $SK/scripts/*.luau。
已知限制（遇到時請在此處修正）
- 驅動程式無法點擊 GUI 按鈕。請使用按鈕呼叫的 Remote（使用
invoke），就像 hatch 鏡頭所做的那樣。 - 從標籤取得的固定
localOffset只是初步估算；預計在每個鏡頭的第一次錄製後進行調整。 - 玩家攝影機無法模擬滑鼠滾輪縮放。請使用
look.dist在不同的節拍之間改變距離。 - 伺服器設定無法
require即時遊戲模組：execute_luau/eval_server_runtime 會獲得一個全新的 require 快取（2026-10-11 在一個寵物孵化遊戲中測得：當玩家已載入時，PlayerState.all()竟然是空的）。請將設定程式碼放在一個 RunContext=Server 的 Script 中，並匯入到工具包旁邊，這個 Script 會暴露一個 BindableFunction，然後讓server程式碼片段透過:Invoke來呼叫它。模式：一個TrailerHookScript（僅限預告片使用，絕不儲存在 Place 中）從遊戲自身的伺服器 VM 內部require遊戲自己的模組，並建立ServerStorage.TrailerHook（BindableFunction，:Invoke(cmd, args) -> (ok, result)），每個設定步驟對應一個小型指令（給予金幣、添加指定等級的道具、讓計時器準備就緒、強制下一次轉蛋的機率、restore）。它會儲存它變更的每個設定值，並在restore以及 Script 被銷毀時恢復這些值。請像build_kit.py打包工具包一樣，將它打包成一個.rbxmx檔案。 - 在 1470x956 pt 的螢幕上，開啟 Explorer/Properties 面板的 Studio 視口比例約為 1.26:1；請在校準前隱藏面板（或使用檢視 > 全螢幕），否則 16:9 裁切會丟棄約三分之一的畫面。