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> |
||
|---|---|---|
| backend | ||
| gradle/wrapper | ||
| src | ||
| .gitattributes | ||
| .gitignore | ||
| build.gradle | ||
| gradle.properties | ||
| gradlew | ||
| gradlew.bat | ||
| README.md | ||
| settings.gradle | ||
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/allowArrowOnMultiplayertotrue. 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
- Install Fabric Loader for Minecraft 1.21.4.
- Put Fabric API for 1.21.4 into your
modsfolder. - Put
combocoal-1.0.0.jarinto themodsfolder.
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
Okey. - Hats for pets are not implemented in v1.
- The mod is client-only:
"environment": "client".