package com.livingworld.core.services;

import com.livingworld.core.simulation.LivingWorldCalendar;

/**
 * Service interface for managing simulation time.
 * 
 * <p>This service provides access to the simulation tick counter and calendar,
 * as well as methods to advance the simulation clock.</p>
 */
public interface TimeService {

    /**
     * Returns the current simulation tick counter value.
     * 
     * @return the current simulation tick (non-negative)
     */
    long getSimulationTick();

    /**
     * Returns the current {@link LivingWorldCalendar} instance.
     * 
     * <p>The calendar tracks day, month, year based on the simulation tick.</p>
     *
     * @return the current living world calendar
     */
    LivingWorldCalendar getCalendar();

    /**
     * Advances the simulation clock by a single tick.
     * 
     * <p>This method increments the simulation tick counter and updates the
     * corresponding calendar date.</p>
     */
    void advanceSimulationTick();

    /**
     * Advances the simulation clock by the specified number of ticks.
     * 
     * @param ticks number of ticks to advance (must be non-negative)
     * @throws IllegalArgumentException if ticks is negative
     */
    void advanceSimulationTicks(long ticks);
}
