Installation • Features • Usage • Community • Contributing

📝 Why Choose Catalyst?

It is the ultimate drop-in, gain performance mod for both Client and Server to get more performance without affecting gameplay.

• Catalyst only optimizes performance. It doesn't modify:

  • Any game mechanics
  • Visuals
  • Or behavior

• The optimizations apply everywhere, automatically.

• Every optimization can be toggled and tuned at runtime via an in-game GUI. No restarts required.

• Designed to work alongside other mods, early plugins, and the Hyxin Mixin framework.

🔧 How It Works

Catalyst uses ASM bytecode manipulation to inject optimizations directly into Hytale's classes as they're loaded by the JVM.

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Hytale Server  │ ──▶│    Catalyst     │ ──▶│ Optimized Code  │
│                 │     │                 │     │   (Bytecode)    │
└─────────────────┘     └─────────────────┘     └─────────────────┘

This approach provides:

• Zero runtime overhead — Optimizations are baked into the bytecode at load time

• No JAR patching — Works without modifying game files

• Fully reversible — Just remove the plugin to restore vanilla behavior

• Thread-safe toggling — All config fields are volatile for safe runtime changes: no vulnerabilities

📥 Installation

For Server Operators

1. Download the latest JAR from the Releases Page

2. Place it in your early-plugins/ folder:

3. Start your server or singleplayer world

⚠️ Important: Catalyst goes in both early-plugins/, and mods/. Early plugin is needed to load before the server starts to intercept class loading and mod is needed for commands to function and UI to appear.

📊 Performance Results

Benchmark data coming soon

┌────────────────────────────────────────────────────────────┐
│  Vanilla:   ████████████████████████████████████  100%     │
│  Catalyst:  ██████████████████████████            ~70%     │
└────────────────────────────────────────────────────────────┘

✨ Features

Catalyst provides a comprehensive set of server-side optimizations, all configurable at runtime:

Runtime Optimizations

Pathfinding

Chunk Generation

Lighting

Visual Effects

Caching

Advanced Optimizations

🖥️ Usage

In-Game Settings

Open the settings menu with:

/catalyst menu

The GUI features:

• Tabbed interface — General, Lighting, Pathfinding, Visual, and Advanced tabs
• Real-time sliders — Adjust values and see changes instantly
• Search functionality — Quickly find any setting
• One-click reset — Restore all defaults with a single button

Settings are saved automatically to mods/com.criticalrange_Catalyst/catalyst.json.

Commands

⚙️ Configuration

Catalyst stores its configuration in JSON format:

mods/com.criticalrange_Catalyst/catalyst.json

You can edit this file directly, then use /catalyst reload to apply changes without restarting.

{
  "entityDistanceEnabled": false,
  "entityViewMultiplier": 32,
  "chunkRateEnabled": false,
  "chunksPerTick": 4,
  "pathfindingEnabled": false,
  "maxPathLength": 200,
  "openNodesLimit": 80,
  "totalNodesLimit": 400,
  "chunkPoolSizeEnabled": false,
  "chunkPoolSize": 8,
  "chunkCacheSizeEnabled": false,
  "generatorCacheSize": 50000,
  "caveCacheSize": 5000,
  "prefabCacheSize": 50,
  "chunkThreadPriorityEnabled": false,
  "chunkThreadPriority": 5,
  "lightSkipEmptyEnabled": false,
  "particlesEnabled": true,
  "animationsEnabled": true,
  "blockSectionCacheEnabled": false,
  "blockTypeCacheEnabled": false,
  "blockTypeCacheSize": 256,
  "localChunkCacheEnabled": false,
  "blockEntitySleepEnabled": false,
  "blockEntitySleepInterval": 20,
  "statRecalcThrottleEnabled": false,
  "statRecalcInterval": 5,
  "blockUpdateBatchingEnabled": false,
  "blockUpdateBatchSize": 64,
  "floodFillLimitEnabled": false,
  "floodFillMaxIterations": 5000,
  "pathfindingPoolEnabled": false,
  "pathfindingPoolSize": 512
}

✅ Compatibility

Known Limitations

• Catalyst must be placed in early-plugins/, not mods/
• Some optimizations are disabled by default for stability
• Experimental features should be tested before production use

💬 Community

🙇 Getting Help

For technical support (including installation problems and crashes), please:

1. Check the FAQ below
2. Search existing issues
3. Join our Discord server for real-time help

📬 Reporting Issues

Found a bug? Please open an issue with:

• Hytale version
• Catalyst version
• Steps to reproduce
• Error logs (if applicable)

❓ FAQ

🛠️ For Developers

Building from Source

# Clone the repository
git clone https://github.com/CriticalRange/Catalyst.git
cd Catalyst

# Build the JAR
./gradlew build

# Launch server with mod loaded
./gradlew runServer

# Launch client via official launcher
./gradlew runClient

Build artifacts can be found in build/libs/.

Creating Custom Transformers

Extend BaseTransformer and register via META-INF/services:

public class MyTransformer extends BaseTransformer {
    @Override
    protected boolean shouldTransform(String className) {
        return className.equals("com.hypixel.hytale.some.TargetClass");
    }
    
    @Override
    protected ClassVisitor createClassVisitor(ClassWriter cw, String className) {
        return new MyClassVisitor(cw);
    }
    
    @Override
    public String getName() {
        return "MyTransformer";
    }
}

All config fields are volatile for thread-safe runtime toggling.

Project Structure

Catalyst/
├── src/main/java/com/criticalrange/
│   ├── Catalyst.java              # Main plugin class
│   ├── CatalystConfig.java        # Configuration fields
│   ├── CatalystConfigFile.java    # JSON persistence
│   ├── transformer/               # Bytecode transformers
│   │   ├── BaseTransformer.java
│   │   ├── EntityDistanceTransformer.java
│   │   ├── ChunkRateTransformer.java
│   │   └── ...
│   └── util/
│       └── CatalystSettingsGui.java
└── src/main/resources/
    ├── META-INF/services/         # Transformer registration
    └── Common/UI/Custom/Pages/    # GUI definitions

Directory Structure (Runtime)

~/.var/app/com.hypixel.HytaleLauncher/data/Hytale/
└── install/
    ├── early-plugins/              # Catalyst JAR goes here
    ├── mods/
    │   └── com.criticalrange_Catalyst/
    │       └── catalyst.json       # Configuration file
    └── release/package/game/latest/
        ├── Server/HytaleServer.jar
        └── Assets.zip

🌟 Contributing and Supporting Development

Contributions are welcome! Here's how you can help:

• Report bugs — Found an issue? Open a bug report

• Suggest features — Have an idea? Start a discussion

• Submit PRs — Code contributions are appreciated!

• Improve docs — Help make the documentation better

• Star the repo — Show your support!

Before submitting a PR, please:

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

🙏 Credits

• CriticalRange — Lead developer
• ASM Team — Bytecode manipulation library
• Hypixel Studios — For creating an amazing game
• All Contributors — Everyone who helps improve Catalyst

📜 License

Catalyst is licensed under the MIT License — do whatever you want with this code, just keep the copyright notice.

See LICENSE for the full license text.

_{Made with ❤️ for the Hytale community}