Hercule Documentation

Quick Start

New to Hercule? Start small. Enable one module, understand what it does, then tune settings. Most issues come from enabling too many conflicting modules at once.

UI, HUD, and Scaling

Hercule includes a ClickGUI, HUD editor, visual labels, and style controls. If the GUI looks too small, use the Settings tab to increase GUI scale.

Module Index

Complete reference for all 130+ modules. Each card shows the module name, category, and a short description of what it does.

Combat

Modules for attacking, targeting, and PvP advantage.

Movement

Modules for flight, speed, traversal, and movement control.

Player

Modules for inventory, survival, interaction, and player utilities.

Visual

Modules for ESP, HUD elements, rendering, and visual information.

World

Modules for mining, building, pathfinding, and world interaction.

Misc

Modules for automation, anti-cheat bypass, social features, and utilities.

Baritone Guide

Baritone is Hercule's advanced pathfinding module. It can route, jump, bridge, tunnel, dig, avoid threats, render paths, and includes integrated safety and route recording.

Builder System

The Builder module lets you save structures from the world, load them from files, and automatically rebuild them block by piece. It supports full structure analysis, block counting, and incremental building with Baritone integration.

Packet System

Understanding how Hercule handles network packets is key to advanced scripting and module behavior. Bedrock Edition communicates with servers using packets — structured binary messages for movement, actions, inventory, and more.

Config System

Hercule stores all module settings, keybinds, and HUD positions in configuration files. Understanding the config system lets you back up setups, share them, and switch between playstyles quickly.

Lua Scripting Basics

Lua scripts let you create custom modules without editing C++. Use a table, register it, then define lifecycle functions.

local MyModule = {}

function MyModule.on_enable(self)
    client.notification("Hercule", "Module enabled", 2)
end

function MyModule.on_tick(self)
    local x, y, z = player.getPos()
    if module.get("My Module", "Debug") then
        client.chat("Y = " .. tostring(math.floor(y)))
    end
end

module.register("My Module", "Beginner friendly example", "Misc", MyModule)
module.addBool("My Module", "Debug", "Print position info", false)

Lua API Reference

Complete reference for the functions available to Lua scripts. All functions are crash-protected and sandboxed. Dangerous standard libraries (io, os, debug, package) are blocked.

module — Module Registration & Settings

client — Chat, Input, Notifications

player — Position, Rotation, Combat

world — Blocks, Entities, Raycasting

render — Custom Drawing (use in on_render)

packet — Packet Creation & Manipulation

auth — PlayerAuthInput Helpers

Event Callbacks

Define these functions inside your module table. The engine calls them automatically.

Useful Packet IDs

Script Examples

Simple Fly

local Fly = {}

module.register("LuaFly", "Simple movement script", "Movement", Fly)
module.addSlider("LuaFly", "Speed", "Move speed", 0.1, 5.0, 1.5)

function Fly.on_disable(self)
    player.setMotion(0, 0, 0)
end

function Fly.on_tick(self)
    local speed = module.get("LuaFly", "Speed")
    local yaw = player.getRot()
    local rad = math.rad(yaw + 90)
    local mx, mz = 0, 0
    if client.isKeyDown("w") then
        mx = math.cos(rad) * speed
        mz = math.sin(rad) * speed
    end
    local my = 0
    if client.isKeyDown("space") then my = speed end
    if client.isKeyDown("shift") then my = -speed end
    player.setMotion(mx, my, mz)
end

Block Warning

local BlockWarn = {}

function BlockWarn.on_tick(self)
    local x, y, z = player.getPos()
    local below = world.getBlock(math.floor(x), math.floor(y - 1), math.floor(z))
    if below and string.find(below, "magma") then
        client.notification("Warning", "You are standing on magma", 1.5)
    end
end

module.register("BlockWarn", "Warns about dangerous blocks", "World", BlockWarn)

GUI Translation Pack

Translations are simple runtime overrides. Dump the live key list first so you can see exact scoped names like Combat.Killaura.Range, then save the script as UTF-8 and reload scripts.

local template = client.dumpTranslationKeysText()
print(template) -- copy from the Script console and replace values with your language

client.setTranslations({
    ["tab.Settings"] = "TRANSLATED_SETTINGS_TAB",
    ["Combat.Killaura.Range"] = "TRANSLATED_RANGE",
    ["Combat.Killaura.Range.tooltip"] = "TRANSLATED_RANGE_TOOLTIP",
    ["Combat"] = "مبارزه",
    ["Movement"] = "حرکت",
    ["Visual"] = "视觉",
    ["Console"] = "Консоль",
    ["Keybind"] = "键位",
    ["Press any key to bind, DEL/BACK to unbind, ESC to cancel."] =
        "按任意键绑定，DEL/BACK 取消绑定，ESC 退出。"
})

local GuiLang = {}
module.register("GuiLang", "Loads custom GUI translations", "Misc", GuiLang)

Table Criticals (Advanced)

This example shows a complete combat script with packet caching, lifecycle cleanup, settings, and attack-triggered packet sends. Move once after enabling to cache a valid PlayerAuthInput packet.

local Criticals = {} 

local PACKET_AUTH_INPUT = 144 

local cached_packet_template = nil
local has_valid_cache = false

local function log(msg)
    print("[TableCrit] " .. tostring(msg))
end

function Criticals.on_enable(self)
    has_valid_cache = false
    cached_packet_template = packet.create(PACKET_AUTH_INPUT)
    log("Enabled.")
end

function Criticals.on_disable(self)
    has_valid_cache = false
end

function Criticals.on_packet_send(self, pkt)
    if packet.getId(pkt) == PACKET_AUTH_INPUT then
        if cached_packet_template ~= nil then
            packet.copy(cached_packet_template, pkt)
            has_valid_cache = true
        end
    end
end

function Criticals.on_attack(self, target)
    if not has_valid_cache or cached_packet_template == nil then
        log("No cache. Move first!")
        return
    end

    local count = module.get("LuaCrit", "Packet Count")
    local x, y, z = auth.getPos(cached_packet_template)

    local jump_pkt = packet.create(PACKET_AUTH_INPUT)
    packet.copy(jump_pkt, cached_packet_template)
    
    auth.setPos(jump_pkt, x, y + 1.0, z)
    auth.clearVertical(jump_pkt)
    
    client.sendPacket(jump_pkt)

    local fall_y = y + 0.5
    
    for i = 1, count do
        local fall_pkt = packet.create(PACKET_AUTH_INPUT)
        packet.copy(fall_pkt, cached_packet_template)
        
        auth.setPos(fall_pkt, x, fall_y, z)
        auth.clearVertical(fall_pkt)
        
        client.sendPacket(fall_pkt)
    end
    
    log("Crit! (" .. count .. " packets)")
end

module.register("LuaCrit", "Criticals using Lua Table Structure", "Combat", Criticals)
module.addSlider("LuaCrit", "Packet Count", "Packets sent per hit", 1, 10, 6)

Command Reference

All 24 active commands. Use . prefix for client commands, # for Baritone commands. Type in chat or use the console (F6).

General

Module Control

Teleportation

Navigation & World

Targeting & Social

Server & System

Script Playground

Test Lua snippets in a live terminal. Type code and press Enter or click Run to execute. This runs a sandboxed Lua interpreter in your browser for quick experimentation.

Troubleshooting