V4 revamp

build.gradle.kts

@@ -28,6 +28,10 @@ repositories {
     maven("https://repo.codemc.io/repository/maven-public/") {
         mavenContent { includeGroup("com.ghostchu") }
     }
+
+    maven("https://nexus.neetgames.com/repository/maven-releases/") {
+        mavenContent { includeGroup("com.gmail.nossr50.mcMMO") }
+    }
 }
 
 dependencies {
@@ -45,6 +49,13 @@ dependencies {
     implementation(libs.hikaricp) {
         exclude(group = "org.slf4j", module = "slf4j-api")
     }
+    compileOnly(libs.mcmmo) {
+        exclude("com.sk89q.worldguard")
+        exclude("com.comphenix.protocol")
+    }
+    compileOnly(libs.lynchpin.pursuits)
+    compileOnly(libs.lynchpin.towny)
+    compileOnly(libs.lynchpin.advancements)
 }
 
 tasks {

docs/advancements.md

@@ -0,0 +1,42 @@
+# Advancements Endpoint
+Accessed at https://api.earthmc.net/v4/advancements
+
+The advancements endpoint provides information about the first time an advancement was completed. The information here is live.  
+
+Example **GET** response
+```json5
+{
+  "minecraft:story/mine_diamond": { // Advancement name
+    "player": "e25ad129-fe8a-4306-b1af-1dee1ff59841", // UUID of the player who completed it first
+    "date": "2026-05-10" // The date it was completed
+  },
+  "minecraft:adventure/revaulting": {
+    "player": "e25ad129-fe8a-4306-b1af-1dee1ff59841",
+    "date": "2026-05-10"
+  },
+  "minecraft:adventure/root": {
+    "player": "0bacd488-bc41-4f76-ba8b-50dc843efe49",
+    "date": "2026-04-29"
+  },
+  "minecraft:adventure/under_lock_and_key": {
+    "player": "e25ad129-fe8a-4306-b1af-1dee1ff59841",
+    "date": "2026-05-10"
+  },
+  "minecraft:adventure/trade_at_world_height": {
+    "player": "5b8274bf-b162-4336-85a0-48f9d5380a78",
+    "date": "2026-04-12"
+  },
+  "minecraft:story/smelt_iron": {
+    "player": "e25ad129-fe8a-4306-b1af-1dee1ff59841",
+    "date": "2026-05-10"
+  },
+  "minecraft:adventure/sleep_in_bed": {
+    "player": "5b8274bf-b162-4336-85a0-48f9d5380a78",
+    "date": "2026-04-12"
+  },
+  "minecraft:adventure/fall_from_world_height": {
+    "player": "5b8274bf-b162-4336-85a0-48f9d5380a78",
+    "date": "2026-04-07"
+  }
+}
+```

docs/keys.md

@@ -6,4 +6,5 @@ You may at anytime copy your existing API key with `/api key copy`
 
 Keys currently serve 2 purposes:
 1. Allowing access to the server's SSE endpoint (`/events`)
-2. Allowing players to query their own data - Players can query their own resident information even if they have opted out, and they may view information about their shops in the `/shop` endpoint.
+2. Allowing players to query their own data - Players can query their own resident information even if they have opted out, and they may view additional information about themselves. Example endpoints: `/shop`, `/mcmmo`.
+3. Allowing players to query 'private' endpoints which have a stricter rate limit. Example endpoints: `/pursuits`, `/mcmmo-top`

docs/mcmmo.md

@@ -0,0 +1,84 @@
+# mcMMO Endpoints
+## Personal endpoint
+Accessed at https://api.earthmc.net/v4/mcmmo
+
+The mcMMO endpoint provides information about a player's mcMMO levels.
+It is important to note that the information here is not public, and players can only access their own information, using their API key.
+
+The rate limit for this endpoint is one request per hour per API key (and thus per player).
+
+Example **POST** request
+```json5
+{
+  "query": ["PLAYER_UUID"],
+  "key": "API_KEY"
+}
+```
+The player UUID must match the API key's owner.
+
+Example **POST** response
+```json5
+[
+  {
+    "name": "Veyronity",
+    "ACROBATICS": 21,
+    "ALCHEMY": 0,
+    "ARCHERY": 0,
+    "AXES": 0,
+    "CROSSBOWS": 0,
+    "EXCAVATION": 0,
+    "FISHING": 0,
+    "HERBALISM": 0,
+    "MACES": 0,
+    "MINING": 1,
+    "REPAIR": 0,
+    "SALVAGE": 0,
+    "SMELTING": 0,
+    "SPEARS": 0,
+    "SWORDS": 0,
+    "TAMING": 0,
+    "TRIDENTS": 0,
+    "UNARMED": 0,
+    "WOODCUTTING": 50
+  }
+]
+```
+The player's name and their level in each primary skill. The overall power level can be calculated by adding all the values.
+
+## Top endpoint
+Accessed at https://api.earthmc.net/v4/mcmmo-top
+
+The mcMMO-top endpoint provides the leaderboard of a specified skill.  
+
+The rate limit for this endpoint is one request per 2 minutes per API key.
+
+Example **POST** request
+```json5
+{
+  "query": ["SKILL"], // Skill name (E.g. 'FISHING', 'MINING'), or 'POWER' for the overall power leaderboard
+  "key": "API_KEY"
+}
+```
+
+Example **POST** response
+```json5
+[
+  {
+    "skill": "power",
+    "1": {
+      "player": "K1kimor",
+      "level": 12078
+    },
+    "2": {
+      "player": "Veyronity",
+      "level": 72
+    },
+    "3": {
+      "player": "Andre1098",
+      "level": 29
+    },
+    "lastUpdated": 1779619278
+  }
+]
+```
+The information is not live, it is cached & updated every 15 minutes. The field `lastUpdated` provides the epoch second that the information was last updated at.

docs/nations.md

@@ -50,6 +50,7 @@ Example **POST** response
     "dynmapColour": "FFA500", // Nation's hex Dynmap colour
     "dynmapOutline": "FFFF00", // Nation's hex Dynmap outline
     "wiki": null, // The nation's wiki URL as a string if set, returns null if not
+    "discord": null, // The nation's discord URL
     "king": {
       "name": "tuzzzie",
       "uuid": "8391474f-4b57-412a-a835-96bd2c253219"
@@ -185,6 +186,30 @@ Example **POST** response
       ],
       "Colonist": [],
       "Diplomat": []
+    },
+    "embargoes": {
+      "own": [ // A JSON array representing all nations that this nation has placed an embargo on
+        {
+          "name": "woodland",
+          "uuid": "625a3d73-b179-4335-a512-58366c90dcfe"
+        }
+      ],
+      "against": [] // A JSON array representing all nations that have placed an embargo on this nation
+    },
+    "pacts": { // Container for 'active' and 'pending' JSON dictionaries for pacts this nation is involved in, where the key is the name of the other nation in the pact, and the value is a detailed pact object
+      "active": { // A JSON dictionary representing active pacts this nation has
+        "LizardLand": {
+          "sender": "dev",
+          "receiver": "LizardLand",
+          "status": "ACTIVE",
+          "stats": {
+            "createdAt": 1779459092037,
+            "expiresAt": 1779545525988,
+            "duration": 1
+          }
+        }
+      },
+      "pending": {} // A JSON dictionary representing pending pacts this nation has.
     }
   }
 ]

