BusinessesCore

A full-featured, modular business simulation plugin for Hytale. Players create and run businesses, hire workers, fulfill customer orders, compete server-wide, and grow through an upgrade system. All through a native in-game UI.

Architecture

BusinessesCore is built natively on Hytale's ECS (Entity Component System). All UI screens use the native InteractiveCustomUIPage system. Business state is managed entirely server-side through typed managers, with no client-side trust.

Modules are separate JARs that register themselves against the core API at startup. The core never imports module code directly; modules implement the BusinessModule interface and are discovered at runtime.

Installation

Core plugin

1. Drop BusinessesCore.jar into your server's plugins/ folder.
2. Start the server once; config files are generated automatically in plugins/BusinessesCore/.
3. Edit settings.json and lang.json as needed.
4. Restart or reload.

Modules (add-ons)

1. Download the module JAR from the plugin page.
2. Drop the module JAR into the same plugins/ folder alongside the core.
3. Start the server; the module registers itself and generates its own config files.

Generated files

Quick Start

As a server admin

1. Install the plugin and start your server.
2. Give yourself OP or the businesses.admin permission.
3. Run /business create MyShop foodshop to create a test business.
4. Run /business setmanager <businessId> <yourName> to assign yourself as manager.
5. Run /business manage to set a warp point and core location.
6. Toggle on-service from /business info.
7. A second player can now run /business browse and place an order.

As a player

1. Run /business browse to see open businesses.
2. Warp to one with /business warp <id>.
3. Run /order at the business location to place an order.
4. Wait for a worker to accept — a progress bar shows in your HUD.
5. Collect your items when complete and leave a review with /business review <id> <1-5> <comment>.

Commands

All commands use the /business root. Arguments in <angle brackets> are required; [square brackets] are optional.

Player commands

Available to any player on the server.

Worker commands

Available to any player who is a member (worker or manager) of a business.

Manager commands

Available to the designated manager of a business (or OP players).

Admin commands

Require the businesses.admin permission or OP.

Permissions

Configuration — Economy

Located under the Economy block in settings.json.

Configuration — Business

Located under the Business block in settings.json.

Configuration — Anti-Exploit

Located under the AntiExploit block in settings.json.

Configuration — Competition

Located under the Competition block in settings.json.

Configuration — Database

Located under the Database block in settings.json.

Language Keys — Core

All messages are in lang.json. Values support MiniMessage formatting. The placeholder {prefix} is replaced by the configured prefix (default: <dark_gray>[Businesses]</dark_gray>).

General

Business creation & management

Workers

Orders

Warp

Competition

Reviews

Messaging

Order Lifecycle

Every order moves through a defined set of statuses managed by OrderManager.

Worker System

Roles

Workers have a role (Worker / Manager) and a level (Trainee / Skilled / Expert). Both affect wage multipliers.

• Only one manager per business. The manager is set by an admin with /business setmanager.
• Promote/demote level with /business promote and /business demote.
• Higher levels = higher wageMultiplier and speedMultiplier.

On/Off service

Workers toggle their service status from the business dashboard (/business info). Only on-service workers receive order notifications and can accept orders. Off-service workers are invisible to the order system.

Movement enforcement

When a worker accepts an order their position is recorded. Every 2 seconds, OrderManager checks if they have moved more than WorkerTaskMoveLimit blocks from that position. If so, they are teleported back and notified — the order is not cancelled.

A broader proximity check runs every 10 seconds. Workers farther than WorkerProximityRadius from the business core are automatically taken off service.

Wages

Every PaymentIntervalSeconds, the payment cycle runs:

1. Each worker's receipts (completed orders) count is read.
2. Wage = (receipts × PayPerReceipt + BaseWagePerInterval) × roleMultiplier × levelMultiplier × upgradeWageMultiplier
3. Wage is deposited to the worker's personal balance and deducted from the business balance.
4. Receipt count is reset to 0.

Economy System

BusinessesCore ships with a built-in economy (BuiltInEconomy). Balances are stored per-player UUID and persisted to disk.

• Player balances are separate from business balances.
• Customers pay from their personal balance into the business balance when an order is confirmed.
• Workers receive wages from the business balance into their personal balance.
• Refunds go back to the customer's personal balance. No money is created or destroyed on refund.

Upgrade System

Businesses start at level 1 and can be upgraded by spending business balance. Each upgrade level provides multipliers that affect worker wages, order speed, and pricing.

• Upgrade costs, worker slot increases, and multipliers are all configured in the upgrades section of settings.json.
• Managers access the upgrade screen via /business upgrade.
• The business must have sufficient balance — the cost is deducted automatically.
• UpgradeManager.getWorkSpeedMultiplier(moduleId, level) is applied to task duration at order confirmation time.
• UpgradeManager.getPriceMultiplier(moduleId, level) adjusts the final price shown to customers.

Competition System

Server-wide vote competitions where players vote for their favourite businesses. At the end of each cycle, the top-ranked businesses receive a balance reward.

