inpControllerButtonHit

Checks if controller button just pressed this frame (single press detection). Takes controller (controller handle from inpCreateController, positive integer), button (button ID constant, integer). Returns 1 if button just pressed this frame, 0 otherwise. Detects button press edge (transition from released to pressed), returns true only once per press.

Button hit detection: 1=button just pressed this frame (was released last frame, pressed this frame), 0=button held (already pressed last frame), 0=button released (not pressed), single-shot detection (returns 1 only on first press frame, then 0 until released and pressed again).

Button IDs: use predefined button constants (A, B, X, Y, LB, RB, LT, RT, Start, Back, LS, RS, etc.), button values map to XInput/DirectInput standards (Xbox controller layout), consult input constants for available button IDs.

Use cases: (1) Discrete actions (jump, shoot once, toggle, menu select - actions that happen once per press), (2) Menu navigation (move cursor, select option, back button), (3) Toggle states (press once to toggle on/off), (4) Single-shot attacks (press to fire single bullet, not auto-fire), (5) Combo inputs (detect button sequence for fighting game combos).

Common patterns: single action = If inpControllerButtonHit(controller%, BUTTON_A) Then player jump; menu select = If inpControllerButtonHit(controller%, BUTTON_A) Then select menu item; toggle = If inpControllerButtonHit(controller%, BUTTON_START) Then paused=Not paused; combo sequence = If inpControllerButtonHit(controller%, BTN_A) Then combo[0]=True (detect first hit in sequence).

Hit vs Down: inpControllerButtonHit returns 1 only on first press frame (single-shot detection, use for discrete actions like jumps/menu navigation), inpControllerButtonDown returns 1 every frame while held (continuous detection, use for sustained actions like running/auto-fire), ButtonHit prevents repeated actions from single press (no auto-repeat), ButtonDown enables continuous actions while held (auto-repeat behavior).

Common usage: use ButtonHit for jump (press once to jump, not continuous jumping), use ButtonHit for menu navigation (press once to move cursor, not rapid scrolling), use ButtonDown for running (hold to keep running), use ButtonDown for charging (hold to charge attack).

Performance: fast query (~0.001ms, simple state comparison), safe for per-frame calls (intended usage pattern), no controller update required (reads cached state from last inpUpdateController).

Controller state: requires inpUpdateController called each frame (updates button states from hardware), compares current frame to previous frame (detects edge transition), button state from previous update (call inpUpdateController before querying).

Return values: 1 if button just pressed this frame (edge detected), 0 if button already held (was pressed last frame), 0 if button released (not pressed), 0 on error (invalid controller handle or button ID).

Validation: returns 0 for invalid controller handle (prints error if handle out of range), returns 0 for invalid button ID (button index beyond available buttons), check inpIsControllerConnected before use (avoid querying disconnected controllers).

Related: inpControllerButtonDown checks continuous press (held state), inpUpdateController updates controller state from hardware, inpCreateController creates controller handle, inpIsControllerConnected checks connection status.