Steamworks 文獻庫
遊戲內動作檔案

概覽


開發人員必須為自己的遊戲提供輸入配置的 IGA(In-Game Actions,遊戲內動作)檔,定義遊戲的動作、操作組合,與基礎架構。 本文將說明 IGA 檔案的整體結構,並提供多款遊戲的明確範例。

範例檔案


手動編寫遊戲內動作檔案

首先從上述範例內連結的遊戲內動作(IGA)檔案中擇一下載 。 接著在 Steam 檔案夾內建立一個「controller_config」路徑,通常為 C:/Program Files (x86)/Steam/controller_config,然後將檔案置於此路徑下。 在 Steam 檔案夾內存在一個名稱十分相近的檔案夾,因此請確定您將該檔案置於「controller_config」檔案夾,而非「controller_base」檔案夾。 將檔案重新命名為:「game_actions_X.vdf」,其中 X 是您遊戲的 Steam AppID。 若您不知道您遊戲的 Steam AppID 是什麼,登入您的 Steam 合作夥伴網站即可尋得。

現在,在您常用的文字編輯器中打開該檔案。 該檔案採用標準的 Valve 格式,我們稱為 KeyValues,它是一個簡單並容易閱讀的格式。 下載我們的遊戲內檔案樣版或《Portal 2》的 IGA作為參考可能對您也有幫助。

透過使用 Steam 控制器 API 的現存遊戲來建立 IGA 檔案


如果您把任何 Steam 遊戲的配置儲存為「本機」配置,那麼您可以依循以下路徑找到對應的檔案:
[Steam 路徑]\UserData\[您的使用者 ID]\241100\remote\controller_config\[App ID]\[存檔名稱].vdf

下圖是我的《Defender's Quest》本機配置在一台普通 Windows 10 電腦中的儲存位置:

whereisvgf.png

請注意,這些檔案並非開發人員上傳的主 IGA 檔案的精確複本,但這個檔案中的「動作」和「在地化」兩個區塊是直接從母檔案中拉出來的,您可以透過這兩個區塊了解原始結構。

請點擊以下連結下載上圖所示的 #library_controllersavedefaulttitle_0.vdf 檔案,將它與《Defender's Quest》的主 IGA 做比較可能對您有所幫助。

IGA 格式


IGA 檔案採用 VDF 文件的格式,VDF 是 Valve 自己的資料格式,透過配對索引碼 / 值字串來建立結構化物件資料。

基本架構


IGA 的基本架構是由一個名為「遊戲內動作」的包裝函式物件,與名為「動作」和「在地化」的兩個子物件所組成:

"In Game Actions" { "actions" { } "localization" { } }

操作組合

讓我們來仔細看看「動作」物件, 這個物件內含您的操作組合。 「動作」物件的架構看起來像這樣:
"actions" { "ActionSetNameGoesHere" { "title" "#TitleGoesHere" "StickPadGyro" { } "AnalogTrigger" { } "Button" { } } }

在上方範例中,使用者只該覆蓋「ActionSetNameGoesHere」和「#TitleGoesHere」這兩個字串,其餘皆為應保留的關鍵字。

用來覆蓋「ActionSetNameGoesHere」的值為您在 Steam 控制器 API 中使用的操作組合名稱。 用來覆蓋「#TitleGoesHere」的值則是您之後在檔案中的「localization」區段中使用的在地化權杖。 請注意這裡需要 # 符號。

每一個操作組合都應具備不重複的字串名稱,想新增操作組合時,應該在容器物件「動作」的範圍內建立物件。 請勿包含逗點或方括弧,這是 VDF 格式,不是 JSON。

每個操作組合物件中可能有三種子物件, 分別為「StickPadGyro」、「AnalogTrigger」,和「Button」。 您只能定義這三個子物件,這三個子物件同時也是將容納您的獨立動作定義的容器。 然而,並非這三個類別全部都要提供。