• Players vote with /business vote <id>. One vote per player. Changing your vote removes it from the previous business.
• Workers cannot vote for their own business.
• Rankings are visible in /business leaderboard.
• With AutoStart: true, a new cycle starts automatically when the previous one ends.
• Admins can manually start/end cycles regardless of AutoStart with /business competition start and /business competition end.
• Winners are announced server-wide via the CompBroadcastWinner message (one per reward rank).

Review System

Customers who have completed at least one order at a business can leave a star rating (1-5) with a comment.

• One review per customer per business. Cannot be changed after submission.
• Workers cannot review their own business.
• Average rating is calculated from all reviews and shown in the browse UI, dashboard, and business cards.
• Ratings display as 4.7/5 with trailing .0 omitted (e.g. 4/5).

Customer Messaging

Customers can send a message to a business's on-service workers without placing an order.

• Command: /business contact <id> — opens a text picker, sends selected message to all on-service workers.
• Subject to ContactCooldown configured in anti-exploit settings.
• The business dashboard shows an inquiry banner when a message is pending. Workers can reply via /business reply or the reply button on the dashboard.
• Replies use preset quick-response strings shown in a picker UI.
• Only the most recent inquiry is kept per business.

Pending Messages

Messages can be queued for offline players using BusinessesAPI.sendOrQueue(uuid, rawTinyMessage). If the player is online the message is delivered immediately; if offline it is stored and delivered on their next login. Modules can also use BusinessesAPI.queueMessage(uuid, raw) to force a message to appear specifically at login.

Anti-Exploit

Multiple layers protect against economy farming:

• Self-order block — workers cannot order from their own business.
• Order cooldown — minimum time between orders at the same business.
• Worker-customer cooldown — a worker cannot serve the same customer repeatedly.
• Max concurrent orders — limits how many orders a customer can have open at one business.
• IP check (optional) — blocks orders between players on the same IP.
• Movement enforcement — workers are teleported back if they leave their task position.
• Proximity enforcement — workers are auto-removed from service if they leave the business area.

Module — Food Shop

Adds a foodshop business type. Workers prepare food orders for customers. All menu items, prices, and item IDs are configurable. Customers can order multiple units of the same item in one order.

Order flow

1. Customer opens /order at the food shop, selects a food item.
2. If MaxQuantityPerOrder > 1, a quantity picker is shown (1 to max).
3. Order is placed and all on-service workers are notified.
4. A worker accepts from /business orders — cooking begins immediately.
5. After the cooking duration (scaled by quantity × upgrade speed multiplier), the food is delivered to the customer's inventory.

Food Shop Settings

File: FoodShop/settings.json

Items are stored as a JSON array — add or remove entries freely. No item count field, no numbered slots. Admins can also supply their own custom Hytale item IDs.

Food Shop Language Keys

File: FoodShop/lang.json

Module — Tool Repair Shop

Adds a toolrepair business type. Customers drop damaged tools; workers repair them and return them fully restored. Three service tiers with configurable pricing per item.

Order flow

1. Customer opens /order at the repair shop and selects a repair tier (Basic / Advanced / Instant).
2. Order is created with isReadyForWorker = false — workers cannot see it yet.
3. Customer is prompted to drop damaged tools from their hotbar. Each drop is intercepted — only items with maxDurability > 0 are accepted.
4. After dropping items, the customer opens /order and clicks Confirm & Pay. This finalises the price and makes the order visible to workers.
5. A worker accepts from /business orders. The customer is charged, the repair task begins.
6. After the repair duration, items are returned to the customer at full durability.

Pricing formula

Tool Repair Settings

File: ToolRepairShop/settings.json

Service tiers are stored as a JSON array — add or remove tiers freely, no ServiceCount field needed.

Tool Repair Language Keys

File: ToolRepairShop/lang.json

Module API

To create a custom module, implement BusinessModule and register it with BusinessesAPI.registerModule() during plugin startup.

ModuleItemConfig — per-module config base class

All modules that expose a configurable list of items or service tiers should define a local ModuleItemConfig abstract class inside their own module package. This base provides the four fields common to every module: Id, DisplayName, Description, MinLevel.

Step 1 — copy this base class into your module's settings file:

Step 2 — declare the array field in the outer settings class:

The resulting settings.json is a clean, human-readable array:

ServiceDefinition

Database Providers

The storage layer is abstracted behind DatabaseProvider. Implement it to plug in any storage backend.

Register your provider in Main.initDatabase() by setting the DatabaseType to your type key and returning your implementation from the factory.

Custom Economy Provider

By default BusinessesCore uses its own built-in coin economy. You can replace it with any external economy system by implementing the EconomyProvider interface and registering it during your plugin's setup().

Register your provider from your economy plugin's setup() method:

The provider is also accessible to modules via BusinessesAPI:

HytaleBase

BusinessesCore and all its modules are built on top of HytaleBase, an open-source utility library for Hytale plugins. It provides EasyConfig, EasyConfigBuilder, TinyMessage, command abstractions, and other shared infrastructure.

HytaleBase is publicly available on GitHub:

When building a module, include HytaleBase as a dependency so your module has access to the same utilities (EasyConfig, ArrayCodec, TinyMessage, etc.) without duplicating code. All HytaleBase classes are provided by the server at runtime — do not shadow-jar them into your module.