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, twoClimateUnitView.States andInstrumentView.Kind.AIR_MONITOR,AIR_SENSORandWIND_SENSOR. Aswitchover an EZvac enum with nodefaultthrowsMatchExceptionat runtime when it meets one an addon was built without, so give such switches adefaultbranch.
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(), orthermostatOf(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 followsDeviceAddedEventandDeviceRemovedEvent. 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).
EquipmentStateChangeEventcovers 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.ymlthrough 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
startsOnfalse 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:
registerAddonis new in 1.9. To also run on older ones, checkapiVersion()first and keep the call in a class of its own, soAddonis 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), andcontext.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.lineshas{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. Overrideinline(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.hiddenswitches sections off by id, and/hvac hud sectionslists them. - Older EZvacs:
hud()is new in 1.1. If your addon should also run on 1.0, checkapiVersion()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.apipackages 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@sincetags 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,Windand 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()andareaHeight(),ThermostatView.profile(),mini(),attention()andblocked()), and 1.8 with BETA 1.0 Pilot 3 (the wind's direction,windAt(),outdoorAirAt(),windForecast(location, days), and a station'swind(),airQuality()and each day'saqi()), and 1.9 with BETA 1.0 Pilot 4 (precipitationAt(),snowLineAt(),freezingWaterF(),dailyMeanAirF(),WeatherPlan,WeatherEvent,setWeatherPlan(),Precipitation,SeasonView.progress(), andregisterAddon()withAddonandAddonSwitches), and 1.10 with BETA 1.0 Pilot 5 (systemSpace()andSystemSpace), and 1.11 (setShowsWeather(),HudContext.gauge()), and 1.12 with BETA 1.0 Pilot 7 (refrigeration:ClimateUnitView.KindMINI_FRIDGE,FRIDGE,REFRIGERATORandDEEP_FREEZERwithinsideF(), andstorageTemperatureF(), also by slot; and controlling devices:control(),EzvacControl,ControlResult,ControlSource,DeviceControlEvent, andThermostatTargetChangeEvent.CauseAPIandSCREEN), and 1.13 with BETA 1.0 Pilot 8 (ThermostatView.modeSince(),lastRun()withRun,timeInMode(), andloaded()on thermostat, equipment and climate unit views). Depend on the oldest EZvac whose API has what you use.