Skip to content

Contributing to MegaOrbitals

Thanks for helping. New cannons, bug fixes and ideas are all welcome.

  • Found a bug or have a cannon idea? Open an issue and pick a template.
  • Want to write code? Fork the repo, make your change on a branch and open a pull request.

Want your own cannons without changing MegaOrbitals? Write an addon plugin instead: see docs/addons.md.

Building

You need JDK 25 and Maven.

mvn clean package

The jar is written to target/. The build also regenerates src/main/resources/configs/*.yml and CANNONS.md. Include those generated files in your pull request.

To test, copy the jar into a Paper 26.1.2 server's plugins/ folder. Fire your cannon with /orbital <id>.

Adding a cannon

  1. Create a class in src/main/java/dev/megaorbitals/cannons/ that extends Cannon. It is found automatically, and its id is the class name in lower case (MyCannon → /orbital mycannon).
  2. Pick a name that is not already used. See CANNONS.md.
  3. Add the id to a tier and a category in src/main/java/dev/megaorbitals/Catalog.java.
public final class MyCannon extends Cannon {
    public MyCannon() {
        super("&c&lMy Cannon", Material.TNT, "First line of the description.", "Second line.");
        warning(30, "#FF4040");            // warning time in ticks and ring colour
        option("radius", 8.0, "Size of the blast.");
    }

    @Override
    public void strike(Strike s) {
        for (LivingEntity v : s.victims(s.at(), d("radius"))) s.damage(v, 10);
        s.explode(s.at(), 4f, false);
    }
}

Look at existing cannons for examples: HotPotato (timers), KingOfTheHill (minigame with a boss bar), Turrets (repeating attacks) and Crusher (moving block displays).

Rules

  • Change blocks only with Blocks.set / Blocks.put, never with setType or setBlockData. That way /orbital undo can put them back.
  • Respect the break-blocks setting. s.explode and s.blocks already do. For your own block changes, check s.breaks() first.
  • Use s.damage, s.victims and s.players. They skip the shooter (unless hurt-shooter is on) and players with megaorbitals.immune.
  • Big block edits should go through s.blocks(...), which spreads the work over several ticks to avoid lag.
  • Don't keep PotionEffectType, Enchantment or Attribute values in static fields. The build creates every cannon without a server, so use them inside methods only.
  • Clean up after yourself: remove spawned displays and entities when the cannon ends (s.expire helps).

The arsenal

The 1000 arsenal cannons are generated. To add a payload or pattern, edit Arsenal.java, then run:

python tools/generate_arsenal.py

Don't edit the generated classes (they start with // Generated by tools/generate_arsenal.py).

Pull requests

  • Keep each pull request to one thing (one cannon, or one fix).
  • Make sure mvn clean package passes. It must print Exported N cannon configs with no FAILED lines.
  • Add a line under ## [Unreleased] in CHANGELOG.md.
  • Say how you tested it in game.

By contributing, you agree your work is released under the project's CC0 1.0 licence.