Calendar Events 2.1.0

Call a custom event at specific dates and times

  1. Nikl
    Native Minecraft Version:
    1.14
    Tested Minecraft Versions:
    • 1.7
    • 1.8
    • 1.9
    • 1.10
    • 1.11
    • 1.12
    • 1.13
    • 1.14
    • 1.15
    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!


    For MC < 1.14 please use CalendarEvents v1 (1.9.0)

    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 once for every player online at the event time. The placeholder %allOnline% will be replaced by the player names.
      • Use %allOffline% for offline players
      • Use %allPlayers% for online and offline players
    • Send a broadcast
    • Send a broadcast only to players with a specific permission
    • Send a Title
      • Optionally set a permission that receiving players need
    • Send an Action bar
      • Optionally set a permission that receiving players need

    Configuration file with some examples:
    Code (YAML):

    # ---------------------------------------------------------------------------- #
    #                                                                              #
    #                          Calender Events config                              #
    #                                                                              #
    # ---------------------------------------------------------------------------- #

    # All times int this configuration file are interpreted in the timezone of your server

    # the following events are examples for you to understand how to add custom events with this plugin.
    # 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
    :
     # The event label needs to be unique and is used as its identifier in the 'listener' section
      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 fired on christmas 2022
      christmas2022
    :
       timing
    :
         occasion
    : "24.12.2022"
         time
    : "12:00"

      # Event called every day, every two hours
      everyDayEveryTwoHours
    :
       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 hour
      workingDaysEveryHour
    :
       timing
    :
         occasion
    : "monday, tuesday, wednesday, thursday, friday"
         # use the placeholder 'x' to stand for any possible number
         time
    : "xx:00"


      # COMBINED EVENTS
      #  combined events can be used to create special scheduling like e.g. every first sunday of a month
      #  combined events contain a list of "normal" calendar event labels and are only fired when ALL of the listed events are fired

      # lets create some normal events to use in a combined event
      sunday
    : # every sunday
       timing
    :
         occasion
    : "sunday"
         time
    : "12:00" # SAME TIME AS THE OTHER EVENT BELOW (IMPORTANT)
      firstWeekOfMonth
    : # every day of the first week in a month
       timing
    :
         occasion
    : "01, 02, 03, 04, 05, 06, 07"
         time
    : "12:00"

      # this event will fire on every first sunday in a month at 12:00
      firstSundayInMonth
    :
       events
    : # lables of the two "normal" events above
         - "sunday"
         - "firstWeekOfMonth"


    # 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 use the listener for basic actions such as
    # sending commands, actionbars, broadcasts and 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
    :
      workingDaysEveryHour
    :
      # %allOnline%    --->  this gets called for every online player and will be replaced with the player name
       # %allOffline%   --->  this gets called for every offline player and will be replaced with the player name
       # %allPlayers%   --->  this gets called for every player (online and offline) and will be replaced with the player name
       commands
    :
      # - "tell %allOnline% &4Hey there %allOnline% &1:)"

       # all commands in this section will run for EVERY player that has the given permission
       commandsWithPerm
    :
        # for every unique key commands and perm have to be defined
         example
    :
          # list of commands.
           #     %player% is replaced by the player name
           #     %allOnline% is replaced by the player name
           #     %perm% is replaced by the permission
           commands
    :
            - "tell %player% &4Hey there %player% &1You have the permission %perm%"
           # the commands above are only dispatched for the player, if he has the defined permission
           perm
    : "example.perm"

       # 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!"
         # ticks (20 = 1s) the title is visible (default 10). 10 ticks fading-in and 10 ticks fading-out are hardcoded!
         ticksToDisplay
    : 20

      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/features 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</groupId>
            <artifactId>calendarevents</artifactId>
            <version>2.1.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.

Recent Reviews

  1. Blsk
    Blsk
    5/5,
    Version: 1.8.3
    As a free work, its function has never been stronger. Thank you for sharing ——Machine translation
  2. BackSam_
    BackSam_
    5/5,
    Version: 1.8.0
    I use a 1.15.1 Spigot Bukkit.
    but, I wan't 1.15.1 version support.
    pls update!
    and Happy New Year!!!
    1. Nikl
      Author's Response
  3. 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!
    1. Nikl
      Author's Response
  4. Small_Ye
    Small_Ye
    5/5,
    Version: 1.4.2
  5. 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
  6. lehuubi
    lehuubi
    5/5,
    Version: 1.4.2
    best plugin command event time.
    pls support random time .............
    goodluck day !
    1. Nikl
      Author's Response
  7. 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
  8. 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 :)
  9. MoMOAH
    MoMOAH
    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.
  10. 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!