144 lines
5.3 KiB
Markdown
144 lines
5.3 KiB
Markdown
# Getting Started with Hytale Server Modding
|
|
|
|
## Overview
|
|
|
|
The Hytale Server provides a comprehensive modding API that allows developers to extend and customize the game. This
|
|
documentation covers the essential systems and APIs available for mod development.
|
|
|
|
## Architecture Overview
|
|
|
|
The server is built on several core systems:
|
|
|
|
| System | Purpose |
|
|
|-------------------------------|----------------------------------------------------------------|
|
|
| Plugin System | Mod loading, lifecycle management, and dependency resolution |
|
|
| Entity Component System (ECS) | High-performance entity management with components and systems |
|
|
| Event System | Prioritized event dispatching with sync/async support |
|
|
| Command System | Player and console command handling |
|
|
| Asset System | Game asset loading and registration |
|
|
| Codec System | Data serialization/deserialization framework |
|
|
| Protocol Layer | Network communication and packet handling |
|
|
|
|
## Package Structure
|
|
|
|
The codebase is organized under `com.hypixel.hytale`:
|
|
|
|
```
|
|
com.hypixel.hytale/
|
|
├── server/core/ # Core server functionality
|
|
│ ├── plugin/ # Plugin management
|
|
│ ├── command/ # Command system
|
|
│ ├── entity/ # Entity management
|
|
│ ├── universe/ # World/Universe management
|
|
│ ├── registry/ # Server registries
|
|
│ └── ...
|
|
├── event/ # Event bus and handlers
|
|
├── component/ # ECS framework
|
|
├── codec/ # Serialization framework
|
|
├── protocol/ # Network protocol
|
|
├── common/ # Shared utilities
|
|
├── math/ # Math utilities and vectors
|
|
└── builtin/ # Built-in game modules
|
|
```
|
|
|
|
## Creating Your First Mod
|
|
|
|
### 1. Project Setup
|
|
|
|
Create a new Java project with the Hytale Server API as a dependency.
|
|
|
|
### 2. Create the Plugin Manifest
|
|
|
|
Create a `manifest.json` file in your JAR's root:
|
|
|
|
```json
|
|
{
|
|
"Group": "com.example",
|
|
"Name": "MyFirstMod",
|
|
"Version": "1.0.0",
|
|
"Description": "My first Hytale mod",
|
|
"Authors": ["YourName"],
|
|
"Main": "com.example.MyFirstMod",
|
|
"ServerVersion": ">=1.0.0",
|
|
"Dependencies": {},
|
|
"IncludesAssetPack": false
|
|
}
|
|
```
|
|
|
|
### 3. Create the Main Plugin Class
|
|
|
|
```java
|
|
package com.example;
|
|
|
|
import com.hypixel.hytale.server.core.plugin.JavaPlugin;
|
|
import com.hypixel.hytale.server.core.plugin.java.JavaPluginInit;
|
|
|
|
public class MyFirstMod extends JavaPlugin {
|
|
|
|
public MyFirstMod(JavaPluginInit init) {
|
|
super(init);
|
|
}
|
|
|
|
@Override
|
|
protected void setup() {
|
|
// Called during plugin setup phase
|
|
// Register commands, events, components here
|
|
getLogger().info("MyFirstMod is setting up!");
|
|
}
|
|
|
|
@Override
|
|
protected void start() {
|
|
// Called when the plugin starts
|
|
getLogger().info("MyFirstMod has started!");
|
|
}
|
|
|
|
@Override
|
|
protected void shutdown() {
|
|
// Called when the plugin is shutting down
|
|
// Clean up resources here
|
|
getLogger().info("MyFirstMod is shutting down!");
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4. Build and Deploy
|
|
|
|
1. Build your project as a JAR file
|
|
2. Place the JAR in the server's `mods/` directory
|
|
3. Start the server
|
|
|
|
## Plugin Lifecycle
|
|
|
|
Plugins go through the following states:
|
|
|
|
1. **NONE** - Initial state before loading
|
|
2. **SETUP** - `setup()` is called; register components, commands, events
|
|
3. **START** - `start()` is called; plugin becomes active
|
|
4. **ENABLED** - Plugin is fully operational
|
|
5. **SHUTDOWN** - `shutdown()` is called during server stop
|
|
6. **DISABLED** - Plugin is disabled and unloaded
|
|
|
|
## Available Registries
|
|
|
|
Your plugin has access to several registries for registration:
|
|
|
|
| Registry | Access Method | Purpose |
|
|
|-----------------------|------------------------------|-------------------------------|
|
|
| CommandRegistry | `getCommandRegistry()` | Register custom commands |
|
|
| EventRegistry | `getEventRegistry()` | Register event listeners |
|
|
| EntityRegistry | `getEntityRegistry()` | Register custom entity types |
|
|
| BlockStateRegistry | `getBlockStateRegistry()` | Register block states |
|
|
| TaskRegistry | `getTaskRegistry()` | Schedule recurring tasks |
|
|
| AssetRegistry | `getAssetRegistry()` | Register custom asset types |
|
|
| ClientFeatureRegistry | `getClientFeatureRegistry()` | Register client-side features |
|
|
| EntityStoreRegistry | `getEntityStoreRegistry()` | Register ECS entity stores |
|
|
| ChunkStoreRegistry | `getChunkStoreRegistry()` | Register chunk data stores |
|
|
|
|
## Next Steps
|
|
|
|
- [Plugin Development](02-plugin-development.md) - In-depth plugin creation guide
|
|
- [Event System](03-event-system.md) - Handling game events
|
|
- [Command System](04-command-system.md) - Creating custom commands
|
|
- [Entity System](05-entity-system.md) - Working with entities and ECS
|
|
- [World Management](06-world-management.md) - Managing worlds and chunks
|