B-Side Adventure RPG Exploration

An exploratory Hytale server mod showcasing RPG mechanics and modding concepts. This project demonstrates how to build plugin systems for Hytale, serving as a learning resource for the modding community.

Screenshots

XP bar and level display integrated with the game HUD

Quest objectives using Hytale's built-in Objectives plugin

Custom UI page with navigation tabs

What This Project Demonstrates

Plugin Architecture

• Plugin lifecycle management (JavaPlugin, setup(), start(), shutdown())
• Event registration and handling
• Optional plugin dependencies via reflection
• Asset pack integration

ECS (Entity Component System)

• Custom damage event systems (DamageEventSystem)
• Entity stat access and modification
• Stat modifiers (additive bonuses)
• Detecting lethal damage before entity removal

Custom UI

• Interactive UI pages with navigation (InteractiveCustomUIPage)
• HUD overlays with progress bars (CustomUIHud)
• UI command builders and event bindings
• Hytale's UI DSL syntax

Player Data

• Player data persistence patterns
• JSON storage implementation
• Pluggable storage interface design

Quest/Objective System

• Custom objective completion handlers
• Integration with built-in Objectives plugin
• Quest definitions via JSON assets

Features

• Experience & Leveling - Gain XP by defeating enemies, level up your character
• Character Stats - Health, Stamina, Mana display with level-based bonuses
• Character Menu - Multi-page UI with navigation tabs
• Starter Quests - Example quest chain using the Objectives system
• XP HUD - Real-time level and progress bar overlay

UI Pages (Exploration)

The character menu includes placeholder pages demonstrating UI scaffolding:

Page	Status	Purpose
Character	Implemented	Shows player stats and level
Talents	Scaffold	Example of a planned feature page
Professions	Scaffold	Example of a planned feature page
Achievements	Scaffold	Example with placeholder content

Installation

1. Place BSideAdventureRPG-x.x.x.jar in your server's mods/ folder
2. Start the server

Commands

Command	Description
/character	Opens the character stats menu

Project Structure

src/main/java/com/bsidegames/adventurerpg/
├── BSideAdventureRPG.java      # Main plugin class
├── config/                      # Configuration management
├── experience/                  # XP system & ECS damage listener
├── player/                      # Player data management
├── storage/                     # Pluggable storage interface
├── objectives/                  # Custom quest completions
└── ui/                          # Custom UI pages & HUD

src/main/resources/
├── manifest.json                # Plugin manifest
├── config.json                  # Default configuration
├── Common/UI/Custom/            # UI templates
└── Server/Objective/            # Quest definitions

Configuration

{
  "maxLevel": 100,
  "debugMode": false,
  "hardcoreMode": false
}

Known Issues

Bounty tasks in questlines: When a Bounty objective completes and the next objective is also a Bounty, the server crashes with:

IllegalStateException: Store is currently processing!

This is a Hytale bug - the system tries to spawn the next NPC during ECS processing. Workaround: Don't have consecutive Bounty objectives, or put non-spawning objectives (Gather) between them.

Open Questions

I was not able to figure out yet, if we can indeed modify/overwrite existing UI without CustomUI on top.

Contributing

Contributions welcome! This is a learning resource - feel free to:

• Add examples of other Hytale modding patterns
• Improve documentation and code comments
• Implement the placeholder features
• Fix bugs or improve existing code

License

MIT License - Use freely for any purpose.

---

Made by B-Side Games GmbH