此結構依然完全有效,請看下方範例:
"actions" { "ActionSetName1" { "title" "#Title1" "AnalogTrigger" { } "Button" { } } "ActionSetName2" { "title" "#Title2" "StickPadGyro" { } } "ActionSetName3" { "title" "#Title3" "Button" { } } }

StickPadGyro

此類比動作的操作組合區塊可具有最多兩個動作軸,您可能會想將其綁定至搖桿觸控板,或陀螺儀上。 任何您可能想透過滑鼠或其他類似裝置來操控的,也包含在內。

AnalogTrigger

此類比動作的操作組合區塊只具有一個動作軸,您可能會想將其綁定至類比板機鍵這類部位。

Button

此操作組合區塊僅適用回報開或關兩種狀態的純數位動作。 儘管區塊的名稱叫做「Button」,數位動作可與任何實體輸入綁定,包括原設計是輸出類比資料的裝置,如搖桿、觸控板等。

動作


直到收到定義完畢的動作之前,IGA 檔案並不會產生實際作用,因此現在來加入一些定義吧!

StickPadGyro 動作

就從新增一些 StickPadGyro(二軸類比)動作開始。 加入讓角色移動的動作如何?就叫它「移動」吧;再來一個控制視角的「視角」。

"actions" { "FPSControls" { "title" "#Set_FPSControls" "StickPadGyro" { "Move" { "title" "#Action_Move" "input_mode" "joystick_move" } "Camera" { "title" "#Action_Camera" "input_mode" "absolute_mouse" } } } }

由此可以看出動作 StickPadGyro 的抽象結構為:
"ActionNameHere" { "title" "#ActionTitleHere" "input_mode" "<analog_mode>" }

在這個結構中,使用者可自行更改的值只有我標出來的「ActionNameHere」、「#ActionTitleHere」,與「<analog_mode>」。 以上三個物件分別對應的是 Steam 輸入 API 用的動作字串名稱、本檔案的在地化區段中使用的在地化索引碼,與掌管如何處理與解釋類比資料的輸入來源模式。

input_mode」屬性有兩個可能數值可用於「StickPadGyro」動作:

  • joystick_move
  • absolute_mouse

將被解釋為搖桿動作的值應使用 「joystick_move」(以中心點為準持續偏移),更加需要彈性的一般目的類比動作則應使用「absolute_mouse」。 不確定時,請使用 absolute_mouse

joystick_move」vs 「absolute_mouse

當為第一或第三人稱遊戲或任何主要使用游標的遊戲建立視角輸入時,應永遠使用「absolute_mouse」類型,把它當成滑鼠來回應差異,這一點非常重要。

API 會自動為搖桿輸入進行正確的設定,因此如果您的視角是用在類比搖桿(PS4 或 Xbox 型)上、同時感應死區或反應曲線調至最大,那麼搖桿輸入便可調整。 這可以在您的預設配置中進行調整。 同樣的輸入便會跨搖桿、觸控板,或運動控制陀螺儀(Steam 控制器或 PS4),未來將支援的滑鼠亦然。

視角不應使用基於「joystick_move」的輸入方式,因為無法對應相反方向為觸控板、陀螺儀、滑鼠、運動控制取得一比一的資料。

同樣的原理也適用於基於游標的輸入:「absolute_mouse」基於搖桿的輸入中就能順利發揮滑鼠的功能,因此,就算您需要基於搖桿的游標,也不必自行建立。

您可以選擇將低階的滑鼠事件與您的類比資料一同送出。 您的遊戲無法區別這種滑鼠事件與來自您的作業系統的滑鼠事件。 執行方法為添加「os_mouse」值,並將其設為 1。

範例如下:
"StickPadGyro" { "Mouse" { "title" "#Action_Mouse" "input_mode" "absolute_mouse" "os_mouse" "1" } }


