Add-ons for setups

Our setup plugins are closed, but each has a small add-on kit so you (or your AI) can build on top without seeing our code. The kit is versioned; this page describes version 1.0.0. A change that could break an add-on raises the first number.

There are three ways to add to a setup, from easiest to most powerful:

1. Data files: prices, crates, rewards, events, bosses, regions, warps and holograms are plain YAML files your AI can write (see each page), or settings on the settings page. They can only use the typed actions below.
2. Typed actions: one thing a reward does, such as giving an item or a crate key.
3. A Java add-on plugin that uses the services and events below. Add depend: [sh-core, sh-api] (and the other parts you use, for example sh-events) to your plugin.yml. Add-on jars go through the same checks as any plugin you upload. Plugin names starting with sh- are kept for our own plugins, so pick another name.

Actions

An action is one thing a reward does, written as data. Crates, events, bosses, weekly prizes, the daily reward and vote rewards all use them, from one shared list: any file can use any action below, and the ones your add-ons register. Run /shapi on your server to see every action type and its settings.

For example, a King of the hill prize:

rewards:
  "1":
    - {type: give_key, key: event, amount: 2}
    - {type: broadcast, text: "<gold>{player} is King of the hill!"}

Two small differences, because the daily and vote rewards (rewards.yml) come from the shared base plugin: there, give_item takes item: minecraft:diamond and amount: 3, and message and sound take the same settings as above. Everything else reads the same in every file.

The command lists are yours only. Crates, events and bosses use the list under "Commands rewards may run" in the shared add-on settings (empty at first); the daily and vote rewards use the same setting of the base plugin (eco give, shcrates give and say at first). Only you change them, on the settings page: your AI can write rewards, but it cannot add commands to either list. Commands like op, stop, ban and permission changes are never allowed, whatever is on the list. List only the start of a command, like eco give; rewards fill in the player. An entry that could never work is left out, with a warning in the console that says why.

Services

Get a service in your plugin's enable, for example EconomyService.get() or, for the add-on kit's services, from Bukkit's services manager.

Events

Events that can be cancelled run before the change; the others report what already happened.

Rules every add-on keeps

• Money and keys only change through the ledger and the key service. There is no way around the audit, the daily key limit or the "earned only" rule for keys.
• Keys can never come from a purchase, and crate chances are always shown. The give_currency action cannot give crate keys; use give_key, which keeps the daily limit.
• Sell boosters and other multipliers must be earned in game or be server-wide events, never sold or tied to a paid rank (no pay-to-win). However large they are, /sell still never pays more than the shop charges for the same item.
• Hearts, revives, protection and shorter bans are never sold or tied to a paid rank, and never come from crates. Add-on heart rules can only make steals smaller.
• Player data is stored by player ID only; do not store names, internet addresses or chat.