# ComboCoal A just-for-fun, **client-only** Fabric mod for Minecraft **1.21.4** that turns coal mining into a mobile-game grind: a fullscreen combo counter, ranks, popups, confetti, XP, coins, a daily quest, dancing client-side pets, a step-by-step coal guide with an arrow, and tool-durability warnings. Needs only Fabric Loader (0.16+) and Fabric API. Nothing has to be installed on the server. > ## Warning: ESP features can get you banned > > The **Coal ESP** (highlights coal through walls) and the **coal arrow** (points to the nearest > coal) are x-ray style helpers. Most multiplayer servers forbid them, and using them can get you > **banned**. Both are therefore: > > * **on by default only in singleplayer**, > * **off on multiplayer** unless you explicitly set `allowEspOnMultiplayer` / `allowArrowOnMultiplayer` > to `true`. A warning is printed in chat once per launch when they are active on a server. > > Check the rules of the server before enabling them. You are responsible for what you enable. ## Features * **Combo**: +1 for every coal ore broken (coal and deepslate coal). Resets after 5 seconds without coal. * **Ranks**: C (0+) COAL!, B (10+) NICE VEIN!, A (20+) COAL-ASSAULT!, S (30+) UNSTOPPABLE!, SSS (50+) COAL MANIAC!!! (rainbow text). Rank-ups fire a sound, confetti and a "RANK UP!" popup. * **Mobile-style HUD**: elastic combo number, rank label, timer bar, floating popups, confetti, optional HUD-only screen shake from x25, top bar with level, XP bar and coins. * **Progress**: XP per coal = 10 + combo, coins = 1 + combo / 10, level threshold = level x 100. Saved to `config/combocoal_save.json`. * **Daily quest** ("Mine 50 coal", key `K`): earned by playing, with a pulsing CLAIM! button. No paid chests, no timers, no monetization tricks. * **Pets**: one per 5 combo (max 12), alternating wolves and cats with different collars. They orbit you, hop at 120 BPM and toggle sit/stand on the beat. They exist only in your own client (never sent to or known by the server), have no AI, collision, sounds or interaction, and are removed on combo loss, world leave and disconnect. * **Coal Maniac mode** (off by default): refuses to break ores that are not coal, with the message "You swore an oath to coal!". Stone, dirt and wood stay breakable. **Strict mode** blocks everything except coal and logs. * **Coal ESP**: highlights coal within a radius, brighter for bigger veins, the biggest vein pulses. Chunks are scanned incrementally and cached, so it is cheap. * **Coal guide** (key `G`): logs, crafting table, wooden pickaxe, stone pickaxe, find coal, mine the vein, craft torches. Steps are detected from your inventory. During "find coal" a rotating arrow and the distance to the nearest coal are shown. * **Durability warning**: a flashing warning and alarm when the held tool is below 10%. Repairing it gives a small combo bonus popup. * **Optional online features** (all opt-in, off by default, see below): leaderboard, a shared **team combo** for players on the same server, **"Help!" pings** and a **Help servers** list in the multiplayer screen. ## Install 1. Install [Fabric Loader](https://fabricmc.net/use/) for Minecraft 1.21.4. 2. Put [Fabric API](https://modrinth.com/mod/fabric-api) for 1.21.4 into your `mods` folder. 3. Put `combocoal-1.0.0.jar` into the `mods` folder. ## Build from source Requires JDK 21. ``` ./gradlew build # jar ends up in build/libs/ ./gradlew runClient # dev client ./gradlew runClientGameTest # automated end-to-end test (opens a window for about a minute) ``` ## Keys | Key | Action | |-----|--------------------------| | `G` | Show / hide coal guide | | `K` | Open daily quest | | `O` | Open ComboCoal settings | All keys can be rebound in the controls menu under the *ComboCoal* category. ## Config Edit in game (`O`) or in `config/combocoal.json`: | Option | Default | Meaning | |----------------------------|---------|---------| | `hapticShake` | `true` | HUD shakes from combo x25 | | `maniacMode` | `false` | Refuse to break non-coal ores | | `strictMode` | `false` | With maniac mode: only coal and logs are breakable | | `esp` | `true` | Coal ESP (singleplayer only, see below) | | `allowEspOnMultiplayer` | `false` | Allow the ESP on multiplayer servers (**ban risk**) | | `espRadius` | `32` | ESP and arrow search radius in blocks (8 to 64) | | `arrow` | `true` | Guide arrow to nearest coal | | `allowArrowOnMultiplayer` | `false` | Allow the arrow on multiplayer servers (**ban risk**) | | `pets` | `true` | Dancing pets | | `sounds` | `true` | Mod sounds (vanilla sounds only) | | `statsOptIn` | `false` | Enable the online features (stats, team combo, help pings) | | `statsEndpoint` | `"https://master.combocoal.wihuk.pro"` | https base URL of the stats server | | `statsConsentShown` | `false` | Set once the first-launch consent screen was answered | | `statsToken` | `""` | Captcha token, filled in automatically | | `hudScale` | `1.0` | HUD size, 0.5 to 2.0 | The ESP and arrow are active when `esp` / `arrow` is `true` **and** you are in singleplayer, or the matching `allow...OnMultiplayer` flag is `true`. ## Online features (opt-in) Everything below needs a stats server (see *Example backend*) and is **off by default**. On the first launch a consent screen explains exactly what is sent. "No thanks" (or closing the screen) keeps everything off. Nothing is sent unless `statsOptIn` is `true`, `statsEndpoint` is an `https://` URL **and** you solved the one-time captcha (the consent screen leads you there; later via the settings button *Verify (captcha)*). What is sent, always asynchronously with a 5 second timeout (the game never waits for the network): | Feature | When | Data | |---------|------|------| | Stats / leaderboard | leaving a world, closing the game, every 5 minutes if coal changed | player name, coal this session, best combo, server address | | Team combo | about once per second on a multiplayer server | player name, server address, coal broken since the last sync | | "Help!" ping | multiplayer, pickaxe below 10% durability at combo 20+, at most every 5 minutes | player name, server address, combo | Nothing else is sent. The mod never puts your IP address into the data; as with any web request the receiving server can see it. **Team combo.** Players on the same server address who opted in share one combo. Every coal any of them breaks raises it, and it ends after 5 seconds without a hit from anyone. Your own XP and coins still only come from coal you break yourself. The HUD shows "TEAM: N players". If the server stops answering, the mod falls back to your normal personal combo after a few seconds. **Help servers.** The multiplayer screen has a *Help servers* button listing servers (marked `[HELP]`) where players asked for help in the last 10 minutes, with a *Join* button. **Captcha and proof of work.** The captcha (a small sum) is solved once and gives a signed token valid for 30 days. Every upload also includes a proof of work (the server sends a challenge and the mod finds a nonce whose SHA-256 hash has enough leading zero bits; a fraction of a second for stats and help, much less for the team sync). Both are simple on purpose: they stop casual scripts, not a determined cheater. ### Example backend `backend/app.py` is a small Flask + SQLite server for all of the above: ``` cd backend pip install -r requirements.txt python app.py # http://127.0.0.1:5000 for local testing ``` Endpoints: `GET /captcha`, `POST /captcha`, `GET /pow` (`?scope=team` for the easier team challenge), `POST /stats`, `GET /leaderboard`, `POST /help`, `GET /help`, `POST /team/sync`. The secret that signs tokens is read from `COMBOCOAL_SECRET` or created in `backend/secret.key` (shared by all workers). All state (stats, team combo, used proof-of-work challenges) is stored in SQLite, so the server can run with any number of worker processes. `backend/Dockerfile`, `docker-compose.yml` and `Caddyfile` are a ready deployment with automatic HTTPS (edit the domain in the `Caddyfile`). The mod only talks https, so put it behind a TLS reverse proxy for real use (or set `COMBOCOAL_TLS_CERT` and `COMBOCOAL_TLS_KEY` to PEM files to let `app.py` serve https itself for development). Stats are self-reported; do not treat the leaderboard as trustworthy. ### Testing against a local backend `./gradlew runClientGameTest -PtestTrustStore= -PtestEndpoint=https://localhost:5443` runs the full online scenario (captcha, team combo with a simulated teammate on a dedicated server, help ping, stats upload). The truststore must contain your test certificate (password `changeit`). For two real clients on one external server, start `./gradlew runServer` (offline mode, ops `CoalA` and `CoalB`) and run two instances of `./gradlew runClientGameTest -PtestTrustStore=... -PtestEndpoint=... -PtestServer=localhost:25570 -PtestUsername=CoalA -PtestRunDir=build/run/clientA` (and the same with `CoalB` / `clientB`). Both must end with the stacked combo of 12. ## Translations All visible text goes through translation keys in `src/main/resources/assets/combocoal/lang/en_us.json`. To add a language, copy that file to e.g. `de_de.json` in the same folder and translate the values. ## Notes * Mod Menu integration is not included (the mod depends on Fabric API only); use the `O` key. * Hats for pets are not implemented in v1. * The mod is client-only: `"environment": "client"`.