Installation

This guide will walk you through downloading and installing HyperFactions on your Hytale server.

Requirements

Before installing HyperFactions, ensure you have:

• Hytale Server (Early Access)
• Java 25 or higher
• Recommended: HyperPerms or LuckPerms for permission management

Optional Dependencies

Download

Download the latest version of HyperFactions from one of these sources:

• GitHub Releases: github.com/HyperSystemsDev/HyperFactions/releases
• CurseForge: curseforge.com/hytale/mods/hyperfactions

Installation Steps

1. Stop Your Server

Before installing any mods, make sure your Hytale server is stopped. Type stop in the server console or use your hosting panel's stop button.

2. Install the Mod

Copy the HyperFactions-x.x.x.jar file to your server's mods folder:

your-server/
├── mods/
│   └── HyperFactions-0.8.0.jar  ← Place here
├── config.json
├── universe/
├── logs/
└── HytaleServer.jar

3. Start Your Server

Start your Hytale server. HyperFactions will automatically generate its configuration files on first run.

For instructions on starting your Hytale server, see the official Hytale Server Manual.

4. Install Optional Dependencies

VaultUnlocked (Economy):

If you want faction treasury features (deposits, withdrawals, transfers), install VaultUnlocked and an economy provider.

OrbisGuard-Mixins (Advanced Zone Flags):

For advanced zone flags like keep inventory, invincible items, NPC spawning control, and manual item pickup:

1. Install Hyxin as an early plugin (in earlyplugins/ folder)
2. Install OrbisGuard-Mixins in your mods/ folder
3. HyperFactions will detect it automatically on startup

5. Permission Setup

Using HyperPerms (Recommended):

Run these commands from the console or as an operator:

/hp group setperm default hyperfactions.use
/hp group setperm default hyperfactions.faction.*
/hp group setperm default hyperfactions.member.*
/hp group setperm default hyperfactions.territory.*
/hp group setperm default hyperfactions.teleport.*
/hp group setperm default hyperfactions.relation.*
/hp group setperm default hyperfactions.chat.*
/hp group setperm default hyperfactions.info.*
/hp group setperm default hyperfactions.economy.*

This grants all standard faction features (including economy) to the default group.

Using LuckPerms:

/lp group default permission set hyperfactions.use true
/lp group default permission set hyperfactions.faction.* true
/lp group default permission set hyperfactions.member.* true
/lp group default permission set hyperfactions.territory.* true
/lp group default permission set hyperfactions.teleport.* true
/lp group default permission set hyperfactions.relation.* true
/lp group default permission set hyperfactions.chat.* true
/lp group default permission set hyperfactions.info.* true
/lp group default permission set hyperfactions.economy.* true

For detailed permission information, see Permissions Reference.

6. Verify Installation

Once the server is running and permissions are configured, verify the installation:

/f help

If you see the HyperFactions help menu, the installation was successful!

Data Directory Structure

After installation, HyperFactions creates the following structure:

mods/com.hyperfactions_HyperFactions/
├── config.json               ← Main configuration
├── config/                   ← Module configurations
│   ├── announcements.json    ← Announcement settings
│   ├── backup.json           ← Backup settings
│   ├── chat.json             ← Chat formatting settings
│   ├── debug.json            ← Debug options
│   ├── economy.json          ← Economy/treasury settings
│   ├── faction-permissions.json  ← Default faction territory permissions
│   ├── gravestones.json      ← Gravestone integration settings
│   └── worldmap.json         ← World map display settings
├── backups/                  ← Automatic and manual backups
├── factions/                 ← Per-faction data files
│   └── {uuid}.json
├── players/                  ← Player power & preferences
│   └── {uuid}.json
└── zones.json                ← SafeZone and WarZone definitions

Troubleshooting

Mod Not Loading

If HyperFactions doesn't appear to load:

1. Check server logs for errors
2. Verify you're using Java 25 or higher
3. Ensure the JAR file is in the correct mods folder
4. Make sure the file isn't corrupted (re-download if needed)

Commands Not Working

If /f commands don't work:

1. Verify the mod loaded (check server startup logs)
2. Check permissions - Ensure you have the hyperfactions.use permission
3. Try /faction or /hf as alternatives
4. Confirm HyperPerms or your permission system is configured

Permission Denied Errors

If you see "Permission denied" messages:

1. Verify hyperfactions.use is granted to your group
2. Check that all required permission categories are granted
3. Use /hp player info <player> to verify permissions
4. See Permissions Reference for the full list

Updating HyperFactions

To update to a new version:

1. Create a backup using /f admin backup create pre-update
2. Stop your server
3. Replace the old JAR with the new one
4. Start your server
5. Run /f admin reload if prompted

Next Steps

Now that HyperFactions is installed:

1. Configure the mod to match your server's needs
2. Set up your first faction to test functionality
3. Review the Permissions Reference for complete access control