minetest_calendar/API.md

Calendar API

This is the API documentation for the Calendar mod.

Concepts

Total days

Most functions use total_days to query the current date. This number is the number of total elapsed days. You can get the 'elapsed days' number for today in Minetest with minetest.get_day_count().

Ordinal and cardinal numbers

Cardinal number basically means the counting starts at 0. Think of it as counting the number of elapsed days/months/years.

There are also ordinal numbers, which means the counting starts at 1. This is for expressions like “1st January”.

Real calendars usually use ordinal numbers.

The calendar mod uses cardinal numbers internally to store the date internally, this is only done to make calculations a bit simpler. total_days is also a cardinal number.

Calendar configuration

Before calling any other function, you probably want to configure the calendar first. Call calendar.config to do so. This is not required, however, the calendar has a default configuration:

By default, ayear has 12 months with 30 days each, the months are January to December, the week has 7 weekdays from Monday to Sunday, starting at Monday.

calendar.config(config)

Configure calendar. Call this function before any other function.

config is a table with the following fields (all fields are optional):

• MONTH_DAYS: Days in a month
• month_names: List of month names (also determines number of months)
• month_names_short: List of short month names
• weekday_names: List of weekday names (also determines number of weekdays)
• weekday_names_short: List of short weekday names
• FIRST_WEEK_DAY: Cardinal number of the weekday that marks the beginning of a week and the calendar

Fields that were nil won't change. You can access each of the calender settings later with calender.<field name>, e.g. calendar.MONTH_DAYS. Note this is read-only access, you must never write to these fields directly. Only use calendar.config to change these fields.

Convenience variables

For convenience, there are also these shortcuts that are automatically set, derived from the other values:

• calendar.MONTHS: Number of months in a year
• calendar.WEEK_DAYS: Number of days in a week
• calendar.YEAR_DAYS: Number of days in a year

Functions

calendar.get_date(total_days, ordinal)

Returns 4 values: days, months, years and days in year (in that order)

• total_days: Number of elapsed days (default: today)
• ordinal: if true, use ordinal numbers if false, use cardinal numbers default: false

calendar.get_total_days_from_date(days, months, years, is_ordinal)

Given a date, returns the total number of elapsed days (cardinal number).

• days/months/years: Date
• is_ordinal: If true, date is interpreted as ordinal numbers, otherwise it is interpreted as cardinal numbers (default: false)

calendar.get_weekday(total_days)

Returns cardinal weekday number for given day.

• total_days: Number of elapsed days (default: today)

calendar.get_date_string(format, total_days)

Returns the game date as a human-readable string

• format: Optional tokenized string to represent the game date Default: "%Y years, %M months, %D days"
• total_days: Number of elapsed days (default: today)

The tokenized string may include one or more date specifiers:

Cardinal values:

• %Y: Elapsed years in epoch
• %M: Elapsed months in year
• %D: Elapsed days in month
• %J: Elapsed days in year

Ordinal values:

• %y: Current year of epoch
• %m: Current month of year
• %d: Current day of month
• %j: Current day of year

Other:

• %b: Full name of current month
• %h: Short name of current month
• %W: Full name of current weekday
• %w: Short name of current weekday
• %z: Literal percent sign

calendar.register_holiday(def)

Register a holiday. A holiday is just a special named day in a calender and can be used for whatever you like: Actual holidays, special events, reminders, whatever. By default, holidays will be marked in the graphical calendar. Holidays can be queried with calendar.get_holidays.

• def: Holiday definition. A table with these fields:
  • name: Human-readable holiday name
  • text_color (optional): Custom text color of day/tooltip text
  • daybox_color (optional): Custom text color of day box
  • type: type of holiday, determines other arguments
  • Arguments when type=="monthday":
    • days: Cardinal month day on which the holiday occurs
    • months: Cardinal month on which the holiday occurs
    • years: (optional) Cardinal year on which the holiday occurs. If not set, occurs every year
  • Arguments when type=="custom":
    • is_holiday: Function that takes total days as parameter and must return true if it's a holiday and false if not. Try to keep your calculations as simple as possible

When no colors are specified, a default green color is used. When multiple holidays fall on the same day and the holidays use different colors, the day box will assume the color of the first registered holiday (the order is not predictable).

Examples

-- First day of every year
calendar.register_holiday({
	name = "New Year's Eve",
	type = "monthday",
	days = 0,
	months = 0
})

-- First Sunday in May
calendar.register_holiday({
	name = "Mother's Day",
	type = "custom",
	is_holiday = function(total_days)
		local d, m, y = calendar.get_date(total_days)
		local wday = calendar.get_weekday(total_days)
		return wday == 6 and m == 4 and d <= 6
	end,
})

calendar.get_holidays(total_days)

Returns table of all holidays for the given day.

Each table value returns a reference to holiday definition that was used in calendar.register_holiday.

• total_days: Number of elapsed days (default: today)

calendar.show_calendar(player_name, settings, wanted_months, wanted_years)

Display a graphical calendar to player. It shows the days of a single month with one numbered box per day. Also, holidays and the current day can be marked and get a tooltip.

• player_name: Named of player
• settings: Table to customize calendar:
  • ordinal: If true, use ordinal numbers, otherwise, use cardinal numbers (default: false)
  • show_weekdays: If true, show weekdays and arrange the day boxes to weekdays (default: true)
  • show_today: If true, mark today (default: true)
  • show_holiday: If true, mark holidays (default: true)
  • changable: Which controls are available:
    • "full": Can change year and month (default)
    • "months": Can change month within selected year only
    • "none": Can't change anything
  • today_button: Whether to show the 'Today' button (default: true) Note: If changable=="none", the 'Today' button is never shown
• wanted_months: Which cardinal calendar month to show (default: current one)
• wanted_years: Which cardinal calendar year to show (default: current one)
• caption_format: Optional format information to change the calendar caption. Is a table with the following fields: [1]: Format string with minetest.translate-style placeholders (from Minetest 5.0.0) [2]: Translator domain for minetest.translate [3]: and further: Parameters for the format string. For each parameter, use a placeholder from calender.get_date_string.

Example for caption_format:

{ N("@1, year @2"), "mymod", "%b", "%Y" }

Will resolve to e.g. "January, Year 1". N is a dummy function function(s) return s end that is used for the translation collector script.