Wikis / MythicSeasons / A P I

A P I

MythicSeasons' developer API: SeasonsAPI below, plus Events, Weather Providers and Cloud Layer Types. Server admins do not need it.

Setup

The jar

MythicSeasons is not on a Maven repository. Compile against the jar from your server, for example in libs.

Gradle (Kotlin)

dependencies {
    compileOnly(files("libs/MythicSeasons.jar"))
}

Gradle (Groovy)

dependencies {
    compileOnly files('libs/MythicSeasons.jar')
}

MythicSeasons is compiled for Java 21, so build with Java 21 or newer.

plugin.yml

Add MythicSeasons to depend, or to softdepend if your plugin also works without it:

depend: [MythicSeasons]

softdepend: [MythicSeasons]

With softdepend, keep every MythicSeasons type out of your main class and use them only when MythicSeasons is enabled:

if (getServer().getPluginManager().isPluginEnabled("MythicSeasons")) {
    SeasonsHook.register(this);
}

SeasonsHook is a class of your own that holds every MythicSeasons call.

Getting SeasonsAPI

SeasonsAPI api = SeasonsAPI.getInstance();

SeasonsAPI is net.taiyou.mythicseasons.api.SeasonsAPI.

getInstance() returns null until MythicSeasons has run its onEnable, which comes before yours when you depend or softdepend on it. It is not in Bukkit's services manager.

Example

import net.taiyou.mythicseasons.api.SeasonsAPI;
import net.taiyou.mythicseasons.calendar.Date;
import org.bukkit.World;
import org.bukkit.entity.Player;

public final class SeasonInfo {

    public static String describe(Player player) {
        SeasonsAPI api = SeasonsAPI.getInstance();
        World world = player.getWorld();
        String season = api.getSeasonId(world);
        if (season.equals("disabled")) {
            return "No season here";
        }
        Date date = api.getDate(world);
        String when = date == null ? "" : ", " + api.getDayOfWeek(world) + " " + date.getDay() + " " + api.getCurrentMonthName(world);
        return "Season: " + season + when;
    }
}

A world without a date shows only its season.

Method reference

Call these from the main thread: MythicSeasons changes this state there without locking. Only the two registries are safe from any thread.

Registries

Method	Returns	Description
`static SeasonsAPI getInstance()`	`SeasonsAPI`	The shared instance, `null` before MythicSeasons has run its `onEnable`.
`WeatherRegistry getWeatherRegistry()`	`WeatherRegistry`	Register a `WeatherProvider` here.
`CloudLayerRegistry getCloudLayerRegistry()`	`CloudLayerRegistry`	Register a `CloudLayerType` here.

Seasons

Method	Returns	Description
`Season getSeason(World w)`	`Season`	`Season.ACTIVE` when the world has a season, else `Season.DISABLED`.
`String getSeasonId(World w)`	`String`	The season id in lower case (the `id` of the season file), or `disabled`.
`void setSeason(World w, Season s)`	`void`	Only `Season.DISABLED` works: it removes the world's season after a cancellable `SeasonChangeEvent`.

Calendar and time

These use the world's Calendar.

Method	Returns	Description
`Date getDate(World w)`	`Date`	The in-game date, or the real date with `sync-time-with-real-world: true` in `calendar.yml`. `null` when the world has no date, and before startup ends.
`void setDate(World w, Date date)`	`void`	Sets the date, firing `DayChangeEvent` first if the world already had one. With `automatic-season-cycling` on, the season then follows the calendar.
`String getDayOfWeek(World w)`	`String`	The weekday from `week-days` in `calendar.yml`. `DISABLED` when MythicSeasons never gave the world a season or the world has no date, and before startup ends. A world whose season was removed (`/ms disable` or `setSeason(world, Season.DISABLED)`) still returns its stored weekday, so test for no season with `getSeasonId(world).equals("disabled")`.
`String getCurrentMonthName(World w)`	`String`	The month name from `calendar.yml`. `DISABLED` in the same cases as `getDayOfWeek`.
`int getHours(World w)`	`int`	Hour of the in-game clock, 0 to 23.
`int getMinutes(World w)`	`int`	Minute, 0 to 59.
`int getSeconds(World w)`	`int`	Second, 0 to 59.

The clock methods return 0 before startup ends. The clock follows the month's day and night lengths (day-length-in-min, night-length-in-min in calendar.yml) while modify-daynight-length in config.yml is on. In a world with no season or date, or with that setting off, it is the vanilla time of day over 24 hours (world time 0 is 06:00). With sync-time-with-real-world: true it is the real clock.

Temperature

Values are whole degrees Celsius, see Temperature.

