HyVoltage

A comprehensive electrical power system library for Hytale mods.

Overview

HyVoltage is a library plugin for Hytale that provides a unified electrical power system framework. It handles the complex simulation and networking logic, allowing mods to focus on creating generators, machines, cables, and batteries.

What HyVoltage Provides

✅ Power Simulation - Proportional allocation, distance loss, failure detection
✅ Network Topology - Automatic graph-based power network management
✅ Voltage Tiers - 5 tiers (LV, MV, HV, EHV, TX AC) with realistic behaviors
✅ Event System - Comprehensive events for network changes and failures
✅ Conversion Devices - DC-DC converters, inverters, and rectifiers
✅ Thread-Safe - All implementations are concurrent and performant

What Mods Create

• Blocks and items (generators, machines, cables, batteries)
• Visual effects and UI
• Gameplay mechanics and recipes
• Mod-specific configuration

---

Features

Power System

• Voltage Tiers: LV (48V), MV (240V), HV (480V), EHV (4,160V), TX (11,000V AC)
• Distance Loss: 1 HyAmp lost per 10 blocks for lossy tiers (all except TX)
• Proportional Allocation: When supply < demand, power is distributed proportionally
• Failure Detection: Overvoltage, overcurrent, brownout, and component burnout

Network Management

• Automatic Topology: Graph-based connected component detection
• Dynamic Merging: Networks merge when cables connect
• Network Splitting: Networks split when connections break
• Event Notifications: Real-time events for all topology changes

Conversion Devices

• DC-DC Converters: Step up/down between DC voltage tiers
• Inverters: Convert DC to AC for TX transmission
• Rectifiers: Convert AC from TX to DC for distribution
• Thermal Simulation: Temperature tracking with configurable failure thresholds

Failure Mechanics

• Configurable: Enable/disable failures per component
• Multiple Types: Overvoltage, overcurrent, brownout, burnout
• Customizable: Mods can implement custom failure logic
• Debug-Friendly: Disable failures for testing/creative mode

---

Quick Start

Prerequisites

• Java 25 JDK
• Hytale Server JAR (for testing)
• Gradle 8.0+

Installation

1. Add HyVoltage as a dependency in your build.gradle.kts:

dependencies {
    compileOnly(files("libs/hyvoltage-0.1.0-alpha.jar"))
}

2. Implement the electrical interfaces for your components:

// A simple generator
public class MyGenerator implements IHVSource {
    private final UUID nodeId = UUID.randomUUID();
    private final BlockPos position;
    private final VoltageTier tier = VoltageTier.LV;
    private final int offeredCurrent = 100; // 100 HyAmps

    public MyGenerator(BlockPos pos) {
        this.position = pos;
    }

    @Override
    public UUID getNodeId() {
        return nodeId;
    }

    @Override
    public BlockPos getPosition() {
        return position;
    }

    @Override
    public int getOfferedCurrent() {
        return offeredCurrent;
    }

    // Implement other interface methods...
}

3. Register your components with the network manager:

HyVoltage.getNetworkManager().registerNode(myGenerator);

4. Subscribe to events for network changes:

HyVoltage.getEventRegistry().subscribe(NetworkFormedEvent.class, event -> {
    HVLogger.info("New network formed: " + event.getNetworkId());
});

---

API Overview

Core Interfaces

Interface	Purpose
IHVNode	Base interface for all electrical components
IHVSource	Generators and power sources
IHVLoad	Machines and power consumers
IHVStorage	Batteries and energy storage
IHVConnector	Cables and wire connections
IHVConverter	Power conversion devices

Event Types

Event	When It Fires
NetworkFormedEvent	New power network created
NetworkMergedEvent	Multiple networks merged
NetworkSplitEvent	Network split into pieces
OvervoltageEvent	Connector voltage exceeded
OvercurrentEvent	Connector current exceeded
ComponentFailureEvent	Component burned out
BrownoutEvent	Load receiving insufficient power

---

Example Use Cases

Creating a Generator

public class CoalGenerator implements IHVSource {
    private int fuelTicks = 0;
    private final BlockPos position;

    public CoalGenerator(BlockPos pos) {
        this.position = pos;
    }

    @Override
    public int getOfferedCurrent() {
        return fuelTicks > 0 ? 200 : 0; // 200 HyAmps when fueled
    }

    @Override
    public void onCurrentAccepted(int accepted) {
        // Track power output for UI/fuel calculation
    }

    // Implement other interface methods...
}

Creating a Machine

public class ElectricFurnace implements IHVLoad {
    private final BlockPos position;
    private int progress = 0;

    @Override
    public int getRequestedCurrent() {
        return 50; // Needs 50 HyAmps to operate
    }

    @Override
    public void onCurrentReceived(int current) {
        if (current >= 50) {
            progress++; // Operating at full power
        }
    }

    @Override
    public void onBrownout() {
        // Slow down or pause operation
    }

    // Implement other interface methods...
}

Creating a Cable

public class CopperCable implements IHVConnector {
    private final BlockPos position;
    private final List<BlockPos> connections;

    @Override
    public int getMaxCurrent() {
        return 100; // Can carry 100 HyAmps
    }

    @Override
    public int getMaxVoltage() {
        return VoltageTier.LV.getNominalVoltage();
    }

    @Override
    public void onFailure(FailureType type) {
        // Replace with burnt cable, spawn particles, etc.
    }

    // Implement other interface methods...
}

---

Configuration

HyVoltage uses minimal configuration. Most behavior is API-driven:

{
  "debugMode": false
}

Mods should create their own configs and call HyVoltage's API based on those settings.

---

Building from Source

# Clone the repository
git clone https://github.com/bangplaysgames/hyvoltage.git
cd hyvoltage

# Build the plugin JAR
./gradlew shadowJar

# Output: build/libs/HyVoltage-0.1.0-alpha.jar

---

Testing

# Run unit tests
./gradlew test

# Run server with plugin
./gradlew runServer

---

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Credits

• Developed by: BangPlaysGames
• Website: bangplays.games
• GitHub: github.com/bangplaysgames/hyvoltage

---

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Note: HyVoltage is a framework/library, not a full tech mod. It provides the API and simulation system that other mods use to create electrical components.