Skip to content

The EZvac API

From ALPHA 2.1, other plugins can use what EZvac knows about the climate: the temperature and "feels like" anywhere and around every player, the outdoors, thermostats and their systems, dehumidifiers, humidifiers and air purifiers, the air quality, the seasons, building sizes, weather stations' forecasts, and events when things change. Addons can also add their own sections to EZvac's climate HUD. An addon is an ordinary Paper plugin that depends on EZvac.

API version 1.6 reads only: nothing an addon does through it changes EZvac's climate or systems. Ways to change things (targets, power) will come in a later API version.

The official addons are complete open-source examples: LiveExposure (body temperature for survival players, with a section on the HUD) and EZdebug+ (every device near a player, drawn from devices(world) and the device events).

Adding the dependency

The API is published through JitPack, built from EZvac's release tags: use the tag of the oldest EZvac whose API has what you need (BETA-1.0-P8 for API 1.13, BETA-1.0-P7 for 1.12, BETA-1.0-P6 for 1.11, BETA-1.0-P5 for 1.10, BETA-1.0-P4 for API 1.9, BETA-1.0-P3 for 1.8, BETA-1.0-P2 for 1.7, BETA-1.0-P1 for 1.6, ALPHA-3.2 for 1.5; see Versions and promises). Use it with provided (Maven) or compileOnly (Gradle) scope: EZvac carries the API's classes at runtime, so never shade them into your jar.

Maven

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.github.EZvac-Plugin.EZvac</groupId>
        <artifactId>ezvac-api</artifactId>
        <version>BETA-1.0-P3</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Gradle (Kotlin)

repositories { maven("https://jitpack.io") }
dependencies { compileOnly("com.github.EZvac-Plugin.EZvac:ezvac-api:BETA-1.0-P3") }

In your plugin.yml, depend on EZvac so it loads first:

depend: [EZvac]        # or softdepend: [EZvac] if your plugin also works without it

Getting the API

EzvacApi ezvac = EzvacApi.get();   // throws IllegalStateException if EZvac is missing

EzvacApi.get() asks Paper's services manager, where EZvac registers itself while it's enabled. ezvac.apiVersion() tells you which API version the server runs.

What you can read

