Hand Shaker

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

🤝 HandShaker 7.0.0 (alpha) Wiki is there!

Modrinth

CurseForge

Paper

Purpur

Wiki

Ko-fi

Fabric API

---

📋 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

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

---

✨ Key Features

| Feature | Description | | ------------------------------- | ------------------------------------------------------------------- | | 🔐 🔐 Custom Actions | Individually set mod allowance to Required, Allowed, or Blacklisted | | 🚫 🔐 Custom Actions | Configurable kick messages and auto-ban capabilities | | 📊 🔐 Custom Actions | Store and query player mod histories | | 👀 🔐 Custom Actions | Administrators can see other players' mod lists | | ✔️ 🔐 Custom Actions | 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+) | | -------------------------- |:----------------------------:|:-----------------------:|:---------------:| | Clickable text in chat | ✅ 6.x+<br/>⚠️ 3.x - 5.x<br/> | ✅ 6.x+<br/>⚠️ 3.x - 5.x | ✅ 6.0.0+ | | Clickable text in chat | ✅ 6.0.0+ | ✅ 6.0.0+ | ✅ 6.0.0+ | | Clickable text in chat | ✅ 5.0.0+ | ✅ 5.0.0+ | ✅ 6.0.0+ | | Clickable text in chat | ✅ 5.2.0+ | ✅ 5.2.0+ | ❌ | | Clickable text in chat | ✅ 5.0.0+ | ✅ 5.0.0+ | ❌ | | Clickable text in chat | ✅ 6.0.0+ | ❌ | ❌ | | Clickable text in chat | ✅ | ❌ | ❌ |

---

🚀 Quick Start

Commands

Installation

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

- NeoForge Client: Place JAR in `mods/` folder - NeoForge Client: Place JAR in `plugins/` folder - NeoForge Client: Place JAR in `mods/` folder

2. Configure the mod/plugin

Basic Configuration

```yaml 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!"

```

```yaml 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 | | ------------ | ----------------------- | ----------- | -------- | ------- | | NeoForge | 1.21 - 1.21.10, 1.21.11 | ✅ Supported | N/A | N/A | | NeoForge | 1.21+ | ✅ Supported | N/A | N/A | | NeoForge | 1.21 - 1.21.10, 1.21.11 | ✅ Supported | 1.20.1 | Planned |

---

📚 Documentation

* 📖 Building from Source * ⬇️ %%MD1%% * ⚙️ %%MD2%% * 💬 %%MD3%% * 🔨 Building from Source * 📋 %%MD4%%

---

Roadmap

- More QoL features

---

🤝 Contributing

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