Titles and Subtitles

/**
 * Represents a title display with main title, subtitle, and timing
 */
interface Title extends Examinable {
    /**
     * Gets the main title text
     * @return the title component
     */
    Component title();
    
    /**
     * Gets the subtitle text
     * @return the subtitle component
     */
    Component subtitle();
    
    /**
     * Gets the title timing configuration
     * @return the times or null for default
     */
    @Nullable Times times();
    
    /**
     * Creates a title with main title and subtitle
     * @param title the main title
     * @param subtitle the subtitle
     * @return new title
     */
    static Title title(ComponentLike title, ComponentLike subtitle);
    
    /**
     * Creates a title with timing
     * @param title the main title
     * @param subtitle the subtitle
     * @param times the timing configuration
     * @return new title
     */
    static Title title(ComponentLike title, ComponentLike subtitle, @Nullable Times times);
    
    /**
     * Title timing configuration
     */
    class Times implements Examinable {
        /**
         * Gets the fade in duration
         * @return fade in duration
         */
        Duration fadeIn();
        
        /**
         * Gets the stay duration
         * @return stay duration
         */
        Duration stay();
        
        /**
         * Gets the fade out duration
         * @return fade out duration
         */
        Duration fadeOut();
        
        /**
         * Creates title timing
         * @param fadeIn fade in duration
         * @param stay stay duration
         * @param fadeOut fade out duration
         * @return new timing configuration
         */
        static Times times(Duration fadeIn, Duration stay, Duration fadeOut);
        
        /**
         * Creates timing with tick values
         * @param fadeInTicks fade in ticks
         * @param stayTicks stay ticks
         * @param fadeOutTicks fade out ticks
         * @return new timing configuration
         */
        static Times of(int fadeInTicks, int stayTicks, int fadeOutTicks);
        
        /**
         * Default title timing
         * @return default times (1s fade in, 3s stay, 1s fade out)
         */
        static Times defaultTimes();
    }
}

/**
 * Individual part of a title for separate updates
 */
interface TitlePart<T> {
    /**
     * Gets the part value
     * @return the value
     */
    T value();
    
    /**
     * Creates a main title part
     * @param title the title text
     * @return title part
     */
    static TitlePart<Component> title(ComponentLike title);
    
    /**
     * Creates a subtitle part
     * @param subtitle the subtitle text
     * @return subtitle part
     */
    static TitlePart<Component> subtitle(ComponentLike subtitle);
    
    /**
     * Creates a timing part
     * @param times the timing configuration
     * @return timing part
     */
    static TitlePart<Title.Times> times(Title.Times times);
}

import net.kyori.adventure.title.Title;
import net.kyori.adventure.title.TitlePart;
import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.format.NamedTextColor;
import java.time.Duration;

// Simple title
Title welcome = Title.title(
    Component.text("Welcome!", NamedTextColor.GOLD),
    Component.text("Enjoy your stay", NamedTextColor.YELLOW)
);
audience.showTitle(welcome);

// Title with custom timing
Title announcement = Title.title(
    Component.text("Server Restart", NamedTextColor.RED),
    Component.text("In 5 minutes", NamedTextColor.WHITE),
    Title.Times.times(
        Duration.ofMillis(500),  // 0.5s fade in
        Duration.ofSeconds(5),   // 5s stay
        Duration.ofSeconds(1)    // 1s fade out
    )
);

// Update title parts separately
audience.sendTitlePart(TitlePart.title(Component.text("Updated Title")));
audience.sendTitlePart(TitlePart.subtitle(Component.text("New subtitle")));

// Quick timing for urgent messages
Title urgent = Title.title(
    Component.text("DANGER!", NamedTextColor.DARK_RED),
    Component.text("Move away immediately", NamedTextColor.RED),
    Title.Times.times(
        Duration.ofMillis(100),  // Fast fade in
        Duration.ofSeconds(2),   // Short display
        Duration.ofMillis(300)   // Quick fade out
    )
);

// Clear and reset titles
audience.clearTitle();  // Clear current title
audience.resetTitle();  // Clear and reset timing

