Package org.spongepowered.api.util

Interface Ticks

  • public interface Ticks
    Represents a game "tick".

    A game tick is a unit of work where the game processes the current state and updates the game world and all the entities in it. It is not a true unit of time, however, to ensure a consistent game play experience, each tick is given a maximum processing time (which is generally interpreted to be the expected duration of the tick, rather than the maximum) in which to complete its work. If a tick takes less time than this allotted time, the rest of the allocated time is unused and the engine simply waits for this time to elapse before processing the work for the next tick - this gives rise to the idea of a maximum ticks per second. However, if a tick takes longer than its effective minimum duration, then the next tick must wait for the current tick to finish before it can start. If multiple ticks take longer than this processing time in a row, this will have the effect of reducing the number of "ticks per second" that can run. At this point, the server may be considered "overloaded" as it cannot keep up with the demand placed upon it and not suffer from degradation in performance.

    Implementations may measure the duration of some in-game mechanics using these server ticks. If this is the case, and the server is overloaded, the increased tick time will result in such mechanics taking longer to resolve. To complicate things further, implementations may choose to "skip" ticks to reduce server load (so some mechanics due to run in two tick's time may instead run in one tick's time). Thus, the use of a tick as a time period is unreliable.

    For these reasons, consumers of this API should not treat a tick as a fixed unit of time. Instead, ticks are an intention of order. A mechanic due to resolve in two ticks will never resolve in a tick before a mechanic that resolves in one tick (but again, due to tick skipping, they may resolve on the same tick).

    Information about the current platform and Engine's expected tick rate can be determined by calling single().expectedDuration(Engine). The tick rate is not defined by the API so may vary amongst different implementations. For all engines based on vanilla Minecraft, this is 50ms for a 20 tick per second rate.

    While a tick is not a reliable measure of wall-clock time, implementations may tie in-game world time to a given number of ticks. This object can thus be used as an accurate in-game duration. However, it is not defined in the API what the correlation between ticks and in-game time is, again, this may vary amongst implementations. For vanilla Minecraft, 1000 ticks corresponds to one in-game hour, meaning there is not an integer correspondence between an in-game minute or second and number of ticks.

    Note that this object does not hold any context about which Engine the number of ticks was generated for. Consumers should use the methods on this object to determine what this object would represent on the target engine.

    • Method Detail

      • zero

        static Ticks zero()
        Represents zero ticks.
        Returns:
        A Ticks

      • single

        static Ticks single()
        Represents a single tick.
        Returns:
        A Ticks

      • minecraftHour

        static Ticks minecraftHour()
        Represents a minecraft hour on the Server in ticks.
        Returns:
        A Ticks

      • minecraftDay

        static Ticks minecraftDay()
        Represents a minecraft day on the Server in ticks.
        Returns:
        A Ticks

      • of

        static Ticks of​(long ticks)
        Returns a Ticks that represents the supplied number of ticks.

        This is platform and potentially Engine dependent - consult the target implementation for what a tick represents.

        Parameters:
        ticks - The number of ticks
        Returns:
        A Ticks object that represents the number of ticks.

      • ofWallClockTime

        static Ticks ofWallClockTime​(Engine engine,
                             long time,
                             java.time.temporal.TemporalUnit temporalUnit)
        Returns a Ticks that would represent the supplied wall-clock time in the ideal case for the given Engine. If the given time would result in a non-integer number of ticks, the number of ticks will be rounded up, resulting in a slightly larger ideal duration.

        The supplied time is a lower bound on the wall-clock time - if the engine is overloaded the time taken to execute the number of ticks this represents will be higher.

        Parameters:
        engine - The Engine to calculate the number of ticks for
        time - The time
        temporalUnit - The TemporalUnit of time given in time.
        Returns:
        The Ticks that represents the number of ticks that would be expected to be run on the given engine in an ideal scenario.

      • ofWallClockSeconds

        static Ticks ofWallClockSeconds​(Engine engine,
                                int seconds)
        Returns a Ticks that would be executed in the given number of wall-clock seconds on the given Engine in an ideal case.
        Parameters:
        engine - The Engine to calculate the number of ticks for
        seconds - The number of seconds
        Returns:
        The Ticks that represents the number of ticks that would be expected to be run on the given engine in an ideal scenario.
        See Also:
        ofWallClockTime(Engine, long, TemporalUnit)

      • ofWallClockMinutes

        static Ticks ofWallClockMinutes​(Engine engine,
                                int minutes)
        Returns a Ticks that would be executed in the given number of wall-clock minutes on the given Engine in an ideal case.
        Parameters:
        engine - The Engine to calculate the number of ticks for
        minutes - The number of minutes
        Returns:
        The Ticks that represents the number of ticks that would be expected to be run on the given engine in an ideal scenario.
        See Also:
        ofWallClockTime(Engine, long, TemporalUnit)

      • ofWallClockHours

        static Ticks ofWallClockHours​(Engine engine,
                              int hours)
        Returns a Ticks that would be executed in the given number of wall-clock hours on the given Engine in an ideal case.
        Parameters:
        engine - The Engine to calculate the number of ticks for
        hours - The number of hours
        Returns:
        The Ticks that represents the number of ticks that would be expected to be run on the given engine in an ideal scenario.
        See Also:
        ofWallClockTime(Engine, long, TemporalUnit)

      • ofWallClockDays

        static Ticks ofWallClockDays​(Engine engine,
                             int days)
        Returns a Ticks that would be executed in the given number of wall-clock days on the given Engine in an ideal case.
        Parameters:
        engine - The Engine to calculate the number of ticks for
        days - The number of days
        Returns:
        The Ticks that represents the number of ticks that would be expected to be run on the given engine in an ideal scenario.
        See Also:
        ofWallClockTime(Engine, long, TemporalUnit)

      • ofMinecraftSeconds

        static Ticks ofMinecraftSeconds​(Engine engine,
                                long seconds)
        Returns a Ticks that represents the given number of Minecraft day-time seconds on the given Engine.

        As a tick may not be an integer number of minecraft seconds, the returned Ticks object may be slightly larger than requested. The number of ticks returned will always be at least the requested duration.

        Parameters:
        engine - The Engine to calculate the number of ticks for
        seconds - The number of minecraft seconds
        Returns:
        The Ticks that represents the number of ticks that would be expected to be run in an ideal scenario.

      • ofMinecraftMinutes

        static Ticks ofMinecraftMinutes​(Engine engine,
                                long minutes)
        Returns a Ticks that represents the given number of Minecraft day-time seconds on the given Engine.

        As a tick may not be an integer number of minecraft minutes, the returned Ticks object may be slightly larger than requested. The number of ticks returned will always be at least the requested duration.

        Parameters:
        engine - The Engine to calculate the number of ticks for
        minutes - The number of minecraft minutes
        Returns:
        The Ticks that represents the number of ticks that would be expected to be run in an ideal scenario.

      • ofMinecraftHours

        static Ticks ofMinecraftHours​(Engine engine,
                              long hours)
        Returns a Ticks that represents the given number of Minecraft day-time hours on the given Engine.

        As a tick may not be an integer number of minecraft hours, the returned Ticks object may be slightly larger than requested. The number of ticks returned will always be at least the requested duration.

        Parameters:
        engine - The Engine to calculate the number of ticks for
        hours - The number of minecraft hours
        Returns:
        The Ticks that represents the number of ticks that would be expected to be run in an ideal scenario.

      • ofMinecraftDays

        static Ticks ofMinecraftDays​(Engine engine,
                             long days)
        Returns a Ticks that represents the given number of Minecraft day-time days on the given Engine.

        As a tick may not be an integer number of minecraft days, the returned Ticks object may be slightly larger than requested. The number of ticks returned will always be at least the requested duration.

        Parameters:
        engine - The Engine to calculate the number of ticks for
        days - The number of minecraft days
        Returns:
        The Ticks that represents the number of ticks that would be expected to be run in an ideal scenario.

      • expectedDuration

        java.time.Duration expectedDuration​(Engine engine)
        Gets the expected Duration of time it would take for the given Engine to process the number of ticks this object represents under ideal conditions.
        Parameters:
        engine - The Engine to get the Duration for
        Returns:
        The effective Duration.

      • ticks

        long ticks()
        Gets the underlying number of ticks that this object represents.

        This number is platform and Engine dependent. It should not be stored and used beyond the current Engine session.

        Returns:
        The number of ticks that this represents.

      • minecraftSeconds

        long minecraftSeconds​(Engine engine)
        Gets the number of in-game seconds that this Ticks represents for the given Engine.

        As there may not be a integer - integer relationship between seconds and ticks, this may be approximate. If the conversion results in a millisecond remainder, the duration is truncated rather than rounded - that is, if this object represents 6.7 seconds, this will return 6, not 7.

        Parameters:
        engine - The Engine to calculate the duration for.
        Returns:
        The approximate number of in-game seconds

      • minecraftDayTimeDuration

        java.time.Duration minecraftDayTimeDuration​(Engine engine)
        Returns the in-game time as a Duration represents for the given Engine.

        This is not wall-clock time. This should not be used with any Duration that represents wall-clock times.

        Parameters:
        engine - The Engine to calculate the duration for.
        Returns:
        A duration representing the in game time.