Server/src/engine/documentation/Handler Specific Documentation/dbPlayerCharacterHandler_Documentation.md

# Player Character Handler Documentation

## Overview
This document describes the database relationships and interactions for the `dbPlayerCharacterHandler` class. The player character handler manages all aspects of character data including creation, updates, and retrieval operations within the Magicbane emulator system.

## Handler Class
**File:** `src/engine/db/handlers/dbPlayerCharacterHandler.java`
**Class:** `dbPlayerCharacterHandler`
**Extends:** `dbHandlerBase`

## Database Tables

### Main Character Table
- **Table Name:** `obj_character`
- **Description:** Core character information including attributes, stats, and personal details
- **Columns:** 
  - UID (Primary Key)
  - char_firstname
  - char_lastname
  - char_isActive
  - char_raceID
  - char_baseClassID
  - char_promotionClassID
  - char_strMod
  - char_dexMod
  - char_conMod
  - char_intMod
  - char_spiMod
  - char_experience
  - char_skinColor
  - char_hairColor
  - char_hairStyle
  - char_beardColor
  - char_beardStyle
  - char_bindBuilding
  - guildUID
  - guild_isInnerCouncil
  - guild_isRecruiter
  - guild_isTaxCollector
  - guild_isFullMember
  - guild_title
  - anniversery
  - hash

### Related Tables

| Table Name | Description | Relationship |
|------------|-------------|--------------|
| `dyn_character_ignore` | Stores character ignore lists for players | accountUID → obj_account.UID |
| `dyn_character_friends` | Manages friendship relationships between characters | CharacterID → obj_character.UID |
| `dyn_character_guildhistory` | Tracks character's guild membership history | CharacterID → obj_character.UID, GuildID → obj_guild.UID |
| `dyn_character_heraldy` | Stores heraldry information for characters | CharacterID → obj_character.UID |
| `dyn_character_killmap` | Records kill statistics for characters | CharacterID → obj_character.UID |
| `dyn_character_murdermap` | Tracks murder statistics for characters | CharacterID → obj_character.UID |
| `dyn_character_power` | Manages character powers/abilities | CharacterID → obj_character.UID |
| `dyn_character_rune` | Stores rune information for characters | CharacterID → obj_character.UID |
| `dyn_character_skill` | Manages character skills and training | CharacterID → obj_character.UID |

## Key Queries

### Create New Character
```sql
CALL `character_CREATE`(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
```
**File:** `dbPlayerCharacterHandler.java`, Line ~35

### Get Characters for Account
```sql
SELECT `obj_character`.*, `object`.`parent` FROM `object` INNER JOIN `obj_character` ON `obj_character`.`UID` = `object`.`UID` WHERE `object`.`parent`=? && `obj_character`.`char_isActive`='1';
```
**File:** `dbPlayerCharacterHandler.java`, Line ~109

### Get All Active Characters
```sql
SELECT `obj_character`.*, `object`.`parent` FROM `object` INNER JOIN `obj_character` ON `obj_character`.`UID` = `object`.`UID` WHERE `obj_character`.`char_isActive`='1';
```
**File:** `dbPlayerCharacterHandler.java`, Line ~127

### Get Character by UID
```sql
SELECT `obj_character`.*, `object`.`parent` FROM `object` INNER JOIN `obj_character` ON `obj_character`.`UID` = `object`.`UID` WHERE `object`.`UID` = ?
```
**File:** `dbPlayerCharacterHandler.java`, Line ~185

### Get Character by Name
```sql
SELECT `char_firstname` FROM `obj_character` WHERE `char_isActive`=1 && `char_firstname`=?
```
**File:** `dbPlayerCharacterHandler.java`, Line ~203

### Update Character Name
```sql
UPDATE `obj_character` SET `char_firstname`=?, `char_lastname`=? WHERE `char_firstname`=? AND `char_isActive`='1'
```
**File:** `dbPlayerCharacterHandler.java`, Line ~222

### Set Character Ignore List
```sql
INSERT INTO `dyn_character_ignore` (`accountUID`, `ignoringUID`, `characterName`) VALUES (?, ?, ?)
```
**File:** `dbPlayerCharacterHandler.java`, Line ~83

### Get Character Ignore List
```sql
SELECT * FROM `dyn_character_ignore` WHERE `accountUID` = ?
```
**File:** `dbPlayerCharacterHandler.java`, Line ~151

## Relationships

1. **Character to Account:** Many-to-one (via `obj_character.parent` field referencing `obj_account.UID`)
2. **Character to Guild:** Many-to-one (via `obj_character.guildUID` field)
3. **Character to Ignore List:** One-to-many (via `dyn_character_ignore.accountUID`)
4. **Character to Friends List:** One-to-many (via `dyn_character_friends.CharacterID`)
5. **Character to Guild History:** One-to-many (via `dyn_character_guildhistory.CharacterID`)
6. **Character to Heraldry:** One-to-one (via `dyn_character_heraldy.CharacterID`)
7. **Character to Skills:** One-to-many (via `dyn_character_skill.CharacterID`)
8. **Character to Powers:** One-to-many (via `dyn_character_power.CharacterID`)
9. **Character to Runes:** One-to-many (via `dyn_character_rune.CharacterID`)

## Java Field to Database Column Mappings

| Java Field | Database Column | Notes |
|------------|-----------------|-------|
| `firstName` | `obj_character.char_firstname` | Character's first name |
| `lastName` | `obj_character.char_lastname` | Character's last name |
| `isActive` | `obj_character.char_isActive` | Boolean flag for active status |
| `race` | `obj_character.char_raceID` | Race identifier |
| `baseClass` | `obj_character.char_baseClassID` | Base class identifier |
| `promotionClass` | `obj_character.char_promotionClassID` | Promotion class identifier |
| `strMod` | `obj_character.char_strMod` | Strength modifier |
| `dexMod` | `obj_character.char_dexMod` | Dexterity modifier |
| `conMod` | `obj_character.char_conMod` | Constitution modifier |
| `intMod` | `obj_character.char_intMod` | Intelligence modifier |
| `spiMod` | `obj_character.char_spiMod` | Spirit modifier |
| `exp` | `obj_character.char_experience` | Experience points |
| `skinColor` | `obj_character.char_skinColor` | Skin color value |
| `hairColor` | `obj_character.char_hairColor` | Hair color value |
| `hairStyle` | `obj_character.char_hairStyle` | Hair style identifier |
| `beardColor` | `obj_character.char_beardColor` | Beard color value |
| `beardStyle` | `obj_character.char_beardStyle` | Beard style identifier |
| `bindBuilding` | `obj_character.char_bindBuilding` | Bind building UID |
| `guildUID` | `obj_character.guildUID` | Guild identifier |
| `isInnerCouncil` | `obj_character.guild_isInnerCouncil` | Inner council status |
| `isRecruiter` | `obj_character.guild_isRecruiter` | Recruiter status |
| `isTaxCollector` | `obj_character.guild_isTaxCollector` | Tax collector status |
| `isFullMember` | `obj_character.guild_isFullMember` | Full member status |
| `guildTitle` | `obj_character.guild_title` | Guild title identifier |
| `anniversery` | `obj_character.anniversery` | Anniversary flag |