Racial_Town 1.5

# HotelRoom - Territory × Race Evolution RPG Plugin

---

## 📌 Plugin Overview

**HotelRoom** is a high-quality RPG enhancement plugin designed for Minecraft Paper servers, perfectly combining **Territory Management** with **Race Evolution System**. Players can build their homes while experiencing unique growth paths of different races, creating an immersive survival adventure experience.

**One-line Introduction**: Territory × Race Evolution, creating immersive RPG survival experience.

---

## ✨ Core Features

### 🏠 Territory System

Complete territory management system with three territory types:

| Type | Description | Use Case |

|------|-------------|----------|

| **Private Territory** | Player's exclusive private space with full protection | Personal residence, private storage |

| **Public Territory** | Multi-player shared area, claimable | Apartment buildings, community housing |

| **Official Territory** | Server official managed areas | Shops, office areas, public facilities |

**Key Features**:

- 🔒 Complete block protection mechanism

- 👥 Member permission management

- 🏆 Honor threshold settings

- 💾 Auto facade snapshot, auto-restore after restart

- 🗺️ Intuitive GUI navigation interface

---

### 🧬 Race Evolution System

Rich race system giving each player a unique growth path:

**Race Features**:

- 🧝 Multiple race choices (Human, Elf, Dwarf, etc.)

- 📈 Level growth system, attributes increase with level

- 🔄 Race evolution paths, unlock new abilities

- 🎨 Race-exclusive appearance changes

- 🎙️ Race-exclusive voice chat channel

**Growth Mechanics**:

- Kill monsters to gain race experience

- Complete quests for bonus experience rewards

- Race evolution unlocks powerful skills

---

### ⚔️ Custom Attribute System

Powerful attribute system supporting 20+ attributes:

**Offensive Attributes**:

| Attribute | Description |

|-----------|-------------|

| Physical Damage | Increases normal attack damage |

| Magic Damage | Increases magic attack damage |

| Crit Rate | Probability of triggering critical hit |

| Crit Damage | Damage multiplier on critical hit |

| Armor Penetration | Ignores target armor value |

| Magic Penetration | Ignores target magic defense |

**Defensive Attributes**:

| Attribute | Description |

|-----------|-------------|

| Physical Defense | Reduces physical damage taken |

| Magic Defense | Reduces magic damage taken |

| Armor Value | Base armor damage reduction |

| Dodge Rate | Probability of completely dodging attack |

| Block Rate | Probability of blocking attack |

**Survival Attributes**:

| Attribute | Description |

|-----------|-------------|

| Health | Maximum health cap |

| Health Regen | Health restored per second |

| Lifesteal | Restore health on attack |

| Mana | Mana cap |

| Mana Regen | Mana restored per second |

**Utility Attributes**:

| Attribute | Description |

|-----------|-------------|

| Movement Speed | Movement speed bonus |

| Attack Speed | Attack frequency bonus |

| Cooldown Reduction | Skill cooldown reduction |

| EXP Bonus | Increased experience gain |

| Drop Bonus | Item drop rate increase |

**Equipment Attributes**:

- Support adding attributes in item Lore

- Auto-apply when equipment is worn

- Support percentage and fixed value bonuses

---

### 👨‍👩‍👧‍👦 Family System

Complete family social system:

**Family Features**:

- 🏰 Create family, establish power

- 👥 Invite members, grow team

- 📊 Family level, unlock privileges

- 💬 Family chat, exclusive channel

- 🎯 Family positions, permission management

**Position System**:

| Position | Permissions |

|----------|-------------|

| Leader | Full management permissions |

| Deputy | Invite/kick members |

| Member | Basic family features |

---

## 🎮 Commands

### Territory Commands

| Command | Description | Permission |

|---------|-------------|------------|

| `/hrlist` | Open territory list and navigation | - |

| `/hotelroom [subcommand]` | Main command | - |

| `/createhotel <name> [system]` | Create territory | `hotelroom.admin` |

| `/createpublichotel <name>` | Create public territory | `hotelroom.admin` |

| `/createofficialhotel <type> <name>` | Create official territory | `hotelroom.admin` |

| `/givehotel <territory> <player>` | Gift territory | `hotelroom.admin` |

| `/removehotel <territory>` | Remove territory | `hotelroom.admin` |

| `/abandon [territory]` | Abandon territory | - |

### Attribute Commands

| Command | Description | Permission |

|---------|-------------|------------|

| `/attr check [player]` | Check attributes | - |

| `/attr set <player> <attr> <value>` | Set attribute | `hotelroom.admin` |

| `/attr add <player> <attr> <value>` | Add attribute | `hotelroom.admin` |

| `/attr reset <player>` | Reset attributes | `hotelroom.admin` |

| `/attr reload` | Reload config | `hotelroom.admin` |

| `/attr item add <attr> <value>` | Add attribute to item | `hotelroom.admin` |

| `/attr item remove <line>` | Remove item attribute | `hotelroom.admin` |

| `/attr item list` | View item attribute list | - |

### Race Commands

| Command | Description | Permission |

|---------|-------------|------------|

| `/racegui` | Open race evolution interface | `hotelroom.race.gui` |

| `/changerace <race>` | Change race | - |

| `/racevoice` | Race voice chat | - |

| `/raceexp give <player> <amount>` | Give race experience | `hotelroom.admin` |

| `/raceexp set <player> <level>` | Set race level | `hotelroom.admin` |

