From ea4497491ef728e3b14c49a1fdf36cb3467674bc Mon Sep 17 00:00:00 2001 From: Kieran Wallbanks Date: Tue, 7 May 2024 16:27:49 +0100 Subject: [PATCH 1/2] feature: Leaderboards and statistic rotations --- schema.graphqls | 74 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/schema.graphqls b/schema.graphqls index 00d2a96..c3b34cb 100644 --- a/schema.graphqls +++ b/schema.graphqls @@ -244,6 +244,14 @@ type Statistics { statisticKey: String! @spectaql(options: [{ key: "example", value: "games_played" }]) ): StatisticValueResult + @deprecated(reason: "This value is not backed by a rotation and will be removed. Use `rotationValue` instead.") + + "Returns the value stored for the given statistic in a rotation." + rotationValue( + statisticKey: String! + @spectaql(options: [{ key: "example", value: "games_played" }]), + rotation: Rotation! = LIFETIME, + ): Int } "A statistic." @@ -254,6 +262,36 @@ type Statistic { "If this statistic generates leaderboards." forLeaderboard: Boolean! + + "The rotations for which this statistic is tracked." + rotations: [Rotation!]! + + """ + Returns the leaderboard for this statistic in a given rotation. + + If this statistic does not generate leaderboards, or the statistic is not tracked for the provided rotation, this will return `null`. + Additionally, the amount is capped at 20. + """ + leaderboard( + rotation: Rotation! = LIFETIME, + amount: Int! = 10, + ): [LeaderboardEntry!] +} + +"An entry in a leaderboard." +type LeaderboardEntry { + """ + The player who has this entry. + + This will be `null` if the player does not have the statistics enabled for the API. + """ + player: Player + + "The rank for this entry." + rank: Int! + + "The value for this entry." + value: Int! } "The result of fetching a value of a statistic." @@ -265,6 +303,28 @@ type StatisticValueResult { value: Int! } +""" +A rotation period. + +Each period resets at 10AM UTC. +""" +enum Rotation { + "A daily rotation that resets." + DAILY + + "A weekly rotation that resets on Tuesdays." + WEEKLY + + "A monthly rotation that resets on the first day of every month." + MONTHLY + + "A yearly rotation that resets on the first day of every year." + YEARLY + + "A lifetime rotation; a rotation period used to indicate something never rotates." + LIFETIME +} + "Available queries." type Query { "Given a UUID, returns a Player if they have logged in to MCC Island." @@ -283,6 +343,20 @@ type Query { "Returns a list of all known statistics." statistics: [Statistic!]! + + """ + Returns when this rotation will next rotate. + + If the rotation is due the exact time this method is called, this method will return the next time that it will rotate. + """ + nextRotation(rotation: Rotation!): DateTime! + + """ + Returns when this rotation last rotated. + + If the rotation is due the exact time this method is called, this method will return the current time. + """ + lastRotation(rotation: Rotation!): DateTime! } "Internal directive used to generate some documentation elements." From effca6e6c98ccb339cf9517a37dc673e0405ba91 Mon Sep 17 00:00:00 2001 From: Kieran Wallbanks Date: Fri, 10 May 2024 18:46:07 +0100 Subject: [PATCH 2/2] docs changes and a method to grab a stat by its name --- schema.graphqls | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/schema.graphqls b/schema.graphqls index c3b34cb..368936c 100644 --- a/schema.graphqls +++ b/schema.graphqls @@ -246,7 +246,11 @@ type Statistics { ): StatisticValueResult @deprecated(reason: "This value is not backed by a rotation and will be removed. Use `rotationValue` instead.") - "Returns the value stored for the given statistic in a rotation." + """ + Returns the value stored for the given statistic in a rotation. + + The returned number will be `null` if the statistic does not track in the provided rotation, or if the statistic doesn't exist. + """ rotationValue( statisticKey: String! @spectaql(options: [{ key: "example", value: "games_played" }]), @@ -263,14 +267,18 @@ type Statistic { "If this statistic generates leaderboards." forLeaderboard: Boolean! - "The rotations for which this statistic is tracked." + """ + The rotations for which this statistic is tracked. + + These are the rotations that can be used to generate leaderboards or fetch rotation values. + Note that the `YEARLY` rotation never generates leaderboards, even if it is returned in this list. + """ rotations: [Rotation!]! """ Returns the leaderboard for this statistic in a given rotation. If this statistic does not generate leaderboards, or the statistic is not tracked for the provided rotation, this will return `null`. - Additionally, the amount is capped at 20. """ leaderboard( rotation: Rotation! = LIFETIME, @@ -284,6 +292,7 @@ type LeaderboardEntry { The player who has this entry. This will be `null` if the player does not have the statistics enabled for the API. + However, for Crown Level or Trophy count leaderboards, the player will not be `null`. """ player: Player @@ -344,6 +353,12 @@ type Query { "Returns a list of all known statistics." statistics: [Statistic!]! + "Returns a statistic by it's name." + statistic( + key: String! + @spectaql(options: [{ key: "example", value: "games_played" }]) + ): Statistic + """ Returns when this rotation will next rotate. @@ -356,7 +371,7 @@ type Query { If the rotation is due the exact time this method is called, this method will return the current time. """ - lastRotation(rotation: Rotation!): DateTime! + previousRotation(rotation: Rotation!): DateTime! } "Internal directive used to generate some documentation elements."