Plugin Manifest (manifest.json)

Plugin Manifest (manifest.json)

Every Hytale plugin requires a manifest.json manifest file in its root directory. This file defines essential metadata about your plugin, including its identity, version, dependencies, and entry point.

Package Location

com.hypixel.hytale.common.plugin.PluginManifest

Location

The manifest file must be placed at the root of your plugin JAR:

• Directorymy-plugin.jar

  • manifest.json # Required manifest file
  • Directorycom/

    • Directoryexample/

      • Directorymyplugin/

        • MyPlugin.class
  • Directoryassets/ # Optional asset pack

    • …

Full Schema Reference

{
  "Group": "com.example",
  "Name": "MyPlugin",
  "Version": "1.0.0",
  "Description": "A description of what this plugin does",
  "Authors": [
    {
      "Name": "Your Name",
      "Email": "you@example.com",
      "Url": "https://yourwebsite.com"
    }
  ],
  "Website": "https://github.com/example/my-plugin",
  "Main": "com.example.myplugin.MyPlugin",
  "ServerVersion": "1.0.0",
  "Dependencies": {
    "Hytale:OtherPlugin": ">=1.0.0"
  },
  "OptionalDependencies": {
    "Hytale:SomeOptional": "*"
  },
  "LoadBefore": {
    "Hytale:LoadAfterMe": "*"
  },
  "DisabledByDefault": false,
  "IncludesAssetPack": false,
  "SubPlugins": []
}

Field Reference

Required Fields

Name

Type: string (required)

The unique name of your plugin. This is used as the plugin’s identifier in combination with the Group.

{
  "Name": "MyAwesomePlugin"
}

Optional Fields

Group

Type: string

The organization or group namespace for your plugin. Similar to Maven group IDs. If not specified, defaults may be inherited from a parent plugin.

{
  "Group": "com.mycompany"
}

The full plugin identifier becomes Group:Name (e.g., com.mycompany:MyAwesomePlugin).

Version

Type: string (Semantic Versioning)

The version of your plugin following Semantic Versioning 2.0.0 format. This string is parsed into a Semver object internally.

{
  "Version": "1.2.3"
}

Supported formats:

• Basic: 1.0.0
• With pre-release: 1.0.0-alpha.1
• With build metadata: 1.0.0+build.123
• Combined: 1.0.0-beta.2+build.456

Description

Type: string

A human-readable description of what your plugin does.

{
  "Description": "Adds custom weather effects and seasonal changes to your server"
}

Authors

Type: AuthorInfo[]

An array of author information objects.

{
  "Authors": [
    {
      "Name": "John Doe",
      "Email": "john@example.com",
      "Url": "https://johndoe.dev"
    },
    {
      "Name": "Jane Smith"
    }
  ]
}

Each AuthorInfo object supports:

• Name (string, optional): Author’s display name
• Email (string, optional): Author’s contact email
• Url (string, optional): Author’s website or profile URL

Website

Type: string

The official website or repository URL for your plugin.

{
  "Website": "https://github.com/mycompany/my-plugin"
}

Main

Type: string

The fully qualified class name of your plugin’s main class. This class must extend JavaPlugin.

{
  "Main": "com.example.myplugin.MyPlugin"
}

ServerVersion

Changed in Update 3

ServerVersion is now stored as a plain String instead of a parsed SemverRange. The getServerVersion() method on PluginManifest returns String instead of SemverRange. A setServerVersion(@Nullable String) setter was also added. Version validation was changed from semver range comparison to a string equality check in the PluginManager. The Update 3 changelog covers all manifest-related changes.

Type: string

Specifies which server version your plugin is compatible with. Since Update 3, this is validated as a plain string equality check rather than a semver range comparison.

{
  "ServerVersion": "1.0.0"
}

Wildcard behavior

Using "*" or omitting ServerVersion entirely will log a warning: “Plugin does not specify a target server version. You may encounter issues, please check for plugin updates. This will be a hard error in the future”. Always set an exact version string for production plugins.

Dependencies

Type: Map<PluginIdentifier, SemverRange>

Plugins that must be loaded before this plugin. Keys are plugin identifiers in Group:Name format.

{
  "Dependencies": {
    "Hytale:WeatherPlugin": ">=1.0.0",
    "com.example:CoreLib": "^2.0.0"
  }
}

Important

If a dependency is missing or doesn’t satisfy the version range, your plugin will fail to load.

OptionalDependencies

Type: Map<PluginIdentifier, SemverRange>

Plugins that enhance functionality if present but aren’t required.

{
  "OptionalDependencies": {
    "Hytale:CraftingPlugin": "*"
  }
}

Your plugin loads regardless of whether optional dependencies are present. Use runtime checks to detect their availability.

LoadBefore

Type: Map<PluginIdentifier, SemverRange>

Specifies plugins that should load after this plugin. Useful for ensuring your plugin initializes first.

{
  "LoadBefore": {
    "Hytale:SomeOtherPlugin": "*"
  }
}

DisabledByDefault

Type: boolean

If true, the plugin won’t be enabled automatically on server start. Administrators must manually enable it.

{
  "DisabledByDefault": true
}

Default: false

IncludesAssetPack

Type: boolean

Set to true if your plugin JAR includes an embedded asset pack. The asset pack will be automatically registered when the plugin starts.

{
  "IncludesAssetPack": true
}

Default: false

Note

When enabled, the server will look for assets in your JAR and register them with the identifier Group:Name.

SubPlugins

Type: PluginManifest[]

An array of nested plugin manifests. Sub-plugins inherit values from their parent manifest if not explicitly specified.

{
  "SubPlugins": [
    {
      "Name": "MySubFeature",
      "Main": "com.example.myplugin.subfeature.SubFeaturePlugin",
      "Description": "Optional sub-feature of MyPlugin"
    }
  ]
}

Sub-plugins automatically:

• Inherit Group if not specified
• Inherit Version if not specified
• Inherit Description if not specified
• Inherit Authors if empty
• Inherit Website if not specified
• Inherit DisabledByDefault if not already true
• Add a dependency on the parent plugin

Minimal Example

The only field enforced by the manifest parser is Name, but Main is needed for the plugin to load a Java class:

{
  "Name": "MinimalPlugin",
  "Main": "com.example.MinimalPlugin"
}

Complete Example

A fully-featured manifest for a production plugin:

{
  "Group": "com.hytalemodding",
  "Name": "EnhancedWeather",
  "Version": "2.1.0",
  "Description": "Adds realistic weather systems including storms, fog, and seasonal effects",
  "Authors": [
    {
      "Name": "WeatherDev",
      "Email": "weather@hytalemodding.com",
      "Url": "https://hytalemodding.com/team/weatherdev"
    }
  ],
  "Website": "https://github.com/hytalemodding/enhanced-weather",
  "Main": "com.hytalemodding.weather.EnhancedWeatherPlugin",
  "ServerVersion": "1.0.0",
  "Dependencies": {
    "Hytale:WeatherPlugin": ">=1.0.0"
  },
  "OptionalDependencies": {
    "Hytale:AmbiencePlugin": "*"
  },
  "DisabledByDefault": false,
  "IncludesAssetPack": true
}

Related

• Plugin Lifecycle - Understanding plugin states and lifecycle methods
• JavaPlugin Class - The main plugin base class
• First Plugin Tutorial - Create your first plugin step by step