Mobile-game style coal grinding: combo counter and ranks, HUD with popups and confetti, XP/coins/daily quest, dancing client-side pets, Coal Maniac mode, coal ESP and guide arrow (off on multiplayer by default), tool durability warnings and an English lang file. Opt-in online features backed by the Flask server in backend/: leaderboard, shared team combo per server, Help pings and a Help servers list, protected by a one-time captcha token and a proof of work. Includes Docker/Caddy deployment files and Fabric client game tests (single player, team combo and a two-client scenario). Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
175 lines
9.5 KiB
Markdown
175 lines
9.5 KiB
Markdown
# 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=<truststore.p12> -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"`.
|