inpCreateController

Creates controller input handle for specified port/player. Takes port (controller port number 0-3, maps to player 1-4). Returns controller handle (positive integer on success, -1 on error). Initializes controller input system for specified port, enabling button/stick queries and rumble control.

Port mapping: 0=player 1 (first controller), 1=player 2 (second controller), 2=player 3 (third controller), 3=player 4 (fourth controller), ports 0-3 supported (maps to XInput user IDs), controller doesn't need to be physically connected at creation time (can be plugged in later).

Controller handle: returned handle used with all controller input functions (inpControllerButtonDown, inpUpdateController, etc.), positive integer on success (valid handle for input queries), -1 on error (invalid port or initialization failure), store handle for later use (required parameter for all controller functions).

Use cases: (1) Single-player games (create controller for port 0, primary player input), (2) Local multiplayer (create controllers for ports 0-3, support up to 4 players), (3) Controller hot-plugging (create handle at startup, check connection status with inpIsControllerConnected), (4) Input system initialization (create controllers during game startup), (5) Mixed input (create controllers alongside keyboard/mouse support).

Common patterns: single player = controller%=inpCreateController(0): If controller%>0 Then controller ready; multiplayer = For i=0 To 3: controllers%(i)=inpCreateController(i): Next (create handles for 4 players); with validation = controller%=inpCreateController(0): If controller%<0 Then error creating controller.

Initialization: call once per port during startup (not every frame), creates internal controller state tracking (button/stick history), allocates memory for controller data (free with inpFreeController when done), returns immediately (no blocking I/O).

Physical connection: controller doesn't need to be connected when calling inpCreateController (handle created regardless), check inpIsControllerConnected each frame (detects hot-plug/unplug events), handle remains valid if controller disconnected (queries return 0/neutral values), controller can be plugged in after handle creation (system detects automatically).

Return values: positive integer=valid controller handle (use with other inp functions), -1=error (invalid port number, initialization failure, system error), 0 not used (all valid handles > 0).

Performance: one-time initialization cost (~0.1-1ms, called at startup only), allocates small memory for controller state (~100 bytes), no per-frame overhead (handle creation is setup, not ongoing cost).

Memory management: handle persists until inpFreeController called (manual cleanup required), creates persistent state tracking (button history for Hit detection), free handle when done (call inpFreeController on game exit or when controller no longer needed).

Error handling: returns -1 if port out of range (port > 3 or port < 0), returns -1 if system initialization fails (check stderr for error messages), valid handle doesn't guarantee connected controller (use inpIsControllerConnected).

Related: inpFreeController releases controller handle and memory, inpIsControllerConnected checks physical connection status, inpUpdateController updates controller state from hardware, inpGetControllerAmount queries number of connected controllers.