Soccer

This is a fork of the original PhysicalBall plugin, reworked into a focused Soccer minigame plugin. The fork continues development, adds gameplay features and quality-of-life improvements, and adapts the plugin for modern Paper servers.

Important: this plugin is developed and tested against the Paper API. It is unlikely to run correctly on older Spigot/Bukkit-only servers, so use Paper for best compatibility.

Overview

Soccer turns the interactive "physical ball" concept into a playable football (soccer) minigame for Minecraft servers. The plugin provides in-world ball physics plus full game mechanics: goals, teams, scoring, visual and sound effects, skins, and admin tools to create and manage matches.

What this fork adds and improves

• Game management: create, list, join and leave matches; assign players to Team 1 or Team 2.
• Goal mechanics: create persistent goals (select with the provided tool), detect when a ball enters a goal and award points.
• Teams & team hats: players can join teams and are given team hats (decorative heads) while in a match; hats are protected and restored on leave/respawn.
• Ball activation: tie a specific ball (item) to a game so it counts for that match.
• Visuals: configurable particle effects for goals, field markers and ball interactions; on-screen markers show goal locations.
• Audio: configurable sound for goal events and broadcast sounds on goals.
• Skins: new skull/head-based skins.
• Stats & admin tools: live game stats command, per-game point tracking, commands to create/remove goals and activate balls.
• Cleaner commands and messages: improved in-game messages and config-driven localization.

Commands (selected)

• /soccer game join <game> <1|2> - join a game and select a team
• /soccer game leave - leave your current game
• /soccer stats <game> - show live stats for a game
• /soccer activate <game> - activate the ball you hold for a game (both goals must exist)
• /soccer goal create <1|2> <game> - start goal selection (gives selection tool)
• /soccer goal remove <1|2> <game> - remove a saved goal
• /soccer games - list configured games
• /soccer skin menu - open the skin selection menu

Permissions

The plugin uses a single main permission:

soccer.use

Players without this permission cannot use the plugin commands. Server operators retain access by default.

Configuration files

• config.yml - physics, throw power, bounce strength, and effect/sound keys and colours.
• messages.yml - all player-facing messages and action-bar text.
• skins.yml - configured skull skins, menu layout and permissions.

Technical notes

• Built for Paper: The plugin uses Paper API features and a per-tick ticker loop that updates ball entities and renders markers. Running on pure Spigot/Bukkit may fail or behave unpredictably.
• Storage: games and goals are persisted in games.yml in the plugin folder.

Where to look in the code (quick pointers)

• Game lifecycle, goals, and scoring: game.de.liebki.soccer.GameManager
• Per-game state and teams: game.de.liebki.soccer.GameSession
• Ball physics and events: ball.de.liebki.soccer.Ball and BallsContainer
• Skins and menu: skin.de.liebki.soccer.SkinChanger, SkullSkin, SkullsContainer
• Particles/sounds helpers: tools.de.liebki.soccer.EffectUtils
• CLI, commands and tab completion: de.liebki.soccer.CommandListener

License & original credits

This repository contains work based on the original PhysicalBall project and remains under the MIT License. Please keep the original copyright and license notices when distributing.

Original project page (for reference): https://modrinth.com/plugin/physicalball

Acknowledgements

Thanks to the authors of the original PhysicalBall plugin and the original-original authors for starting this!