PaperMC / PaperMC/Paper

ParticleBuilder#spawn wrong documentation

Open
#13,339 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

status: accepted version: 1.21.10
Dominant language
Java
Stars
12.7k
Forks
3.5k
Avg merge
3d 13h
Merged PRs (30d)
11

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the ParticleBuilder#spawn documentation and trace the reported path through sendParticlesSource. Determine whether asynchronous use is supported or the documentation is incorrect; done means the API behavior and its async-safety documentation agree, with the relevant behavior verified.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.