a native anticheat for fabric servers.
it catches only what a server can see.
first beta (0.1.0). everything here is what's been tested so far, misses included.
the anticheats i tried either missed hacks or banned honest players for having bad wifi. the second one's worse. a missed hack lets a hacker free, but a false ban costs you a player.
so the quality standard for meshac is simple. if a cheat leaves a trace the server can see, catch it. if it's a real player lagging, don't touch them. zero false flags is the goal, and every check has to prove it against a clean control before it ships.
meshac watches movement, combat, building, mining, interaction and elytra flight. it works out what vanilla physics would allow and steps in when the two don't match.
with enforcement on, every flag can add heat, and heat cools off on its own. a few signals can get a setback. a steady run of them can get a hold and then a removal. we test with lag on purpose, but that can't promise a lagging player never gets flagged.
- the player gets put back
- then held for a moment
- then kicked, and repeat offenders get tempbans that grow each time (on the default preset: 10 minutes, 1 hour, 6 hours, 36 hours, up to 7 days)
permanent bans are off unless you turn them on.
the reports linked below say what was tested, how, and what is still missing.
flight, speed above sprint-jump pace, step, spider, jesus, fast climb, no slow, timer, blink (0.75 s and up), slippy, air jump, high jump, elytra fly and boost, reach, kill aura, criticals, crystal aura, anchor aura, auto totem, nuker, packet mine, ghost hand, auto clicker.
clean controls that ran without a flag: sprint-jumping, wind charges, tnt and crystal knockback, elytra, hand mining through tunnels, lag spikes and a laggy proxy.
- speed at or below sprint-jump pace. it looks exactly like a fast legit player, so meshac doesn't pretend
- short blink (about 0.4 s)
- surround
- bow aimbot
- boosts above 45 blocks per second
- explosion knockback is exempt on purpose, because legit players get launched by explosions all day
some modules just haven't been run yet. that list lives in docs/coverage.md.
the sign text rule and the chat command rule were hooked on the wrong thread, so they never fired. the linked coverage report records the fixes and scripted-bot checks. a quiet test is not proof that its hook ran.
- get a jar for your minecraft version (see below)
- drop it in your server's
modsfolder next to fabric api - start the server.
config/meshac.jsongets written with every default so you can see each knob
players install nothing.
start in monitor mode. set monitorOnly to true and leave egregiousChecks empty so monitor-mode enforcement exceptions are not enabled. leave client fingerprinting off, and set combatLog to false, because the fingerprint rule and combat log protection both act even in monitor mode. watch the logs on your own server before enabling punishment.
| minecraft | local build file | java |
|---|---|---|
| 1.21.11 | meshac-1.21.11.jar |
21 |
| 26.1.2 | meshac-26.1.jar |
25 |
| 26.2 | meshac-26.2.jar |
25 |
| 26.3 | meshac-26.3.jar |
25 |
fabric api is required on all of them. the 0.1.0 beta is available. the file names in the table are what a local build makes. the release files have the mod version in the name too. to build one yourself, see building.
all /mesh commands are op only.
| command | what it does |
|---|---|
/mesh cases |
recent cases |
/mesh case <id> |
what happened and why |
/mesh status <player> |
a player's heat, offences and what happens next |
/mesh watch |
flags in chat as they happen |
/mesh monitor, /mesh monitor on, /mesh monitor off |
show or switch monitor mode |
/mesh kick, /mesh ban |
manual removal |
/mesh pardon <case id>, /mesh unban <player> |
lift a case or a ban |
/mesh reload |
reload the config |
there's an optional discord webhook for holds and removals.
config reference
config/meshac.json, written with defaults on first start. three presets, lenient, default and strict. any knob left null follows the preset, set one to override just that knob.
| key | what it does |
|---|---|
preset |
lenient, default or strict |
monitorOnly |
log and alert unless a check is listed in egregiousChecks |
egregiousChecks |
checks that still enforce in monitor mode; leave empty for log-only testing |
permanentBan |
false caps the ladder at the longest tempban |
holdAt, removeAt |
heat at which a player is held, and removed |
halfLifeSeconds |
how fast heat cools. heatCoolSeconds is still in the config but nothing reads it |
combatLog, combatLogSeconds |
on by default. a player who disconnects while combat-tagged is killed. monitor mode does not stop it |
kicksBeforeTempban |
kicks before the first tempban |
tempbanBaseMinutes, tempbanGrowth, tempbanMaxMinutes |
the tempban ladder |
offenceHalfLifeDays, offenceMemoryDays |
how long old offences count |
requireClusters, requireClustersTierA |
independent causes needed before removal |
discordWebhook, discordOnHold |
webhook url (empty is off) and whether holds post too |
appeal, serverName, accent, warn |
the text and colours players see |
fixPistonWater |
patches MC-130183, the sticky piston flood machine bug. off by default |
veilXray, veilEsp |
anti-xray and anti-esp. off until proven on a real client |
clientFingerprintEnabled |
optional match on client brand or channel names. a client can fake both. off by default. if you turn it on, a match removes the player even if no check flagged anything |
how removal actually works, and its limits, is in docs/PUNISHMENT-DESIGN.md.
coverage by hack
the full per-module tables, with times, holds and kicks:
- docs/coverage.md for wurst
- docs/COVERAGE-METEOR.md for meteor
0 signals only counts as a miss when the hack visibly acted. if it didn't, the row says unproven, not passed.
the last full sweep ran 138 cases with 57 legit controls on the recorded 26.2 jar. no legit control was flagged. kill-aura is only caught on some runs, so treat it as partial. details are in docs/FINAL-SWEEP.md.
how it's tested
rig/ is a throwaway server and real clients on a docker network with no internet. it runs real wurst and meteor clients, scripted bots for packet-level tests, and a lag proxy that stalls and bunches packets so laggy connections get tested on purpose.
the rules for any new check:
- it ships with a test that shows it catching the hack
- and a test that shows it leaving legit play alone
- measure first, never tune blind
see rig/README.md.
false positives we've hit
every one gets written up: what flagged, why, and what the fix does. the short list so far is tunnel mining that looked like a nuker, a block broken "through" another when the hand just grazed a wall edge, and mining checks that tripped under lag. each fix needs a matching clean control.
per-version notes
one source tree builds for 1.21.11, 26.1.2, 26.2 and 26.3. the 1.21.11 jar uses the older obfuscated toolchain and runs on java 21, the rest need java 25. rig/smoke.sh boots each jar on a real server of its version.
real-client runs: wurst on 26.1.2, meteor on 26.2. 26.3 only has a few wurst checks (a nuker run and the tunnel-mining false positive), not a full sweep. 1.21.11 has been built and booted on a server, nothing more. these results are for the jars we tested, not every later commit.
you need java 25.
./gradlew build
the jar ends up in build/libs/. build-all.sh builds every version into dist/. for one version, pass every line of its file in versions/ as a -P flag, the way build-all.sh does. the 1.21.11 file includes remap=1, so don't leave that one out.
- a signal is one check catching something
- heat is a player's recent signals, and it cools off
- a trace is the evidence behind a signal
- a ward is an exemption
- docs/PRINCIPLES.md how code gets written here
- docs/PUNISHMENT-DESIGN.md the heat and ladder math
- docs/IDENTITY.md how it should feel
- docs/coverage.md and docs/COVERAGE-METEOR.md what's caught
gnu affero general public license v3.0 only, see LICENSE. use it, change it, share it. if you distribute it or run a modified copy for others over a network, share your changes under the same license and keep the copyright notices.