docs: Fix a lot of random typos and formatting issues (#1245)

This is far from perfect (or everything), but in theory provides a better experience.
This commit is contained in:
Katie
2025-02-24 21:06:35 +00:00
committed by GitHub
parent a93a4ceb16
commit 3fa1a22714
62 changed files with 83 additions and 93 deletions
+1 -1
View File
@@ -17,7 +17,7 @@ To use authentication with a request, you should set a HTTP header of:
Authorization: Bearer API_KEY
```
Where API_KEY is the api key you wish to use.
Where API_KEY is the API key you wish to use.
### Self-Key Authentication
+2 -2
View File
@@ -3,7 +3,7 @@
Tachi exposes a public API which allows programs to interact with Tachi.
This means you could make your own applications that work off of Tachi's
datasets.
datasets.
!!! warning
This documentation assumes some basic programming knowledge, such as how to make
@@ -38,7 +38,7 @@ send an email to `zk@tachi.ac` and let me know what you're up to. Otherwise, I m
To quote GitHub:
!!! quote
!!! quote
Permissions of this strongest copyleft license are conditioned on making available complete source code of licensed works and modifications, which include larger works using a licensed work, under the same license. Copyright and license notices must be preserved. Contributors provide an express grant of patent rights. When a modified version is used to provide a service over a network, the complete source code of the modified version must be made available.
This is not legal advice.
+1 -1
View File
@@ -5,7 +5,7 @@ Tachi supports webhooks. You can set a `webhookUri` as part of your
## Usage and Security
When a given event happens on Tachi, your webhookUri will recieve a POST
When a given event happens on Tachi, your webhookUri will receive a POST
request with some content and the type of event.
You **MUST** validate that this request was from Tachi! Otherwise, anyone
@@ -19,4 +19,4 @@ being automated in the background).
## That's it!
Seriously -- that's it.
Seriously -- that's it.
+2 -2
View File
@@ -143,7 +143,7 @@ can only be used for USC.
- inGameID
This uses the in-game-ID for this **SONG**. You, therefore,
**MUST** specify the difficulty for this chart aswell.
**MUST** specify the difficulty for this chart as well.
This is supported for the following games:
@@ -158,7 +158,7 @@ This is supported for the following games:
- sdvxInGameID
This uses the in-game-ID for this SDVX song. You must specify
the difficulty for this chart aswell.
the difficulty for this chart as well.
The reason SDVX gets its own special `matchType` is because this
matchType supports `difficulty: "ANY_INF"`. This special difficulty
@@ -5,4 +5,3 @@ codebase reference is technically about implementation details, this part is
for miscellaneous implementation details that wouldn't fit anywhere else.
*****
@@ -10,7 +10,7 @@ representing the same thing.
## Hashing
To create the Goal ID, we perform a [json stable hash](https://github.com/zkrising/fast-json-stable-hash) on the
To create the Goal ID, we perform a [JSON stable hash](https://github.com/zkrising/fast-json-stable-hash) on the
`game`, `playtype`, `charts` and `criteria` of this field.
This enforces that goals are unique on those fields.
@@ -40,4 +40,3 @@ pieces of info (i.e. no judgements), then trying to import that same score with
judgements later will not work, as the scoreID sees it as a duplicate.
See [Clobbering](todo).
+2 -2
View File
@@ -43,7 +43,7 @@ An example of this would be an IIDX score with -1 EX Score.
## Internal Failure
This is an internal failure, and thrown when something bad
has occured on our end.
has occurred on our end.
The most common case for throwing this is the "Song-Chart"
desync. This occurs when a chart has no parent song (and
@@ -57,4 +57,4 @@ a chart must have a parent song.)
If any exception is thrown from a converter that is **NOT**
an `instanceof` ConverterFailure, it is treated as an
InternalFailure.
InternalFailure.
+1 -1
View File
@@ -19,7 +19,7 @@ Else, the import is logged as debug.
An internal document - Import Timings - is created by
storing the time each step of the import process took
in miliseconds.
in milliseconds.
This is analysed regularly to check for performance
degradation and look for potential optimisations.
+1 -1
View File
@@ -17,7 +17,7 @@ fledged Tachi score, and then goes over how it is imported.
## Return Format
The `ImportIterableDatapoint` returns
The `ImportIterableDatapoint` returns
`ImportProcessingInfo` or `null`. The format for the former
can be found in `tachi-common`, and **should be read** before
following this document!
+1 -2
View File
@@ -147,10 +147,9 @@ value of this function.
### Import Timings
Every step in this process is timed in miliseconds.
Every step in this process is timed in milliseconds.
The time each step took is saved alongside the ImportID.
This is used for internal debugging and degraded performance
checks.
+1 -1
View File
@@ -30,4 +30,4 @@ If it results in a success, we have a new DryScore we can import.
!!! note
This is why Converter Functions are completely
static, so we can safely call the same Converter
Function with this data to unorphan scores.
Function with this data to unorphan scores.
+1
View File
@@ -276,6 +276,7 @@ that means that they cannot be dynamically constructed
with closures or similar.
### Arguments
Converters are called with these four arguments:
| Property | Type | Description |
+1 -1
View File
@@ -29,4 +29,4 @@ in successive score import steps.
Some imports may import scores from multiple Playtypes. We
frequently want to only refer to the set of scores modified
under a given playtype (For importing a users game:playtype stats, as an example)
so this is a very useful data structure to have.
so this is a very useful data structure to have.
+1 -1
View File
@@ -17,4 +17,4 @@ is emitted, which could be hooked into by our Discord Bot.
If the progress has changed at all, the data is
pushed to an array which is then returned. This is
attached onto the Import Document.
attached onto the Import Document.
@@ -12,4 +12,4 @@ Tachi fully supports OAuth2. When you create a Tachi API Client, you can set a `
## Client File Flow
Alternatively, if you're just looking for a nice UI for users to create an API Key with the right permissions, check out the [Client File Flow](./file-flow.md).
Alternatively, if you're just looking for a nice UI for users to create an API Key with the right permissions, check out the [Client File Flow](./file-flow.md).
+2 -2
View File
@@ -37,7 +37,7 @@ logger.severe("foo");
`severe` is the second most severe log level in tachi.
Calling this means an error has occured, and that error implies
Calling this means an error has occurred, and that error implies
it will apply to multiple parts of the codebase.
This log level is used with things like a Song-Chart
@@ -54,7 +54,7 @@ logger.error("foo");
`error` is the third most severe log level in tachi.
Calling this means an error has occured, but the impact of
Calling this means an error has occurred, but the impact of
it is limited to the function or general area it was called in.
Errors may be recovered from or ignored by the code, but generally that should be reserved for `warn`.
-2
View File
@@ -179,7 +179,6 @@ If present, and a string, this points to the local dev server for a react app. H
option set results in CORS being enabled for *that* specific URL. This is useful for local
development, but should not be used in production.
### RATE_LIMIT
- Type: Positive Integer
@@ -242,7 +241,6 @@ Where *this* server is hosted. This is used to
provide callback URLs inside emails. You may stub
it out if emails are unsupported.
### EMAIL_CONFIG
- Type: EMAIL_CONFIG | undefined.
+1 -1
View File
@@ -130,7 +130,7 @@ https://boku.tachi.ac/api/v1/foo/bar
The only files allowed to declare endpoints are `router.ts` files.
This allows us to seperate functionality from API structure
This allows us to separate functionality from API structure
in cases where an API call needs to do a lot of things.
## Test Files
+1 -1
View File
@@ -33,7 +33,7 @@ are **thoroughly** appreciated, as `zk` prioritises maintaining the core of work
If you're interested in this, check out the [Documentation Contribution Guide](./components/documentation.md).
j### Database Seeds
### Database Seeds
We use an interesting system for parts of our database. We actually store a game's songs and charts *in*
our GitHub repository! That means you can:
+1 -1
View File
@@ -40,4 +40,4 @@ Use `just load-kamai-dataset` or `just load-boku-dataset` to load a *real* datas
You'll then need to edit `server/conf.json5` and change `MONGO_DATABASE_NAME` to `"anon-kamai"` or `"anon-boku"`.
Everyone's passwords are set to `password`, so feel free to log in as anyone, and see real data!
Everyone's passwords are set to `password`, so feel free to log in as anyone, and see real data!
@@ -42,4 +42,4 @@ It also manages the order of pages on the site. **You need to edit this if you'r
It's just documentation. Make the changes and commit them up, ideally with `docs:` as the commit prefix.
That is to say: your commit messages should look like `docs: fixed typo in API route`.
That is to say: your commit messages should look like `docs: fixed typo in API route`.
@@ -28,4 +28,3 @@ Search for existing issues before opening a new one. There might already be one
## That's it!
Don't fret too much about writing perfect issues, but put some effort into them. The development team look at everything that comes through, and will tidy up bits of your issue for you if you make a mistake.
@@ -18,4 +18,3 @@ The file you're looking to run is `merge-mdb.ts`, but it needs two arguments:
- `--version`, what version of the game this music db is from. For a list of versions, see the [SDVX Config](../../game-support/games/sdvx-Single.md#versions).
You can run this script by typing `ts-node merge-mdb.ts --input YOUR_INPUT_HERE --version YOUR_VERSION_HERE` in the terminal.
+1 -1
View File
@@ -24,4 +24,4 @@ and Tachi's support for your favourite game even better!
## Sounds good.
Awesome! Start with the [Setup](./setup.md) guide. This will get Tachi running on your local PC, so you can test all your changes.
Awesome! Start with the [Setup](./setup.md) guide. This will get Tachi running on your local PC, so you can test all your changes.
+1 -1
View File
@@ -85,7 +85,7 @@ To set everything else up for local development, we'll use [Docker](https://dock
## 2. Fork and pull the repo.
Since you can't just commit straight to someone elses codebase (that would be a massive security issue), you need to make a fork of Tachi - One owned by you!
Since you can't just commit straight to someone else's codebase (that would be a massive security issue), you need to make a fork of Tachi - One owned by you!
Go to [the Tachi repository](https://github.com/zkrising/Tachi) and click the Fork button in the top right (Make sure you're signed in).
+1 -1
View File
@@ -162,4 +162,4 @@ This is a function that takes in the aforementioned `sc` and `chart`, alongside
## That's it!
Congrats! If you've done this, the [Server Implementation](./server-impl.md) and the [Common Configuration](./common-config/index.md), you've just added full support for a game to Tachi! Nice job!
Congrats! If you've done this, the [Server Implementation](./server-impl.md) and the [Common Configuration](./common-config/index.md), you've just added full support for a game to Tachi! Nice job!
@@ -100,4 +100,3 @@ These metrics are defined like any other, but are all allowed to be not-provided
doesn't necessarily have to be enabled by the user - but if it does exist, we want
to track it properly. That is to say, if the user raises their `exScore` but nothing
else, we should still count that as a new score - despite `exScore` being optional!
@@ -96,7 +96,7 @@ This metric is an array of numbers or null.
Metrics of type `ENUM` are special in many ways. Most importantly, they don't require
any sort of validation - the input is either a member of `values` or it isn't.
An ENUM metric looks like this:
An ENUM metric looks like this:
```ts
{
type: "ENUM",
@@ -173,7 +173,7 @@ We will have to write the validator later in the server implementation.
### Formatting
We also want to format these metrics into a string. For example, a `percent` metric may want to stringify into `92.45%` instead of `92.49938222293842`.
More subtle formatting rules can be defined here too, such as how in jubeat, scores are
More subtle formatting rules can be defined here too, such as how in Jubeat, scores are
easier to read written like `903,283` instead of `903283`.
## Graph Metrics
@@ -199,4 +199,4 @@ the array too. You can use this to enforce a certain array size (such as exactly
This is how metrics work, but there's more detail in how they're defined in each game's config.
For example, some metrics (like `grade` for a lot of games) are merely functions of other metrics. Making every import method handle this themselves seems silly. How do we tackle this? This, and more, is answered in [Metric Groups](./metric-groups.md)!
For example, some metrics (like `grade` for a lot of games) are merely functions of other metrics. Making every import method handle this themselves seems silly. How do we tackle this? This, and more, is answered in [Metric Groups](./metric-groups.md)!
@@ -29,4 +29,4 @@ in, it **MAY** pass what version the score was attained on.
This allows us to immediately disambiguate the previous case.
If a version is **not** passed in, we assume that the score is for the chart marked as
`isPrimary: true`. Furthermore, seeds tests **enforce** that duplicates on certain IDs expected-to-be-unique cannot be true unless all-but-one-of-them is marked as `isPrimary: false`.
`isPrimary: true`. Furthermore, seeds tests **enforce** that duplicates on certain IDs expected-to-be-unique cannot be true unless all-but-one-of-them is marked as `isPrimary: false`.
+2 -2
View File
@@ -32,7 +32,7 @@ For more information on what metrics are and how they work, see [TODO]!
## Judgements
The folowing judgements are defined:
The following judgements are defined:
- `pure`
- `far`
@@ -83,4 +83,4 @@ The folowing judgements are defined:
- `inGameStrID`
- `songTitle`
- `tachiSongID`
- `tachiSongID`
+1 -1
View File
@@ -92,4 +92,4 @@ This game has no versions, and presumably doesn't need to disambiguate its IDs.
## Supported Match Types
- `bmsChartHash`
- `tachiSongID`
- `tachiSongID`
+2 -2
View File
@@ -46,7 +46,7 @@ For more information on what metrics are and how they work, see [TODO]!
## Judgements
The folowing judgements are defined:
The following judgements are defined:
- `pgreat`
- `great`
@@ -95,4 +95,4 @@ This game has no versions, and presumably doesn't need to disambiguate its IDs.
## Supported Match Types
- `bmsChartHash`
- `tachiSongID`
- `tachiSongID`
@@ -32,7 +32,7 @@ For more information on what metrics are and how they work, see [TODO]!
## Judgements
The folowing judgements are defined:
The following judgements are defined:
- `jcrit`
- `justice`
@@ -94,4 +94,4 @@ The folowing judgements are defined:
- `inGameID`
- `songTitle`
- `tachiSongID`
- `tachiSongID`
+1 -1
View File
@@ -30,7 +30,7 @@ For more information on what metrics are and how they work, see [TODO]!
## Judgements
The folowing judgements are defined:
The following judgements are defined:
- `MARVELOUS`
- `PERFECT`
+1 -1
View File
@@ -30,7 +30,7 @@ For more information on what metrics are and how they work, see [TODO]!
## Judgements
The folowing judgements are defined:
The following judgements are defined:
- `MARVELOUS`
- `PERFECT`
@@ -32,7 +32,7 @@ For more information on what metrics are and how they work, see [TODO]!
## Judgements
The folowing judgements are defined:
The following judgements are defined:
- `perfect`
- `great`
@@ -83,4 +83,4 @@ The folowing judgements are defined:
- `inGameID`
- `songTitle`
- `tachiSongID`
- `tachiSongID`
@@ -32,7 +32,7 @@ For more information on what metrics are and how they work, see [TODO]!
## Judgements
The folowing judgements are defined:
The following judgements are defined:
- `perfect`
- `great`
@@ -87,4 +87,4 @@ The folowing judgements are defined:
- `inGameID`
- `songTitle`
- `tachiSongID`
- `tachiSongID`
+2 -2
View File
@@ -42,7 +42,7 @@ For more information on what metrics are and how they work, see [TODO]!
## Judgements
The folowing judgements are defined:
The following judgements are defined:
- `pgreat`
- `great`
@@ -148,4 +148,4 @@ The default rating algorithm is `ktLampRating`.
- `inGameID`
- `tachiSongID`
- `songTitle`
- `songTitle`
+2 -2
View File
@@ -42,7 +42,7 @@ For more information on what metrics are and how they work, see [TODO]!
## Judgements
The folowing judgements are defined:
The following judgements are defined:
- `pgreat`
- `great`
@@ -148,4 +148,4 @@ The default rating algorithm is `ktLampRating`.
- `inGameID`
- `tachiSongID`
- `songTitle`
- `songTitle`
+2 -2
View File
@@ -32,7 +32,7 @@ For more information on what metrics are and how they work, see [TODO]!
## Judgements
The folowing judgements are defined:
The following judgements are defined:
- `fantastic+`
- `fantastic`
@@ -83,4 +83,4 @@ This game has no versions, and presumably doesn't need to disambiguate its IDs.
## Supported Match Types
- `itgChartHash`
- `itgChartHash`
@@ -34,7 +34,7 @@ For more information on what metrics are and how they work, see [TODO]!
## Judgements
The folowing judgements are defined:
The following judgements are defined:
- `perfect`
- `great`
@@ -99,4 +99,4 @@ The default rating algorithm is `jubility`.
## Supported Match Types
- `inGameID`
- `tachiSongID`
- `tachiSongID`
@@ -32,7 +32,7 @@ For more information on what metrics are and how they work, see [TODO]!
## Judgements
The folowing judgements are defined:
The following judgements are defined:
- `perfect`
- `great`
@@ -86,4 +86,4 @@ The folowing judgements are defined:
- `songTitle`
- `tachiSongID`
- `inGameID`
- `inGameStrID`
- `inGameStrID`
@@ -32,7 +32,7 @@ For more information on what metrics are and how they work, see [TODO]!
## Judgements
The folowing judgements are defined:
The following judgements are defined:
- `pcrit`
- `perfect`
@@ -93,4 +93,4 @@ The folowing judgements are defined:
## Supported Match Types
- `songTitle`
- `tachiSongID`
- `tachiSongID`
@@ -32,7 +32,7 @@ For more information on what metrics are and how they work, see [TODO]!
## Judgements
The folowing judgements are defined:
The following judgements are defined:
- `critical`
- `near`
@@ -80,4 +80,4 @@ The folowing judgements are defined:
- `songTitle`
- `tachiSongID`
- `inGameID`
- `inGameID`
@@ -37,7 +37,7 @@ For more information on what metrics are and how they work, see [TODO]!
## Judgements
The folowing judgements are defined:
The following judgements are defined:
- `cbreak`
- `break`
@@ -91,8 +91,8 @@ The folowing judgements are defined:
- `tachiSongID`
- `inGameID`
### Song Title matching
### Song Title Matching
There are numerous songs with non-unique names (e.g. Singularity, Singularity and Singularity), but this can be resolved by providing the `artist` field. The only exception is Perfect Shining, which uniquely has two LUNATIC charts and has to be matched by `inGameID`:
- LUNATIC 0 (Loctest chart) `inGameID: 8003`
- LUNATIC 13+ (Re:Master) `inGameID: 8091`
- LUNATIC 13+ (Re:Master) `inGameID: 8091`
@@ -46,7 +46,7 @@ For more information on what metrics are and how they work, see [TODO]!
## Judgements
The folowing judgements are defined:
The following judgements are defined:
- `cool`
- `great`
@@ -91,4 +91,4 @@ This game has no versions, and presumably doesn't need to disambiguate its IDs.
## Supported Match Types
- `bmsChartHash`
- `tachiSongID`
- `tachiSongID`
+2 -2
View File
@@ -46,7 +46,7 @@ For more information on what metrics are and how they work, see [TODO]!
## Judgements
The folowing judgements are defined:
The following judgements are defined:
- `cool`
- `great`
@@ -91,4 +91,4 @@ This game has no versions, and presumably doesn't need to disambiguate its IDs.
## Supported Match Types
- `bmsChartHash`
- `tachiSongID`
- `tachiSongID`
+2 -2
View File
@@ -34,7 +34,7 @@ For more information on what metrics are and how they work, see [TODO]!
## Judgements
The folowing judgements are defined:
The following judgements are defined:
- `cool`
- `great`
@@ -85,4 +85,4 @@ The folowing judgements are defined:
- `inGameID`
- `tachiSongID`
- `popnChartHash`
- `popnChartHash`
+2 -2
View File
@@ -34,7 +34,7 @@ For more information on what metrics are and how they work, see [TODO]!
## Judgements
The folowing judgements are defined:
The following judgements are defined:
- `critical`
- `near`
@@ -95,4 +95,4 @@ The folowing judgements are defined:
- `sdvxInGameID`
- `songTitle`
- `tachiSongID`
- `tachiSongID`
@@ -33,7 +33,7 @@ For more information on what metrics are and how they work, see [TODO]!
## Judgements
The folowing judgements are defined:
The following judgements are defined:
- `critical`
- `near`
@@ -79,4 +79,4 @@ This game has no versions, and presumably doesn't need to disambiguate its IDs.
## Supported Match Types
- `uscChartHash`
- `tachiSongID`
- `tachiSongID`
+2 -2
View File
@@ -33,7 +33,7 @@ For more information on what metrics are and how they work, see [TODO]!
## Judgements
The folowing judgements are defined:
The following judgements are defined:
- `critical`
- `near`
@@ -79,4 +79,4 @@ This game has no versions, and presumably doesn't need to disambiguate its IDs.
## Supported Match Types
- `uscChartHash`
- `tachiSongID`
- `tachiSongID`
+1 -1
View File
@@ -82,4 +82,4 @@ The folowing judgements are defined:
## Supported Match Types
- `songTitle`
- `tachiSongID`
- `tachiSongID`
+2 -2
View File
@@ -87,7 +87,7 @@ A chart in Tachi looks like this:
## Tables and Folders
You'll probably want to create atleast one table and some folders for your game.
You'll probably want to create at least one table and some folders for your game.
There are various utilities for this, like `scripts/rerunners/add-level-version-folders.js` for creating a traditional "Level 1, Level 2, Level 3" kind of table.
@@ -95,4 +95,4 @@ There are various utilities for this, like `scripts/rerunners/add-level-version-
Once you've modified the database seeds, test them with `pnpm test` inside the `seeds/scripts` folder. This will check a bunch of properties about the songs and charts you just made.
If they fail, read why and make appropriate changes. If they pass, move to the root of the Tachi repository and run `pnpm sync-database-local`. This will load the changes into your MongoDB instance.
If they fail, read why and make appropriate changes. If they pass, move to the root of the Tachi repository and run `pnpm sync-database-local`. This will load the changes into your MongoDB instance.
+2 -2
View File
@@ -139,7 +139,7 @@ However, this is often not the case, and there are certain things you expect to
between the metrics of a score.
For example, you shouldn't be able to submit a `PERFECT ULTIMATE CHAIN` if your score
isn't 10 million - the two imply eachother!
isn't 10 million - the two imply each other!
In this part of the server implementation, you may specify as many validation functions
as you like. These assert relations between the fields on a score, and allow you
@@ -149,4 +149,4 @@ Like real life, passing judgements subjects you to more scrutiny -- getting a `F
## That's it!
The only thing left is to define the [Client Implementation](./client-impl.md)!
The only thing left is to define the [Client Implementation](./client-impl.md)!
+2 -2
View File
@@ -66,6 +66,6 @@ View it [here](./codebase).
## Acknowledgements
This documentation is built ontop of the beautiful [Material MKDocs](https://squidfunk.github.io/mkdocs-material) theme.
This documentation is built on top of the beautiful [Material MKDocs](https://squidfunk.github.io/mkdocs-material) theme.
--8<-- "includes/abbreviations.md"
--8<-- "includes/abbreviations.md"
-1
View File
@@ -91,4 +91,3 @@ space inside a value, you should quote it, like this:
`artist="A Tribe Called \"Quest\"" percent>50`
However, it is likely you will never need to use this.
-2
View File
@@ -63,7 +63,5 @@ The following games are supported on [Bokutachi](https://boku.tachi.ac).
| PMS | `pms` | `Controller`, `Keyboard`[^2] |
| unnamed_sdvx_clone | `usc` | `Controller` `Keyboard`[^2] |
[^1]: Pop'n *had* some other playtypes, namely a 5-Button mode, but it seems to be removed now. 9B is used instead of single here for futureproofing.
[^2]: This use of playtypes is a small hack to make separate leaderboards for keyboard and controller players. The split is necessary because the two input mechanisms are *very* different at high levels, but there are still a lot of keyboard players. It's a compromise!
+1 -1
View File
@@ -65,4 +65,4 @@ The rules can be found [here](./rules.md).
Please reach out on discord or [GitHub Issues](https://github.com/zkrising/Tachi)!
--8<-- "includes/abbreviations.md"
--8<-- "includes/abbreviations.md"
+1 -1
View File
@@ -84,7 +84,7 @@ Similarly, try and keep session names and about me's and whatnot appropriate.
In general, just don't be an ass.
## R4: Use Common Sense.
## R5: Use Common Sense.
This list of rules isn't exhaustive, and staff reserve the
right to ban you at any time for any reason. You should use
+1 -1
View File
@@ -87,4 +87,4 @@ You can't check the score timestamp. Games like LR2 do not store timestamps, gam
Similarly, scores are sometimes duplicated across services -- someone might import their FLO scores to EAG using their integration. Those timestamps also get clobbered.
It is safer to be right all the time on deduplication and sacrifice this case.
It is safer to be right all the time on deduplication and sacrifice this case.