Understand Hercule without guessing.

Quick Start

If you are new, start small. Turn on one module, understand what it does, then tune the settings. Most problems happen when too many movement or combat modules fight each other.

UI, HUD, and Scaling

Hercule includes a full ClickGUI, HUD editor, visual labels, and custom style controls. If the GUI looks too small on 1080p, 1440p, or 4K displays, use the Settings tab to increase GUI scale and category sizing.

Capability Map

Here is the client at a glance. Names can change over time, but this explains the major feature families.

Baritone Guide

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

Inventory Manager

InventoryManager keeps armor equipped, promotes the best tools into predictable hotbar slots, and removes unwanted items from your inventory. Treat it like a rule engine: short, clear keywords produce the most reliable behavior.

Safety Tools

Safety modules are designed to prevent panic moments. They work best when configured conservatively.

Lua Scripting Basics

Lua scripts let you create custom modules without editing C++. Scripts use a table, register it as a module, 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

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)

Advanced Lua: Table Criticals

This example shows a complete table-structured combat script with packet caching, lifecycle cleanup, settings, and attack-triggered packet sends. It is intended for experienced users who already understand packet modules and testing in controlled environments.

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

Commands are useful when you want fast, precise control without opening a full settings panel.

Troubleshooting