StellaStella

Stella API

##Stella API

The StellaAPI exposes static methods to interact with Stella from your own mod — query teams, manage members, edit team properties and check membership, all without creating an instance.

INFO

Players are identified by UUID throughout the API. Use StellaAPI.resolvePlayer(name) to turn a name into a UUID, and StellaAPI.getPlayerName(uuid) for the reverse.

###Installation

Add the JitPack repository and the dependency. Replace the version with the latest published tag.

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    modCompileOnly 'com.github.33drygo:StellaMod:1.0.0'
}
INFO

Use modCompileOnly (not compileOnly) so the Fabric Loom plugin treats Stella as a mod dependency at compile time.

Then declare Stella in the suggests block of your fabric.mod.json (use depends instead if Stella is required):

{
  "schemaVersion": 1,
  "id": "mymod",
  "version": "1.0.0",
  "suggests": {
    "stella": "*"
  }
}

###StellaAPI Methods

All methods are static on dev.drygo.stella.api.StellaAPI.

WARNING

Mutating methods (create/delete/set/add/remove) fire Stella's Fabric events and must be called from the server thread. The player-team events are cancellable, so a mutation can return false if a listener vetoes it.

Team queries

  • ####Team getTeam(String id)

    Returns a team by its id, or null if it doesn't exist.
Team red = StellaAPI.getTeam("red");

  • ####boolean teamExists(String id)

    Whether a team with that id exists.

  • ####List<Team> getTeams()

    Every registered team.

  • ####List<String> getTeamIds()

    The ids of every registered team.

Player queries

  • ####Team getMainTeam(UUID player)

    The player's highest-priority team, or null if they're in none.
Team main = StellaAPI.getMainTeam(player.getUuid());

  • ####List<Team> getPlayerTeams(UUID player)

    Every team the player belongs to, highest priority first.

  • ####boolean isInTeam(UUID player, String teamId)

    Whether the player is a member of a specific team.

  • ####boolean isInAnyTeam(UUID player)

    Whether the player belongs to at least one team.

  • ####UUID resolvePlayer(String name)

    Resolves a name to a UUID (online, cached, or known offline), or null.

  • ####String getPlayerName(UUID player)

    The last known name for a UUID, or null.

Team mutations

  • ####Team createTeam(String id, int priority)

    Creates a team and returns it. Returns null if the id is invalid or already in use. Fires the TEAM_CREATED event.
Team team = StellaAPI.createTeam("red", 10);

  • ####boolean deleteTeam(String id)

    Deletes a team. Returns false if it didn't exist. Fires the TEAM_DELETED event.

  • ####boolean setColor(String teamId, String color)

    Sets the team's hex color (#RRGGBB). Returns false if the team is unknown.

  • ####boolean setDisplayName(String teamId, String displayName)

    Sets the team's display name.

  • ####boolean setPriority(String teamId, int priority)

    Sets the team's priority.

Membership mutations

  • ####boolean addMember(String teamId, UUID player)

    Adds a player to a team. Returns false if the team/player is invalid, the player is already a member, or a listener vetoed the PLAYER_JOIN_TEAM event.
StellaAPI.addMember("red", player.getUuid());

  • ####boolean removeMember(String teamId, UUID player)

    Removes a player from a team. Returns false if the team/player is invalid, the player isn't a member, or a listener vetoed the PLAYER_LEAVE_TEAM event.

###Team Model

The dev.drygo.stella.team.Team object exposes:

Method Returns Notes
getId() String The team id (always lowercase).
getDisplayName() String The display name. May contain color codes.
getColor() String Hex color, e.g. #FF5555.
getPriority() int Higher = more important.
getMembers() Set<UUID> Member UUIDs.

Prefer the StellaAPI mutators (setColor, addMember, …) over the Team setters — they persist to teams.json, fire events and refresh the scoreboard hook. Mutating the Team directly does none of that.

###Stella Events

On Fabric the events are exposed as Fabric Events in dev.drygo.stella.api.TeamEvents, not Bukkit listeners. Register a callback on the event you care about:

Click to expand

  • ####TeamEvents.PLAYER_JOIN_TEAM

    Cancellable. Fired before a player is added to a team. Return ActionResult.FAIL to veto the membership; return ActionResult.PASS to allow it.
TeamEvents.PLAYER_JOIN_TEAM.register((player, team) -> {
    // return ActionResult.FAIL; // to veto the membership
    return ActionResult.PASS;
});

  • ####TeamEvents.PLAYER_LEAVE_TEAM

    Cancellable. Fired before a player is removed from a team. Return ActionResult.FAIL to veto the removal.
TeamEvents.PLAYER_LEAVE_TEAM.register((player, team) -> {
    return ActionResult.PASS;
});

  • ####TeamEvents.TEAM_CREATED

    Fired after a team is created. Not cancellable.
TeamEvents.TEAM_CREATED.register((team) -> {
    System.out.println("Team created: " + team.getId());
});

  • ####TeamEvents.TEAM_DELETED

    Fired after a team is deleted. Not cancellable. The Team snapshot is still readable.
TeamEvents.TEAM_DELETED.register((team) -> {
    System.out.println("Team deleted: " + team.getId());
});
WARNING

The exact callback signatures of the TeamEvents events should be confirmed against the published source before relying on them.

###Notes

  • All StellaAPI methods are static — no instantiation needed.
  • Mutations persist to teams.json automatically and refresh the scoreboard hook. There is no LuckPerms hook on Fabric.
  • getMainTeam / getPlayerTeams resolve order by priority (highest first); make priorities unique if exact ordering matters.
  • The player-team events fire before the change is applied and can be vetoed with ActionResult.FAIL; the team created/deleted events fire after and cannot.

###References

cd ../prev
messages.json
Configuration Files