Method	Returns	Description
`int getAirTemperature(Location loc)`	`int`	The air temperature at `loc`: the world's base temperature with weather, time of day, biome and height. The Nether and the End return `modifiers.other-dimensions.nether` and `modifiers.other-dimensions.end` of `temperature.yml`. `5` in an unloaded chunk, `0` before startup ends.
`int getTemperature(Player p)`	`int`	The player's body temperature, meaningful only while the temperature system is on. `0` before startup ends.
`void applyTimedTemperatureEffect(Player p, int effect, int seconds)`	`void`	Adds `effect` degrees for `seconds` seconds. Timed effects stack, and a player's sum of them stays between `temperature-modify-command.min` and `temperature-modify-command.max` in `config.yml` (default -999999 and 999999).
`TemperatureEffect applyPermanentTemperatureEffect(Player p, int modifier)`	`TemperatureEffect`	Adds `modifier` degrees until `cancel()`, without the `temperature-modify-command` limits. Kept through a rejoin, lost on a server restart.

Events

Method	Returns	Description
`List<String> getActiveEvents(World w)`	`List<String>`	Display names (not ids) of the world's active calendar events in start order, without duplicates or events with `display-event: false`. A copy you can change: empty when none is active, `null` before startup ends. See Event Options.

Season particles

Method	Returns	Description
`boolean hasSeasonParticles(Player p)`	`boolean`	`false` after the player turned season particles off with `/toggleseasonparticles`. Same value as `<mythicseasons.particles>` and `%ms_particles%`. Check it before drawing your own cosmetic particles.

Cloud layers

Method	Returns	Description
`boolean isCloudLayerShown(Player p, String toggle)`	`boolean`	Whether the player shows the layers with this toggle name (`/togglecloudlayer`). Same value as `<mythicseasons.cloudlayer.name>` and `%ms_cloudlayer_<name>%`, and `true` before startup ends.

toggle is a layer file's toggle value, such as fog, in any letter case (Player toggles). A player who has not chosen gets true, or false for a name whose layer files set toggle-default: hidden. A name no layer uses gives true, unless the player chose it while a layer still used it. The value is only the player's choice, not whether clouds are drawn.

Biomes

Method	Returns	Description
`SeasonBiome getReplacementSeasonBiome(String biomeName, Season s)`	`SeasonBiome`	The colours MythicSeasons applies to the biome named `biomeName`, or `null`.
`SeasonBiome getReplacementSeasonBiome(Biome b, Season s)`	`SeasonBiome`	The same, by the registry name of `b` without its namespace (for example `plains`). Vanilla biomes only.
`SeasonBiome getReplacementSeasonBiome(Location l, Season s)`	`SeasonBiome`	The same for the biome at `l`. Vanilla biomes only.

Supporting types

Only the members you need are listed.

Type	Package	Members
`Season`	`net.taiyou.mythicseasons.season`	Enum: `ACTIVE`, `DISABLED`. The static `getSeason(String s)` returns `DISABLED` for `DISABLED` in any case, else `ACTIVE`. `getConfigName()` returns the constant name.
`Date`	`net.taiyou.mythicseasons.calendar`	Constructors `Date(int day, int month, int year)` and `Date(int day, int month)` (year 0), getters `getDay()`, `getMonth()`, `getYear()`. Day and month start at 1, and the month is its position in the month list of `calendar.yml`. The static `fromString(String s, boolean isAmericanSystem)` reads `day/month/year`, or `month/day/year` when `true`, and needs all three parts. `toString(boolean isAmericanSystem)` writes the same, `toString()` writes `day/month/year`. `isLaterInYear(Date d)` is `true` when `d` falls on or after this date, by month and day only.
`SeasonCustomEvent`	`net.taiyou.mythicseasons.seasonevent`	The calendar event of `SeasonEventStart` and `SeasonEventEnd`. `getName()` returns `display-name`, or the id. `doDisplay()` returns `display-event`. `getCommands(boolean isStart)` returns `commands.start` (`true`) or `commands.stop` (`false`): the event's own list, not a copy.
`TemperatureEffect`	`net.taiyou.mythicseasons.api`	Handle of a permanent effect. `cancel()` removes it, `getModifier()` returns its degrees.
`SeasonBiome`	`net.taiyou.mythicseasons.api`	A biome's colours: `getSeason()` (always `Season.ACTIVE`), `getOriginalBiome()`, `getFogColorHex()`, `getWaterColoHex()` (spelled that way), `getWaterFogColorHex()`, `getSkyColorHex()`, `getGrassColorHex()` and `getFoliageColorsHex()` (an array). Hex without `#`, empty when the biome file leaves a colour out. Several comma-separated colours come back as one string, except from `getFoliageColorsHex()`, which gives one entry per colour.
`MythicSeasons`	`net.taiyou.mythicseasons`	The main class. `MythicSeasons.getInstance()` returns the plugin, the first argument of `WeatherState`.

Core Plugins