AnalogTrigger 動作
AnalogTrigger 動作是可綁定至板機上的單向類比動作。 若您使用簡單的板機臨界點於開槍或觸發「開鏡瞄準」模式等動作上,比起 AnalogTrigger 動作我們會建議您使用 Button 動作,如此使用者的重新綁定自由度會更高。

在重新綁定介面中可設定 AnalogTrigger 動作的感應死區,可重新調整的數值範圍為 0 至 1.0f。 有數位板機鍵的控制器(如 Nintendo Switch Pro 控制器)只會傳送 0 或 1.0,因此建議您檢查有沒有依賴板機鍵漸進輸入的遊戲程式碼。

AnalogTrigger 動作的格式十分簡單,以動作名稱作為索引碼,而值則使用在地化索引碼。 如同下方所示:
"AnalogTrigger" { "AccelerationAxis" "#Action_Accelerate" "BreakingAxis" "#Action_Brake" }

Button 動作

Button 動作有著相似的格式,使用動作名稱和在地化索引碼:
"Button" { "digital_action_1_name_here" "#DigitalAction1TitleHere" "digital_action_2_name_here" "#DigitalAction2TitleHere" }

必要時,您可以定義原生的低階輸入硬體事件(好比原生的滑鼠點擊),與動作本身同時輸出。 如果您的遊戲仰賴的難搞輸入堆疊有七層那麼深,遊戲對待來自您的應用程式層的模擬滑鼠事件的方式,與對待作業系統直接產生的事件之方式不太一樣,這類少見的狀況就很適合使用上述方法。

"Button" { "simple_click" "#simple_click" "fancy_click" "#fancy_click, mouse_button LEFT" }

送出「fancy_click」動作時,以上程式碼會導致遊戲發出 True 值、作業系統層級的滑鼠左鍵事件。

警告!

不論任何時候,您都不應該依賴這一項技巧為某個動作強制綁定特定輸入。 那將與整個「動作非輸入」的目的互相牴觸,也不再給予使用者配置的全面控制權。 如果您在少數特殊案例之外也廣泛地使用上述作法,代表您很有可能使用過度了。

操作組合階層

除了操作組合外,您亦可使用操作組合階層來將逐步累進的變更加至啟用中的操作組合上。 您可使用操作組合階層來處理一般模式中的特殊部分(如在 OnFoot 控制項中增加一個 Sniper 層),或用於處理在正常遊玩過程中需要彈出遊戲內介面的情況(如投票畫面)。 階層需在自己的區段中宣告,例如:
"action_layers" { "IngameModalLayer" { "title" "#Layer_IngameModal" "legacy_set" "0" "set_layer" "1" "parent_set_name" "InGame" "AnalogTrigger" { } "Button" { "Modal_Accept" "#Action_Modal_Accept" "Modal_Decline" "#Action_Modal_Decline" } } }

在地化


主 IGA 檔案除了操作組合定義,還應該包含一個在地化區段。 在地化物件下的個別子物件會是 Steam 支援的任一語言字串。 請確認當中至少有一個區塊含有英文的動作標題。

"localization" { "english" { "move" "Move" "camera" "Camera" } }

請注意,屬性的名稱與先前區段中的在地化索引碼除了沒有「#」符號以外,其它部分應互相對應。

想新增更多語種,只要添加語言區塊並為每個項目填入在地化文字就行了:

"localization" { "english" { "move" "Move" "camera" "Camera" } "spanish" { "move" "Mover" "camera" "Cámara" } "norwegian" { "move" "Bevege" "camera" "Kamera" } }
所有語言的索引碼都應與「API 語言碼」值相符,例如簡體中文應使用「schinese」。 Steam 支援語言的完整清單請參考此處

Steam 如何利用您的 IGA 檔案


您的主 IGA 檔案只會在開發時期建立(但您仍應該儲存、維護、在您做版本控管時保存此檔案等等)。 當您在開發階段為您的遊戲建立官方輸入配置時,Steam 用戶端會使用您的主 IGA 檔案來製作基礎樣版 。