Calendar Events 1.8.0

Call a custom event at specific dates and times

  1. Nikl
    Tested Minecraft Versions:
    • 1.7
    • 1.8
    • 1.9
    • 1.10
    • 1.11
    • 1.12
    • 1.13
    • 1.14
    Source Code:
    https://github.com/NiklasEi/CalendarEvents
    Support chat on Discord


    Do you want to:
    Wish all players a happy weekend every Friday at 17:15? Run a command 1st of every month? Reset a mine via command every night at 1 am?
    No problem!




    This plugin calls a custom event at configurable times in real time. You can tell the plugin what to do on those events or use it as a dependency and write your own listener (there is a small example for that below).

    For using CalendarEvents in your own plugin there is an API to add and remove events. This ensures that whoever wants to use your plugin does not have to change anything in CalendarEvents configuration file and the events you want to listen to are really there and are scheduled. Read about the API below and take a look at the example project.

    The default configuration file includes some example events and actions that get executed by the plugin when those events are called.


    Possible plugin-intern actions are listed below (in your own listener everything is possible ;)). The placeholders %time%, %day%, %month% can be used in all actions.
    • Dispatch commands
      • Use %allOnline% to dispatch the command with the name of every player that is online
    • Send a broadcast
    • Send a broadcast only to players with a specific permission
    • Send a Title
      • Supports a possible permission players need to get the title and can include a subtitle
    • Send an Action bar
      • Supports a possible permission players need to receive the Action bar

    Configuration file with some examples:
    Code (YAML):
    # ----------------------------------------------------------------------------#
    #                                                                             #
    #                          Calender Events config                             #
    #                                                                             #
    # ----------------------------------------------------------------------------#

    # the following events are examples for you to understand how to add custom events with this plugin.
    # They all get registered and called.
    # You can remove or add any event you want, but make sure that the labels (keys) are different.
    # To let the plugin do something on these events, go to the section 'listener'.
    # For more complex action on events, use the API.
    # Please visit www.spigotmc.org/resources/35536/ for more information on the API.
    events
    :
     # Event called on the first of every month
      newMonth
    :
        timing
    :
         # This will get called on every first of the month.
          # A date with just two numbers is interpreted as any such day in any month.
          # You can add more dates to the '01' just put a ',' in between (e.g. "01,05,25")
          occasion
    : "01"
          # 24h format! Event gets called in the first second of the given minute.
          # Each day goes from 00:00 to 23:59 ;)
          time
    : "00:00"

      # Event called on the first of every week
      newWeek
    :
        timing
    :
          occasion
    : "monday"
          time
    : "00:00"

      # Event called on the first and second of every year
      newYearAndSecond
    :
        timing
    :
         # A date without a year gets called every year
          occasion
    : "01.01, 02.01"
          time
    : "00:00"

      # Event called every day, every two hours
      exampleEvent1
    :
        timing
    :
         # 'every day' gets translated to 'monday, tuesday, wednesday, thursday, friday, saturday, sunday'
          occasion
    : "every day"
          time
    : "01:00,03:00,05:00,07:00,09:00,11:00,13:00,15:00,17:00,19:00,21:00,23:00"

      # Event called every working/school day, every two hours
      workingDays
    :
        timing
    :
          occasion
    : "monday, tuesday, wednesday, thursday, friday"
          time
    : "01:00,03:00,05:00,07:00,09:00,11:00,13:00,15:00,17:00,19:00,21:00,23:00"

      # Event fired on christmas 2022
      christmas2022
    :
        timing
    :
          occasion
    : "24.12.2022"
          time
    : "12:00"

    # General Calendar Events settings
    settings
    :
     # If your server is in a different timezone then most of your players, you can add hours to the server time here.
      # Example:
      #     Server:   UTC +0
      #     Players:  UTC +1
      #     configure addHoursToServerTime = 1
      #     The events above will trigger at the configured times for your UTC +1 players!
      addHoursToServerTime
    : 0
      # The locale defines the month and day names in the event (%day%, %month%).
      # Use an IETF language tag (see: https://r12a.github.io/app-subtags/).
      language
    : "en"

    # You can listen to calendar events in other plugins.
    # But you can also use the listener in this plugin for basic actions.
    # For example: send commands, messages, broadcasts, titles
    # use & for colors
    # %time% will be replaced with the events time (24h format hh:mm)
    # %day% will be replaced with the name of the day in the locale defined at 'settings.locale'
    # %month% will be replaced with the name of the month in the locale defined at 'settings.locale'
    listener
    :
      workingDays
    :
       # %allOnline%    --->  this gets called for every online player and will be replaced with the player name
        commands
    :
       # - "tell %allOnline% &4Hey there %allOnline% &1:)"

        # Broadcast to everyone
        #broadcast: "[Server] &1Hello everyone! Enjoy the game :)"

        broadcastWithPerm
    :
          perm
    : "example.perm"
          broadcast
    : "Hey man, you got a special permission!"

        # %player% will be replaced with the players name
        actionbar
    :
         # Permission is optional. If empty, the actionbar will be send to everyone
          perm
    : "example.perm"
          bar
    : "&1That's a cool actionbar, %player% &r(btw: it's %time%)"

        # %player% will be replaced with the players name
        title
    :
         # perm is optional. If empty, the title will be send to everyone
          perm
    : "example.perm"
          title
    : "&1Hi there %player%"
          subTitle
    : "It's now &4%time%&r!"

      newMonth
    :
        broadcast
    : "It is now &1%month%"

    # CalendarEvents is on bStats: https://bstats.org/plugin/bukkit/CalendarEvents
    # If you don't want any anonymous data to be send, you can opt it out here.
    bstats
    :
     # Please consider leaving this enabled.
      # Having statistics helps me to see in which projects I should invest more time.
      disabled
    : false


    Placeholder in timings

    In timings 'x' is interpreted as any possible and valid number. For example:


    Code (Text):
    exampleEvent:
      timing:
        occasion: "every day"
        time: "00:x5"
    Is the same as
    Code (Text):
    exampleEvent:
      timing:
        occasion: "every day"
        time: "00:05, 00:15, 00:25, 00:35, 00:45, 00:55"


    Code (Text):
    everyHourOnWeekends:
      timing:
        occasion: "saturday, sunday"
        time: "xx:00"
    Will be called on every full hour on Saturdays and Sundays.


    Usage in your own Plugin

    Lets say you want to listen for
    Code (YAML):
    happyWeekend:
        timing
    :
            occassion
    : "friday"
            time
    : "17:15"
    This will be called every friday at 17:15. The label of the event is "happyWeekend". You are going to check for that label in your listener.

    Code (Java):
    // import me.nikl.calendarevents.CalendarEvent
    @EventHandler
    public void onCalendarEvent(CalendarEvent event){
        // check for your label
        if(!event.getLabels().contains("happyWeekend")){
            // not your event
            return;
        }
        // it is friday 17:15:00! Do your stuff here
    }
                   
    If you are using maven, you can get the newest version from my maven repository.
    Code (XML):
    <repositories>
        <repository>
            <id>nikl-repo</id>
            <url>https://repo.nikl.me/artifactory/public</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>me.nikl.calendarevents</groupId>
            <artifactId>CalendarEvents</artifactId>
            <version>1.8.0</version>
        </dependency>
    </dependencies>

    The API

    The CalendarEvents API can be used to register events during runtime. This is helpfull if you want to use CalendarEvents in your own plugin.

    Take a look at the example plugin using the CalendarEvents API on GitHub.

    Retrieve the API like this:
    Code (Java):
    me.nikl.calendarevents.CalendarEvents calendarEvents = (me.nikl.calendarevents.CalendarEvents) Bukkit.getPluginManager().getPlugin("CalendarEvents");
    // get the API
    CalendarEventsApi api = calendarEvents.getApi();
    Code (Java):
    package me.nikl.calendarevents;

    /**
    * @author Niklas Eicker
    *
    * API of CalendarEvents
    *
    * This API enables you to add events to the EventManager from other plugins.
    * You can listen for these custom events.
    * See: https://github.com/NiklasEi/ExampleCalendarEventsAPI
    */

    public interface CalendarEventsApi {
        /**
         * Add a CalendarEvent to the EventManager
         *
         * The event will be automatically scheduled just like the events from the configuration file.
         * The label must be unique.
         *
         * @param label     of the event to add
         * @param occasions e.g. 'monday, 02.05.2150' see configuration file of this plugin for examples
         * @param timings   e.g. '14:25, 16:59' see configuration file of this plugin for more examples
         * @return success in adding the event
         */

        boolean addEvent(String label, String occasions, String timings);

        /**
         * Remove the event with the given label.
         *
         * @param label of the event to remove
         */

        void removeEvent(String label);

        /**
         * Check whether a given label is registered as an event.
         *
         * @param label of the event to check for
         * @return is registered
         */

        boolean isRegisteredEvent(String label);

        /**
         * Calculate the seconds remaining until the next call of the specified event.
         *
         * @param label of the event to remove
         * @return seconds to next call, or -1 if no call left / event does not exist
         */

        int secondsToNextCall(String label);
    }


    Take a look at the source code (link is on top of the page). If you have any comments or know how to do something in a better way, please tell me! I love learning and improving ;)


    If you have problems, suggestions or simply questions please open an issue on GitHub before leaving a review. Thank you.
    TomCreeper, Blsk, canhucko and 5 others like this.

