Add Support for Scoreboard Teams on Folia by Jsinco · Pull Request #3296 · CitizensDev/Citizens2

Jsinco · 2026-02-28T19:30:35Z

This PR adds support for the "scoreboardtrait" trait by introducing this library as a shaded dependency and sending all scoreboard and player-team related things with packets.

I want to note the fact that including this library may make Bukkit-based scoreboard teams obsolete because Citizens does not actually add players to teams and instead sends teams using packets. Citizens appears to only use Bukkit-based teams for registering and getting the client to recognize certain attributes of the team. This library does all of that without making any native calls so including a Bukkit implementation may no longer be required unless you think Citizens will need it.

I made my changes in the ScoreboardTrait class under the assumption that Citizens2 only runs on 1.21.1+ based servers (based on the NMS implementations available).

CLAassistant · 2026-02-28T19:30:40Z

All committers have signed the CLA.

Euphillya · 2026-02-28T19:46:22Z

main/src/main/java/net/citizensnpcs/EventListen.java

+            CitizensAPI.getScheduler().runEntityTask(npc.getEntity(), () -> {
+                boolean despawned = npc.despawn(DespawnReason.WORLD_UNLOAD);
+                if (event.isCancelled() || !despawned) {
+                    for (ChunkCoord coord : Lists.newArrayList(toRespawn.keySet())) {
+                        if (event.getWorld().getUID().equals(coord.worldUUID)) {
+                            respawnAllFromCoord(coord, event);
+                        }
                    }
+                    event.setCancelled(true);
+                    return;
                }
-                event.setCancelled(true);
-                return;
-            }
-            if (npc.isSpawned()) {
-                toRespawn.put(new ChunkCoord(npc.getEntity().getLocation()), npc);
-                Messaging.debug("Despawned", npc, "due to world unload at", event.getWorld().getName());
-            }
+                if (npc.isSpawned()) {
+                    toRespawn.put(new ChunkCoord(npc.getEntity().getLocation()), npc);
+                    Messaging.debug("Despawned", npc, "due to world unload at", event.getWorld().getName());
+                }
+            });


The event cannot be canceled because you are delayed to the next tick, and therefore the event will already have been resolved.

Reverted changes because it's out of scope for this PR

SNWCreations

Looks good. imo it is not necessary to introduce indent changes here.
And I think it is good for moving the codebase towards the lib even when on Spigot, since I know how the lib you used do its great work in my several projects. Also avoid unnecessary scoreboard data created by Citizens got saved by NMS when shutting down servers, provides a more clean experience.

main/src/main/java/net/citizensnpcs/trait/ScoreboardTrait.java

main/src/main/java/net/citizensnpcs/Citizens.java

main/pom.xml

Euphillya · 2026-03-10T04:06:23Z

main/src/main/java/net/citizensnpcs/trait/scoreboard/FoliaTeamImpl.java

+    public void sendToPlayer(Player player, SendMode mode) {
+        // TODO: Currently not implemented
+        /*if (mode == SendMode.ADD_OR_MODIFY) {
+            delegateDisplay.refresh();
+            delegateTeam.display(player, delegateDisplay);
+        } else {
+            delegateTeam.display(player, delegateTeam.defaultDisplay());
+        }*/
+    }


Is there a specific reason why this hasn't been implemented, or is it just an oversight?

Agreed, TODOs should be finished

Okay, after taking a look it just seems to be unnecessary. I had actually forgotten why I commented this out to begin with, but it was because the scoreboard library itself doesn't support not sending anything at all. There always has to be a TeamDisplay assigned to a ScoreboardTeam and all this method would do is just flip-flop between TeamDisplay objects. I commented it out and left the // TODO because I was going to look into it.

If you guys would prefer me to remove the TODO entirely, I can go ahead and do that.

So does the library just refresh every so often or whenever the team is modified?

So does the library just refresh every so often or whenever the team is modified?

The library have its own task queue mechanism for updating team properties. devs change properties through their API, their implementation sends packet in async then, no manual packet sending needed.

Addition: packets for teams created by the lib were only sent to the players who had been added to the team view through "display" method. to make the player a member of the created team, use "addPlayer" on their team objects. "display" method just make players able to see the effects on the players in the team (nametag visibility, invisible see, etc.)
Note that the properties that needs NMS to do specific logic like collision will not work for such teams, because the team collision check is done in NMS code by checking what vanilla team the player is in.

