hytale-server/docs/README.md

# Hytale Server Modding Documentation

Welcome to the Hytale Server modding documentation. This guide provides comprehensive information for creating mods and
extensions for the Hytale Server.

## LLM Reference

**[LLM-Optimized API Reference](00-llm-reference.md)** - Complete API reference with exact class names, method
signatures, and JSON structures. Use this for quick lookups.

## Documentation Index

### Getting Started

1. **[Getting Started](01-getting-started.md)** - Introduction and first mod tutorial

### Core Systems

2. **[Plugin Development](02-plugin-development.md)** - Creating and structuring plugins
3. **[Event System](03-event-system.md)** - Handling game events
4. **[Command System](04-command-system.md)** - Creating custom commands
5. **[Entity System (ECS)](05-entity-system.md)** - Working with entities and components
6. **[World Management](06-world-management.md)** - Managing worlds and chunks

### Communication & Data

7. **[Networking](07-networking.md)** - Network protocol and packet handling
8. **[Asset System](08-asset-system.md)** - Managing game assets
9. **[Configuration](10-configuration.md)** - Plugin and server configuration
10. **[Codec/Serialization](11-codec-serialization.md)** - Data serialization framework

### Game Systems

11. **[NPC/AI System](09-npc-ai-system.md)** - Creating and controlling NPCs
12. **[Built-in Modules](12-builtin-modules.md)** - Using server modules

### UI & Presentation

15. **[UI System](15-ui-system.md)** - Pages, windows, HUD, and UI commands

### Reference

13. **[Utilities](13-utilities.md)** - Common utility classes and APIs
14. **[Early Plugin System](14-early-plugin-system.md)** - Advanced bytecode transformation

## Quick Start

### Creating Your First Mod

1. Create a `manifest.json`:

```json
{
    "Group": "com.example",
    "Name": "MyMod",
    "Version": "1.0.0",
    "Main": "com.example.MyMod"
}
```

2. Create your main class:

```java
public class MyMod extends JavaPlugin {
    public MyMod(JavaPluginInit init) {
        super(init);
    }
    
    @Override
    protected void setup() {
        getLogger().info("MyMod loaded!");
    }
}
```

3. Build and place in `mods/` directory

## Key Concepts

### Plugin Lifecycle

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

- **SETUP**: Register commands, events, entities
- **START**: Initialize plugin logic
- **SHUTDOWN**: Clean up resources

### Available Registries

| Registry          | Purpose         |
|-------------------|-----------------|
| `CommandRegistry` | Custom commands |
| `EventRegistry`   | Event listeners |
| `EntityRegistry`  | Custom entities |
| `AssetRegistry`   | Custom assets   |
| `TaskRegistry`    | Scheduled tasks |

### Event Priority

| Priority | Value  | Use Case           |
|----------|--------|--------------------|
| FIRST    | -21844 | Monitoring/logging |
| EARLY    | -10922 | Pre-processing     |
| NORMAL   | 0      | Standard handling  |
| LATE     | 10922  | Post-processing    |
| LAST     | 21844  | Final processing   |

## Package Structure

```
com.hypixel.hytale/
├── server/core/       # Core server functionality
├── event/             # Event system
├── component/         # Entity Component System
├── codec/             # Serialization
├── protocol/          # Networking
├── common/            # Utilities
├── math/              # Math utilities
└── builtin/           # Built-in modules
```

## API Highlights

### Events

```java
getEventRegistry().register(PlayerConnectEvent.class, event -> {
    Player player = event.getPlayer();
    player.sendMessage("Welcome!");
});
```

### Commands

```java
public class MyCommand extends AbstractCommand {
    public MyCommand() {
        super("mycommand", "Description");
        withRequiredArg("player", "Target player");
    }
    
    @Override
    public void execute(CommandContext ctx, Arguments args) {
        String player = args.getString("player");
        ctx.sendMessage("Hello, " + player);
    }
}
```

### Entities

```java
public class CustomEntity extends Entity {
    public CustomEntity(World world) {
        super(world);
    }
}

// Register
getEntityRegistry().register("custom", CustomEntity.class, CustomEntity::new);
```

### Configuration

```java
public static final Codec<MyConfig> CODEC = BuilderCodec.of(MyConfig::new)
    .with("enabled", Codec.BOOLEAN, c -> c.enabled, true)
    .with("maxCount", Codec.INTEGER, c -> c.maxCount, 100)
    .build();
```

## Best Practices

1. **Register in setup()** - All registrations should happen during setup
2. **Use events** - Prefer events over polling
3. **Respect lifecycle** - Don't access other plugins during setup
4. **Handle errors** - Log and handle exceptions gracefully
5. **Clean up** - Release resources in shutdown()
6. **Use codecs** - Serialize data with the codec system
7. **Namespace assets** - Use your mod ID as namespace
8. **Document** - Document your mod's features and configuration

## Support

For questions and support:

- Check the [Hytale modding forums](#)
- Join the [Discord community](#)
- Report issues on [GitHub](#)

## Contributing

Contributions to this documentation are welcome. Please submit pull requests with improvements or corrections.

---

*This documentation is for Hytale Server modding. For official Hytale information,
visit [hytale.com](https://hytale.com).*