⚽ NeaFutbol

Modern, lightweight soccer minigame designed for Minecraft lobbies and arcade networks. Features custom ball physics, holographic live scoreboards, automatic team balancing, goal fireworks, persistent player statistics, and native PlaceholderAPI integration.

---

Overview

NeaFutbol turns any area in your server into an interactive soccer stadium. Players join matches, get assigned to teams (Blue vs. Red) with colored leather armor, and compete to score goals. Everything runs smoothly without heavy external dependencies or impacting server TPS.

---

Features

• ⚽ Realistic Ball Physics: Smooth ball trajectory calculations with configurable kick power (kick-power), launch height (kick-height), passing speed (pass-power), friction deceleration, and boundary bounces.
• 📊 Real-Time Floating Hologram: Native, lightweight floating scoreboard displaying live match time, team scores, and a dynamic color-coded progress bar.
• 👕 Auto Team Balancing: Automatically assigns joining players to Blue and Red teams with colored team armor.
• 🥅 3D Goal Detection: Precise goal hitbox detection triggering fireworks, celebratory titles, sound effects, and central ball reset.
• 📈 Persistent Player Statistics: Tracks lifetime goals, wins, and matches played per player UUID.
• 🧩 PlaceholderAPI Support: Full suite of placeholders for TAB, scoreboard plugins, holograms, and chat formatters.
• 🛑 Out-of-Bounds Detection: Detects when the ball leaves the field and initiates a fair throw-in restart.
• 🧹 Orphan Entity Cleanup: Built-in /nf purgeholo command to clean up any leftover hologram or ball entities.
• 🌐 Fully Configurable: All messages, titles, sounds, and timers can be customized via config.yml and lang.yml.

---

Placeholders

NeaFutbol provides native PlaceholderAPI expansion variables:

Placeholder	Scope	Description	Example
%neafutbol_goals%	Player	Total career goals scored by the player	15
%neafutbol_wins%	Player	Total career matches won	9
%neafutbol_matches%	Player	Total matches played	24
%neafutbol_team%	Player	Current team (Blue, Red, or None)	Blue
%neafutbol_in_game%	Player	Whether the player is currently in a match	true
%neafutbol_score_blue%	Match	Current goals scored by Blue Team	2
%neafutbol_score_red%	Match	Current goals scored by Red Team	1
%neafutbol_match_score%	Match	Live consolidated match score	2 - 1
%neafutbol_match_time%	Match	Formatted remaining match time (MM:SS)	04:12
%neafutbol_time_seconds%	Match	Raw seconds remaining in the match	252
%neafutbol_match_state%	Match	Current game state (Playing, Waiting)	Playing
%neafutbol_players%	Match	Current number of active players	4
%neafutbol_max_players%	Match	Configured maximum player capacity	4

---

Commands

Primary command: /neafutbol (Aliases: /nf, /futbol).

Player Commands

Command	Permission	Description
/nf join	neafutbol.join	Join the matchmaking queue or active match.
/nf leave	neafutbol.use	Leave the current match and return to previous location.
/nf help	neafutbol.use	Display the help menu.

Admin Commands

Command	Permission	Description
/nf wand	neafutbol.admin	Receive the selection stick tool for boundaries and goals.
/nf setarena	neafutbol.admin	Save field boundaries using your wand selection.
`/nf setgoal <team1	team2>`	neafutbol.admin
`/nf setspawn <team1	team2	lobby>`
/nf setball	neafutbol.admin	Set the center ball spawn point.
/nf setholo	neafutbol.admin	Spawn or move the floating scoreboard hologram.
/nf removeholo	neafutbol.admin	Remove the active scoreboard hologram.
/nf purgeholo	neafutbol.admin	Clean up orphaned armor stands or residual ball entities.
/nf forcestart	neafutbol.admin	Force the match countdown to start immediately.
/nf reload	neafutbol.admin	Hot-reload config.yml and lang.yml.

---

Permissions

Permission	Description	Default
neafutbol.use	Access to basic player commands and help menu.	Everyone
neafutbol.join	Allows joining soccer matches.	Everyone
neafutbol.admin	Full access to arena configuration and admin commands.	OP

---

Setup Guide

Set up a working soccer arena in under 5 minutes:

1. Build the Stadium: Construct your field with enclosed boundaries (walls/glass) and goal nets at both ends.
2. Define Field Boundaries:
   • Run /nf wand to get the selection stick.
   • Left-click corner 1 (bottom corner).
   • Right-click corner 2 (opposite diagonal top corner).
   • Run /nf setarena.
3. Define Goal Areas:
   • Select the interior of the Blue goal with /nf wand and run /nf setgoal team1.
   • Select the interior of the Red goal with /nf wand and run /nf setgoal team2.
4. Set Spawn Locations:
   • Stand where Blue team should spawn and run /nf setspawn team1.
   • Stand where Red team should spawn and run /nf setspawn team2.
   • Stand at the waiting lobby and run /nf setspawn lobby.
   • Stand in the exact center of the field and run /nf setball.
5. Add Floating Scoreboard:
   • Fly to where you want the scoreboard floating and run /nf setholo.

---

Configuration

config.yml

game:
  min-players: 2        # Minimum players required to start match
  max-players: 4        # Maximum player capacity per match
  duration-seconds: 300 # Match length in seconds (5 minutes)
  countdown-seconds: 60 # Lobby countdown before match starts
  goal-radius: 2.0      # Goal detection radius
  team-armor: true      # Automatically equip colored leather armor

ball:
  skin: "MHF_CoconutB"  # Skull skin for soccer ball
  y-modifier: -0.5      # Height offset for ball center of mass
  hitbox-range: 3.5     # Interaction radius for kicking
  kick-power: 1.2       # Ball shoot velocity
  kick-height: 0.6      # Vertical lift on shots
  pass-power: 1.2       # Ground pass velocity

---

Support

• Author: Nea#9654
• GitHub Repository: NeaCol/NeaFutbol
• Issue Tracker: NeaCol/NeaFutbol Issues