docs/pursuits.md

@@ -0,0 +1,60 @@
+# Pursuit Endpoint
+Accessed at https://api.earthmc.net/v4/pursuits
+
+The pursuits endpoint provides information about pursuits' leaderboards.  
+Only the top 10 entries are included.
+
+The rate limit for this endpoint is one request per minute per API key.
+
+Example **POST** request
+```json5
+{
+  "query": ["TYPE"], // The pursuit type (PLAYER, TOWN, or NATION) - 'ALL' for all
+  "key": "API_KEY"
+}
+```
+
+Example **POST** response
+```json5
+[
+    {
+        "PLAYER": {
+            "name": "mcmmo-smelting",
+            "isActive": true,
+            "top": {
+                "1": {
+                    "player": "686b1bfa-38de-4eb9-9628-43ed3b56b76e",
+                    "score": 50.0
+                },
+                "2": {
+                    "player": "5b8274bf-b162-4336-85a0-48f9d5380a78",
+                    "score": 25.0
+                },
+                "3": {
+                    "player": "be66697b-bde8-4d70-b339-4ba15b390fa9",
+                    "score": 10.0
+                }
+            }
+        },
+        "NATION": {
+            "name": "votes",
+            "isActive": true,
+            "top": {}
+        },
+        "TOWN": {
+            "name": "votes",
+            "isActive": true,
+            "top": {
+                "1": {
+                    "town": "f6bc3242-77a6-4020-ad1c-7df4a4c0e436",
+                    "score": 35.0
+                },
+                "2": {
+                    "town": "fa14cbc6-3215-481c-b427-a411b519178f",
+                    "score": 12.0
+                }
+            }
+        }
+    }
+]
+```

