Audience System

/**
 * Universal interface for any receiver of Minecraft media
 */
interface Audience extends Pointered {
    // Message sending
    /**
     * Sends a chat message to this audience
     * @param message the message to send
     */
    void sendMessage(ComponentLike message);
    
    /**
     * Sends a message with a specific message type
     * @param message the message
     * @param type the message type
     * @deprecated for removal since 4.12.0, MessageType is deprecated for removal, use {@link #sendMessage(ComponentLike)} instead
     */
    @Deprecated
    void sendMessage(ComponentLike message, MessageType type);
    
    /**
     * Sends a signed message
     * @param signedMessage the signed message
     * @param boundChatType the chat type
     */
    void sendMessage(SignedMessage signedMessage, ChatType.Bound boundChatType);
    
    /**
     * Deletes a signed message
     * @param signature the message signature to delete
     */
    void deleteMessage(SignedMessage.Signature signature);
    
    /**
     * Sends an action bar message
     * @param message the action bar message
     */
    void sendActionBar(ComponentLike message);
    
    // Player list (tab list) management
    /**
     * Sends player list header and footer
     * @param header the header component
     * @param footer the footer component
     */
    void sendPlayerListHeaderAndFooter(ComponentLike header, ComponentLike footer);
    
    /**
     * Sends player list header
     * @param header the header component
     */
    void sendPlayerListHeader(ComponentLike header);
    
    /**
     * Sends player list footer
     * @param footer the footer component
     */
    void sendPlayerListFooter(ComponentLike footer);
    
    // Title display
    /**
     * Shows a title to this audience
     * @param title the title to show
     */
    void showTitle(Title title);
    
    /**
     * Clears the currently displayed title
     */
    void clearTitle();
    
    /**
     * Resets the title (clears and resets timing)
     */
    void resetTitle();
    
    /**
     * Sends a specific title part
     * @param part the title part to send
     * @param value the value for the title part
     */
    <T> void sendTitlePart(TitlePart<T> part, T value);
    
    // Boss bar management
    /**
     * Shows a boss bar to this audience
     * @param bar the boss bar to show
     */
    void showBossBar(BossBar bar);
    
    /**
     * Hides a boss bar from this audience
     * @param bar the boss bar to hide
     */
    void hideBossBar(BossBar bar);
    
    // Sound playback
    /**
     * Plays a sound to this audience
     * @param sound the sound to play
     */
    void playSound(Sound sound);
    
    /**
     * Plays a sound at a specific location
     * @param sound the sound to play
     * @param x the x coordinate
     * @param y the y coordinate  
     * @param z the z coordinate
     */
    void playSound(Sound sound, double x, double y, double z);
    
    /**
     * Plays a sound following an emitter
     * @param sound the sound to play
     * @param emitter the sound emitter
     */
    void playSound(Sound sound, Sound.Emitter emitter);
    
    /**
     * Stops sound playback
     * @param stop the sound stop request
     */
    void stopSound(SoundStop stop);
    
    // Books and UI
    /**
     * Opens a book for this audience
     * @param book the book to open
     */
    void openBook(Book book);
    
    // Resource pack management
    /**
     * Sends resource pack requests to this audience
     * @param request the resource pack request
     */
    void sendResourcePacks(ResourcePackRequest request);
    
    /**
     * Removes resource packs from this audience
     * @param request the resource pack removal request
     */
    void removeResourcePacks(ResourcePackRequest request);
    
    /**
     * Removes resource packs by info
     * @param first the first resource pack to remove
     * @param others additional resource packs to remove
     */
    void removeResourcePacks(ResourcePackInfoLike first, ResourcePackInfoLike... others);
    
    /**
     * Removes resource packs by UUID
     * @param id the first resource pack ID to remove
     * @param others additional resource pack IDs to remove
     */
    void removeResourcePacks(UUID id, UUID... others);
    
    /**
     * Removes resource packs by UUID collection
     * @param ids the resource pack IDs to remove
     */
    void removeResourcePacks(Iterable<UUID> ids);
    
    /**
     * Sends resource pack info directly
     * @param first the first resource pack to send
     * @param others additional resource packs to send
     */
    void sendResourcePacks(ResourcePackInfoLike first, ResourcePackInfoLike... others);
    
    // Audience filtering and properties
    /**
     * Filters this audience based on a predicate
     * @param filter the filter predicate
     * @return filtered audience
     */
    default Audience filterAudience(Predicate<? super Audience> filter) {
        return filter.test(this) ? this : Audience.empty();
    }
    
    /**
     * Executes an action against all audiences
     * @param action the action to perform
     */
    default void forEachAudience(Consumer<? super Audience> action) {
        action.accept(this);
    }
    