Method Gives
readingAt(location) The climate at a spot, exactly as /hvac temperature reads it
readingFor(player) The climate a player is in, as their HUD reads it (head first, the water when in water)
latestFor(playerId) The reading the last player update gave; safe from any thread
outdoorAt(location) The outdoors there: air, natural water, humidity, dew point, feels-like, weather, and how much the season shifts it
thermostats(), thermostats(world) Thermostats: room and target temperature, mode, on/off, pool or room, humidity, running and total equipment
thermostatAt(position), thermostatOf(world, system) The thermostat whose sign is at a position, or the thermostat of a system, by the system key a view or reading gives you (1.3)
thermostat(world, id) Deprecated in 1.3: labels can repeat, so it gives the lowest-placed thermostat with that label
linkTool() Whether an item is EZvac's link tool, and what it has selected: a thermostat and its system, or a sensor hub (1.3)
climateUnits(), climateUnits(world) Dehumidifiers, humidifiers and, since 1.5, air purifiers: humidity, setpoint, state, power, a dehumidifier's tank, a purifier's filter and the air it cleans (1.5)
equipment(), equipment(world) Heat pumps, air conditioners, furnaces, boilers and pool heat pumps: kind, system, on/off, running, mode, motor RPM (1.2), and tier (1.4): 1 single-stage, 2 two-stage, 3 variable
vents(), vents(world) Vents: system, and whether they blow air or water (1.2)
instruments(), instruments(world) Thermometers and hygrometers, sensors, sensor hubs (with the sensors they show), RPM monitors and settings panels (1.2); air monitors, air sensors and wind sensors (1.5)
devices(world) Every device in a world, of every kind (1.2)
season(world) The season and its day, or empty where there are no seasons. Its progress() is how far through the year it is, 0 to 1 (1.9)
windForecast(world, days) Today's wind and the next days', each a Wind.Day with its level and mean speed; empty where there is no wind (1.5)
windForecast(location, days) The same for the region around a spot, which can be up to a level windier or calmer than the world's (1.8)
windAt(world, x, z) The wind on open, level ground there right now, with its direction: anywhere, explored or not, without loading a chunk, so a map can draw it (1.8)
outdoorAirAt(world, x, z) The open outdoor air there right now as an AirQuality: its biomes' air with the season's pollen, the rain and the wind, and since 1.9 the smoke of fires burning in the open nearby; anywhere, without loading a chunk (1.8)
precipitationAt(world, x, y, z) What is falling at a block right now: Precipitation.NONE, RAIN or SNOW, by EZvac's air there (1.9)
setWeatherPlan(plugin, plan), weatherPlan() Plan the weather from an addon (1.9): a WeatherPlan gives each day's Outlook (rain and thunder chances, a temperature shift, a WeatherEvent: SNOWSTORM, THUNDERSTORM, HEAT_WAVE, COLD_SNAP, and a note), the shift and event right now. Stations forecast from it, the outdoor air takes its shift, a snowstorm's wind is a gale. One plan at a time; it goes with its plugin. The addon drives Minecraft's weather to match
dailyMeanAirF(world, x, y, z) Today's average outdoor air at a block: halfway between its noon and midnight, with the season, a planned heat wave or cold snap, the weather and the height counted. Snow on the ground answers to it, so a cold night's snow outlasts a mild morning (1.9)
systemSpace(world, system) The space a system fills as EZvac last mapped it: its edge (blocks beside something outside it, at most a few thousand) and its openings (blocks of its air beside open sky: the doorways, windows and holes it leaks through). Empty until it is mapped (1.10)
ThermostatView.modeSince(), lastRun(), timeInMode() When it went into its mode, in real time ("Heating since 14:02"), its last finished heating or cooling run with when it started and ended ("Last heated 14:02 to 14:20"), and how long it has been in its mode. Saved, so they hold across restarts. EZvac keeps only the current mode and the last run; for a full history, log ThermostatModeChangeEvent (1.13)
loaded() on ThermostatView, EquipmentView and ClimateUnitView Whether the device's chunk is loaded. False, EZvac runs it from what it last saw there (where simulation.unloaded-devices is on, the default): a web or phone dashboard can control and watch a house nobody is near (1.13)
storageTemperatureF(world, x, y, z) How cold it is inside a container at a block: an EZvac fridge's, refrigerator's or freezer's inside, else the air there. NaN where the chunk isn't loaded. EZvac spoils nothing itself; an addon can keep food by it (1.12). With a fifth argument, slot, it's that slot's: different only in a mini fridge's chiller box (1.12)
HudContext.gauge(fraction, colorAt) For an addon's HUD section: a meter drawn exactly as EZvac's feels-like bar, the gauge coloured along its own scale with the marker where the value stands (or filled blocks, by hud.bar.style) (1.11)
setShowsWeather(plugin, worlds) Say your addon shows players EZvac's rain and snow (by precipitationAt and snowLineAt) in the worlds the test accepts. There, EZvac's HUD, sensors and forecasts word the weather by its air, and rain reaches deserts as weather.dry-areas says; elsewhere they follow Minecraft's own weather, by biome, and deserts stay dry. It goes with its plugin; null removes it (1.11)
freezingWaterF(world, x, y, z) How cold natural water is getting at a block, before EZvac holds liquid water at 33 °F: at or below 32 °F a lake would be freezing (1.9)
snowLineAt(world, x, z) The height above which rain would come down as snow at a column right now, raining or not: negative infinity where it would snow at every height, positive infinity where it would rain at every height, NaN where rain doesn't reach (a dry place outside a thunderstorm) (1.9)
units() Whether the server shows players °F or °C
systemSize(world, system) A system's size in blocks of air (or water), its openings and how much faster it leaks, what equipment it has and needs for cooling and heating, and the systems its air touches; empty while its air isn't mapped or with building size off (1.6)
serverSettings() What the owner has switched in /hvac quicksettings: device kinds off server-wide (by their devices.disabled names), air quality, pollen, wind, seasons and building size (1.6)
weatherStations(world), weatherStationAt(position) Weather stations: label, on/off, whether the tower stands, lightning strikes, the outdoor temperature around it and its seven-day forecast (1.6)
weatherStationsNear(location) The working stations a player there could see with /hvac forecast, nearest first (1.6)

