# Player Features

# Player Features

Advanced player management features including offline player tracking, death history, inventory viewing, and chat management.

## Player List

### Online & Offline Tabs

The Players page shows two tabs:
- **Online Players** - Currently connected players
- **Offline Players** - All players who have ever joined

### Player Information

| Column | Description |
|--------|-------------|
| Name | Player username with avatar |
| World | Current or last known world |
| Gamemode | Creative or Adventure |
| Health | Color-coded health bar |
| Position | X, Y, Z coordinates |
| Playtime | Total time played |
| Sessions | Number of join sessions |

### Auto-Refresh

The player list automatically refreshes every 10 seconds. Manual refresh is available via the refresh button.

## Player Actions

Click on a player to access quick actions:

| Action | Permission | Description |
|--------|------------|-------------|
| **Heal** | `players.heal` | Restore to full health |
| **Kill** | `players.kill` | Reduce health to 0 |
| **Kick** | `players.kick` | Remove from server |
| **Ban** | `players.ban` | Permanently ban |
| **Teleport** | `players.teleport` | Move to location |
| **Gamemode** | `players.gamemode` | Change gamemode |
| **Give Item** | `players.give` | Add items |
| **Clear Inventory** | `players.clear_inventory` | Remove all items |
| **Clear Effects** | `players.effects` | Remove status effects |
| **OP** | `players.op` | Grant/revoke operator |
| **Whitelist** | `players.whitelist` | Add to whitelist |
| **Respawn** | `players.respawn` | Move to spawn |
| **Message** | `players.message` | Send private message |

## Teleportation System

Three teleport modes are available:

### Player-to-Player

1. Select **Teleport to Player**
2. Choose target player from dropdown
3. Click **Teleport**

### To Coordinates

1. Select **Teleport to Coordinates**
2. Enter X, Y, Z values (Y defaults to 64)
3. Click **Teleport**

### To Death Location

1. Select **Teleport to Death**
2. View last death location info
3. Click **Teleport** to move player there

## Player Details Modal

Click the **Details** button to open the comprehensive player inspector with five tabs:

### Info Tab

- World name
- Gamemode
- Last position (X, Y, Z)
- Discovered zones count
- NPC memories count
- Unique items used count

### Inventory Tab

View all inventory slots:
- **Hotbar** (9 slots) - Active slot highlighted
- **Armor** (4 slots) - Helmet, Chest, Gloves, Legs
- **Utility** (4 slots)
- **Tools** (variable)
- **Storage** (36 slots)
- **Backpack** (if player has upgrades)

Each item shows:
- Item icon and name
- Durability bar (color-coded)
- Stack amount
- Item type

### Stats Tab

Real-time player statistics:
- **Health** - Current/Max with color bar
- **Stamina** - Percentage remaining
- **Oxygen** - Percentage (for underwater)
- **Mana** - Current value
- **Immunity** - Percentage

### Chat Tab

Player's chat history:
- Last 100 messages by default
- Formatted timestamps
- Color-coded player names
- Configurable time range

### Deaths Tab

Complete death history:
- World where death occurred
- Exact coordinates
- In-game day
- **Quick teleport** button for each death
- Most recent death highlighted

## Offline Player Features

Offline players show:
- Last seen date/time
- Total playtime (hours/minutes)
- Session count
- Last known world
- Last gamemode

### Available Actions

For offline players you can:
- Ban (prevents future joins)
- Whitelist management
- View full details (if data exists)
- View chat history
- View death locations

## Death Tracking

The panel automatically tracks all player deaths:

### What's Recorded

- Exact X, Y, Z coordinates
- World name
- In-game day number
- Camera rotation (pitch, yaw, roll)

### Accessing Death Data

1. Open Player Details
2. Go to **Deaths** tab
3. View all recorded deaths
4. Click **Teleport** to go to any location

### API Access

```
GET /api/players/:name/deaths
GET /api/players/:name/deaths/last
POST /api/players/:name/teleport/death
```

## Chat Management

### View Chat History

1. Go to **Chat** in sidebar
2. View global server chat
3. Filter by player name