public class TitleAnnouncements {
    public static void showPlayerJoin(Audience audience, String playerName) {
        Title joinTitle = Title.title(
            Component.text(playerName + " joined!", NamedTextColor.GREEN),
            Component.text("Welcome to the server", NamedTextColor.GRAY)
        );
        audience.showTitle(joinTitle);
    }
    
    public static void showLevelUp(Audience audience, int level) {
        Title levelTitle = Title.title(
            Component.text("Level Up!", NamedTextColor.GOLD),
            Component.text("Level " + level, NamedTextColor.YELLOW),
            Title.Times.times(Duration.ofSeconds(1), Duration.ofSeconds(2), Duration.ofSeconds(1))
        );
        audience.showTitle(levelTitle);
    }
    
    public static void showCountdown(Audience audience, int seconds) {
        Component countdownText = Component.text(
            String.valueOf(seconds), 
            seconds <= 3 ? NamedTextColor.RED : NamedTextColor.YELLOW
        );
        
        Title countdown = Title.title(
            countdownText,
            Component.text("Get ready!", NamedTextColor.WHITE),
            Title.Times.times(Duration.ofMillis(200), Duration.ofMillis(800), Duration.ofMillis(200))
        );
        audience.showTitle(countdown);
    }
}

// Countdown sequence
public void startCountdown(Audience audience, int startSeconds) {
    for (int i = startSeconds; i > 0; i--) {
        final int seconds = i;
        scheduleTask(() -> {
            Component countText = Component.text(String.valueOf(seconds))
                .color(seconds <= 3 ? NamedTextColor.RED : NamedTextColor.YELLOW);
            audience.sendTitlePart(TitlePart.title(countText));
        }, (startSeconds - i) * 1000L); // 1 second intervals
    }
    
    // Final "GO!" message
    scheduleTask(() -> {
        Title goTitle = Title.title(
            Component.text("GO!", NamedTextColor.GREEN),
            Component.empty()
        );
        audience.showTitle(goTitle);
    }, startSeconds * 1000L);
}

// Health status updates
public void updateHealthTitle(Audience audience, double health, double maxHealth) {
    double percentage = health / maxHealth;
    NamedTextColor color;
    
    if (percentage > 0.6) color = NamedTextColor.GREEN;
    else if (percentage > 0.3) color = NamedTextColor.YELLOW;  
    else color = NamedTextColor.RED;
    
    Component healthText = Component.text()
        .append(Component.text("Health: ", NamedTextColor.WHITE))
        .append(Component.text(String.format("%.0f", health), color))
        .append(Component.text("/", NamedTextColor.GRAY))
        .append(Component.text(String.format("%.0f", maxHealth), NamedTextColor.WHITE))
        .build();
    
    audience.sendTitlePart(TitlePart.subtitle(healthText));
}

public class TimedTitles {
    // Show temporary information
    public static void showTemporaryInfo(Audience audience, Component info, Duration displayTime) {
        Title infoTitle = Title.title(
            info,
            Component.empty(),
            Title.Times.times(
                Duration.ofMillis(300),
                displayTime,
                Duration.ofMillis(300)
            )
        );
        audience.showTitle(infoTitle);
    }
    
    // Achievement notification
    public static void showAchievement(Audience audience, String achievementName) {
        Title achievement = Title.title(
            Component.text("Achievement Unlocked!", NamedTextColor.GOLD),
            Component.text(achievementName, NamedTextColor.YELLOW),
            Title.Times.times(
                Duration.ofSeconds(1),
                Duration.ofSeconds(4),
                Duration.ofSeconds(1)
            )
        );
        audience.showTitle(achievement);
    }
    
    // Warning message with urgency
    public static void showWarning(Audience audience, String warning, boolean urgent) {
        Duration fadeIn = urgent ? Duration.ofMillis(100) : Duration.ofMillis(500);
        Duration stay = urgent ? Duration.ofSeconds(3) : Duration.ofSeconds(5);
        Duration fadeOut = urgent ? Duration.ofMillis(200) : Duration.ofSeconds(1);
        
        Title warningTitle = Title.title(
            Component.text("WARNING", urgent ? NamedTextColor.DARK_RED : NamedTextColor.RED),
            Component.text(warning, NamedTextColor.WHITE),
            Title.Times.times(fadeIn, stay, fadeOut)
        );
        audience.showTitle(warningTitle);
    }
}