Spooky season is here. Happy Halloween from Lattice!
Lattice
Docs/LatSantasSleigh

LatSantasSleigh

A sleigh flies a route on a schedule and drops presents for players to race to.

Overview

Module id
santas-sleigh
Version
1.0.0
Platforms
paper
Price
Paid
Authors
Atlantis Services

Install

  1. Install Lattice on a Paper or Folia server, if it is not there yet.
  2. Drop the LatSantasSleigh jar into plugins/Lattice/modules/. It loads straight away.
  3. Put your license key in lattice.yml, then run /lat license refresh.
  4. Edit config/global/santas-sleigh/ and apply it with /lat reload santas-sleigh.

Commands

Command names and aliases are set in config.yml, so yours may differ. <required> [optional]

Command Description Permission
/sleigh
also /santa
When the next sleigh flies santassleigh.use
/sleigh start
Send the sleigh out now santassleigh.admin
/sleigh stop
Remove the sleigh and its presents santassleigh.admin

Permissions

Permission Lets a player use
santassleigh.use
/sleigh
santassleigh.admin
/sleigh start, /sleigh stop

Placeholders

Filled in Lattice's own messages, and in any plugin that reads PlaceholderAPI when it is installed.

Placeholder Notes
%santassleigh_next%
%santassleigh_collected%

config.yml

Written to config/global/santas-sleigh/config.yml on first start. Edit it, then /lat reload santas-sleigh.

# Santa's sleigh: a sleigh flies a fixed route on a schedule and drops presents for players to race to.
# Start one by hand with /sleigh start, stop it with /sleigh stop.

# Generated from SantasSleighSettings. Keys you delete return to their default;
# keys that are not in the schema are ignored and reported on load.

command:
  # Command for the next run, and for staff to start and stop one. Takes effect on restart.
  name: "sleigh"
  aliases:
    - "santa"
  permission: "santassleigh.use"
  # Permission for /sleigh start and /sleigh stop.
  admin-permission: "santassleigh.admin"
# Timezone for the schedule, start, end and the daily limit, e.g. Europe/London.
timezone: "UTC"
# First day, as MM-DD, repeating every year. Leave start and end empty to run all year.
# An end before the start runs over the new year.
start: "12-01"
# Last day, inclusive, as MM-DD.
end: "12-26"
# Times of day the sleigh takes off, as HH:mm in the timezone above, on every day in the season.
# Empty means only /sleigh start. Only one run at a time: a slot that comes up while the
# sleigh is still out is skipped.
times:
  - "12:00"
  - "18:00"
# Minutes before takeoff that players are warned, in chat and on a boss bar. 0 for no warning.
warn-minutes: 5
# The flight path, in order. At least two points, all in one world, no two neighbours further
# apart than maxSegment. Every point's chunk must be loaded when a run starts, or the run is skipped:
# the sleigh never loads chunks. Replace this example with a route over your spawn.
route:
  - world: "world"
    x: 0.0
    y: 110.0
    z: 0.0
  - world: "world"
    x: 200.0
    y: 120.0
    z: 0.0
  - world: "world"
    x: 400.0
    y: 110.0
    z: 200.0
# How fast the sleigh flies. Position follows the clock, so server lag does not stretch a run.
speed-blocks-per-second: 12.0
# Longest allowed stretch between two waypoints, in blocks. A guard against a mistyped coordinate.
max-segment: 500.0
# Item shown as the whole sleigh when sleighModel is set. Otherwise the sleigh is built from the look.* items.
sleigh-item: "CHEST_MINECART"
# Item model key, as namespace:key, for a resource pack's own sleigh, replacing the built one. Empty to build it.
sleigh-model: null
# Reindeer flying ahead of the sleigh, 0 to 4.
reindeer: 2
# A present falls from the sleigh every this many blocks of route.
drop-every-blocks: 40.0
# Seconds a landed present waits before it disappears.
present-seconds: 60
# Most presents that exist at once. A drop that would go over is skipped.
max-presents: 8
# Walk this close to a landed present to collect it. Right-clicking it works too.
collect-radius: 1.5
# Chance, from 0 to 1, that a dropped present is a rare one, paying rareReward instead of reward.
rare-chance: 0.1
# Presents each player can collect per day, across every server sharing this storage.
# A present collected over the limit stays for someone else.
per-player-per-day: 5
# Given for an ordinary present.
reward:
  # Console commands. {player} is the player's name.
  commands:
    - "minecraft:give {player} cookie 8"
  # Sent to the player as a success line in the server theme. Empty for none.
  message: "<body>You caught a present. Cookies!"
  # Sound key, e.g. entity.player.levelup. Empty for none.
  sound: "entity.item.pickup"
# Given for a rare present.
rare-reward:
  # Console commands. {player} is the player's name.
  commands:
    - "minecraft:give {player} golden_apple 2"
  # Sent to the player as a success line in the server theme. Empty for none.
  message: "<accent>A rare present! Santa was feeling generous."
  # Sound key, e.g. entity.player.levelup. Empty for none.
  sound: "ui.toast.challenge_complete"
