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 for permission management

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.4.3.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. 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.*

This grants all standard faction features to the default group.

For detailed permission information, see Permissions Reference.

5. 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
│   ├── backup.json           ← Backup settings
│   ├── chat.json             ← Chat formatting settings
│   ├── debug.json            ← Debug options
│   ├── economy.json          ← Economy integration settings
│   └── faction-permissions.json  ← Default faction territory permissions
├── 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