Archived on 2026-10-24. This is a historical implementation note, not current setup instructions or an active task list. Original claims, code examples, file paths, and completion statements have not all been revalidated. Use the current documentation and issue register for maintenance decisions.

Joystick Detection System¶

Overview¶

This system provides a complete solution for detecting and configuring gamepad/controllers in your Unity game. It includes automatic controller type detection (Xbox vs PlayStation), manual layout override, and a user-friendly UI for controller management.

Features¶

Automatic Controller Detection: Scans for connected joysticks when needed
Controller Type Detection: Automatically identifies Xbox and PlayStation controllers
Manual Layout Override: Users can switch between Xbox/PS layouts if auto-detection is incorrect
UI Integration: Full integration with your existing Page and MenuController system
Multi-Controller Support: Can detect and display multiple connected controllers

Components¶

1. InputManager Enhancements¶

New Properties: - InputManager.DetectedControllerLayout - Gets the current controller layout (Xbox/PlayStation) - InputManager.DetectedControllerName - Gets the name of the detected controller

New Methods: - InputManager.RefreshJoysticks() - Rescans for connected joysticks - InputManager.DetectControllerLayout(string joystickName) - Detects layout type from joystick name - InputManager.SetControllerLayout(ControllerLayout layout) - Manually sets the layout - InputManager.GetDetectedJoystickNames() - Gets all detected joystick names - InputManager.GetConnectedJoystickCount() - Gets the number of connected joysticks

New Enum: - ControllerLayout.Xbox - Xbox controller layout - ControllerLayout.PlayStation - PlayStation controller layout

2. JoystickDetectionView¶

The main UI component that displays detected controllers and handles user interactions.

Serialized Fields: - controllerListContainer - Transform where controller items are spawned - controllerItemPrefab - Prefab for individual controller items - statusText - Text showing detection status - noControllerText - Text shown when no controllers detected - refreshButton - Button to refresh controller list - confirmButton - Button to confirm and apply selected layout - xboxLayoutButton - Button to force Xbox layout - psLayoutButton - Button to force PlayStation layout - xboxIndicator - Image indicator for Xbox layout - psIndicator - Image indicator for PlayStation layout - selectedColor - Color for selected state - unselectedColor - Color for unselected state

3. ControllerItem¶

Represents a single controller in the detection list.

Serialized Fields: - controllerNameText - Text displaying controller name - layoutText - Text displaying current layout type - selectionHighlight - Image showing selection state - selectButton - Button to select this controller - selectedColor - Color when selected - unselectedColor - Color when not selected

4. JoystickDetectionPage¶

Page component that integrates with your MenuController system.

Serialized Fields: - joystickDetectionView - Reference to the JoystickDetectionView - firstSelectedButton - First button to select when page opens

Unity Setup¶

Step 1: Create the UI Structure¶

Create a UI structure like this in your Canvas:

JoystickDetectionPage (CanvasGroup, JoystickDetectionPage script)
├── JoystickDetectionView (JoystickDetectionView script)
│   ├── StatusText (TMP_Text)
│   ├── NoControllerText (TMP_Text)
│   ├── ControllerListContainer (Vertical Layout Group)
│   ├── RefreshButton (Button)
│   ├── ConfirmButton (Button)
│   ├── XboxLayoutButton (Button)
│   ├── PSLayoutButton (Button)
│   ├── XboxIndicator (Image)
│   └── PSIndicator (Image)

Step 2: Create Controller Item Prefab¶

Create a prefab with this structure:

ControllerItemPrefab (ControllerItem script, Button component)
├── ControllerNameText (TMP_Text)
├── LayoutText (TMP_Text)
└── SelectionHighlight (Image)

Configure the ControllerItem script: - Assign the Text components - Assign the Image for selection highlight - Assign the Button component - Set selected/unselected colors

Step 3: Configure JoystickDetectionView¶

Assign references: - Link controllerListContainer to the container transform - Link controllerItemPrefab to the prefab you created - Assign all text, button, and image references - Set appropriate colors for selected/unselected states

Step 4: Configure JoystickDetectionPage¶

Assign references: - Link to the JoystickDetectionView component - Set firstSelectedButton to your RefreshButton

Step 5: Add to MenuController¶

Integrate the page into your menu system:

// In your scene initialization code:
JoystickDetectionPage joystickDetectionPage = GetComponentInChildren<JoystickDetectionPage>();

MenuController.instance.Configure(
    initialPage: yourInitialPage,
    exitPage: yourExitPage,
    firstFocusItem: yourFirstFocusItem,
    onRootBackPressed: YourRootBackPressedHandler,
    onGateAnimationComplete: YourGateAnimationHandler
);

To open the joystick detection page:

// Call this from a button or menu option:
MenuController.instance.PushPage(joystickDetectionPage);

