Getting started

Anything you can write in zones.yml, you can build from code instead. What the API adds is rules that read live game state: reveal whoever holds the point right now, reveal the top three of the standings, and let both follow the game without any code running on change.

1. Add the dependency.

   The artifact holds interfaces only, the implementation lives in the plugin. Depend on it with compileOnly in Gradle or provided in Maven, and do not shade it into your jar.

   • Gradle (Groovy)
   • Gradle (Kotlin)
   • Maven

   repositories {
     maven {
       name = 'soma'
       url = 'https://sowmha.github.io/maven/'
     }
   }
   
   dependencies {
     compileOnly 'top.soma:hider-api:1.16.5'
   }

2. Declare the plugin.

   depend: [SomaHider]

   Use softdepend instead if your plugin should still work when SomaHider is absent. You then guard your calls with SomaHiderProvider.getOrNull().

3. Get the API.

   import top.soma.hider.api.SomaHider;
   import top.soma.hider.api.SomaHiderProvider;
   
   SomaHider hider = SomaHiderProvider.get();

   Call this from onEnable() or later, never from your constructor or onLoad(): SomaHider registers itself while it enables, so it does not exist yet at those points.

import java.time.Duration;

import top.soma.hider.api.rule.Reveal;
import top.soma.hider.api.zone.HiderZone;
import top.soma.hider.api.zone.Region;

Region arena = Region.circle(center, 40.0);

HiderZone zone = SomaHiderProvider.get()
        .hide(arena)
        .named("arena")
        .duration(Duration.ofMinutes(30))
        .reveal(Reveal.sameGroup())
        .open();

Everyone inside the circle is now hidden from everyone else, except that players sharing a group see each other. Close it when your event ends:

zone.close();

A zone opened with a duration also closes on its own. One opened without runs until you close it: unlike /sh start, the API applies no ceiling of its own, so nothing will stop a zone you forget.

Reveal.sameGroup() needs to know what a group is, and only your plugin can answer that. A GroupResolver maps a player to a group id, or to null when they belong to none. A null group is never revealed.

.groupResolver(player -> {
    Faction faction = FactionUtils.getFactionByPlayer(player);
    return faction != null && faction.isNormal() ? faction.getId() : null;
})

Set it once on the zone, and every group-based rule uses it.

A real integration is the page to read next. It walks through a working event plugin end to end, and the patterns in it cover most of what you will write.

For the details: zones for the builder and regions, reveal rules for the rule catalogue and how to keep them cheap, and disguises for changing the look from code.