Module:Jam leaderboards/doc

This module is designed for use in Template:All jam stats and, by extension, Visual novel jam statistics. Through various invoke calls, it can generate any of the 8 types of leaderboard tables found on the statistics page. It also has a helper function to generate the content of the "Record(s) held" section of Template:Infobox jam.

There are four externally-callable functions:

Leaderboard functions

These functions generate the leaderboards found on Visual novel jam statistics.

All three of these functions accept date and vnOnly parameters. They should simply be passed through from Template:All jam stats, where they are invoked, as demonstrated in the example usage for each.

The template, in turn, gets them either from Form:All jam stats filter or from its direct call on Visual novel jam statistics. (See Template:All jam stats/doc for details on this.) They can also be empty (hence the vertical bars within the parameter arguments), and will default to today's date and all jams, respectively.

occurrence

The occurrence function generates leaderboards where the unit of analysis is jam occurrences. Example usage is as follows:

{{#invoke:Jam leaderboards | occurrence | statType=entries | date={{{date|}}} | vnOnly={{{vnOnly|}}} }}

The statType parameter will accept the following values:

• entries ("Most entries in a single jam")
• participants ("Most participants in a single jam")
• top prize ("Largest top prize")
• prize pool ("Largest total prize pool")

series

The series function generates leaderboards where the unit of analysis is jam series (e.g., Spooktober as a whole rather than Spooktober 2024). Example usage is as follows:

{{#invoke:Jam leaderboards | series | statType=entries | date={{{date|}}} | vnOnly={{{vnOnly|}}} }}

The statType parameter can be either entries or participants, which will generate the "Cumulative entries per jam" and "Cumulative participants per jam" leaderboards respectively.

year

The year function generates the leaderboards where each row is a year and jam occurrences during that year are ranked first, second, or third in a given metric. Example usage is as follows:

{{#invoke:Jam leaderboards | year | statType=entries | date={{{date|}}} | vnOnly={{{vnOnly|}}} }}

The statType parameter can be either entries or participants, which will generate the "Most entries per year" and "Most participants per year" leaderboards respectively.

seriesStats

The seriesStats function generates the content of the "Record(s) held" section of Template:Infobox jam. Usage is as follows:

{{#invoke:Jam leaderboards | seriesStats | name={{PAGENAME}} }}

A jam series name can also be specified manually, if desired. It should exactly match the page name of that jam series.

If no records are found (that is, neither the jam series nor any of its occurrences appear on any of the 8 standard leaderboards without any filters), the text "None recorded" will be displayed.

Helper functions

To facilitate code flexibility & reusability, the processing of leaderboard data is handled separately from the display of the tables. The occurrence and series functions each handle the formatting and display of the requested tables, but they have corresponding functions (processOccurrence and processSeries) which run the queries, sort the leaderboard tables, break ties, and remove excess list items.

The year function is an exception to this, because its data has relatively few reuse applications. It could be similarly split in the future if a need arises.

This display/processing split is utilized in the seriesStats function, which uses processOccurrence and processSeries to determine the records held if any. As a result, there should never be any discrepancy between the unfiltered tables on Visual novel jam statistics and the individual jam series pages, except as a result of caching.

Technical limitations

The leaderboards system is not intended to handle 4-way ties or more; 3-way ties are the maximum it is designed to support. The principal changes needed to increase this cap are additional nested if statements during the tiebreaking logic; and increasing the distance between rowsToTest and rowsToShow to 4 or more. These changes would not have significant performance impacts, but have been omitted to keep code as clean as possible.

The system has not been tested in scenarios where there are fewer than rowsToTest items that meet the vnOnly and date filter criteria. As a result, an earliest date limit of September 19th, 2015 has been established in Form:All jam stats filter.

There is a limitation with the numToOrdinal function that will result in incorrect number suffixes ("st", "th", etc.) for leaderboard items higher than 20th place. This should never occur in the current application of the code as of writing this, but if any leaderboards are created with a length longer than 20 ranks, this function should be adjusted.