C# 遊戲手柄程式開發 - API 篇 (1)：被動模式訊息處理

C# 遊戲手柄開發系列 (1)：WinMM API 被動模式完整入門

購買北通 USB 手柄玩懷舊模擬器後，靈機一動：能否寫外掛讓手柄玩 Flash 遊戲？Flash 不支援手柄 API，但可透過外掛將手柄事件轉鍵盤/滑鼠事件。網路多為 C++ 範例，本系列以 C# 實作完整流程。

一、兩大開發模式

1. 被動模式：joySetCapture 向系統註冊，系統定時推送訊息到視窗。
2. 主動模式：依需求呼叫 joyGetPos/joyGetPosEx 主動查詢。

本篇專注被動模式。

二、核心 API 速查表

三、joySetCapture 簽章與使用

[DllImport("winmm.dll")]
public static extern int joySetCapture(
    IntPtr hWnd,      // 視窗控制代碼
    int uJoyID,       // 裝置 ID (0-15)，JOYSTICKID1 或 JOYSTICKID2
    int uPeriod,      // 輪詢間隔 (毫秒)
    bool fChanged     // 是否僅在移動超過閾值才通知
);

• 成功回傳 JOYERR_NOERROR (0)，失敗回傳非零錯誤碼。
• 不再使用時必須呼叫 joyReleaseCapture 釋放。

四、系統推送訊息類型

重寫 WndProc 處理訊息。針對 JOYSTICKID1：

JOYSTICKID2 對應 MM_JOY2MOVE、MM_JOY2BUTTONDOWN、MM_JOY2BUTTONUP。

重要：MM_JOYXMOVE 會持續推送，無論是否操作！

五、判斷按鍵狀態：WParam 與 LParam

1. WParam：按鈕位元組合

• 儲存除方向鍵外所有按鈕狀態，值為位元組合（如 JOY_BUTTON1 | JOY_BUTTON2）。
• 注意：BUTTONDOWN/UP 的按鈕值定義與 MOVE 不同！

2. LParam：X/Y 座標 (方向鍵判斷依據)

• 高 16 位 = Y 座標，低 16 位 = X 座標。
• 中心點為基準，偏移判斷上下左右：

private void GetXYButtonsStateFromLParam(int lParam, ref JoystickButtons buttons)
{
    int x = lParam & 0x0000FFFF;        // 低 16 位 X
    int y = (int)((lParam & 0xFFFF0000) >> 16); // 高 16 位 Y
    int m = 0x7EFF; // 中心點數值

    if (x > m) buttons |= JoystickButtons.Right;
    else if (x < m) buttons |= JoystickButtons.Left;

    if (y > m) buttons |= JoystickButtons.Down;
    else if (y < m) buttons |= JoystickButtons.Up;
}

六、被動模式總結

1. 呼叫 joySetCapture 註冊視窗接收訊息。
2. 覆寫 WndProc 解析 MM_JOYXMOVE、BUTTONDOWN、BUTTONUP。
3. 利用 LParam 解析方向鍵，WParam 解析功能鍵。
4. 下一篇將介紹主動模式與按鍵去抖動核心邏輯。