[Brigadier] Forks and redirects

[Strokkur424]

Note

This issue is part of a series of issues regarding the extension of the Paper documentation regarding Paper's Brigadier API.

Continuing with the advanced topics, there should also be a page noting the usage of .fork, .forward, and .redirect. Thanks to PaperMC/Paper#11868, this can now be achieved without the usage of internals or userdev.

Basically, the difference between these "flow controlling" methods should be noted and an example should be given. Furthermore, a reference to the CommandSourceStack#withExecutor/Location should be included. The fact that this is only available since the middle of version 1.21.4 could also be helpful.

A possible example could look like this:

final CommandDispatcher<CommandSourceStack> dispatcher = commands.getDispatcher();
final LiteralCommandNode<CommandSourceStack> node = dispatcher.register(Commands.literal("say")
    .then(Commands.literal("hi")
        .executes(ctx -> {
            if (ctx.getSource().getExecutor() instanceof Entity entity) {
                Bukkit.broadcast(MiniMessage.miniMessage().deserialize("<aqua><entity></aqua> says hi!",
                    Placeholder.component("entity", entity.name())
                ));
            }

            return 1;
        })));

dispatcher.register(Commands.literal("say-five").forward(node, ctx -> {
    final List<CommandSourceStack> stacks = new ArrayList<>();
    final List<Entity> entities = ctx.getSource().getLocation().getWorld().getEntities().stream().toList();

    for (int i = 0; i < 5; i++) {
        if (entities.size() < i) {
            break;
        }

        stacks.add(ctx.getSource().withExecutor(entities.get(i)));
    }

    return stacks;
}, true));