Max/zkldi_Tachi
1
0
Fork 0
mirror of https://github.com/zkldi/Tachi.git synced 2026-09-28 01:48:11 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
e045ed4cbfabd5c35bde2bb35780ab65400a76fa
zkldi_Tachi/old-docs/docs/api/routes/gpt.md
T
zk e363bd2532 docs: migrate from mkdocs to mdbook (#1558) 
* docs: migrate from mkdocs to mdbook

- Rename old mkdocs docs/ to old-docs/ for reference
- Set up new docs/ with mdbook (book.toml + src/ tree)
- Mirror full nav structure from mkdocs.yml into SUMMARY.md
- Add Justfile-docs with docs-serve, docs-build, docs-check, docs-install recipes
- Import Justfile-docs from root Justfile
- Rewrite .github/workflows/docs.yml: build step uses taiki-e/install-action
  to install mdbook, split into separate build + deploy jobs, PR builds
  run the check step too

* ci(docs): pin actions to SHAs, install mdbook via release binary

* ci(docs): install mdbook from apt instead of curling a release binary

* dev: replace mkdocs python stack with mdbook in dev image

* ci(docs): apt only works on Debian; restore release binary install for Ubuntu CI

* docs: fix duplicate file entries in SUMMARY.md

* docs: remove docs-install recipe

* docs: remove site-url from book.toml to fix asset loading

* dev: install mdbook from upstream release binary, not Debian apt

The Debian package (0.4.x+ds) strips bundled font assets, leaving the
built site without fonts/fonts.css. Use the upstream tarball (same as CI)
so the theme is complete. Handles x86_64 and aarch64.

* docs: vendor mdbook tarballs in dev/mdbook/, install from there

Dockerfile.dev uses COPY + tar to install the right arch at build time.
CI extracts the x86_64 tarball directly from the checkout.
No network access required for either — and no stripped-fonts Debian package.

* fix: unwritten
2026-05-22 20:43:07 +01:00

16 KiB
Raw Blame History

Game:Playtype Endpoints

These endpoints are for games + their playtypes. To find out what games are supported by a service programmatically, you should see Game Endpoints.

Retrieve Game:Playtype Configuration.

GET /api/v1/games/:gameGroup/:playtype

Parameters

None.

Response

Property Type Description
config GamePTConfig The configuration file for this game + playtype.

!!! warning A GamePTConfig is different to a GameConfig! Read more here.

Example

Request

GET /api/v1/games/iidx/SP

Response

{
	"config": {
		"idString": "iidx:SP",

		"percentMax": 100,

		"defaultScoreRatingAlg": "ktRating",
		"defaultSessionRatingAlg": "ktRating",
		"defaultProfileRatingAlg": "ktRating"

		// ... more props - a lot more props
	}
}

Retrieve the player leaderboard.

GET /api/v1/games/:gameGroup/:playtype/leaderboard

Parameters

Property Type Description
alg (Optional) String If present, specifies an alternative algorithm to sort players on, instead of the default.

Response

Property Type Description
gameStats Array<GameStats> The sorted statistics for the leaderboards.
users Array<UserDocument> All of the related users for the above statistics.

Example

Request

GET /api/v1/games/iidx/SP/leaderboard

Response

{
	"gameStats": [
		{
			"userID": 1,
			"ratings": {
				"ktRating": 4
				// ...
			}
			// ...
		}
	],
	"users": [
		{
			"id": 1,
			"username": "zkldi"
		}
	]
}

Retrieve a song and its charts.

GET /api/v1/games/:gameGroup/:playtype/songs/:songID

Parameters

None.

Response

Property Type Description
song SongDocument The requested song document.
charts ChartDocument[] All of the charts that belong to this song for this playtype.

Example

Request

GET /api/v1/games/iidx/SP/songs/1

Response

{
	"song": {
		"id": 1,
		"title": "5.1.1."
	},
	"charts": [
		{
			"songID": 1,
			"playtype": "SP",
			"difficulty": "HYPER"
			// ...
		},
		{
			"songID": 1,
			"playtype": "SP",
			"difficulty": "ANOTHER"
			// ...
		}
	]
}

Get popular charts for this game + playtype.

GET /api/v1/games/:gameGroup/:playtype/charts

Parameters

Property Type Description
search (Optional) String A song title to search for.

!!! note If no search parameter is set, then the most popular 100 charts for this game are returned.

If a search parameter is set, then the most popular
charts that match the search criteria will be returned,
in that order.

Response

Property Type Description
charts Array<ChartDocument with __playcount> The chart documents that matched this search, or the most popular 100 charts for this game.
songs Array<SongDocument> The associated song documents for the charts.

!!! info The __playcount property is patched onto the chart documents returned. This indicates the amount of unique players that have played this chart.

Example

Request

GET /api/v1/games/iidx/SP/charts?search=AA

Response

{
	"songs": [
		{
			"title": "AA",
			"id": 3
			// ...
		},
		{
			"title": "AA -rebuild-",
			"id": 133
			// ...
		}
	],
	"charts": [
		{
			"songID": 3,
			"difficulty": "ANOTHER",
			"__playcount": 1049
			// ...
		},
		{
			"songID": 133,
			"difficulty": "ANOTHER",
			"__playcount": 120
		}
		//...
	]
}

Retrieve a chart at a specific ID.

GET /api/v1/games/:gameGroup/:playtype/charts/:chartID

Parameters

None.

Response

Property Type Description
song SongDocument The parent song for this chart.
chart ChartDocument The requested chart document.

Example

Request

GET /api/v1/games/iidx/SP/charts/some_chart_id

Response

{
	"song": {
		"id": 123,
		"title": "BLOCKS"
		// ...
	},
	"chart": {
		"chartID": "some_chart_id",
		"songID": 123,
		"playtype": "SP"
		// ...
	}
}

Retrieve playcount for this chart.

GET /api/v1/games/:gameGroup/:playtype/charts/:chartID/playcount

Parameters

None.

Response

Property Type Description
count Integer The amount of plays on this chart.

Example

Self-explanatory.

Retrieve leaderboards for this chart.

GET /api/v1/games/:gameGroup/:playtype/charts/:chartID/pbs

Parameters

Property Type Description
startRanking (Optional) Specify a start point to return 100 pbs from. Defaults to 1. Inclusive.

Response

Property Type Description
pbs Array<PBDocument> The array of pbs sorted by ranking.
users The users these PBs belong to.

Example

Request

GET /api/v1/games/iidx/SP/charts/some_chart/pbs

Response

{
	"pbs": [{
		"chartID": "some_chart",
		"userID": 1,
		"rankingData": {
			"rank": 1,
			"outOf": 100,
		},
		// ...
	},
		//...
	],
	"users": [{
		"id": 1,
		"username": "zkldi
		// ...
	},
		// ...
	]
}

Search for a user's PB on this chart.

GET /api/v1/games/:gameGroup/:playtype/charts/:chartID/pbs/search

Parameters

Property Type Description
search String The user whose PB you're searching for.

Response

Same as /api/v1/games/:gameGroup/:playtype/charts/:chartID/pbs.

Example

See Above.

Search a GPT's folders.

GET /api/v1/games/:gameGroup/:playtype/folders

Parameters

Property Type Description
search String A string to search for a given folder.

Response

Property Type Description
<body> Array<FolderDocument> The folders that matched this search.

Example

Request

GET /api/v1/games/iidx/SP/folders?search=12

Response

[
	{
		name: "beatmania IIDX Level 12",
		// ...
	},
];

Retrieve information on a specific folderID

GET /api/v1/games/:gameGroup/:playtype/folders/:folderID

Parameters

None.

Response

Property Type Description
songs Array<SongDocument> The related song documents for this folder.
charts Array<ChartDocument> The related chart documents for this folder.
folder FolderDocument The folder document at this ID.

Example

Request

GET /api/v1/games/iidx/SP/folders/some_folder_id

Response

{
	songs: [{
		id: 123,
		title: "Epic Song",
		artist: "foo bar",
		// ...
	}],
	charts: [{
		chartID: "foo_bar",
		songID: 123,
		difficulty: "ANOTHER",
		// ...
	}],
	folder: {
		name: "beatmania IIDX Level 12",
		folderID: "some_folder_id",
		// ...
	}
}

Return all the tables for this game

GET /api/v1/games/:gameGroup/:playtype/tables

!!! note Unlike the folders endpoint, this one doesn't have a search parameter. This is because we expect the total table count to stay rather small.

If this changes in the future, this might become a paginated search like endpoint.

Parameters

None.

Response

Property Type Description
tables Array<TableDocument> Every table for this GPT.

Example

Request

GET /api/v1/games/bms/7K/tables

Response

{
	tables: [
		{
			name: "Insane",
			// ...
		},
		{
			name: "Overjoy",
			// ...
		},
	];
}

Retrieve folder documents for a specific table.

GET /api/v1/games/:gameGroup/:playtype/tables/:tableID

Parameters

None.

Response

Property Type Description
folders Array<FolderDocument> All of the folders for this table.
table TableDocument The table document at this ID.

Example

Request

GET /api/v1/games/bms/7K/tableID/insane

Response

{
	folders: [
		// insane lv1, insane lv2 -- insane lv 25, so on.
	],
	table: {
		tableID: "insane",
		name: "Insane",
		// ...
	}
}

Retrieve the PB leaderboard for this Game.

GET /api/v1/games/:gameGroup/:playtype/pb-leaderboard

Parameters

Property Type Description
alg String An alternative algorithm to use instead of the GPTs default.
limit Optional Integer Optionally, provide a number between 1 and 50 to change the amount of scores returned.

Response

Property Type Description
pbs Array<PBDocument> The array of pbs part of the PB leaderboard.
songs Array<SongDocument> The array of songs part of the PBs.
charts Array<ChartDocument> The array of charts part of the PBs.
users Array<UserDocument> The array of users part of the PBs.

Get the distribution of players for a provided class.

GET /api/v1/games/:gameGroup/:playtype/player-distribution

Parameters

Property Type Description
class String Must be one of the GPTs supported classes, This specifies what distribution to return.

Response

Property Type Description
<body> Record<ClassValue, integer> Returns a record of the class value against the amount of people who have it.

Example

Request

GET /api/v1/games/bms/7K/player-distribution?class=stslDan

Response

{
	"12": 1,
	"11": 5,
	"10": 7,
	"9": 6,
	"8": 4,
	// Note that keys will be empty if nobody has them.
	"5": 30,
	// ... so on
}

!!! info You can find the humanised conversions for these classes in the gameConfig for this GPT.

See [tachi/common](https://github.com/zkldi/Tachi/tree/main/common) for more information.

Retrieve recent class updates from all users on this game.

GET /api/v1/games/:gameGroup/:playtype/player-distribution

Parameters

Property Type Description
limit Optional Integer Optionally, An integer between 1 and 50 can be provided to limit the amount of returns. Defaults to 10.

Response

Property Type Description
users Array<UserDocument> Array of the users who achieved the courses.
classes Array<ClassAchievementDocument> Data about the recently achieved classes.

Retrieve the most recent highlighted scores for this GPT.

GET /api/v1/games/:gameGroup/:playtype/scores/highlighted

Parameters

Property Type Description
limit Optional Integer Optionally, provide an integer between 1 and 100 to return this amount of scores. Defaults to 100.

Response

Property Type Description
scores Array<ScoreDocument> The highlighted scores.
users Array<UserDocument> The users who own the scores.
songs Array<SongDocument> The songs the scores are on.
charts Array<ChartDocument> The charts the scores are on.
Reference in New Issue View Git Blame Copy Permalink