# Player Controls - Dubai Metaverse

## Overview

This document describes the player control system and input mapping for the Dubai Metaverse project.

## Control Schemes

### First-Person Controls

**Primary control scheme**

#### Movement

- **Forward**: W key / Gamepad left stick up
- **Backward**: S key / Gamepad left stick down
- **Left**: A key / Gamepad left stick left
- **Right**: D key / Gamepad left stick right
- **Sprint**: Left Shift / Gamepad left trigger
- **Walk**: Default speed

#### Camera

- **Look Up/Down**: Mouse Y / Gamepad right stick Y
- **Look Left/Right**: Mouse X / Gamepad right stick X
- **Mouse Sensitivity**: Configurable
- **Invert Y**: Optional

#### Interaction

- **Interact**: E key / Gamepad A button
- **Cancel**: ESC key / Gamepad B button

---

### Third-Person Controls (Optional)

**Alternative control scheme**

#### Movement

- **Same as First-Person**: W/A/S/D or gamepad stick
- **Camera Follow**: Camera follows player
- **Camera Distance**: Adjustable camera distance

#### Camera

- **Orbit**: Mouse / Gamepad right stick orbits camera
- **Zoom**: Mouse wheel / Gamepad triggers
- **Reset**: Reset camera position

---

## Input Mapping

### Keyboard & Mouse

#### Movement Actions

- **MoveForward**: W
- **MoveBackward**: S
- **MoveLeft**: A
- **MoveRight**: D
- **Jump**: Space (if implemented)
- **Sprint**: Left Shift

#### Camera Actions

- **LookUp**: Mouse Y (negative)
- **LookDown**: Mouse Y (positive)
- **Turn**: Mouse X
- **Mouse Sensitivity**: Configurable

#### Interaction Actions

- **Interact**: E
- **Cancel**: ESC
- **Menu**: Tab or M

---

### Gamepad

#### Movement Actions

- **MoveForward**: Left stick up
- **MoveBackward**: Left stick down
- **MoveLeft**: Left stick left
- **MoveRight**: Left stick right
- **Sprint**: Left trigger

#### Camera Actions

- **LookUp**: Right stick up
- **LookDown**: Right stick down
- **Turn**: Right stick left/right
- **Sensitivity**: Configurable

#### Interaction Actions

- **Interact**: A button
- **Cancel**: B button
- **Menu**: Start button

---

## Player Pawn

### BP_PlayerPawn

**Player pawn with movement and camera**

### Components

1. **Capsule Component**: Collision capsule
2. **Camera Component**: First-person camera
3. **Movement Component**: Character movement
4. **Interaction Component**: Interaction system

### Settings

#### Movement

- **Max Walk Speed**: 300-400 units/second
- **Max Sprint Speed**: 600-800 units/second
- **Acceleration**: 2048 units/second²
- **Deceleration**: 2048 units/second²
- **Ground Friction**: 8.0

#### Camera

- **Field of View**: 90 degrees (configurable)
- **Camera Height**: Eye level (170 units)
- **Camera Pitch Limits**: -89 to +89 degrees

---

## Player Controller

### BP_PlayerController

**Player controller for input and interaction**

### Functions

#### SetupInputComponent

- **Purpose**: Set up input mapping
- **Implementation**: Bind input actions
- **Called**: On begin play

#### HandleMovement

- **Purpose**: Handle movement input
- **Implementation**: Apply movement to pawn
- **Parameters**: Input values

#### HandleCamera

- **Purpose**: Handle camera input
- **Implementation**: Rotate camera
- **Parameters**: Input values

#### HandleInteraction

- **Purpose**: Handle interaction input
- **Implementation**: Check for interactables, interact
- **Parameters**: None

---

## UI Controls

### Menu Controls

- **Main Menu**: ESC or Tab
- **Mini-Map**: M key (toggle)
- **Inventory**: I key (if implemented)
- **Settings**: Settings menu access

### Menu Navigation

- **Navigate**: Arrow keys or gamepad D-pad
- **Select**: Enter or gamepad A
- **Back**: ESC or gamepad B

---

## Vehicle Controls

### When in Vehicle

**Controls switch to vehicle controls**

#### Vehicle Movement

- **Throttle**: W / Gamepad right trigger
- **Brake**: S / Gamepad left trigger
- **Steering**: A/D / Gamepad left stick
- **Handbrake**: Space / Gamepad X button

#### Exit Vehicle

- **Exit**: E / Gamepad Y button

---

## Settings

### Configurable Settings

#### Movement

- **Walk Speed**: Adjustable
- **Sprint Speed**: Adjustable
- **Sprint Toggle/Hold**: Toggle or hold to sprint

#### Camera

- **Mouse Sensitivity**: Adjustable (0.1-5.0)
- **Invert Y**: Toggle
- **Field of View**: Adjustable (70-110 degrees)

#### Controls

- **Key Bindings**: Customizable
- **Gamepad Support**: Enable/disable
- **Control Scheme**: First-person / Third-person

---

## Accessibility

### Accessibility Options

1. **Subtitles**: Enable/disable subtitles
2. **Color Blind Mode**: Color blind support
3. **Reduced Motion**: Reduce motion effects
4. **Large Text**: Increase text size

---

## Testing

### Control Testing

1. **Movement**: Test all movement controls
2. **Camera**: Test camera controls
3. **Interaction**: Test interaction controls
4. **Settings**: Test settings changes

### Platform Testing

1. **Keyboard & Mouse**: Test on PC
2. **Gamepad**: Test with gamepad
3. **Different Resolutions**: Test at different resolutions

---

## Troubleshooting

### Common Issues

**Issue**: Controls not responding
- **Solution**: Check input mapping
- **Solution**: Verify player controller setup

**Issue**: Camera too sensitive/not sensitive
- **Solution**: Adjust mouse sensitivity
- **Solution**: Check camera settings

**Issue**: Movement feels wrong
- **Solution**: Adjust movement speed
- **Solution**: Check movement component settings

---

## Documentation

### Control Documentation

Document controls for users:
- **Control Scheme**: First-person controls
- **Input Mapping**: All input mappings
- **Settings**: Configurable settings
- **Accessibility**: Accessibility options

---

**Version**: 1.0
**Last Updated**: [Current Date]