ParticleBuilder#spawn wrong documentation

[3add]

Expected behavior

For either async to work as intended or the docs to state not async safe.

Observed/Actual behavior

The async doesn't work correctly, I lag out very fast on my client when I do so. Or the docs to state not async safe.

Steps/models to reproduce

When using the particle builder to spawn a particle ParticleBuilder#spawn says "Sends the particle to all receiving players (or all). This method is safe to use Asynchronously". Which is untrue because it eventually reroutes to the code below

public <T extends ParticleOptions> int sendParticlesSource(List<ServerPlayer> receivers, @Nullable Entity sender, T type, boolean overrideLimiter, boolean alwaysShow, double posX, double posY, double posZ, int particleCount, double xOffset, double yOffset, double zOffset, double speed) {
    ClientboundLevelParticlesPacket clientboundLevelParticlesPacket = new ClientboundLevelParticlesPacket(type, overrideLimiter, alwaysShow, posX, posY, posZ, (float)xOffset, (float)yOffset, (float)zOffset, (float)speed, particleCount);
    int i = 0;

    for(int i1 = 0; i1 < receivers.size(); ++i1) {
        ServerPlayer serverPlayer = (ServerPlayer)receivers.get(i1);
        if ((sender == null || serverPlayer.getBukkitEntity().canSee(sender.getBukkitEntity())) && this.sendParticles(serverPlayer, overrideLimiter, posX, posY, posZ, clientboundLevelParticlesPacket)) {
            ++i;
        }
    }

    return i;
}

Plugin and Datapack List

[09:02:08 INFO]: ℹ Server Plugins (10):
[09:02:08 INFO]: Bukkit Plugins:
[09:02:08 INFO]:  - FastAsyncWorldEdit, LiteBans, LuckPerms, NBTAPI, packetevents, StarRaid, Tebex, ViaBackwards, ViaVersion, Vulcan
[09:02:19 INFO]: There are 3 data pack(s) enabled: [vanilla (built-in)], [file/bukkit (world)], [paper (built-in)]
[09:02:19 INFO]: There are no more data packs available

Paper version

[09:02:32 INFO]: Checking version, please wait...
[09:02:32 INFO]: This server is running Paper version 1.21.10-113-main@9fc21bc (2025-11-14T16:11:13Z) (Implementing API version 1.21.10-R0.1-SNAPSHOT)
You are 2 version(s) behind
Download the new version at: https://papermc.io/downloads/paper
Previous version: 1.21.10-108-97452e1 (MC: 1.21.10)

Other

No response

[3add]

The async particle spawning does work, but it's not optimal because minecraft won't group the packets and thus you will overload users eventually resulting in them disconnecting. I guess u can consider it thread safe but in practice you'd never do this off the main thread. (Not a valid bug report)

[Malfrador]

To clarify, this issue has nothing to do with the client. Client performance is independent from the server. If you send a ton of particles, the client will lag. It does not matter if you do it on the main thread on the server or not.

However, the canSee access is indeed really not thread-safe, being backed by a plain old HashMap. That should be fixed or the Javadocs changed. If I recall correctly, canSee in general is kinda due for some improvements due to some other (performance) issues with that logic.