001package org.mcaccess.minecraftaccess.api;
002
003import org.jetbrains.annotations.Contract;
004import org.jetbrains.annotations.NotNull;
005
006/**
007 * A status to be narrated in the player status readout or to trigger warnings.
008 *
009 * @see AddonRegistry#register(String, Status)
010 * @since 1.12.0
011 */
012public interface Status {
013    /**
014     * The message to be narrated to the player.
015     *
016     * <p>This should in most cases contain the name of the status (E.g. "Health") along with some value.
017     *
018     * @return The message to be narrated.
019     * @since 1.12.0
020     */
021    @Contract(pure = true)
022    @NotNull String message();
023
024    /**
025     * Weather this status should appear in the player status readout or the conditional status readout.
026     *
027     * @implSpec Returns {@link Visibility#NORMAL} by default.
028     * @return See {@link Visibility}.
029     * @see Visibility
030     * @since 1.12.0
031     */
032    @Contract(pure = true)
033    default @NotNull Visibility visibility() {
034        return Visibility.NORMAL;
035    }
036
037    /**
038     * Returns the current warning severity for this status.
039     *
040     * <p>A warning is triggered whenever the returned {@link WarningLevel} increases from the previous tick.
041     * When a warning is triggered, a sound is played depending on the {@link WarningLevel} and the {@link #message()} is narrated.
042     *
043     * @implSpec The default implementation always returns {@link WarningLevel#NONE}, effectively disabling warnings for this status.
044     * @return The current warning severity.
045     * @see WarningLevel
046     * @since 1.12.0
047     */
048    @Contract(pure = true)
049    default @NotNull WarningLevel warning() {
050        return WarningLevel.NONE;
051    }
052
053    /**
054     * Weather this status should appear in the player status readout or the conditional status readout.
055     *
056     * @see Status#visibility()
057     * @since 1.12.0
058     */
059    enum Visibility {
060        /**
061         * The status will not be included in any readout.
062         *
063         * @since 1.12.0
064         */
065        NONE,
066
067        /**
068         * The status will be included in the normal readout but not the conditional readout.
069         *
070         * @since 1.12.0
071         */
072        NORMAL,
073
074        /**
075         * The status will be included in both the normal and conditional readouts.
076         *
077         * @since 1.12.0
078         */
079        IMPORTANT
080    }
081
082    /**
083     * Represents a warning level from {@link Status#warning()}.
084     *
085     * @see Status#warning()
086     * @since 1.12.0
087     */
088    enum WarningLevel {
089        /**
090         * No warning.
091         *
092         * <p>No sound will ever be played nor will anything be narrated.
093         *
094         * @since 1.12.0
095         */
096        NONE,
097
098        /**
099         * A regular warning.
100         *
101         * <p>The non-severe warning sound will be played and {@link Status#message()} will be narrated.
102         *
103         * @since 1.12.0
104         */
105        WARNING,
106
107        /**
108         * A critical warning.
109         *
110         * <p>The severe warning sound will be played and {@link Status#message()} will be narrated.
111         *
112         * @since 1.12.0
113         */
114        CRITICAL,
115
116        /**
117         * A final warning.
118         *
119         * <p>Behaves the same as {@link #CRITICAL}.
120         * The severe warning sound will be played and {@link Status#message()} will be narrated.
121         *
122         * @since 1.12.0
123         */
124        FINAL
125    }
126}