From ccd4e369e94f22a40d0544d9d93011d5955523e4 Mon Sep 17 00:00:00 2001 From: prescientmoon Date: Wed, 4 Sep 2024 00:53:18 +0200 Subject: [PATCH] Add basic readme --- README.md | 76 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..40f4852 --- /dev/null +++ b/README.md @@ -0,0 +1,76 @@ +# Shimmeringmoon + +Arcaea screenshot analyzer! + +This bot analyzes your Arcaea screenshots (both of your scores, and taken in the song-select menu), extracts score data from them, and keeps track of such score data in a database. This bot is still in development. Contact `@prescientmoon` on discord if you want to help out in any way. + +## Features + +- song/chart info queries +- score queries (eg: listing your best score for a given chart) +- B30 (heck, even B300, if you so desire) rendering +- Multiple scoring systems to choose from (including sdvx like EX-scoring) +- Achievements (work in progress) +- Graph plotting (work in progress) + +## How does it work + +- The bot uses [poise](https://github.com/serenity-rs/poise) in order to communicate with discord +- The bot renders images using [my own custom bitmap renderer & layout system](./src/bitmap.rs) +- The bot recognises images using [my own jacket recognition algorithm](./src/arcaea/jacket.rs) +- The bot reads text using [my own OCR algorithm](./src/recognition/hyperglass.rs). The project started off by using [Tesseract](https://github.com/tesseract-ocr/tesseract), although it was unreliable, and had big issues reading fonts with a lot of kerning (like Arcaea's song font for the bigrams `74` and `24`). My implementation is much more accurate because it's much less general purpose, and uses knowledge of the font to achieve better results. + +No neural-networks/machine-learning is used by this project. All image analysis is done using classical algorithms I came up with by glueing basic concepts together. + +## Running locally + +The bot needs the following environment variables to be set in order to run: + +``` +SHIMMERING_DISCORD_ID=yourtoken +SHIMMERING_DATA_DIR=shimmering/data +SHIMMERING_ASSET_DIR=shimmering/assets +SHIMMERING_CONFIG_DIR=shimmering/config +SHIMMERING_LOG_DIR=shimmering/logs +``` + +### Fonts + +The following fonts must be present in `$SHIMMERING_ASSET_DIR/fonts`: + +``` +arial.ttf +exo-variable.ttf +geosans-light.ttf +kazesawa-bold.ttf +kazesawa-regular.ttf +noto-sans.ttf +saira-variable.ttf +unifont.otf +``` + +### Assets + +Most of the assets in this repo have been drawn by me, although you need to bring in your own song jackets and place them at `$SHIMMERING_ASSET_DIR/songs`. This subdirectory must contain a subdirectory for each song in the game, with such subdirectories containing their default jacket at `base_256.jpg`. Different files can be created to override the jacket for each difficulty. For more details, check out the implementation in [./src/arcaea/jacket.rs](./src/arcaea/jacket.rs). + +Additionally, you must place a custom `b30` background at `$SHIMMERING_ASSET_DIR/b30_background.jpg`. + +> [!CAUTION] +> As far as I am concerned, the code in this repository does not violate the Arcaea terms of service in any way. Importing jackets that have been datamined/ripped out of the game is against the aforementioned TOS, and is highly discouraged. + +### Importing charts + +The charts are stored in [$SHIMMERING_CONFIG_DIR/charts.csv](./shimmering/config/charts.csv). This is a csv-version of Lumine's [Arcaea song table](https://tinyurl.com/mwd5dkfw) ([with permission](https://discord.com/channels/399106149468733441/399106149917392899/1256043659355226163)). Importing song-data from any other source (such as datamined database files) will not only be more difficult for you (all the scripts I have written are built around the aforementioned spreadsheet), but is also against the Arcaea terms of service. + +To add charts that have just been added to the CSV file into the database, run [import-charts.py](./scripts/import-charts.py). + +## Thanks + +Many thanks go to: + +- `@.luminexus` for providing the amazing [Arcaea song table](https://tinyurl.com/mwd5dkfw) +- `@siloricity` for helping with development assets +- `@black._heart_.sl` for being the first person I discussed this idea with +- `@dyuan01` for discussing different scoring system ideas with me +- [George Dragomir](https://github.com/BlueGhostGH) for, at my request, writing [a new set](https://github.com/BlueGhostGH/hypertesseract) of [Tesseract](https://github.com/tesseract-ocr/tesseract) bindings for the Rust programming language. The [popular rust bindings for Tesseract](https://crates.io/crates/tesseract) are incomplete, unidiomatic, painful to use, easy to misuse, and leak copious amounts of memory. Please avoid them at all cost. +- The members of a certain small-scale Arcaea server for enduring my shimmeringmoon-related rambles :3