Calendar Events 2.3.0

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
• 1.16

Source Code:

https://github.com/NiklasEi/CalendarEvents

Donation Link:

https://paypal.me/NiklasEicker

☛ 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.

PlacehoderAPI Integration

You can display the time until an event is called the next time via PlaceholderAPI

"%calendarevents_until:myEventLabel%" returns time in d h min s
"%calendarevents_until-s:myEventLabel%" returns time in s
"%calendarevents_until-min:myEventLabel%" returns time in min
"%calendarevents_until-min-plus-one:myEventLabel%" returns time in min plus one
"%calendarevents_until-h:myEventLabel%" returns time in h
"%calendarevents_until-d:myEventLabel%" returns time in d

Since all events get called in the first second of a minute, the placeholder
"until-min" shows one minute less, than one might expect. For this reason, there is the "until-min-plus-one" placeholder which does exactly what it says

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();

Spoiler: API

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.​