Installing Mods on a Hytale Server

Critical: Folder Location

mods/

plugins/

server/
├── mods/           ← PUT MODS HERE (.jar files)
│   ├── YourMod.jar
│   └── YourMod/    ← Config folder (auto-generated)
├── plugins/        ← OLD/WRONG location - mods won't load here
├── config.json     ← Server config
└── universe/       ← World data

Installation Steps

1. Download the Mod

.jar

2. Upload to Server

scp YourMod.jar user@server:/path/to/hytale/server/mods/

3. Restart Server

# For Docker:
cd /path/to/hytale && docker compose restart

# For bare metal:
# Stop → Start the server process

4. Verify Loading

docker logs hytale-server 2>&1 | grep -i 'YourModName'

[PluginManager] - com.author:ModName

5. Configure the Mod

mods/
└── com.author_ModName/
    └── ModName.json    ← Edit this file

Common Issues

Issue 1: Mod Not Loading

1. Wrong folder - Move from

   plugins/

   to

   mods/

2. Docker not mounting - Check

   docker-compose.yml

   volumes include

   ./server/mods:/server/mods

3. Mod not registered - Some mods need entry in

   config.json

   Mods section

Issue 2: Config Changes Not Applying

docker compose stop    # Not restart!
# Edit config
docker compose start

Issue 3: BlockCounter Limiting Features

BlockCounter.json

docker compose stop
# Reset the counter:
echo '{"BlockPlacementCounts":{}}' > server/universe/worlds/default/resources/BlockCounter.json
docker compose start

Issue 4: LuckPerms Not Found Warning

Docker Considerations

1. Volume mounts matter - Only mounted folders are accessible
2. File ownership - Files created by Docker may be owned by root
3. Restart vs Stop/Start - Use

   stop

   then

   start

   when editing files the server writes to

Typical docker-compose.yml volumes:

volumes:
  - ./server:/server
  - ./server/mods:/server/mods

Quick Reference

scp mod.jar host:/path/server/mods/

docker compose restart

docker compose stop

docker logs container 2>&1 | grep ModName

ls server/mods/com.author_ModName/

Pre-Built Mods vs Custom Development

Pre-Built Mods (CurseForge)

.jar

mods/

Packs (Data Mods) - CAN Create From Scratch ✅

hytale-pack-creator

• Add blocks, items, textures
• Override game configs (GameplayConfigs, etc.)
• Add translations

mods/YourPackName/

manifest.json

Java Plugins - CAN Create ✅ (but setup required)

1. Java 25 - Hard requirement, uses modern features
2. Extract API from HytaleServer.jar - Install to local Maven cache:
   bash

   mvn install:install-file \
       -Dfile="HytaleServer.jar" \
       -DgroupId=com.hypixel.hytale \
       -DartifactId=Server \
       -Dversion=1.0-SNAPSHOT \
       -Dpackaging=jar

3. Use community maven mirror:

   maven.hytale-modding.info/releases

4. Use

   hytale-mod

   Gradle plugin for build tooling

hytale-plugin-dev