☛ 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.
Configuration file with some examples:
# ---------------------------------------------------------------------------- #
# #
# 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:
Is the same as
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
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.
If you are using maven, you can get the newest version from my maven repository.
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:
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.
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"
timing:
occasion: "every day"
time: "00:x5"
Code (Text):
exampleEvent:
timing:
occasion: "every day"
time: "00:05, 00:15, 00:25, 00:35, 00:45, 00:55"
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"
timing:
occasion: "saturday, sunday"
time: "xx:00"
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"
timing:
occassion : "friday"
time : "17:15"
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
}
@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
}
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>
<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 ( ) ;
// 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 ) ;
}
/**
* @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.
Resource Information
Author:
----------
Total Downloads:
11,909
First Release:
Jan 28, 2017
Last Update:
Dec 3, 2020
Category:
---------------
All-Time Rating:
Find more info at nikl.me...
21 ratings
Version
-----
Released:
--------------------
Downloads:
------
Version Rating:
----------------------
-- ratings