Hand Shaker

⚠️ This project requires to be set up on both sides, client and server side ⚠️

🤝 HandShaker 7.0.0 (alpha) Wiki is there!

📋 What is HandShaker?

HandShaker is a cross-platform mod/plugin verification system for Minecraft servers and clients. It enables servers to detect which mods players are running and enforce mod restrictions with customizable policies.

🎯 Core Functionality

• Fabric/Neoforge Client → Sends your active mod list to the server upon join
• Paper/Fabric/NeoForge Server → Validates mod lists against configured rules and enforces restrictions
• Multi-platform Support → Works across Fabric, Paper, and NeoForge
• Cryptographic Integrity → Prevents tampered or self-compiled HandShaker mods
• Flexible Configuration → Per-mod rules: Required, Allowed, or Blacklisted

✨ Key Features

Feature · Description
🔐 Per-Mod Configuration · Individually set mod allowance to Required, Allowed, or Blacklisted
🚫 Customizable Enforcement · Configurable kick messages and auto-ban capabilities
📊 Player History Database · Store and query player mod histories
👀 Player Mod Viewing · Administrators can see other players' mod lists
✔️ Integrity Verification · Cryptographic signatures prevent spoofed mod reports
🔐 Custom Actions · Allows to setup custom events (commands) for triggered mods

🏗️ Platform Comparison

✅ Supported/Working
⚠️ Issues/Unsupported
❌ Unsupported/Broken

Features · Paper (1.x - 6.x) · Fabric (2.x - 6.x) · NeoForge (6.x+)
| Integrity Checking | ✅ 6.x+
⚠️ 3.x - 5.x
| ✅ 6.x+
⚠️ 3.x - 5.x | ✅ 6.0.0+ |
Configurable Rules · ✅ 6.0.0+ · ✅ 6.0.0+ · ✅ 6.0.0+
Database Storage · ✅ 5.0.0+ · ✅ 5.0.0+ · ✅ 6.0.0+
GeyserMC/Floodgate · ✅ 5.2.0+ · ✅ 5.2.0+ · ❌
Permissions · ✅ 5.0.0+ · ✅ 5.0.0+ · ❌
Folia Compatibility · ✅ 6.0.0+ · ❌ · ❌
Clickable text in chat · ✅ · ❌ · ❌

🚀 Quick Start

Commands

Installation

1. Download the appropriate mod/plugin for your platform:

• Fabric Client: Place JAR in mods/ folder
• Paper Server: Place JAR in plugins/ folder
• NeoForge Client: Place JAR in mods/ folder

1. Configure the mod/plugin

Basic Configuration

config: v4

Behavior: "strict" - Force requires client-side mod or "vanilla" allow also non-mod clients

behavior: strict

Integrity Mode: "signed" or "dev" - allow unsigned mods (if you are building own client/server fork)

integrity-mode: signed

Whitelist mode: true = only allowed mods (inside whitelisted.yml), false = allowed by default.

To work properly set "mods-whitelisted-enabled" must be true

whitelist: false

Allow Bedrock players

allow-bedrock-players: false

Player Database: Store and track player mod history (requires playerdb to be enabled)

playerdb-enabled: false

Mod List Toggles: Enable/disable each mod list without losing configuration

mods-required-enabled: true
mods-blacklisted-enabled: true
mods-whitelisted-enabled: true

Kick Messages - customize as needed (use {mod} for mod name)

messages:
kick: "You are using a blacklisted mod: {mod}. Please remove it to join this server."
no-handshake: "To connect to this server please download 'Hand-shaker' mod."
missing-whitelist: "You are missing required mods: {mod}. Please install them to join this server."
invalid-signature: "Invalid client signature. Please use the official HandShaker client mod."

ban: "You have been banned for using a blacklisted mod: {mod}."
bedrock: "Bedrock players are not allowed on this server."

custom messages for actions can be added here

placeholders are {mod} - mod which triggered, {player}

test_action: "Hi, {player}! You are using {mod}! Thanks for using it!"

actions:

System actions (Uses hardcoded functions, not recomended to copy these)

kick:
commands:

• "kick {player} {messages.kick}"

ban:
commands:

• "ban {player} {messages.ban}"

log: true

log:
missing: "{player} tried to join but missing required mod/mods: {mod}"
blacklisted: "{player} tried to join with blacklisted mod/mods: {mod}"

Examples of custom actions

placeholders are {mod} - mod which triggered, {player}, {messages.name_from_config.yml}

test_action:
commands:

• "msg {player} {messages.test_action}"
• "give {player} minecraft:diamond 1"
• "say Say Hello to {player}, who is using {mod}!"

watchdog:
commands:

• "ac increase_alert_level {player} 1000"

📝 Permissions

Permission · Description · Default
handshaker.admin · Access to admin commands · Operator
handshaker.bypass · Bypass mod restrictions · False

🎮 Supported Versions

Loader · Versions · Status · Versions · Status
Fabric · 1.21 - 1.21.10, 1.21.11 · ✅ Supported · N/A · N/A
Paper · 1.21+ · ✅ Supported · N/A · N/A
NeoForge · 1.21 - 1.21.10, 1.21.11 · ✅ Supported · 1.20.1 · Planned

📚 Documentation

• 📖 **Full Wiki**
• ⬇️ **Installation Guide**
• ⚙️ **Configuration Guide**
• 💬 **Commands Reference**
• 🔨 Building from Source
• 📋 **Changelog**

Roadmap

• More QoL features

🤝 Contributing

Issues, pull requests, and suggestions are welcome! Check the GitHub repository for contribution guidelines.