Recent Reviews

  1. SpokenWig620933
    SpokenWig620933
    5/5,
    Version: 1.8.0
    Truely Amazing plugin! I use it a lot, but there's a few things you SHOULD add that will make this tons better!

    1. placeholderapi placeholders support, at least in commands.
    2. Ability to specify seconds!
  2. Small_Ye
    Small_Ye
    5/5,
    Version: 1.4.2
  3. LordRothschild
    LordRothschild
    4/5,
    Version: 1.4.2
    Very nice plugin thanks alot!
    However: Is it possible to send commands only to players that have a certain permission, just like it is possible to do that with your permbroadcast system?
    This would really help us a lot.
    Thanks again
    1. Nikl
      Author's Response
      Update: since 1.5.0 this is supported :)

      Old comment: I don't have any time in the next 3 months due to my studies, but it's on the list for later. Thank you for your review. If you have more suggestions please use the issue tracker on GitHub, the forum or Discord.
      https://github.com/NiklasEi/calendarevents/issues/6
  4. lehuubi
    lehuubi
    5/5,
    Version: 1.4.2
    best plugin command event time.
    pls support random time .............
    goodluck day !
    1. Nikl
      Author's Response
  5. comne
    comne
    5/5,
    Version: 1.4.2
    good plugin

    can you add "random time"option? (15:00-16:00) (Minimum spacing: 3min Maximum spacing:7min)(max run frequency:5)
    i think this option is good!
    1. Nikl
      Author's Response
  6. Hoshino
    Hoshino
    5/5,
    Version: 1.3.3
    Nice plugin, hope author will not give up it.
    This plugin has great potential
    Hope to have more features and usage
    1. Nikl
      Author's Response
      Thank you :)
  7. cwyfl
    cwyfl
    5/5,
    Version: 1.3.3
    ------------------------------------------------------------------------------
    Nice plugin, hope author will not give up it. Keep going !
    ------------------------------------------------------------------------------
    1. Nikl
      Author's Response
      Thank you :)
      I am not giving up, Calendar Events is still being updated.
  8. ppt4973
    ppt4973
    5/5,
    Version: 1.3.1
    Both the author and this plugin are great!
    He has enthusiasm, patience and responsibility in this project!
    Most important is the Bugs are fixed quickly!
    1. Nikl
      Author's Response
      Thank you for the review!
  9. BourneDev
    BourneDev
    5/5,
    Version: 1.3.0
    This is super dope! Thanks for putting in all the time and effort to make this, and I highly appreciate the fact you made this free as well!
    1. Nikl
      Author's Response
      Thank you :)
      It was fun writing this.
  10. Playcoco
    Playcoco
    5/5,
    Version: 1.2.1
    Excellent plugin !

    Can you add "every minute/hour" option for the section time or we have to write each minute in the config (ex 16:01, 16:02, 16:03...) ?
    1. Nikl
      Author's Response
      Thank you for your review :)

      As of version 1.3.0 you can use 'x' as a placeholder in timings, which makes calling an event every minute very easy.