| `/raceexp check <player>` | Check race info | `hotelroom.admin` |

### Family Commands

| Command | Description | Permission |

|---------|-------------|------------|

| `/family` | Open family main interface | `hr.family.use` |

| `/family create <name>` | Create family | `hr.family.create` |

| `/family invite <player>` | Invite player | `hr.family.invite` |

| `/family kick <player>` | Kick member | `hr.family.kick` |

| `/family leave` | Leave family | `hr.family.use` |

| `/family info` | View family info | `hr.family.use` |

---

## 🔌 API & PAPI Variables

### PlaceholderAPI Variables

#### Player Related

| Variable | Description |

|----------|-------------|

| `%hotelroom_player_honor%` | Player honor value |

| `%hotelroom_player_health%` | Current health |

| `%hotelroom_player_max_health%` | Max health |

| `%hotelroom_player_health_percent%` | Health percentage |

#### Attribute Related

| Variable | Description |

|----------|-------------|

| `%hotelroom_attr_<attribute>%` | Specified attribute value |

| `%hotelroom_all_attributes%` | All attributes list |

#### Territory Related

| Variable | Description |

|----------|-------------|

| `%hotelroom_in_land%` | Whether in territory |

| `%hotelroom_land_name%` | Current territory name |

| `%hotelroom_land_owner%` | Territory owner |

| `%hotelroom_land_honor%` | Territory honor threshold |

| `%hotelroom_in_public_hotel%` | Whether in public hotel |

| `%hotelroom_public_members_count%` | Public territory member count |

#### Race Related

| Variable | Description |

|----------|-------------|

| `%hotelroom_race%` | Current race name |

| `%hotelroom_race_name%` | Race internal ID |

| `%hotelroom_is_race_<race>%` | Whether specified race |

#### Family Related

| Variable | Description |

|----------|-------------|

| `%hotelroom_family_name%` | Family name |

| `%hotelroom_family_position%` | Family position |

| `%hotelroom_family_level%` | Family level |

| `%hotelroom_family_member_count%` | Member count |

#### Mob Related

| Variable | Description |

|----------|-------------|

| `%hotelroom_mob_health%` | Targeted mob current health |

| `%hotelroom_mob_max_health%` | Targeted mob max health |

| `%hotelroom_mob_health_percent%` | Targeted mob health percentage |

| `%hotelroom_mob_name%` | Targeted mob name |

### Developer API

```java

// Get attribute manager

AttributeManager manager = AttributeManager.getInstance();

// Get player attributes

PlayerAttribute attr = manager.getPlayerAttribute(player.getUniqueId());

double damage = attr.getAttribute("physical_damage");

// Set player attribute

manager.setPlayerAttributeValue(uuid, "physical_damage", 50.0);

manager.refreshPlayerAttributes(player);

// Get territory info

HotelInfo hotel = SelectionMgr.HOTELS.get("territory_name");

if (hotel != null) {

    UUID owner = hotel.owner;

    boolean isPublic = hotel.isPublic;

    Location[] corners = hotel.corners;

}

// Check if player is in territory

HotelInfo currentHotel = ProtectionListener.getHotelAt(player.getLocation());

```

---

## ⚙️ Configuration

### File Structure

```

plugins/HotelRoom/

├── config.yml              # Main config file

├── hotels.db               # SQLite database

├── attributes/

│   └── attributes.yml      # Attribute system config

└── races/

    ├── human.yml           # Human race config

    ├── elf.yml             # Elf race config

    └── dwarf.yml           # Dwarf race config

```

### Custom Attribute Example

```yaml

custom-attributes:

  true_damage:

    display-name: "§c⚡ True Damage"

    default-value: 0.0

    min-value: 0.0

    max-value: 1000.0

    type: offensive

    trigger: on_attack

    formula: "damage + {true_damage}"

    ignore-defense: true

    description: "Deals defense-ignoring extra damage"

```

---

## 📋 Permissions

| Permission | Description | Default |

|------------|-------------|---------|

| `hotelroom.admin` | Admin permission | OP |

| `hotelroom.attr.others` | View others' attributes | OP |

| `hotelroom.race.gui` | Use race evolution GUI | Everyone |

| `hr.family.use` | Use family system | Everyone |

| `hr.family.create` | Create family | Everyone |

| `hr.family.admin` | Family admin | OP |

| `hr.family.invite` | Invite family members | OP |

| `hr.family.kick` | Kick family members | OP |

---

## 📥 Installation

### Requirements

- **Server**: Paper 1.21.4 or higher

- **Java**: JDK 21 or higher

- **Optional Dependencies**:

  - PlaceholderAPI (Recommended)

  - MythicMobs (Optional)

  - CustomMoney (Optional)

### Installation Steps

1. Download the latest HotelRoom.jar

2. Place the file in server's `plugins` folder

3. Start server, wait for config files to generate

4. Modify config files as needed

5. Use `/attr reload` to reload config or restart server

---

## 🔄 Changelog

### v1.5

- Added Family System

- Optimized attribute calculation performance

- Fixed territory protection issues

- Added race voice feature

- Improved API interfaces

---

## 💬 Support

- **Bug Reports**: Please submit via GitHub Issues

- **Feature Requests**: Welcome to discuss in Discussions

- **Usage Questions**: Please check documentation first

---

## 📜 License

This project is open-sourced under **Apache 2.0** License.

---

<div align="center">

**If this plugin helps you, please give a ⭐ Star!**

Made with ❤️ by HUD

</div>