look:
  # The sleigh and the reindeer are built from blocks and items shown as displays. These are the
  # materials: the hull and its seat, the runners, Santa's coat and hat, his face, and the white trim
  # (hat bobble and beard). Ignored for the sleigh when sleighModel is set.
  hull-item: "RED_WOOL"
  runner-item: "DARK_OAK_PLANKS"
  santa-item: "RED_CONCRETE"
  face-item: "PINK_TERRACOTTA"
  trim-item: "WHITE_WOOL"
  # A reindeer's body and legs, its head and antlers, and the glowing nose on the one in front.
  reindeer-item: "BROWN_WOOL"
  reindeer-head-item: "BROWN_TERRACOTTA"
  nose-item: "RED_CONCRETE"
  # Present heads, as base64 skin texture values. Each present picks one at random, and the sack on the
  # sleigh uses the first. Rare presents use the same heads and glow gold.
  present-textures:
    - "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvMjFiYzlkNDJiMDA0MWU4Zjk1Y2I5YjI2NjI4ZmRhZjUwY2QwZTM2ZjdiYjlkNmIzYTRkMmFmMzk0OWRhOTdkNiJ9fX0="
    - "eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvMmIxZWM3ZGM3NTMwNjFjYTE3NDQyNGVhNDVjZjk0OTBiMzljZDVkY2NhNDc3ZDEzOGE2MDNlNmJlNzU1ZWM3MiJ9fX0="
  # Items that fly out when an ordinary present is opened. Only for show: the reward is the one above.
  burst-items:
    - "COOKIE"
    - "SUGAR"
    - "SNOWBALL"
    - "EMERALD"
    - "GOLD_NUGGET"
    - "SWEET_BERRIES"
  # Items that fly out when a rare present is opened.
  rare-burst-items:
    - "GOLDEN_APPLE"
    - "DIAMOND"
    - "NETHER_STAR"
    - "EMERALD"
    - "ENCHANTED_GOLDEN_APPLE"
  # How many items fly out of an opened present. 0 for none.
  burst-count: 10
  # Seconds the items fly before they vanish, 0.3 to 5.
  burst-seconds: 1.4
  # Size of the whole sleigh. 1 is about two blocks long.
  sleigh-scale: 1.0
  # Size of each reindeer.
  reindeer-scale: 1.0
  # Size of a present head.
  present-scale: 1.6
  # Blocks between the sleigh and the first row of reindeer, and between rows. They fly in pairs.
  reindeer-spacing: 3.0
  # How far the sleigh and reindeer rise and fall as they fly, in blocks. 0 to fly level.
  bob-blocks: 0.3
  # Particles in the trail behind the sleigh, per update. 0 for no trail.
  trail-particles: 3
  # Seconds a present takes to fall from the sleigh to the ground, 0.1 to 2.9.
  present-fall-seconds: 1.5
  # Seconds the sleigh keeps flying off past the last waypoint before it is removed.
  fly-off-seconds: 4
sounds:
  # Played to everyone when the sleigh takes off. Empty for none, here and below.
  takeoff: "entity.experience_orb.pickup"
  # Played at the sleigh every second or so while it flies, at a random pitch: its bells.
  bells: "block.note_block.bell"
  # Played at the sleigh as it lets a present go.
  drop: "entity.chicken.egg"
  # Played where a present lands.
  land: "block.chest.close"
  # Played where a rare present lands.
  rare-land: "block.amethyst_block.chime"
  # Played where a present bursts open.
  burst: "entity.firework_rocket.blast"
  # Played where a rare present bursts open.
  rare-burst: "entity.firework_rocket.twinkle"

Messages

Every line players see, in config/global/santas-sleigh/messages.yml. Uses MiniMessage formatting.

Show messages.yml (27 lines)
# Player-facing text for santas-sleigh.
# Placeholders in {braces} are filled in by the module.
# A key you delete falls back to its built-in default.

already-running: A sleigh is already out.
bar-flying: <accent><bold>Santa's sleigh</bold></accent><body> is flying! Catch the
  presents!
bar-waiting: <accent><bold>Santa's sleigh</bold></accent><body> takes off in <accent>{time}</accent>
busy: Your presents are still loading. Try again in a moment.
caught-today: '<body>Presents caught today: <accent>{count}</accent><muted>/</muted><accent>{limit}</accent>'
closed: Santa's sleigh is closed right now.
finished: <body>The sleigh has flown off. <accent>{total}</accent> present(s) were
  caught.
flying-now: <body>The sleigh is flying right now!
next: '<body>Next sleigh: <accent>{time}</accent> <muted>({zone})</muted>'
no-world: World '{world}' from the route is not loaded, so no run started.
none-scheduled: No sleigh is scheduled. Staff can start one.
not-running: No sleigh is out.
over-limit: You have already caught <accent>{limit}</accent> presents today. Leave
  this one for someone else.
started: <body>The sleigh is on its way.
stopped: <body>The sleigh was stopped and everything removed.
takeoff: <accent><bold>Santa's sleigh is in the air!</bold></accent><body> Follow
  it and catch the presents.
unloaded-waypoint: Waypoint {waypoint} is in an unloaded chunk, so no run started.
warning: <accent><bold>Santa's sleigh</bold></accent><body> takes off in <accent>{minutes}</accent>
  minute(s)! Get ready to catch presents.