A ClimateReading holds the temperature, feels-like, humidity (NaN in water), the outdoor temperature, whether the spot is in water, the weather, the season, which system conditions the spot and how strongly, and since 1.5 its airQuality() and the wind() felt there. A ThermostatView has its room's airQuality() too, and an OutdoorClimate the wind() out in the open. Since 1.6 a reading gives the airflowStrength() the HUD shows (100 only in a vent's core), and a ThermostatView says unitsOff() while every unit that could heat or cool its system is switched off server-wide.

A WeatherStationView (1.6) holds its forecast(): seven ForecastDays, today first, each with its high and low, Sky (CLEAR, RAIN, SNOW, THUNDER), chance of rain and of thunder, the day's Wind.Day, pollen, and a note() of what is certain about the day (Rain from 15:00), and since 1.8 its expected aqi() (-1 with air quality off). It is empty while the station isn't forecasting. Since 1.8 a station also gives the wind() and airQuality() over its area right now, and its areaRadius() (1.7), which is what MapPeek draws. Weather stations are not HvacDevices: a switch over every device kind an addon was built with stays complete.

A Wind (1.5) holds the speed in m/s (kmh() and mph() convert it) and its Level: CALM, BREEZY, WINDY or GALE. It is calm indoors, in water, where a system conditions the spot, outside the overworld and on servers with wind.enabled: false. Since 1.8 it has fromDegrees(), where it blows from (0 north, which is Minecraft's -Z, then 90 east), with compass() (NW) and towardDegrees(), the way an arrow on a map points; hasDirection() is false where it isn't known. A Wind.Day has its fromDegrees() too: for a world, as it blows in the temperate westerlies; for a region or a station, as it blows there. See Wind.

An AirQuality (1.5) holds PM2.5 and PM10 in µg/m³, pollen in grains/m³, the AQI (0-500) with its Band, the dominant() pollutant (PM2.5 reads as smoke, PM10 as dust) and the PollenLevel. It is empty in water, before a room is first simulated, and on servers with air-quality.enabled: false. EZvac only measures the air; what it does to players is up to addons.

Switch with a default branch. 1.5 adds ClimateUnitView.Kind.AIR_PURIFIER, two ClimateUnitView.States and InstrumentView.Kind.AIR_MONITOR, AIR_SENSOR and WIND_SENSOR. A switch over an EZvac enum with no default throws MatchException at runtime when it meets one an addon was built without, so give such switches a default branch.

Every temperature is Fahrenheit, whatever the server's units. Records have ...C() helpers, and Temperatures converts.

Controlling devices

Since 1.12 (BETA 1.0 Pilot 7) a plugin can change devices the way a player can at their signs and screens: from a web panel, a Discord bot, an automation, anything. Get a controller with control(plugin), and say whose behalf it acts on with as(playerUuid):

EzvacControl control = EzvacApi.get().control(this).as(user.minecraftId());
control.setTarget(thermostat.position(), 70.0).thenAccept(result -> {
    if (result.ok()) panel.show(result.device().orElseThrow());
    else panel.error(result.message());
});

EZvac checks nothing. It does what a controller asks, on any device. Deciding who may control which thermostat, and logging people in, is your plugin's job. The player you pass is only recorded: in DeviceControlEvent, and as "Last changed by" in /hvac info.

Any thread. Every call returns a CompletableFuture at once. The change is made on the main thread: straight away when you're already on it, else on the next tick. A web server can call straight from its request threads. To read views from another thread, wrap the read: control.read(() -> api.thermostats()). If EZvac stops while a call waits, its future still completes.

Call On
setTarget(position, targetF) a thermostat; kept within its range (a pool thermostat's is wider)
setEnabled(position, on) a thermostat, and so its whole system
setProfile(position, profile) the system of a thermostat or a linked settings panel
setPowered(position, on) a dehumidifier, humidifier, air purifier, or refrigeration appliance
setSetpoint(position, value) a dehumidifier's or humidifier's % RH (to its nearest preset); a fridge's, mini fridge's or deep freezer's °F; a refrigerator's freezer's °F
setFridgeSetpoint(position, f) a refrigerator's fridge
setFan(position, fan) an air purifier: LOW, MEDIUM, HIGH or AUTO
startDefrost(position) a deep freezer, or a refrigerator's freezer
setAutoDefrost(position, on) a refrigerator's freezer (a deep freezer never defrosts itself)
setEquipmentEnabled(position, on) a heat pump, AC, furnace, boiler or pool heat pump

A device's position is the one its view gives, or any other block of it (a fridge's barrel). Each call's ControlResult has a status (DONE, ADJUSTED when kept within range or rounded to a preset, UNCHANGED, NOT_FOUND, NOT_SUPPORTED, or CANCELLED), a short message fit to show a player, and the device as it is now.

Before every change made through the API or by a button on a device's screen, EZvac fires DeviceControlEvent: the device, the setting, the value asked for, and its source (API with the plugin's name, or SCREEN, each with the player). Cancel it to stop the change: a claims plugin can keep strangers off a thermostat this way.