Usage Examples¶

Detecting Controllers Manually¶

// Refresh joystick detection
bool detected = InputManager.RefreshJoysticks();

if (detected)
{
    int count = InputManager.GetConnectedJoystickCount();
    Debug.Log($"Detected {count} controller(s)");

    string[] names = InputManager.GetDetectedJoystickNames();
    foreach (string name in names)
    {
        Debug.Log($"Controller: {name}");
    }
}

Checking Current Controller Layout¶

// Get current layout
ControllerLayout layout = InputManager.DetectedControllerLayout;
string controllerName = InputManager.DetectedControllerName;

Debug.Log($"Using {layout} layout with {controllerName}");

Manually Setting Controller Layout¶

// Override auto-detection
InputManager.SetControllerLayout(ControllerLayout.PlayStation);

Detecting Layout from Joystick Name¶

string joystickName = "DualSense Wireless Controller";
ControllerLayout layout = InputManager.DetectControllerLayout(joystickName);
// layout will be ControllerLayout.PlayStation

Controller Detection Patterns¶

Xbox Controllers¶

The system detects Xbox controllers by looking for these patterns in joystick names: - "Xbox" - "XInput" - "Xbox 360" - "Xbox One" - "Xbox Series"

PlayStation Controllers¶

The system detects PlayStation controllers by looking for these patterns in joystick names: - "DualSense" - "DualShock" - "Wireless Controller" - "PS5" - "PS4" - "PLAYSTATION"

Default Behavior¶

Unknown controllers default to Xbox layout.

Integration with Existing Input System¶

The system works seamlessly with your existing InputManager:

// The system automatically updates joystick detection when RefreshJoysticks() is called
// Button prompts will display based on the detected/selected layout

Testing¶

Testing Joystick Detection¶

Connect a controller (Xbox or PlayStation)
Open the Joystick Detection Page
Click "Refresh" to scan for controllers
Verify the controller name and layout appear correctly
Try switching between Xbox/PS layouts manually
Click "Confirm" to apply the layout

Testing Remote Play¶

Start the game
Connect a controller remotely (via Steam Remote Play, etc.)
Open the Joystick Detection Page
Click "Refresh" to detect the new controller
Verify the controller is detected and layout is correct

Troubleshooting¶

Controller Not Detected¶

Problem: Clicking "Refresh" shows no controllers.

Solutions: - Ensure the controller is properly connected - Try unplugging and reconnecting the controller - Check if the controller is recognized by your OS - Try a different USB port or Bluetooth connection

Wrong Layout Detected¶

Problem: Auto-detection selects the wrong layout type.

Solutions: - Use the manual Xbox/PS layout buttons to override - The system will remember your manual selection

Page Not Showing¶

Problem: Joystick Detection Page doesn't appear when called.

Solutions: - Ensure the Page component is properly set up - Check that MenuController.instance is not null - Verify the page is assigned correctly in your scene

Best Practices¶

Call Refresh When Needed: Only call RefreshJoysticks() when the user requests it or when a new controller is connected.
Save Controller Preference: Consider saving the user's controller layout preference to game settings.
Handle Multiple Controllers: The system supports multiple controllers, but for simplicity, it applies the first selected controller's layout to all joystick inputs.
UI Feedback: Provide clear visual feedback when controllers are detected and when layouts are changed.
Default Selection: Always select the first detected controller by default for better UX.

Future Enhancements¶

Potential improvements for the system:

Add per-player controller detection for local multiplayer
Save controller preferences per controller type
Add visual controller icons for Xbox/PS
Support for more controller types (Nintendo Switch, etc.)
Add controller disconnection detection
Implement automatic refresh when controllers are connected/disconnected

API Reference¶

InputManager¶

// Properties
public static bool IsJoystickDetected { get; }
public static ControllerLayout DetectedControllerLayout { get; }
public static string DetectedControllerName { get; }

// Methods
public static bool RefreshJoysticks()
public static ControllerLayout DetectControllerLayout(string joystickName)
public static void SetControllerLayout(ControllerLayout layout)
public static string[] GetDetectedJoystickNames()
public static int GetConnectedJoystickCount()

JoystickDetectionView¶

// Public Methods
public void RefreshControllerList()
public void ResetSelection()

ControllerItem¶

// Properties
public ControllerLayout SelectedLayout { get; }

// Events
public event System.Action<ControllerItem> OnSelected;

// Methods
public void Setup(string controllerName, ControllerLayout detectedLayout, bool isSelected)
public void SetSelected(bool selected)
public void SetLayout(ControllerLayout layout)

JoystickDetectionPage¶

```csharp // Methods public override void Enter(bool PlayAudio) public override void Exit(bool PlayAudio) public void ResetSelection()