{"id":29422121,"url":"https://github.com/zyypj/revampleaderboards","last_synced_at":"2026-05-17T08:33:17.013Z","repository":{"id":304242948,"uuid":"1018219653","full_name":"zyypj/RevampLeaderboards","owner":"zyypj","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-11T20:51:55.000Z","size":18467,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-11T22:19:44.560Z","etag":null,"topics":["bukkit","java","javaplugin","minecraft","plugin","spigot"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zyypj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-11T20:23:00.000Z","updated_at":"2025-07-11T20:51:58.000Z","dependencies_parsed_at":"2025-07-11T22:29:49.749Z","dependency_job_id":null,"html_url":"https://github.com/zyypj/RevampLeaderboards","commit_stats":null,"previous_names":["zyypj/revampleaderboards"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/zyypj/RevampLeaderboards","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyypj%2FRevampLeaderboards","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyypj%2FRevampLeaderboards/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyypj%2FRevampLeaderboards/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyypj%2FRevampLeaderboards/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zyypj","download_url":"https://codeload.github.com/zyypj/RevampLeaderboards/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zyypj%2FRevampLeaderboards/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264935172,"owners_count":23685493,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bukkit","java","javaplugin","minecraft","plugin","spigot"],"created_at":"2025-07-12T04:02:03.677Z","updated_at":"2026-05-17T08:33:17.008Z","avatar_url":"https://github.com/zyypj.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RevampLeaderboards\n\n[![SpigotMC](https://img.shields.io/badge/SpigotMC-✔️-blue.svg)](#)  \n[![Java 1.8+](https://img.shields.io/badge/Java-1.8%2B-orange.svg)](#)  \n[![PlaceholderAPI](https://img.shields.io/badge/PlaceholderAPI-✔️-blue.svg)](#)\n\nA high‑performance Spigot/Paper plugin that generates **daily**, **weekly**, **monthly** and **total** leaderboards from any PlaceholderAPI placeholder — with **SQLite** \u0026 **MySQL** support and an optional embedded HTTP server for RESTful access.\n\n---\n\n## 🚀 Installation\n\n1. Drop `RevampLeaderboards.jar` into your server’s `plugins/` folder.  \n2. Restart the server to generate the default configuration files in `plugins/RevampLeaderboards/`.  \n\n---\n\n## 💬 PlaceholderAPI Integration\n\nRevampLeaderboards ships with a set of built‑in PlaceholderAPI expansions under the `%lb_…%` namespace, plus support for **custom‑placeholders** defined in your `config.yml`.\n\n### Built‑in placeholders\n\n- **Remaining time until next reset**  \n```\n\n%lb\\_remains\\_\u003cperiod\u003e%\n\n```\n- `\u003cperiod\u003e`: `daily` | `weekly` | `monthly` | `total`  \n- Returns a human‑readable duration until the next leaderboard reset (e.g. “in 02h 15m”).\n\n- **Player’s own rank**  \n```\n\n%lb\\_position\\_\u003cperiod\u003e\\_\u003cboardKey\u003e%\n\n```\n- `\u003cboardKey\u003e`: your board identifier (e.g. `player_kills`)  \n- Returns the 1‑based position of the requesting player.\n\n- **Any column from a given rank entry**  \n```\n\n%lb\\_\u003cdataType\u003e*\u003cperiod\u003e*\u003cposition\u003e\\_\u003cboardKey\u003e%\n```\n\n- `\u003cdataType\u003e`:\n  - `playerName` – display name  \n  - `uuid` – player UUID  \n  - `amount` – the raw numeric value (formatted)  \n- `\u003cposition\u003e`: 1‑based rank index  \n- Example:\n  ```text\n  %lb_amount_weekly_1_player_kills%\n  ```\n  → value of the top player on the **weekly** kills board.\n\n### 🎨 Custom placeholders\n\nIf you need more fields—tags, guild colors, titles, etc.—define them under `custom-placeholders` in your **`plugins/RevampLeaderboards/config.yml`**:\n\n```yaml\ncustom-placeholders:\n# slot 0 → %lb_tag_\u003cposition\u003e_\u003cperiod\u003e_\u003cboardKey\u003e%\n0:\n  can-be-null: false          # never return empty (defaults to \"\")\n  data: tag                   # logical name used in the placeholder\n  placeholder: \"%leaftags_tag_prefix%\"\n\n# slot 1 → %lb_guild_\u003cposition\u003e_\u003cperiod\u003e_\u003cboardKey\u003e%\n1:\n  can-be-null: true           # allow null/empty results\n  data: guild\n  placeholder: \"%leafguilds_guild_colortag%\"\n````\n\nAfter reloading (`/lb reload`), you can use:\n\n```\n%lb_tag_1_total_player_kills%\n%lb_guild_3_daily_bw_wins%\n```\n\n* The numeric index you choose becomes part of the placeholder’s **dataType**.\n* `can-be-null: false` forces an empty string (`\"\"`) when no value is found; `true` will actually return `null`/empty.\n* The `placeholder` field is any valid PlaceholderAPI expression, evaluated per player in offline or online context.\n\n---\n\n## 🔧 Commands (in‑game)\n\n| Command                     | Permission           | Description                                                        |\n| --------------------------- | -------------------- | ------------------------------------------------------------------ |\n| `/lb reload`                | `leaderboard.reload` | Reload all configurations (application, boards, config, messages). |\n| `/lb verify`                | `leaderboard.verify` | Verify boards and refresh cache.                                   |\n| `/lb board add \u003ckey\u003e`       | `leaderboard.board`  | Add a new leaderboard at runtime.                                  |\n| `/lb board remove \u003ckey\u003e`    | `leaderboard.board`  | Remove an existing leaderboard.                                    |\n| `/lb board list`            | `leaderboard.board`  | List all registered leaderboards.                                  |\n| `/lb board test \u003ckey\u003e`      | `leaderboard.board`  | Show top 10 and next reset time for `\u003ckey\u003e`.                       |\n| `/lb sensive resetDatabase` | `OP`                 | Wipe the entire database (server operators only).                  |\n\n---\n\n## 🛠️ REST API Usage\n\nAll API endpoints live under:\n\n```\nhttp://\u003chost\u003e:\u003cport\u003e\u003cbase-path\u003e\n```\n\nBy default:\n\n```\nhttp://localhost:8080/api\n```\n\n### 1. List all registered boards\n\n* **Endpoint**: `GET /boards`\n* **Description**: Returns a list of all board keys.\n* **Example**:\n\n  ```bash\n  curl http://localhost:8080/api/boards\n  ```\n* **Response**:\n\n  ```json\n  [\n    \"player_kills\",\n    \"player_deaths\",\n    \"bw_wins\"\n  ]\n  ```\n\n---\n\n### 2. Retrieve a leaderboard\n\n* **Endpoint**: `GET /boards/{key}`\n* **Query Parameters**:\n\n  * `period` (optional): `daily` | `weekly` | `monthly` | `total`\n    *Default: `total`*\n  * `page` (optional): zero-based page index *(default: 0)*\n  * `size` (optional): page size *(default: 10; set to 0 for all entries)*\n* **Example**:\n\n  ```bash\n  curl \"http://localhost:8080/api/boards/player_kills?period=weekly\u0026page=0\u0026size=5\"\n  ```\n* **Response**:\n\n  ```json\n  {\n    \"totalItems\": 42,\n    \"totalPages\": 9,\n    \"currentPage\": 0,\n    \"pageSize\": 5,\n    \"items\": [\n      { \"uuid\": \"uuid‑1\", \"playerName\": \"Alice\", \"value\": 128 },\n      { \"uuid\": \"uuid‑2\", \"playerName\": \"Bob\",   \"value\": 115 }\n      // …\n    ]\n  }\n  ```\n\n---\n\n### 3. Get a player’s position\n\n* **Endpoint**: `GET /boards/{key}/{period}/position/{uuid}`\n* **Description**: Returns the 1‑based rank of the specified player on the given board and period.\n* **Example**:\n\n  ```bash\n  curl http://localhost:8080/api/boards/player_kills/weekly/position/123e4567-e89b-12d3-a456-426614174000\n  ```\n* **Response**:\n\n  ```text\n  5\n  ```\n\n---\n\n### 4. List all supported periods\n\n* **Endpoint**: `GET /periods`\n* **Description**: Returns the list of valid period identifiers.\n* **Example**:\n\n  ```bash\n  curl http://localhost:8080/api/periods\n  ```\n* **Response**:\n\n  ```json\n  [\"daily\",\"weekly\",\"monthly\",\"total\"]\n  ```\n\n---\n\n### 5. Fetch top entries for every board in a period\n\n* **Endpoint**: `GET /boards/period/{period}`\n* **Query Parameters**:\n\n  * `limit` (optional): max entries per board *(default: all)*\n* **Example**:\n\n  ```bash\n  curl \"http://localhost:8080/api/boards/period/daily?limit=3\"\n  ```\n* **Response**:\n\n  ```json\n  {\n    \"player_kills\": [\n      { \"uuid\": \"uuid‑1\", \"playerName\": \"Alice\", \"value\": 12 },\n      { \"uuid\": \"uuid‑2\", \"playerName\": \"Bob\",   \"value\": 10 },\n      { \"uuid\": \"uuid‑3\", \"playerName\": \"Carol\", \"value\": 8 }\n    ],\n    \"bw_wins\": [\n      // …\n    ]\n  }\n  ```\n\n---\n\n### 6. Get historical snapshots\n\n#### 6.1 Board history\n\n* **Endpoint**: `GET /history/board/{key}/{period}`\n* **Query Parameters**:\n\n  * `from` (optional): ISO‑8601 date‑time\n  * `to`   (optional): ISO‑8601 date‑time\n* **Example**:\n\n  ```bash\n  curl \"http://localhost:8080/api/history/board/player_kills/weekly?from=2025-07-01T00:00\u0026to=2025-07-27T23:59\"\n  ```\n* **Response**:\n\n  ```json\n  [\n    {\n      \"snapshotTime\": \"2025-07-01T00:00:00\",\n      \"entries\": [\n        { \"uuid\":\"uuid‑1\",\"playerName\":\"Alice\",\"value\":15 },\n        // …\n      ]\n    },\n    // …\n  ]\n  ```\n\n#### 6.2 Player history\n\n* **Endpoint**: `GET /history/player/{uuid}/{key}/{period}`\n* **Query Parameters**: same as board history\n* **Example**:\n\n  ```bash\n  curl \"http://localhost:8080/api/history/player/123e4567-e89b-12d3-a456-426614174000/player_kills/daily\"\n  ```\n* **Response**:\n\n  ```json\n  [\n    { \"snapshotTime\": \"2025-07-25T00:00:00\", \"value\": 7 },\n    { \"snapshotTime\": \"2025-07-26T00:00:00\", \"value\": 9 }\n  ]\n  ```\n\n---\n\n### 7. List online players\n\n* **Endpoint**: `GET /players`\n* **Description**: Returns the UUID and name of each player currently online.\n* **Example**:\n\n  ```bash\n  curl http://localhost:8080/api/players\n  ```\n* **Response**:\n\n  ```json\n  [\n    { \"uuid\":\"uuid‑1\",\"name\":\"Alice\" },\n    { \"uuid\":\"uuid‑2\",\"name\":\"Bob\" }\n  ]\n  ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzyypj%2Frevampleaderboards","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzyypj%2Frevampleaderboards","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzyypj%2Frevampleaderboards/lists"}