Or in Player Details:
1. Open player modal
2. Click **Chat** tab
3. View that player's messages

### Configuration

- **Time Range** - Default 7 days, 0 = all time
- **Limit** - Messages per page
- **Offset** - For pagination

### Send Messages

Send private messages to online players:
1. Select player
2. Click **Message** action
3. Enter message (max 256 characters)
4. Click **Send**

## Item Management

### Give Items

1. Select player
2. Click **Give Item**
3. Search for item (autocomplete)
4. Set quantity (1-64)
5. Click **Give**

Item ID format: `lowercase_with_underscores`

**Examples:**
- `furniture_crude_sign`
- `weapon_sword_iron`
- `food_apple`

### Item Categories

- Weapons (swords, axes, maces)
- Tools (pickaxes, repair tools)
- Armor (helmets, chestplates, leggings)
- Accessories (shields, teleporters)
- Consumables (food, potions)
- Materials (ores, ingredients)
- Blocks (rocks, soil)
- Plants (flowers, cacti)

## Player Statistics

View server-wide player statistics:

- **Total Players** - All-time unique players
- **Online Count** - Currently connected
- **Peak Today** - Highest concurrent today
- **Average Playtime** - Per player
- **Total Playtime** - Server-wide

### Activity Tracking

- Daily activity graphs
- Configurable time range
- Join/leave events logged

## API Reference

### Player Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/players` | Online players |
| GET | `/api/players/all` | All players with status |
| GET | `/api/players/offline` | Offline players |
| GET | `/api/players/count` | Online count |
| GET | `/api/players/history` | All-time players |
| GET | `/api/players/statistics` | Server stats |
| GET | `/api/players/activity` | Activity data |

### Player Action Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/players/:name/kick` | Kick player |
| POST | `/api/players/:name/ban` | Ban player |
| DELETE | `/api/players/:name/ban` | Unban |
| POST | `/api/players/:name/whitelist` | Add to whitelist |
| DELETE | `/api/players/:name/whitelist` | Remove from whitelist |
| POST | `/api/players/:name/op` | Grant OP |
| DELETE | `/api/players/:name/op` | Revoke OP |
| POST | `/api/players/:name/teleport` | Teleport |
| POST | `/api/players/:name/kill` | Kill |
| POST | `/api/players/:name/respawn` | Respawn |
| POST | `/api/players/:name/gamemode` | Change gamemode |
| POST | `/api/players/:name/give` | Give item |
| POST | `/api/players/:name/heal` | Heal |
| POST | `/api/players/:name/effect` | Apply effect |
| POST | `/api/players/:name/inventory/clear` | Clear inventory |
| POST | `/api/players/:name/message` | Send message |

### Data Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/players/:name/deaths` | Death history |
| GET | `/api/players/:name/deaths/last` | Last death |
| GET | `/api/players/:name/chat` | Chat history |
| POST | `/api/players/:name/teleport/death` | Teleport to death |

## Permissions

| Permission | Description |
|------------|-------------|
| `players.view` | View player list |
| `players.edit` | Edit player data |
| `players.kick` | Kick players |
| `players.ban` | Ban players |
| `players.unban` | Unban players |
| `players.whitelist` | Manage whitelist |
| `players.op` | Manage operator status |
| `players.permissions` | Manage permissions |
| `players.teleport` | Teleport players |
| `players.kill` | Kill players |
| `players.respawn` | Respawn players |
| `players.gamemode` | Change gamemode |
| `players.give` | Give items |
| `players.heal` | Heal players |
| `players.effects` | Manage effects |
| `players.clear_inventory` | Clear inventory |
| `players.message` | Send messages |

## Data Storage

### Player Files

Location: `/opt/hytale/server/universe/players/`

Each player has a JSON file containing:
- Inventory
- Stats (health, stamina, etc.)
- Position
- Gamemode
- Death positions
- Discovered zones

### Server Lists

- `whitelist.json` - Whitelisted players
- `bans.json` - Banned player UUIDs
- `ops.json` - Operators

### Chat Logs

- Daily chat log files
- Contains full message content
- Player name and UUID
- Timestamps