AI 戰場編輯器

這是什麼

每一場戰役都是一份資料 package(factions / terrain / structures / units / scene / audio 六層 JSON),引擎 play.html 只負責演出。你可以「看」(上面任一場),也可以在本機「編輯」或從零「編一場新的」。公開網站是唯讀;編輯都在本機進行。

推薦做法:交給 AI 編寫(從零做、大幅修改)

適合從零做一整場、或大改(重寫旁白、補一整幕、整場重配樂)。做法:把這個 repo 交給一個能執行指令的 AI coding agent(如 Claude Code) —— 它要實際持有這個 repo 並能跑 shell,才用得到 repo 裡的 scaffold / 驗證 / 旁白等工具;貼到一般聊天視窗沒有用(它碰不到工具)。叫它照 skills/author-battlefield/SKILL.md 走。上面的「淝水之戰」就是這樣做出來的 —— 一個只拿到 repo 加一句話的 agent 自己編成、過四關。

新增一場戰役(貼給這樣的 agent):

在 battlefield-editor repo,照 skills/author-battlefield/SKILL.md
做一場「淝水之戰(383,前秦苻堅 vs 東晉謝玄)」,約 8 幕,涵蓋
投鞭斷流、洛澗夜襲、隔淝水對峙、秦軍後退失控、風聲鶴唳。
依序編六層、過機器四關、配旁白與背景音樂;完成後自動上首頁。

大幅修改既有戰役(貼給 agent):

在 battlefield-editor repo,幫我把 packages/guandu 的第六幕旁白
重寫得更生動、補一幕「白馬之圍」、整場配樂重配成更悲壯的;
改完跑四道機器關確認全綠。

agent 會自己 scaffold、編資料、用 edge-tts 生旁白、從音樂庫指派配樂、跑驗收;機器關擋不到的(地點合理、運鏡、聲音、史實)再由你看一遍。

小修 / 要精準位置:用編輯器更快,不必動 AI。改幕標題、換某幕配樂、移動某座城 —— 直接在下面的編輯器選物件 → 改位置 / 文字 → 存檔。位置要精準就用 Shift+點地圖(會顯示並複製 [x, z]);真要叫 AI 改位置,也是把這個從編輯器取得的 [x, z] 給它寫入,而不是「南一點」(除非你只要大概位置)。

一、在本機編輯器手動調(小修最快)

node tools/editor-server.mjs
# 開 http://localhost:8090/play.html?pkg=packages/<slug>/battlefield.json

只有本機經 editor-server 開才會出現編輯面板(公開站不會)。進去是俯視整張戰場、自由運鏡,右側面板用 ◀ ▶ 選要編哪一幕。

二、編輯面板能做什麼

• 旁白:改該幕旁白文字 → 按「更新此幕語音」跑 edge-tts 重生語音 + 字幕,並自動對齊幕長(雙聲變長變短都調)。
• 破音字 SUBS:台灣讀音;罕用字 / 破音字餵同音替身,重生時自動套用。
• 背景音樂:每幕一個下拉,從音樂庫(74 首 CC0)挑。
• 座標:選物件(城 / 營 / 單位)→ 填 x/z,或開「點圖設位置」後 Shift+點地圖 → 即時移動。
• 資訊文字:幕標題 / 年代 / 敘述就地改。
• 跑驗收:一鍵跑機器檢查。

所有編輯都寫回 package 資料檔(來源真實),重整頁面即生效。

三、從零新增一場戰役

node tools/new-package.mjs <slug> "顯示名"

產出最小骨架(本身就過機器關),接著依序編六層(對照 docs/authoring/):

factions → terrain → structures → units → scene → audio

編好會自動登錄到本首頁列表。每改一批跑機器四關(綠了才往下):

node tools/validate-data.mjs --pkg packages/<slug>/battlefield.json
node tools/residue-scan.mjs  --pkg packages/<slug>/battlefield.json
node tools/render-check.mjs   --pkg packages/<slug>/battlefield.json
node tools/audio-check.mjs    --pkg packages/<slug>/battlefield.json

四、加旁白語音

旁白稿放 packages/<slug>/narration/script.json(每幕一段),跑:

/tmp/ttsenv/bin/python3 packages/<slug>/narration/generate.py

edge-tts 雙聲(男 / 女)生 mp3 + 句級字幕;台灣讀音,罕用字用 SUBS 替身。也可直接在編輯器改文字按「更新此幕語音」。每幕長度要 ≥ 旁白長度,否則會被切(編輯器重生會自動調,CLI 則用 tools/fit-durations.mjs)。

五、加背景音樂 / 音效

node tools/assign-music.mjs --list                       # 看音樂庫(74 首 CC0,依情緒分類 + 評分)
node tools/assign-music.mjs <slug> <一幕一首 id...>        # 依幕序指派配樂
node tools/assign-sfx.mjs   <slug> battlecry sword1 ...   # 指派音效

皆 CC0,自動複製素材 + 補 CREDITS.md。庫不夠用?在 tools/music-library.json / sfx-library.json append 一筆即可(整池與新曲都能被指派)。

界線:機器驗結構,人驗好壞

四道機器關保證「結構合法、跨檔引用完整、旁白不被切、載入不炸」;但地點合不合理、運鏡好不好看、聲音貼不貼、史實對不對由人判。完整的 AI 編寫流程見 SKILL.md。