docs/shop.md

@@ -4,6 +4,8 @@ Accessed at https://api.earthmc.net/v4/shop
 The shop endpoint provides information about player-owned QuickShops.
 It is important to note that the information here is not public, and players can only access their own shops' information, using their API key.
 
+The rate limit for this endpoint is one request per hour per API key (and thus per player).
+
 Each shop object has the following properties:
 - `item` - The Material/name of the item being traded
 - `price` - The price of one transaction

docs/towns.md

@@ -49,6 +49,7 @@ Example **POST** response
     "board": "Fishing every Friday! Join our Discord, link can be found on the signs!", // Town's board as seen on /t, null if none is present
     "founder": "tuzzzie", // The founder of the town as seen on /t
     "wiki": null, // The town's wiki URL as a string if set, returns null if not
+    "discord": null, // The town's wiki URL
     "mayor": {
       "name": "Fruitloopins",
       "uuid": "fed0ec4a-f1ad-4b97-9443-876391668b34"
@@ -71,8 +72,10 @@ Example **POST** response
       "isRuined": false, // True if the town is ruined
       "isForSale": false, // True if the town is for sale
       "hasNation": true, // True if the town has a nation
-      "hasOverclaimShield": false, // True if the town currently has an overclaim shield
       "canOutsidersSpawn": false, // True if the town allows outsiders to teleport
+      "canPassiveMobsSpawn": true, // True if the town has passive mob spawn enabled
+      "hasSnowAccumulation": true, // True if the town has snow accumulation enabled
+      "hasFriendlyFire": false, // True if the town has friendly-fire enabled
     },
     "stats": {
       "numTownBlocks": 473, // The total number of town blocks the town has
@@ -270,7 +273,22 @@ Example **POST** response
       "Treasurer": [],
       "Realtor": [],
       "Settler": []
-    }
+    },
+    "warps": [
+      {
+        "name": "cool_warp",
+        "uuid": "936fe2be-1461-4a77-828f-a9aa073f827e",
+        "createdAt": 1779458705887,
+        "createdBy": "Veyronity",
+        "access": "RESIDENT",
+        "location": {
+          "x": 1,
+          "y": 185,
+          "z": -9
+        }
+      }
+    ]
+  }
   }
 ]
 ```

gradle/libs.versions.toml

@@ -8,6 +8,8 @@ mysterymaster-api = "1.0.0"
 superbvote = "0.6.0"
 quickshop = "6.2.0.11"
 hikaricp = "7.0.2"
+mcmmo = "2.2.040"
+lynchpin-api = "1.0-SNAPSHOT"
 
 # plugins
 conventions = "1.0.8"
@@ -24,6 +26,10 @@ superbvote = { group = "net.earthmc.superbvote", name = "SuperbVote", version.re
 quickshop = { group = "com.ghostchu", name = "quickshop-bukkit", version.ref = "quickshop" }
 quickshop-api = { group = "com.ghostchu", name = "quickshop-api", version.ref = "quickshop" }
 hikaricp = { group = "com.zaxxer", name = "HikariCP", version.ref = "hikaricp" }
+mcmmo = { group = "com.gmail.nossr50.mcMMO", name = "mcMMO", version.ref = "mcmmo" }
+lynchpin-pursuits = { group = "net.earthmc.lynchpin.api", name = "pursuits", version.ref = "lynchpin-api"}
+lynchpin-towny = { group = "net.earthmc.lynchpin.api", name = "towny", version.ref = "lynchpin-api"}
+lynchpin-advancements = { group = "net.earthmc.lynchpin.api", name = "advancements", version.ref = "lynchpin-api"}
 
 [plugins]
 conventions-java = { id = "net.earthmc.conventions.java", version.ref = "conventions" }