polywright 是做什麼的？
3D 模型工作的中樞。它決定模型的製作方式，將每個資產保存在一個帶有清單的資料夾中，並透過數字和圖片驗證每個步驟。相關技能則負責深入細節。
腳本：此技能資料夾中的 scripts/pw.py（Python 3.9+，標準函式庫，每個指令一個 JSON 物件；
scripts/pw_bpy.py 是其 Blender 部分，切勿手動執行）。
每次工作階段執行一次 python <此資料夾>/scripts/pw.py doctor：它會尋找 Blender（任何作業系統）、Python 網格
函式庫、切片器和 ComfyUI 主機，並報告缺少的項目。完整指令列表：references/cli.md。
步驟 1：簡報（只問你無法推斷的資訊）
- 內容：物體或場所，真實或想像，以及其可辨識程度。
- 目標：
pw.py check --list中的一個或多個目標（game-roblox, game-unity, game-unreal, web-threejs, ar-usdz, commerce-gltf, print-fdm, print-resin, video-blockout, cad-step）。目標決定預算。 - 實際尺寸（以公尺為單位）（長凳長 1.8 公尺；人高 1.7 到 1.8 公尺）。錯誤的比例是最常見的
隱性錯誤；
check --real-size-m可以捕捉到它。 - 輸入：提示詞、照片、草圖、測量數據、地圖位置、現有的網格。
- 精細度與預算：初步區塊建模、遊戲就緒、頂級模型；託管產生器可能花費的時間或金錢。
建立：pw.py new <dir> --name <名稱> --kind real|imagined|hybrid --route <途徑> --targets a,b --real-size-m X。
資料夾：refs/（參考資料，每個記錄為一個來源）、work/（.blend、中間檔案）、out/（每個目標
一個交付物）、renders/（審閱圖表）、brief.md、manifest.json。給其他外掛的合約：
references/contract.md。
步驟 2：選擇途徑（滿足簡報需求的最便宜方式）
| 情境 | 途徑 | 技能 |
|---|---|---|
| 常見物體；許可證允許重複使用 | 尋找：Poly Haven, Kenney, Quaternius (CC0)，Sketchfab 和列印網站（檢查每個許可證） | 此技能, references/routes.md |
| 有尺寸、可配合的零件、銳利邊緣（支架、外殼、建築物、家具） | 程式碼 (--route procedural)：bpy, build123d/CadQuery/OpenSCAD | polywright-generate, polywright-blender |
| 真實地點（公園、街道、校園、地形） | 地點：OSM + 高程 (pw.py place) | polywright-capture |
| 可以拍照或掃描的真實物體 | 捕捉：攝影測量法、高斯潑濺、掃描器，或根據測量數據建模 | polywright-capture |
| 想像的有機體或一次性物體（雕像、生物、道具） | 生成：先產生參考圖表，再進行影像轉 3D | polywright-references, polywright-generate |
| 會變形的頂級角色 | 生成或雕刻作為基礎，再進行重拓樸和綁定 | polywright-generate, polywright-finish |
大多數好的結果會混合多種途徑：一個 OSM 公園配上生成的主要道具，一個用程式碼建造的房屋配上生成的 雕像。在清單中記錄每個零件的途徑。
步驟 3：先有參考資料，再有幾何圖形
對於非現成的任何東西，先收集或產生參考資料（polywright-references）：在共享的地面線上放置正交視圖， 並帶有高度條、材質樣本、比例參考。產生的輸入決定了影像轉 3D 的大部分結果。
步驟 4：建立，然後驗證（每種途徑）
- 先進行區塊建模，使用實際尺寸：用基本幾何體確定輪廓和比例。在此修正比例；現在修正成本很低。
- 數字：
pw.py inspect <檔案>：三角形數、物件數、尺寸、材質、紋理、UV、水密性、 零件數。在每個破壞性步驟前後讀取它。 - 圖片：
pw.py render <檔案> --out renders/<步驟>：六個視圖和一張sheet.png。閱讀這個圖表， 而不是六張截圖。與參考資料比較：輪廓、比例、遺失或浮動的零件、著色異常、錯誤的軸向（側躺）、 錯誤的比例。 - 目標：
pw.py check <檔案> --target <t> --real-size-m X。失敗意味著在交付前修正；警告 意味著在交接時說明。 - 記錄：
pw.py manifest <目錄> --add-output out/<檔案> --target <t> --inspect，每個來源使用--add-source <URL> --licence <l> --author <a>，然後使用--validate。
規劃、執行和批評是分開的階段：建立完成後，以批評者的角度查看圖表，並在聲稱完成前列出缺陷。
值得花兩輪修復回溯錯誤；超過這個次數，就應該重新考慮方法。
為每個里程碑保存一個編號的 .blend 檔案（work/<名稱>_v03.blend），以便長時間的工作可以從磁碟重新開始。
將模型合成到圖片中
當影像或影片模型一直錯誤地繪製設計好的道具時（例如分鏡圖、場景參考圖、海報），請採用圖片的構圖和模型的形狀：
- 僅挑選用於構圖的圖片：人物的站位、光線、目標。使用一個簡單的替代道具即可。
pw.py match model.blend --still pic.png --out work/match.png --anchor-px X,Y --anchor-local=X,Y,Z --aim-px X,Y --aim-local=X,Y,Z --depth M --horizon ROW --hide BOX --mask-add BOX：模型的錨點（一個 握柄）落在手上，其瞄準點（一個尖端）落在精確的像素上，使用圖片的鏡頭和水平線渲染 RGBA。設定--depth使其寬度（像素）與替代物相符（寬度 = f_px x 直徑 / depth；f_px在結果中）。--hide將零件隱藏在手後面；--mask-add將手加到遮罩中。- 以 3 倍縮放讀取裁剪後的
match_paste.png：檢查形狀、在畫面中的尺寸、瞄準點。修正 depth 和像素，重新執行（幾秒鐘）。 - 在
match_mask.png內部使用低降噪的遮罩影像編輯進行混合（FLUX.2 Klein 或任何 inpaint 模型： 降噪 0.3 到 0.5，低 cfg），然後將結果透過遮罩貼回，使外部的每個像素保持原樣。整個圖片的編輯會重繪所有內容（HDR 色彩、更大的道具）。 - 以全尺寸檢查；保留兩個或更多種子。
道具的參考圖表也來自模型（polywright-references，步驟 2b）。
從模型產生遊戲精靈圖表
當影像模型在遊戲精靈圖表中一直弄錯機械結構時（例如不圓的輪子、屋頂上的葉片），請建立模型，透過遊戲自己的攝影機渲染， 並僅讓影像模型負責上色：
pw.py spritecam <registry.json> --like <精靈圖表> --out camera.json：根據遊戲的地面菱形（L-014）擬合的正交攝影機。 在其中設定tile_m為模型每瓷磚的實際公尺數。- 使用每個物件的零件前綴（
wheel_、roof_...）在場景屬性sprite_parts中建立模型， 將活動零件放在一個在零件自己空間中建立的樞紐空白物件下，並將運動放在場景屬性loop中。 pw.py sprite model.blend --camera camera.json --out renders/L1 --scale 10.6667（一個 96 像素精靈圖表使用 1024 像素）： 以「sheet」樣式讀取通道和最終圖像，並與遊戲的精靈圖表並排比較；對動畫零件使用--frames N --frame-passes id,pos， 對不需要輪子的板子使用--hide wheel_。 然後在上色前，檢查其尺寸是否與遊戲中相鄰的精靈圖表相符：aw.py sprite <96 像素的最終圖像> --refs <同類 精靈圖表>如果覆蓋率低於其中位數的 0.9 則失敗。菱形擬合設定了地面比例，而不是建築物讀取的大小： 首先增加體積和道具（更高的牆壁、披屋、庭院），然後提高px_per_tile並移動footprint_centre_px， 使邊界框像相鄰的精靈圖表一樣跨越畫布（L-016）。保持細樑遠離圓柱體的輪廓：一個水平的原木越過傾斜的軌道， 看起來像是穿過它們上方和下方（L-017）。- 使用黏土的 Canny 邊緣作為控制（使用 ControlNet 的影像模型）來繪製最終圖像，用渲染的 Alpha 通道裁剪它，使
框架和
groundBase保持精確，然後根據sprite.json中的 ID 和邊緣數據檢查繪圖。
從模型產生場景插圖
一個圍繞已存在模型（建築物、機器）的載入畫面、主視覺或封面：在 Blender 中建立場景，並讓影像模型繪製它， 以便機械結構和佈局保持正確。
- 圍繞模型建立場景，使用每個物件的零件前綴放在場景屬性
scene_parts中，輪子和圓盤放在rings中， 關鍵點或路徑放在scene_points中。沿著路徑的堤岸、堤防和牆壁每個都是一個sweep（從scripts/pw_scene.py在pw.py bpy腳本中匯入），而不是一排盒子（L-020）。 pw.py framecam problem.json --out cameras.json：世界點與螢幕盒子、保持在畫面內且避開 UI 文字區域的點、 要最大化的尺寸度量；將最佳攝影機作為預設值印出。從真實的 UI 檔案（其內邊距和錨點）取得文字區域， 而不是經驗法則（L-018）。pw.py scene scene.blend --cameras cameras.json --camera framecam_1 --out renders/v1 --size 1280x720（ 繪圖工作流程的首次傳遞尺寸）：黏土、最終圖像、深度、法線、ID、線條和scene.json。先讀取黏土和深度； 除非預設需要固定，否則將深度範圍留給場景自己的測量（L-019）。- 使用控制（深度或線條）進行繪製，然後根據
scene.json檢查繪圖：環形邊緣、點、ID 顏色。
人群和戰鬥場景的區塊建模（AI 影片）
影片模型在處理人群時會出錯；Blender 則不然。讓 Blender 放置軍隊，讓影片模型繪製外觀：
pw.py crowd --out work/crowd --action clash --preview（或 march, advance, charge, hold；--view、--lens、--move），然後閱讀work/crowd/sheet.png。- 丟棄
--preview以獲得完整鏡頭：depth.mp4（主要控制）、pose.mp4（前排）、mask.mp4、clay.mp4、camera.json；預設為 832x480，81 幀，16 fps（Wan）。 - 將黏土的第 1 幀重新繪製成已核准的起始靜止圖像；使用深度影片和該靜止圖像驅動 Wan VACE 或 Wan 2.2 Fun Control。 提示詞包含服裝、每側顏色、光線和霧氣，而非人數。
詳細資訊和未經測試的內容：references/crowd-blockouts.md。鏡頭規劃由 cinewright 負責。
兩個戰士：pw.py duel shot.json --preview 將兩個假人模型放置在場景中它們的標記處，透過鏡頭的攝影機（examples/duel.json）；
閱讀 sheet.png，然後丟棄 --preview 以獲得每個控制的 mp4。
更多內容：crowd-blockouts.md，"Two fighters"。
一小批真實人物或玩具（交換側面、額外人物、標記遺失）：從照片中為每個人建立網格，使用 pw.py mark 修正顏色和
塗裝標記，給影片模型提供 pw.py turnaround 圖片作為參考，並提供一個 pw.py lineup（隊伍在固定側面，深度和遮罩）
作為其開場：references/figures-for-video.md。
用於電影鏡頭的場景和道具：references/film-and-video.md。
步驟 5：完成與交接
每個目標的完成處理（UV、LOD、法線貼圖慣例、軸向和單位轉換、壓縮）由 polywright-finish 負責；
3D 列印（水密實體、牆壁、底座、分割、3MF）由 polywright-print 負責。將資料夾交給使用它的外掛：
three.js 頁面（threewright）、電影和影片（cinewright）、Roblox 場所（roblox-agent）、Unity 專案
（unity-agent）、用於列印設定的特定印表機或切片器技能、用於更多圖片的影像技能。他們讀取 manifest.json 和 out/。
交接訊息：
模型：<名稱> (<途徑>) -> out/<檔案> 用於 <目標>：<三角形數> 個三角形, <尺寸> 公尺, <水密/零件>
檢查：<目標> 通過|警告 (<規則>) 審閱：renders/<步驟>/sheet.png
來源：<數量> 個，附帶許可證；AI 生成的部分：<哪些，哪個模型> 待辦事項：<尚未完成的工作>
規則
- 在 Blender 和 glTF 中使用實際尺寸（以公尺為單位）（Blender 中 +Z 朝上，glTF 中 +Y 朝上）；僅在列印檔案中使用公釐。
- 絕不要僅憑檔案名稱或產生器的說詞就斷言網格沒問題：檢查、渲染、驗證。
- 每個下載或產生的輸入都必須有一行來源記錄，附帶其許可證。商店和列印網站（Fab, Unity Asset Store, Sketchfab, MakerWorld, Printables, Steam）要求揭露 AI 生成的內容；清單會記錄它。
- 透過 MCP 運行的 Blender 橋接會執行任意 Python 程式碼：優先使用
pw.py bpy操作副本；僅在使用者觀看時 使用即時 MCP 工作階段（polywright-blender）。 - Google 逼真 3D 圖塊可以被檢視，但絕不能匯出、快取或追蹤（依據其條款）。
維護
常青單元，tier fast（產生器和 Blender 每月更新）。配套檔案：RESEARCH.md，
CHANGELOG.md，LEARNINGS.md，TESTS.md 附帶 evals/evals.json，
MAINTENANCE.md，狀態在 evergreen.json 中。每次使用時閱讀 evergreen.json；如果到期，先完成任務，然後刷新（evergreen-refresh）。
在發生時將經驗教訓寫入 LEARNINGS.md。