hytale-server-mods

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Installing Mods on a Hytale Server

在Hytale服务器上安装模组

This skill covers installing and configuring mods on a Hytale dedicated server.

本指南涵盖Hytale专用服务器上模组的安装与配置方法。

Critical: Folder Location

重点：文件夹位置

Mods go in the
mods/
folder, NOT
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

模组需放在
mods/
文件夹中，而非
plugins/
！

server/
├── mods/           ← 在此处放置模组（.jar文件）
│   ├── YourMod.jar
│   └── YourMod/    ← 自动生成的配置文件夹
├── plugins/        ← 旧的/错误的位置 - 模组无法在此加载
├── config.json     ← 服务器配置文件
└── universe/       ← 世界数据

Installation Steps

安装步骤

1. Download the Mod

1. 下载模组

Get the

.jar

file from CurseForge or other source.

从CurseForge或其他来源获取

.jar

文件。

2. Upload to Server

2. 上传至服务器

bash

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

bash

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

3. Restart Server

3. 重启服务器

bash

undefined

bash

undefined

For Docker:

针对Docker环境：

cd /path/to/hytale && docker compose restart

For bare metal:

针对裸金属服务器：

Stop → Start the server process

先停止服务器进程，再重新启动

undefined

undefined

4. Verify Loading

4. 验证加载状态

Check server logs for the mod name:

bash

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

Look for:

[PluginManager] - com.author:ModName

在服务器日志中查找模组名称：

bash

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

查找以下内容：

[PluginManager] - com.author:ModName

5. Configure the Mod

5. 配置模组

After first load, config folder appears:

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

Important: Stop the server before editing configs (server may overwrite on shutdown).

首次加载后，会生成配置文件夹：

mods/
└── com.author_ModName/
    └── ModName.json    ← 编辑此文件进行配置

重要提示： 编辑配置文件前请先停止服务器（服务器可能会在关闭时覆盖配置）。

Common Issues

常见问题

Issue 1: Mod Not Loading

问题1：模组无法加载

Symptom: No log messages, commands not working

Causes & Fixes:

Wrong folder - Move from
```
plugins/
```
to
```
mods/
```

Docker not mounting - Check

docker-compose.yml

volumes include

./server/mods:/server/mods

Mod not registered - Some mods need entry in
```
config.json
```
Mods section

症状： 无日志信息，模组命令无法生效

原因与解决方法：

文件夹错误 - 将模组从
```
plugins/
```
移动到
```
mods/
```
Docker未挂载目录 - 检查
```
docker-compose.yml
```
中的卷配置是否包含
```
./server/mods:/server/mods
```
模组未注册 - 部分模组需要在
```
config.json
```
的Mods部分添加条目

Issue 2: Config Changes Not Applying

问题2：配置更改未生效

Symptom: Edit config, restart, settings revert

Fix: Stop server completely before editing:

bash

docker compose stop    # Not restart!

症状： 编辑配置后重启服务器，设置恢复原状

解决方法： 编辑前完全停止服务器：

bash

docker compose stop    # 不要使用restart！

Edit config

编辑配置文件

docker compose start

undefined

docker compose start

undefined

Issue 3: BlockCounter Limiting Features

问题3：BlockCounter限制功能

Symptom: "Limit reached" even with mod configured for unlimited

Cause:

BlockCounter.json

tracks placements from before mod was active

Fix:

bash

docker compose stop

症状： 即使模组配置为无限制，仍显示“已达限制”

原因：

BlockCounter.json

会追踪模组激活前的方块放置记录

解决方法：

bash

docker compose stop

Reset the counter:

重置计数器：

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

undefined

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

undefined

Issue 4: LuckPerms Not Found Warning

问题4：LuckPerms未找到警告

Symptom: Log shows "LuckPerms API class not found"

Impact: Usually harmless - mod falls back to config file settings. Only install LuckPerms if you need per-rank permissions.

症状： 日志显示“LuckPerms API class not found”

影响： 通常无危害 - 模组会回退到配置文件设置。仅当您需要按权限组配置权限时，才需要安装LuckPerms。

Docker Considerations

Docker相关注意事项

The server runs in Docker, which means:

Volume mounts matter - Only mounted folders are accessible
File ownership - Files created by Docker may be owned by root
Restart vs Stop/Start - Use
```
stop
```
then
```
start
```
when editing files the server writes to

服务器运行在Docker环境中，意味着：

卷挂载至关重要 - 只有挂载的文件夹才会被服务器访问
文件所有权 - Docker创建的文件可能归root用户所有
Restart与Stop/Start的区别 - 编辑服务器会写入的文件时，请使用
```
stop
```
再
```
start
```

Typical docker-compose.yml volumes:

典型的docker-compose.yml卷配置：

yaml

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

yaml

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

Quick Reference

快速参考

Task	Command
Upload mod	`scp mod.jar host:/path/server/mods/`
Restart server	`docker compose restart`
Stop for config edit	`docker compose stop`
Check mod loaded	`docker logs container 2>&1 \| grep ModName`
View config folder	`ls server/mods/com.author_ModName/`

任务	命令
上传模组	`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)

预构建模组（CurseForge）

Download

.jar

from CurseForge → Put in

mods/

→ Configure → Done!

从CurseForge下载

.jar

文件 → 放入

mods/

→ 配置 → 完成！

Packs (Data Mods) - CAN Create From Scratch ✅

数据包（数据模组）- 可自行创建 ✅

Use the

hytale-pack-creator

skill to create Packs that:

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

Packs go in

mods/YourPackName/

with a

manifest.json

使用

hytale-pack-creator

工具创建数据包，实现以下功能：

添加方块、物品、纹理
覆盖游戏配置（GameplayConfigs等）
添加翻译内容

数据包需放在

mods/YourPackName/

目录下，并包含

manifest.json

文件。

Java Plugins - CAN Create ✅ (but setup required)

Java插件 - 可自行开发 ✅（但需完成相关配置）

You CAN create Java plugins. The setup requires:

Java 25 - Hard requirement, uses modern features

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

Use community maven mirror:
```
maven.hytale-modding.info/releases
```
Use
hytale-mod
Gradle plugin for build tooling

See

hytale-plugin-dev

skill for full setup guide.

您可以开发Java插件，配置步骤如下：

Java 25 - 硬性要求，需使用其现代特性

从HytaleServer.jar中提取API - 安装到本地Maven仓库：

bash

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

使用社区Maven镜像：
```
maven.hytale-modding.info/releases
```
使用
hytale-mod
Gradle插件进行构建

完整配置指南请参考

hytale-plugin-dev