fullwall · 2026-03-10T16:30:44Z

Looks good, have you tested these changes actually load?

fullwall · 2026-03-13T17:22:05Z

Can merge if someone can confirm that these are tested changes on a Folia server

Reviewed

SNWCreations · 2026-03-14T03:49:39Z

Can merge if someone can confirm that these are tested changes on a Folia server

In the meantime, did these changes tested on regular Spigot/Paper server as well?

Jsinco · 2026-03-16T15:22:39Z

Will update this PR sometime tomorrow or the day after

Jsinco · 2026-03-20T02:03:56Z

I have only tested these changes on Folia and Canvas, not on Paper or Spigot. I imagine everything will work the same because I pretty much copied-pasted the original implementations into delegate classes, but it's possible I may have made a typo or something. I can test on Paper sometime tomorrow or this weekend but my schedule has been a bit random lately.

(I have been running this in production on my Canvas server.)

Jsinco · 2026-03-20T02:05:09Z

If there's anything else that needs to be addressed, feel free to let me know and I'll update this PR as soon as possible.

Jsinco · 2026-04-12T19:13:06Z

I've updated sendToPlayer with the code from the listeners so as to properly implement it and keep parity with the BukkitTeamImpl

SNWCreations · 2026-04-12T22:43:07Z

main/src/main/java/net/citizensnpcs/trait/scoreboard/FoliaTeamImpl.java

-            delegateTeam.display(player, delegateDisplay);
+        if (mode == SendMode.ADD_OR_MODIFY) {
+            plugin.getTeamManager().addPlayer(player);
        } else {


not recommended to use else unless you are sure the enum will not have new members in refactoring from future. consider switch statement or use "else fail" if all known literal from enum is checked but no match.

All are in my opinion. Don't know how fullwall think.

Add Folia scoreboard support

b49c613

Euphillya suggested changes Feb 28, 2026

View reviewed changes

Add Javadocs

3444a52

Jsinco force-pushed the master branch from 15322af to 3444a52 Compare February 28, 2026 19:56

Remove unnecessary changes

025c4ee

SNWCreations reviewed Mar 7, 2026

View reviewed changes

fullwall reviewed Mar 7, 2026

View reviewed changes

Jsinco added 5 commits March 9, 2026 20:10

Merge remote-tracking branch 'origin/master'

0b66668

feat(folia): cleanup code

7820418

feat(folia): properly relocate scoreboardlibrary

df752cf

feat(folia): cleanup

88271f6

feat(folia): remove uncalled try-catch

4e0d7e4

Jsinco requested review from Euphillya and fullwall March 10, 2026 00:38

Jsinco added 2 commits March 9, 2026 20:54

feat(folia): move dummy scoreboard utility

99c68b3

feat(folia): use javax annotations

25e20a4

Euphillya previously requested changes Mar 10, 2026

View reviewed changes

Merge branch 'master' of https://github.com/CitizensDev/Citizens2

bc75c7e

Jsinco added 3 commits April 12, 2026 06:22

Merge remote-tracking branch 'origin/master'

688e800

feat(folia): properly implement sendToPlayer

769f624

chore(26.1.2): update 26.1.1 to 26.1.2

56aa40f

SNWCreations reviewed Apr 12, 2026

View reviewed changes

Merge remote-tracking branch 'origin/master'

0d36910

Uh oh!

Conversation

Jsinco commented Feb 28, 2026

Uh oh!

CLAassistant commented Feb 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Euphillya Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

Jsinco Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

SNWCreations left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Euphillya Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

fullwall Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Jsinco Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fullwall Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

SNWCreations Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

SNWCreations Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

fullwall commented Mar 10, 2026

Uh oh!

fullwall commented Mar 13, 2026

Uh oh!

SNWCreations commented Mar 14, 2026

Uh oh!

Jsinco commented Mar 16, 2026

Uh oh!

Jsinco commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Jsinco commented Mar 20, 2026

Uh oh!

Jsinco commented Apr 12, 2026

Uh oh!

SNWCreations Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

CLAassistant commented Feb 28, 2026 •

edited

Loading

fullwall Mar 13, 2026 •

edited

Loading

Jsinco Mar 20, 2026 •

edited

Loading

Jsinco commented Mar 20, 2026 •

edited

Loading