    /**
     * Shows a dialog to this audience (since 4.22.0, Minecraft 1.21.6)
     * @param dialog the dialog to show
     */
    void showDialog(DialogLike dialog);
    
    /**
     * Deletes a signed message
     * @param signedMessage the signed message to delete
     */
    void deleteMessage(SignedMessage signedMessage);
    
    /**
     * Stops a specific sound
     * @param sound the sound to stop
     */
    void stopSound(Sound sound);
    
    /**
     * Opens a book using a book builder
     * @param book the book builder
     */
    void openBook(Book.Builder book);
    
    // Factory methods
    /**
     * Creates an empty audience that ignores all operations
     * @return empty audience
     */
    static Audience empty();
    
    /**
     * Creates an audience that forwards to many other audiences
     * @param audiences array of audiences
     * @return forwarding audience
     */
    static Audience audience(Audience... audiences);
    
    /**
     * Creates an audience that forwards to many other audiences
     * @param audiences iterable of audiences
     * @return forwarding audience
     */
    static ForwardingAudience audience(Iterable<? extends Audience> audiences);
    
    /**
     * Provides a collector to create a forwarding audience from a stream
     * @return collector for audiences
     */
    static Collector<? super Audience, ?, ForwardingAudience> toAudience();
}

import net.kyori.adventure.audience.Audience;
import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.format.NamedTextColor;

// Send a simple message
audience.sendMessage(Component.text("Hello World!", NamedTextColor.GREEN));

// Send an action bar message
audience.sendActionBar(Component.text("Health: 100%", NamedTextColor.RED));

// Show a title
Title title = Title.title(
    Component.text("Welcome!", NamedTextColor.GOLD),
    Component.text("Enjoy your stay", NamedTextColor.YELLOW),
    Title.Times.times(Duration.ofSeconds(1), Duration.ofSeconds(3), Duration.ofSeconds(1))
);
audience.showTitle(title);

// Play a sound
Sound sound = Sound.sound(Key.key("entity.experience_orb.pickup"), Sound.Source.PLAYER, 1.0f, 1.0f);
audience.playSound(sound);

/**
 * Audience that forwards operations to multiple underlying audiences
 */
interface ForwardingAudience extends Audience {
    /**
     * Gets the audiences that this audience forwards to
     * @return iterable of audiences
     */
    Iterable<? extends Audience> audiences();
    
    /**
     * Performs an action on each audience
     * @param action the action to perform
     */
    default void forEachAudience(Consumer<? super Audience> action) {
        for (final Audience audience : this.audiences()) {
            action.accept(audience);
        }
    }
}

/**
 * Forwarding audience that targets a single underlying audience
 */
interface ForwardingAudience.Single extends ForwardingAudience {
    /**
     * Gets the single audience this forwards to
     * @return the target audience
     */
    @NotNull Audience audience();
    
    /**
     * Default implementation returns singleton iterable
     * @return iterable containing single audience
     */
    @Override
    default @NotNull Iterable<? extends Audience> audiences() {
        return Collections.singleton(this.audience());
    }
}

/**
 * Utility class for audience operations and factories
 */
final class Audiences {
    /**
     * Creates an audience that will send a message to each audience
     * @param message the message to send
     * @return consumer that sends the message
     */
    static Consumer<? super Audience> sendingMessage(ComponentLike message);
}

import net.kyori.adventure.audience.Audiences;
import java.util.Arrays;
import java.util.stream.Stream;

// Create composite audience
Audience broadcast = Audiences.audience(player1, player2, console);
broadcast.sendMessage(Component.text("Broadcast message"));

// Create audience from collection
List<Audience> playerList = getOnlinePlayers();
Audience allPlayers = Audiences.audience(playerList);

// Use collector to combine audiences
Audience adminBroadcast = admins.stream()
    .collect(Audiences.toAudience());

/**
 * Types of messages that can be sent to audiences
 * @deprecated for removal since 4.12.0, use separate methods or ChatType.Bound instead
 */
@Deprecated
enum MessageType {
    /**
     * A standard chat message
     * @deprecated for removal since 4.12.0
     */
    @Deprecated
    CHAT,
    
    /**
     * A system message (server announcements, etc.)
     * @deprecated for removal since 4.12.0
     */
    @Deprecated
    SYSTEM;
    
    /**
     * Gets the message type by ordinal
     * @param index the ordinal
     * @return the message type
     * @deprecated for removal since 4.12.0
     */
    @Deprecated
    static MessageType byOrdinal(int index);
}

/**
 * Marks an object as having an identity
 */
interface Identified {
    /**
     * Gets the identity of this object
     * @return the identity
     */
    Identity identity();
}

/**
 * Represents an identity with UUID and name
 */
interface Identity extends Examinable {
    /**
     * Gets the UUID of this identity
     * @return the UUID
     */
    UUID uuid();
    
