Add-ons for setups

Build on a premade setup without our code: data files, typed actions, and the Java services and events of add-on kit 1.0.0.

Our setup plugins are closed, but each has an add-on kit so you or your AI can build on top. This page covers kit version 1.0.0; a breaking change raises the first number.

Three ways to add, easiest first:

Data files: prices, crates, rewards, events, bosses, regions, warps and holograms are YAML files your AI can write. They use the actions below.
Actions: one thing a reward does, such as giving an item.
A Java plugin: add depend: [sh-core, sh-api] (plus the parts you use) to plugin.yml. It goes through the same jar checks as any plugin. Names starting with sh- are ours.

Actions

Crates, events, bosses, weekly prizes, daily and vote rewards share one list of actions, including ones your add-ons register. /shapi lists them all.

Action	Settings	What it does
`message`, `broadcast`	`text`	A message to the player, or everyone (`{player}` filled in)
`title`	`title`, `subtitle`	A big title
`give_item`	`item` like `diamond x3`, `name`	Items; offline players get them in `/collect`. At most 2,304 per action to start (your reward limits).
`sound`	`sound`, `volume`, `pitch`	A sound
`effect`, `potion`	`effect`, `seconds`, `level`	A potion effect, up to 10 minutes, level 1 to 5
`command`	`command`	A console command, only if it starts with one on your allowed list
`give_currency`	`currency`, `amount`	Money, at most 100,000 per action to start (your reward limits)
`give_key`	`key`, `amount`	Crate keys; the daily limit applies
`give_spawner`	`type_id`, `amount`	Spawner items
`start_event`	`event`	Starts an event
`spawn_boss`	`boss`, `pad`	Calls a boss
`give_generator`	`tier` (1 to 12), `amount` (1 to 16)	Gens generators

give_item can never give operator items, spawners or spawn eggs, nor the items on your power-cap list (netherite gear, enchanted golden apples, totems, elytra and maces to start). Change the reward limits with /shcore settings sh-core reward-limits.max-money 250000 (also max-items and power-cap); your AI asks you first. In rewards.yml, give_item takes item: minecraft:diamond and amount: 3.

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

The command lists are yours only. See Setup settings.

Services

From ShCore.api(), a get() method, or Bukkit's services manager:

sh-core: currencies and the audited money ledger, player data, settings, menus, the action registry, the collection box, playtime.
sh-economy EconomyService: balances, prices, registerPrice for your own items.
sh-api: ActionRegistry, CurrencyService, SnapshotService (ask for a backup first).
sh-crates KeyService: give earned keys.
sh-events: LeaderboardService, BoosterService, SeasonService, EventTypes.
sh-display DisplayService: your own boards and holograms.
sh-guard GuardService: combat and protection state, flags for staff.
sh-zones ZoneService: regions and your own flags.
sh-travel TravelService: spawn, warps, teleports with our warm-up.
sh-rewards RewardsService: record votes.
sh-teams TeamLookup, sh-bosses BossAbilities.
sh-lifesteal LifestealService: hearts and the bank, registerRule to lower or veto a steal (never raise), completeSpiritTrial, and telling real Heart items apart.
sh-box BoxService and sh-gens GensService: see Box PvP and Gens.

Events

Each part fires events. Cancellable ones run before a change; the rest report after. Examples: SellEvent (add a named multiplier), KeyGrantEvent, CrateOpenEvent (add a bonus; the rolled prize never changes), EventStartEvent, SeasonEndEvent, SpawnerGenerateEvent, BossEvents.Death, TeamEvents.Join, ZoneEnterEvent, TeleportEvent, CombatTagEvent, and the Box, Gens and Lifesteal events on their own pages.

Rules every add-on keeps

Money and keys change only through the ledger and key service: audited, within the daily key limit, keys earned only.
Crate chances are always shown. No key from a purchase.
Multipliers must be earned or server-wide, never sold. /sell never pays more than the shop.
Hearts, revives, protection and shorter bans are never sold or put in crates. Add-on heart rules can only make steals smaller.
Store players by ID only; no names, addresses or chat.