• On most platforms (Windows, Nintendo Switch), calling it once is actually enough. Later, connecting and disconnecting controllers is automatically detected. So you only need to call cgeref:TGameControllers.Initialize[Controllers.Initialize] once in your application.

• However, on some platforms (Linux currently), it is necessary to call cgeref:TGameControllers.Initialize[Controllers.Initialize] again to detect newly-connected controllers. To account for this, we recommend either giving the user an explicit button/menu item to do this (like a button "Detect Connected Game Controllers") and/or calling cgeref:TGameControllers.Initialize[Controllers.Initialize] automatically at certain times (e.g., every 5 seconds, or every time the user opens a pause menu).

var
  Controller: TGameController;
begin
  Controllers.Initialize;
  WritelnLog('Number of game controllers found: %d', [Controllers.Count]);
  for Controller in Controllers do
    WritelnLog('Game controller %d: %s', [
      Controller.Index,
      Controller.Name
    ]);
end;

cgeref:TGameControllerPressRelease.Button[Event.Controller.Button]

Button that was pressed or released.

This uses controller-agnostic enumeration names. In particular, the 4 "face buttons" (which have rather inconsistent names and looks between some popular gamepads — A B X Y or square triangle circle cross) are mapped to cgeref:gbNorth[], cgeref:gbEast[], cgeref:gbSouth[], cgeref:gbWest[]. See the cgeref:TGameControllerButton[] documentation for more information.

cgeref:TGameControllerPressRelease.Meaning[Event.Controller.Meaning]

Additional possible "conventional meaning of the button". This can be cgeref:gmConfirm[] or cgeref:gmCancel[] for buttons that by convention act like this on a given controller type. For example, A on Xbox controller is cgeref:gmConfirm[], B is cgeref:gmCancel[].

For most buttons it is just cgeref:gmNone[].

cgeref:TGameControllerPressRelease.Caption[Event.Controller.Caption]

Button caption that matches the controller type. For example, the four "face buttons" on Xbox controller are 'A', 'B', 'X', 'Y'.

The intended purpose is to use this to display messages to the user like WritelnLog('You pressed %s.', [Event.Controller.Caption]);. There is also a method cgeref:TGameController.ButtonCaption[] to get button’s caption independently of it being pressed, to use it like Button.Caption := Format('Press %s to jump', [Controllers[0].ButtonCaption(gbSouth)]);.

cgeref:TGameControllerPressRelease.ControllerIndex[Event.Controller.ControllerIndex]

Index of the controller in the cgeref:TGameControllers.Items[] array.

This is useful if different controllers map to different players, e.g. controller 0 controls the left car, while controller 1 controls the right car in a split-screen car racing game.

function TMyView.Press(const Event: TInputPressRelease): Boolean;
begin
  Result := inherited;
  if Result then Exit; // allow the ancestor to handle keys
  if Event.IsKey(keyEscape) or
     Event.IsController(gmCancel) then
  begin
    // ... do something
    Exit(true); // handled
  end;
end;

• Left stick, 2D, cgeref:TGameController.AxisLeft[]. Both X and Y coordinates are in range [-1, 1].

• Right stick, 2D, cgeref:TGameController.AxisRight[]. Both X and Y coordinates are in range [-1, 1].

• Left trigger, 1D, cgeref:TGameController.AxisLeftTrigger[]. In the range [0, 1].

• Right trigger, 1D, cgeref:TGameController.AxisRightTrigger[]. In the range [0, 1].

procedure TViewMain.Update(const SecondsPassed: Single; var HandleInput: Boolean);
var
  MovementSpeed: TVector2;
begin
  inherited;
  if Controllers.Count > 0 then
  begin
    MovementSpeed := Controllers[0].AxisLeft;
    // Move the object in XZ plane
    PlayerAvatar.Translation := PlayerAvatar.Translation +
      Vector3(MovementSpeed.X, 0, MovementSpeed.Y) * SecondsPassed;
  end;
end;

procedure SetupController;
var
  BindingAxis: TInputShortcutBindingControllerAxis;
  BindingButton: TInputShortcutBindingControllerButton;
begin
  // left stick to move
  BindingAxis := TInputShortcutBindingControllerAxis.Create(Self);
  BindingAxis.Axis := gaLeftStick;
  BindingAxis.Positive := true;
  BindingAxis.Coord := 1;
  BindingAxis.ControllerIndex := ControllerIndex;
  MyWalkNavigation.Input_Forward.Bindings.Add(BindingAxis);
  BindingAxis := TInputShortcutBindingControllerAxis.Create(Self);
  BindingAxis.Axis := gaLeftStick;
  BindingAxis.Positive := false;
  BindingAxis.Coord := 1;
  BindingAxis.ControllerIndex := ControllerIndex;
  MyWalkNavigation.Input_Backward.Bindings.Add(BindingAxis);
  BindingAxis := TInputShortcutBindingControllerAxis.Create(Self);
  BindingAxis.Axis := gaLeftStick;
  BindingAxis.Positive := true;
  BindingAxis.Coord := 0;
  BindingAxis.ControllerIndex := ControllerIndex;
  MyWalkNavigation.Input_RightStrafe.Bindings.Add(BindingAxis);
  BindingAxis := TInputShortcutBindingControllerAxis.Create(Self);
  BindingAxis.Axis := gaLeftStick;
  BindingAxis.Positive := false;
  BindingAxis.Coord := 0;
  BindingAxis.ControllerIndex := ControllerIndex;
  MyWalkNavigation.Input_LeftStrafe.Bindings.Add(BindingAxis);
  // other buttons
  BindingButton := TInputShortcutBindingControllerButton.Create(Self);
  BindingButton.Button := gbSouth;
  BindingButton.ControllerIndex := ControllerIndex;
  MyWalkNavigation.Input_Jump.Bindings.Add(BindingButton);
  BindingButton := TInputShortcutBindingControllerButton.Create(Self);
  BindingButton.Button := gbEast;
  BindingButton.ControllerIndex := ControllerIndex;
  MyWalkNavigation.Input_Crouch.Bindings.Add(BindingButton);
  BindingButton := TInputShortcutBindingControllerButton.Create(Self);
  BindingButton.Button := gbLeftStickClick;
  BindingButton.ControllerIndex := ControllerIndex;
  MyWalkNavigation.Input_Run.Bindings.Add(BindingButton);
end;

procedure TViewMain.Start;
begin
  inherited;
  Controllers.Initialize;
  MyWalkNavigation.UseGameController;
end;