An unofficial web-based implementation of the Hitster card game by Koninklijke Jumbo B.V.
View Stable Demo
·
View Development Demo
·
Report Bug
·
Request Feature
Table of Contents
Hitster is a music quiz card game developed and released by Koninklijke Jumbo B.V. Its very easy to play and is fun to play for literally everyone. Here is a short rundown of how to play:
- Everyone receives a hit card at the beginning of a game. A hit contains information about a song, containing its title, the artist and year when it was released.
- A short snippet of a hit is played to you. You'll have to guess if it was released either before or after the hit that you already have in your collection.
- If you guessed correctly, you'll earn the hit card and add it to your collection. The game will continue to the next player.
- Next time it's your turn, you'll be played a hit again, but this time, you'll have to guess if it was released either before your earliest hit's release year, between your two hits, or after the latest hit release. Guess correctly to earn yourself another hit card, grow your collection, but also make it harder to guess your next hit correctly.
There is more to it, like tokens you can earn by also guessing title and artist of a hit, and paying them to intercept your opponents by correcting their guesses to earn their hit for your own. But see for yourself, you don't need to register, just visit the demo and play a game with at least one of your friends.
... and loads more
Hitster consists of two separate projects:
- a server component deploying a REST API, written in Rust and based on Rocket
- a client application responsible for displaying the game's UI and interacting with the server, written in React and TypeScript
Follow these steps to get a dev environment ready to run the project locally.
The project is supposed to run inside a Docker container. As such, it holds a Dockerfile which builds the project. It also pushes docker images whenever a commit is created. If you just want to spin it up locally to give it a try, run the following command with Docker installed:
docker run -p 8000:8000 tonironaldbarth/hitster:latestMultiple containers are available to choose from:
| tag | purpose |
|---|---|
| latest | newest stable version |
| dev | bleeding edge dev (might break unpredictably, contains all newest features that haven't been merged into stable) |
| <release_name> | a specific release that won't change anymore, see the list of available tags for your possible options |
The Docker containers currently only automatically gets built for amd64 and arm64, feel free to open an issue or pull request to add/request more build targets.
If you want to build the container for yourself, clone the repository, open a command line and navigate into the project directory, then run the following commands:
docker build -t hitster .
docker run -p 8000:8000 hitsterThe Hitster application will be accessible on localhost Port 8000 afterwards. Please see below for a list of environment variables to further configure the container.
The Docker container exposes some volumes which you can connect to to persist your data. The following table holds information about the available paths:
| Path | Description |
|---|---|
| /hitster.sqlite | the database holding registered user information etc |
| /hits | the folder where downloaded hits are stored |
You can launch a docker container by specifying your volumes like follows:
docker run -v hits:/hits -v hitster.sqlite:/hitster.sqlite -p 8000:8000 tonironaldbarth/hitsterAn easier way of launching a Hitster server is by utilizing Docker Compose. You can find an example docker-compose.yml file below:
services:
hitster:
image: tonironaldbarth/hitster:latest
### comment above line and uncomment if you want to build from source
#build:
# context: .
restart: unless-stopped
volumes:
- ./hitster.sqlite:/hitster.sqlite
- ./hits:/hits
environment:
- ROCKET_SECRET_KEY=generate_me_a_secret_key
- ROCKET_ADDRESS=0.0.0.0
ports:
- "8000:8000"Setting up the project locally will requires several tools, which need to be accessible on your PATH environment variable to be called without having to know their exact path. We strictly recommend to stick to a Docker-based development environment instead. Should you want to still go for a local setup, please find the instructions below.
You'll need the following tools to be installed:
- Node.js v20
- Rust: we recommend to install the most recent stable version, that'll most likely be the version we're developing with as well
- FFMpeg: we recommend installing the yt-dlp compatible static builds from its corresponding GitHub repository
- FFMpeg-normalize
- (optional) yt-dlp. Make sure to check the list of environment variables to enable the usage of yt-dlp (disabled by default)
Ensure that everything is working by running the following test commands and ensuring proper output:
node -v
rustup show
ffmpeg -version
ffmpeg-normalize
yt-dlp -vStart by cloning this repository. Open a command line and navigate into the folder of the cloned repository. Afterwards, run those commands to build both components of the Hitster project:
- client:
cd client npm install npm run build cd ..
- server:
cd server cargo run
Please note that you'll need to specify a certain set of environment variables when running the application locally in order for it to start. You can find the list of environment variables below.
When launching the server, Hitster will always download all missing hits. That means that especially when starting it for the first time, downloading all hits will take quite a while. You can monitor the progress by skimming through the process output. The server will not be running while the download is in progress. It is planned to further parallelize the process to have the server running while downloading in the background.
The project can be configured through environment variables. Environment variables can be populated in different ways, depending on how you are running it.
- (local only) by setting them via EXPORT on Linux or SET on Windows, e.g.:
export DATABASE_URL=~/sqlite://hitster.sqlite
- (local only) by specifying them inside a .env file, which will have to be placed inside the server directory of this repository. A file could look like this:
DATABASE_URL=sqlite://hitster.sqlite
- (Docker only) handing them to the docker run command via the -e switch, e.g.:
docker run -e DATABASE_URL=sqlite://hitster.sqlite -p 8000:8000 tonironaldbarth/hitster
The following environment variables are available. Required variables are set to default values when running via docker.
| variable | required | meaning |
|---|---|---|
| DATABASE_URL | yes | location of the database file, must be in the format of sqlite://path_to_file.sqlite, /hitster.sqlite in Docker containers by default |
| CLIENT_DIRECTORY | no | specify the location of the compiled client files, usually not needed in Docker, ./client in local mode |
| DOWNLOAD_DIRECTORY | no | download location of the songs downloaded by the server, /hits in Docker containers by default, ./hits otherwise |
| USE_YT_DLP | no | enable the use of yt-dlp as a fallback if the server-internal YouTube downloader fails, enabled in Docker containers by default, disabled otherwise |
In addition to those custom environment variables, the server can be further tweaked by populating Rocket-specific environment variables. Some important variables would be ROCKET_ADDRESS to specify the address to bind to the server, as well as ROCKET_PORT to change the port the server is listening on. For a permanently deployed service, we recommend setting the ROCKET_SECRET_KEY environment variable to a randomly generated key, which will allow users to stay logged in even if the server restarts. Please see the list of rocket environment variables on the rocket website.
See the open issues for a full list of proposed features (and known issues).
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the GNU General Public License, version 3. See LICENSE for more information.
Toni Barth - [email protected] - [email protected]
Project Link: https://github.com/Timtam/hitster
