No description
Find a file
Arigadam 324e6f75c8 Add ComboCoal client-only Fabric mod for Minecraft 1.21.4
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>
2026-10-11 18:29:07 +03:00
backend Add ComboCoal client-only Fabric mod for Minecraft 1.21.4 2026-10-11 18:29:07 +03:00
gradle/wrapper Add ComboCoal client-only Fabric mod for Minecraft 1.21.4 2026-10-11 18:29:07 +03:00
src Add ComboCoal client-only Fabric mod for Minecraft 1.21.4 2026-10-11 18:29:07 +03:00
.gitattributes Add ComboCoal client-only Fabric mod for Minecraft 1.21.4 2026-10-11 18:29:07 +03:00
.gitignore Add ComboCoal client-only Fabric mod for Minecraft 1.21.4 2026-10-11 18:29:07 +03:00
build.gradle Add ComboCoal client-only Fabric mod for Minecraft 1.21.4 2026-10-11 18:29:07 +03:00
gradle.properties Add ComboCoal client-only Fabric mod for Minecraft 1.21.4 2026-10-11 18:29:07 +03:00
gradlew Add ComboCoal client-only Fabric mod for Minecraft 1.21.4 2026-10-11 18:29:07 +03:00
gradlew.bat Add ComboCoal client-only Fabric mod for Minecraft 1.21.4 2026-10-11 18:29:07 +03:00
README.md Add ComboCoal client-only Fabric mod for Minecraft 1.21.4 2026-10-11 18:29:07 +03:00
settings.gradle Add ComboCoal client-only Fabric mod for Minecraft 1.21.4 2026-10-11 18:29:07 +03:00

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 for Minecraft 1.21.4.
  2. Put 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".