Skip to content

Home

Jump to bottom
Roark McKibben edited this page Mar 31, 2023 · 3 revisions

Welcome to the Spigot-Origins wiki!

DISCLAIMER

THIS API IS IN EXTREME ALPHA AND IS IN NO WAY FINISHED

API Definitions

Origin: An Origin is a collection of Traits with an Icon for visual representation. Each player can have one Origin.

Trait: A Trait is a class that changes gameplay for a player. It also has an Icon.

Ability: An Ability is an inheritor of the Trait class that changes one aspect of gameplay for a player.

Compound Ability: A Compound Ability is a collection of Abilities combined under one name for reusability's sake.

Authenticator: An Authenticator is just a means by which you can verify (or authenticate) an event to see if a method should fire based on specified criteria.

Defining an Origin

An Origin is defined in the origins.json file.

{
  "id": "enderian",
  "impact": "MEDIUM",

  "icon": {
    "name": "Enderian",
    "desc": "A member of the Ender race, Enderians share many characteristics and behavior with Endermen.",
    "color": "DARK_PURPLE",
    "material": "ENDER_PEARL"
  },

  "traits": [
    {
      "id": "hydrophobic"
    },

    {
      "id": "spatial-jumper"
    },

    {
      "id": "gourdophobic"
    },

    {
      "id": "silky-hands"
    },

    {
      "id": "pacify-mob",
      "icon": {
        "name": "Enderkin",
        "desc": "You are so closely related to Endermen, that you cannot cause them to become angry with you.",
        "color": "LIGHT_PURPLE",
        "material": "ENDER_EYE"
      },
      "type": "POSITIVE",
      "args": [
        [
          "ENDERMAN"
        ]
      ]
    }
  ]
}

Origin's data:

  • id: The id of an Origin is how the plugin will refer to the Origin (All IDs are written in kebab-case).
  • impact: The impact of an Origin tells a player how much this Origin will change their gameplay. Can be LOW, MEDIUM, or HIGH.
  • icon: The icon of an Origin defines how this origin will appear in the OriginSelector GUI.
    • name: The name of the Origin.
    • desc: A brief description of the Origin.
    • color: The color of the name of the Origin.
    • material: The Item Material of the Icon (See also Spigot's Material class for possible values).
  • traits: An array of all the Traits that this Origin will possess.

When declaring a Trait that an Origin implements, you can pass in args or arguments to the Trait's constructor. You can pass them in as either string, array, integer, boolean or number JSON literals.

You can also add an icon to the Trait (depending on the Trait) that is defined the exact same as an Origin's icon. If you choose to define an icon for a trait, you must define the type property to (don't worry about forgetting this, as the schema enforces it).

Defining Traits

Traits are defined in Java code. They must all implement one of the Trait, Ability, or CompoundAbility classes.

Below is an example of an Ability.

// You must declare what type of event you will be primarily listening to. If you cannot constrain yourself to one Event, then you should be using a CompoundAbility instead.
public class Roost extends Ability {
  private static final int MINIMUM_SLEEP_HEIGHT = 128;
  // IMPORTANT: Every single inheritor of Trait MUST define an ID (abstract classes and lambdas don't count)
  public static final String ID = "roost";

  public Roost() {
    super("Roost", "You can only sleep at high altitudes", ChatColor.GRAY, Material.RED_BED, Type.NEGATIVE);
  }

  @EventHandler
  public void preventSleep(PlayerBedEnterEvent event) {
    if (!new PlayerAuthenticator(this).authenticate(event)) return;

    Player player = event.getPlayer();

    if (player.getLocation().getY() < MINIMUM_SLEEP_HEIGHT) {
      player.spigot().sendMessage(ChatMessageType.ACTION_BAR, TextComponent.fromLegacyText("You cannot sleep below altitude " + MINIMUM_SLEEP_HEIGHT));
      event.setCancelled(true);
    }
  }
}

If you wish to include the capability to have an icon and type defined in json, simply inherit the Trait(ItemIcon, Type) constructor. The API will handle deserialization into these types, however this all the deserialization that the API will handle. You must define any extra deserialization you want to happen (the JSON library used is json-simple).

Below is an example of a CompoundAbility.

public class FrailBody extends CompoundAbility {
    // Every single inheritor of the Trait class MUST define a public static final ID (this includes abstract classes).  
    public final static String ID = "frail-body";

    public FrailBody() {
        super(
                "Frail Body",
                "Your body is frail and light, and therefore you move quickly, and fall slowly, however, you inept when it comes to combat.",
                ChatColor.GOLD,
                Material.EGG,
                Type.NEUTRAL,

                // Specify which Traits this CompoundAbility Posses.
                new PermanentEffect(PotionEffectType.SPEED, 0),
                new PermanentEffect(PotionEffectType.SLOW_FALLING, 0),
                new PermanentEffect(PotionEffectType.WEAKNESS, 0)
                );
    }
}

This example takes advantage of the PermanentEffect class in order to combine several effects into one, but you can still see that a CompoundAbility is simply just a collection of Traits under one name and icon.

This may seem like a lot of info, but once you learn this API, it just becomes regular Spigot programming that is optimized for creating Origins.

Defining an Authenticator

Authenticators are just this API's approach to checking that an EventHandler is firing when it is supposed to.

Below is an example of an Authenticator.

// Every Authenticator must declare what type of Event it will listen to, and this Authenticator is used in many contexts, so it just accepts any event that is a child of PlayerEvent.
public class PlayerAuthenticator <T extends PlayerEvent> extends Authenticator<T> {
  public PlayerAuthenticator(Ability ability) {
    super(ability);
  }

  @Override
  public boolean authenticate(T event) {
    return playerHasTrait(event.getPlayer(), getAssociatedAbility());
  }

  public static boolean playerHasTrait(Player player, Trait trait) {
    Origin origin = PlayerManager.getInstance().getOrigin(player);

    return Arrays.asList(origin.getAllTraits()).contains(trait);
  }
}

Authenticators are a simple part of the API, and you probably won't have to define any, unless you are trying to authenticate an extremely niche Event (If you ever find yourself in a situation where you are writing some kind of EventHandler and you can't find an Authenticator that works, write your own! The API is ever expanding, and can always use more!).

Wrapping Up

As time goes on, the hope for Spigot Origins is that the API will be populated with so many reusable resources, that you won't have to know how to write any of these but instead will be able to just define exactly what you want in JSON, but until then, this info will be essential if you want to write any kind of Origin.

Clone this wiki locally