Events

All fired on the main thread. They are informational, except DeviceControlEvent (1.12), which can be cancelled.

Event When
PlayerClimateUpdateEvent Every player's climate is read again, on the HUD's cadence (hud.update-ticks, every half second by default), with the previous reading. Fired only while some plugin listens to it
ThermostatModeChangeEvent A system starts cooling or heating, or goes idle
ThermostatTargetChangeEvent A target changes, from the control menu (MENU), /hvac thermostat set (COMMAND), a plugin (API, 1.12) or a button on its screen (SCREEN, 1.12)
DeviceControlEvent A device is about to be changed through the API or by a button on its screen; cancellable (1.12)
EquipmentStateChangeEvent A heat pump, air conditioner, furnace, boiler or pool heat pump starts or stops
SeasonChangeEvent A world's season turns, as the days pass or when an admin sets it
DeviceAddedEvent A device is created: with /hvac create, or a vent with the link tool (1.2)
DeviceRemovedEvent A device is gone: broken (BROKEN), removed with /hvac remove or unlinked with the link tool (COMMAND), or found missing (MISSING) (1.2)

Weather stations (1.6) fire neither event and don't appear among the devices; read them with weatherStations(world).

EZvac only builds an event while some plugin listens to it, so it costs nothing on servers without addons.

Systems

Since EZvac 3.0 (API 1.3) a system is a thermostat and whatever is linked to it with the link tool; it has no name of its own. The system a view or reading gives you is an opaque key:

  • a system upgraded from EZvac 2.x keeps its old group name as its key, and a new one is # and a number;
  • a key is stable while its system exists. When a headless system (one whose thermostat is gone) is linked to a thermostat, its devices take that thermostat's key;
  • don't show keys to players. Show the thermostat's label instead: ThermostatView.id(), ClimateReading.thermostat(), or thermostatOf(world, key) for any view's system. Labels may repeat, so two houses can both be Home.
String name = ezvac.thermostatOf(world, vent.system())
        .map(ThermostatView::id).orElse("Headless");

Devices

Since API 1.2 every device is in the API with its position, filterable by world: thermostats, equipment, vents, dehumidifiers and humidifiers, and the instruments (thermometers, sensors, hubs, RPM monitors, settings panels). Each view is an HvacDevice, a sealed type, so one switch covers them all:

for (HvacDevice device : ezvac.devices(world)) {
    String label = switch (device) {
        case ThermostatView thermostat -> "Thermostat " + thermostat.id();
        case EquipmentView equipment -> equipment.kind() + (equipment.running() ? " (running)" : "");
        case VentView vent -> vent.medium() + " vent of " + vent.system();
        case ClimateUnitView unit -> unit.kind() + " " + unit.label();
        case InstrumentView instrument -> instrument.kind() + " " + instrument.label();
    };
    addMarker(device.position(), label);   // your map's own call
}
  • Staying in sync: a map addon reads devices(world) once, then follows DeviceAddedEvent and DeviceRemovedEvent. The removed event carries the device as it was, so you know which marker to take down. Devices hvac.yml brings back at startup fire no event; read the lists when your plugin enables.
  • What changes without an event: a running state, a mode, a hub's links, or which system a device is linked to (3.0). EquipmentStateChangeEvent covers equipment starting and stopping; for anything else, read the lists again.
  • Readings aren't in the views. A sensor's view says where it is and what it reads, not its value. To show a value, read the spot with readingAt(device.position().toLocation()).
  • Mind what you publish. These are every player's builds. A public web map of everyone's systems is the server's choice to make, so let admins switch it off.

The Addons menu

Since API 1.9 an addon can register with EZvac's Addons menu, so a server can switch it on and off while it runs:

AddonSwitches switches = ezvac.registerAddon(this, new Addon() {
    @Override
    public void setActive(boolean active) {
        if (active) start(); else stop();
    }

    @Override
    public List<Part> parts() {
        return List.of(new Part("markers", "Map markers", "Off: no markers are drawn.", on -> markers = on));
    }
});
if (switches.active()) start();
markers = switches.partOn("markers");
  • Start in the state it hands back: a server's choices are kept in EZvac's config.yml through restarts.
  • Switched off, stay loaded but do nothing: stop tasks, take down what you show, and let listeners do nothing.
  • Parts are optional. A part only runs while the addon itself is on. One made with startsOn false is off until a server switches it on.
  • The menu lists EZvac's official addons. Any plugin may register; one that isn't official is always on.
  • Older EZvacs: registerAddon is new in 1.9. To also run on older ones, check apiVersion() first and keep the call in a class of its own, so Addon is never loaded there.

HUD sections

Since API 1.1 an addon can add a few lines of its own to the climate HUD (/hvac hud), drawn for every player who has it switched on:

ezvac.hud().register(this, "thirst", context -> {
    int thirst = thirstOf(context.player());           // your own state
    if (thirst < 0) return List.of();                  // an empty list hides it for this player
    return List.of(
            Component.text("Thirst: ", NamedTextColor.GRAY)
                    .append(Component.text(thirst + "%", NamedTextColor.WHITE)),
            context.bar(thirst / 100.0, TextColor.color(0x5AB0FF)));
});
  • Its id is your plugin's name and the key, in lowercase: myaddon:thirst. Registering the same key again replaces it, and it goes away by itself when your plugin is disabled.
  • When it's called: on the main thread, every HUD update (twice a second by default), once per player with the HUD on. Keep it cheap: draw from state you already have. context.reading() is the climate the HUD shows them.
  • Matching EZvac's look: context.bar(fraction, color) is the server's own bar (its glyphs, length and empty colour), and context.temperature(f) writes a temperature the way the HUD does, in the server's units.
  • Where it shows: on the sidebar, where the server's hud.sidebar.lines has {addons} (every section, in the order they were registered), or a line that's just {section:myaddon:thirst}. Stock sidebars have {addons} under the season line. The action bar and boss bar have one line only, so a section shows there only where the server puts {section:<id>} into the format. Override inline(context) to choose the one-line form; by default it's your lines joined with spaces.
  • Mistakes stay yours: a section that throws is logged once and left out; the rest of the HUD carries on.
  • Servers stay in control: hud.sections.hidden switches sections off by id, and /hvac hud sections lists them.
  • Older EZvacs: hud() is new in 1.1. If your addon should also run on 1.0, check apiVersion() before calling it.

