Calendar Events 1.8.0

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

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

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

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