    /**
     * Creates an identity from a UUID
     * @param uuid the UUID
     * @return new identity
     */
    static Identity identity(UUID uuid);
    
    /**
     * Creates a nil identity (all zeros UUID)
     * @return nil identity
     */
    static Identity nil();
}

/**
 * Objects that can have pointers attached
 */
interface Pointered {
    /**
     * Gets the pointers for this object
     * @return the pointers collection
     */
    @NotNull Pointers pointers();
    
    /**
     * Gets a value by pointer
     * @param pointer the pointer key
     * @return optional containing the value
     */
    default <T> @NotNull Optional<T> get(@NotNull Pointer<T> pointer) {
        return Optional.ofNullable(this.pointers().get(pointer));
    }
    
    /**
     * Gets a value by pointer with a default
     * @param pointer the pointer key
     * @param defaultValue the default value
     * @return the value or default
     */
    default <T> @Nullable T getOrDefault(@NotNull Pointer<T> pointer, @Nullable T defaultValue) {
        return this.pointers().get(pointer, defaultValue);
    }
    
    /**
     * Gets a value by pointer or computes it
     * @param pointer the pointer key
     * @param defaultValue supplier for default value
     * @return the value or computed default
     */
    default <T> @UnknownNullability T getOrDefaultFrom(@NotNull Pointer<T> pointer, @NotNull Supplier<? extends T> defaultValue) {
        return this.pointers().getOrDefaultFrom(pointer, defaultValue);
    }
}

/**
 * Type-safe key for storing typed values
 */
interface Pointer<T> extends Examinable {
    /**
     * Gets the type of values this pointer holds
     * @return the value type
     */
    Class<T> type();
    
    /**
     * Gets the key identifier
     * @return the key
     */
    Key key();
    
    /**
     * Creates a pointer
     * @param type the value type
     * @param key the key
     * @return new pointer
     */
    static <T> Pointer<T> pointer(Class<T> type, Key key);
    
    /**
     * Creates a pointer with string key
     * @param type the value type
     * @param key the key string
     * @return new pointer
     */
    static <T> Pointer<T> pointer(Class<T> type, String key);
}

/**
 * Collection of pointers with type-safe operations
 */
interface Pointers extends Examinable {
    /**
     * Checks if a pointer is supported
     * @param pointer the pointer
     * @return true if supported
     */
    <T> boolean supports(Pointer<T> pointer);
    
    /**
     * Gets a value by pointer
     * @param pointer the pointer
     * @return the value or null
     */
    <T> @Nullable T get(Pointer<T> pointer);
    
    /**
     * Creates an empty pointers collection
     * @return empty pointers
     */
    static Pointers empty();
    
    /**
     * Creates a builder for pointers
     * @return new builder
     */
    static Builder builder();
    
    interface Builder extends AbstractBuilder<Pointers> {
        /**
         * Sets a pointer value
         * @param pointer the pointer
         * @param value the value
         * @return this builder
         */
        <T> Builder withStatic(Pointer<T> pointer, T value);
        
        /**
         * Sets a dynamic pointer value
         * @param pointer the pointer
         * @param value the value supplier
         * @return this builder
         */
        <T> Builder withDynamic(Pointer<T> pointer, Supplier<T> value);
    }
}

/**
 * Permission checking interface
 */
interface PermissionChecker extends Predicate<String> {
    /**
     * Checks if a permission is granted
     * @param permission the permission string
     * @return true if permission is granted
     */
    @Override
    boolean test(String permission);
    
    /**
     * Creates a permission checker that always returns true
     * @return always-true checker
     */
    static PermissionChecker always();
    
    /**
     * Creates a permission checker that always returns false
     * @return always-false checker
     */
    static PermissionChecker never();
}

// Filter audiences based on permission
Audience permissionFiltered = allPlayers.filterAudience(audience -> 
    audience.get(PERMISSION_POINTER).test("some.permission"));

// Filter by location or other criteria
Audience nearbyPlayers = allPlayers.filterAudience(audience -> {
    Location loc = audience.get(LOCATION_POINTER);
    return loc != null && loc.distance(center) < 100;
});

// Create targeted broadcast
Audience admins = Audiences.audience(
    server.getPlayers().stream()
        .filter(player -> player.hasPermission("admin"))
        .collect(Audiences.toAudience())
);

// Send announcements
Audience everyone = Audiences.audience(players, console);
everyone.sendMessage(Component.text("Server restart in 5 minutes"));

// Consistent message formatting
Component formatServerMessage(String content) {
    return Component.text()
        .append(Component.text("[SERVER] ", NamedTextColor.BLUE, TextDecoration.BOLD))
        .append(Component.text(content, NamedTextColor.WHITE))
        .build();
}

audience.sendMessage(formatServerMessage("Welcome to the server!"));