Threads

Call the API's methods on the main thread, except latestFor, which is safe from any thread (scoreboard and chat plugins often ask from other threads), and a controller's (1.12), which are safe from any thread and do their work on the main thread; control.read(...) reads views safely from anywhere. Everything the API hands out is an immutable snapshot: keep it as long as you like, but it won't change; ask again for fresh numbers.

An example addon

A complete plugin that warns players when it feels too hot:

package com.example.heatwarning;

import com.github.blade.hvac.api.event.PlayerClimateUpdateEvent;
import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.format.NamedTextColor;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;
import org.bukkit.plugin.java.JavaPlugin;

public final class HeatWarning extends JavaPlugin implements Listener {
    private static final double HOT_F = 95.0;

    @Override
    public void onEnable() {
        getServer().getPluginManager().registerEvents(this, this);
    }

    @EventHandler
    public void onClimate(PlayerClimateUpdateEvent event) {
        double now = event.getReading().feelsLikeF();
        double before = event.getPrevious().map(reading -> reading.feelsLikeF()).orElse(now);
        if (before < HOT_F && now >= HOT_F)
            event.getPlayer().sendMessage(Component.text("It's getting dangerously hot here.", NamedTextColor.GOLD));
    }
}
# plugin.yml
name: HeatWarning
version: 1.0
main: com.example.heatwarning.HeatWarning
api-version: '1.21'
depend: [EZvac]

Versions and promises

  • Only the com.github.blade.hvac.api packages are the API. Everything else in EZvac is internal and may change in any release.
  • New things raise the minor version (1.0 → 1.1). Anything that would break an addon only comes with a new major version, and is announced in the changelog first.
  • The API's version is separate from EZvac's: check apiVersion(), or the @since tags in the Javadoc.
  • Which EZvac has which API: 1.0 came with ALPHA 2.1 Pilot 4, 1.1 with ALPHA 2.1 (HUD sections), 1.2 with ALPHA 2.2 (every device, and the device events), and 1.3 with ALPHA 3.0 (linked systems: thermostatAt, thermostatOf, the link tool), 1.4 with ALPHA 3.1 (EquipmentView.tier()), 1.5 with ALPHA 3.2 (AirQuality, air purifiers, air monitors and air sensors, Wind and wind sensors), 1.6 with BETA 1.0 (SystemSize, ServerSettingsView, weather stations, airflowStrength(), unitsOff()), and 1.7 with BETA 1.0 Pilot 2 (WeatherStationView.areaRadius() and areaHeight(), ThermostatView.profile(), mini(), attention() and blocked()), and 1.8 with BETA 1.0 Pilot 3 (the wind's direction, windAt(), outdoorAirAt(), windForecast(location, days), and a station's wind(), airQuality() and each day's aqi()), and 1.9 with BETA 1.0 Pilot 4 (precipitationAt(), snowLineAt(), freezingWaterF(), dailyMeanAirF(), WeatherPlan, WeatherEvent, setWeatherPlan(), Precipitation, SeasonView.progress(), and registerAddon() with Addon and AddonSwitches), and 1.10 with BETA 1.0 Pilot 5 (systemSpace() and SystemSpace), and 1.11 (setShowsWeather(), HudContext.gauge()), and 1.12 with BETA 1.0 Pilot 7 (refrigeration: ClimateUnitView.Kind MINI_FRIDGE, FRIDGE, REFRIGERATOR and DEEP_FREEZER with insideF(), and storageTemperatureF(), also by slot; and controlling devices: control(), EzvacControl, ControlResult, ControlSource, DeviceControlEvent, and ThermostatTargetChangeEvent.Cause API and SCREEN), and 1.13 with BETA 1.0 Pilot 8 (ThermostatView.modeSince(), lastRun() with Run, timeInMode(), and loaded() on thermostat, equipment and climate unit views). Depend on the oldest EZvac whose API has what you use.