hytale-plugin-basics

Hytale Plugin Development Basics

Complete guide for creating Hytale server plugins following the official architecture patterns.

When to use this skill

Use this skill when:

• Creating a new Hytale plugin from scratch
• Setting up plugin project structure
• Configuring plugin manifest (manifest.json)
• Understanding plugin lifecycle hooks
• Registering commands, events, or components
• Managing plugin dependencies

Plugin Architecture Overview

Hytale plugins are Java-based extensions that run on the server. They follow an ECS (Entity Component System) architecture with lifecycle management.

Plugin Types

Type	Location	Description
Core Plugins	Registered programmatically	Built-in server functionality
Builtin Plugins	server.jar/../builtin/	Shipped with server
External Plugins	mods/ directory	User-installed plugins
Early Plugins	earlyplugins/	Bytecode transformers (advanced)

Plugin Lifecycle States

NONE -> SETUP -> START -> ENABLED -> SHUTDOWN -> DISABLED

Project Structure

my-plugin/
├── src/
│   └── main/
│       ├── java/
│       │   └── com/example/myplugin/
│       │       ├── MyPlugin.java
│       │       ├── commands/
│       │       ├── events/
│       │       ├── components/
│       │       └── systems/
│       └── resources/
│           ├── manifest.json
│           └── assets/           # Optional asset pack
│               └── Server/
│                   └── Content/
├── build.gradle
└── settings.gradle

Plugin Manifest (manifest.json)

Required file in JAR root defining plugin metadata:

{
  "Group": "com.example",
  "Name": "MyPlugin",
  "Version": "1.0.0",
  "Description": "My awesome Hytale plugin",
  "Authors": [
    {
      "Name": "Author Name",
      "Email": "[email protected]",
      "Url": "https://example.com"
    }
  ],
  "Website": "https://example.com/myplugin",
  "Main": "com.example.myplugin.MyPlugin",
  "ServerVersion": ">=1.0.0",
  "Dependencies": {
    "Hytale:NPCPlugin": ">=1.0.0"
  },
  "OptionalDependencies": {
    "Hytale:TeleportPlugin": "*"
  },
  "LoadBefore": {
    "Hytale:SomeOtherPlugin": "*"
  },
  "DisabledByDefault": false,
  "IncludesAssetPack": true
}