🤖 nExBot - Next Generation Tibia Bot

A high-performance, intelligent automation bot for OTClientV8 with advanced AI, real-time analytics, and battle-tested reliability

🚀 Quick Start • ✨ Features • 🏗️ How It Works • 📚 Documentation • ⚙️ Configuration

📋 Table of Contents

What is nExBot?
Quick Start
Core Features
How It Works
Architecture
Configuration
Performance
Advanced Topics
Troubleshooting
Contributing

🎯 What is nExBot?

nExBot is a sophisticated, multi-system automation bot for Tibia that combines:

🗺️ CaveBot - Automated waypoint navigation with intelligent floor detection
🎯 TargetBot - AI-powered creature targeting with behavior prediction
💊 HealBot - Ultra-fast healing with spell and potion management
⚔️ AttackBot - Automated spell and rune attack system
📊 Hunt Analyzer - Real-time session analytics with insights engine
🛡️ Defense Systems - Anti-RS protection, condition handling, equipment management

All systems work together seamlessly with a unified event bus, shared analytics, and intelligent decision-making.

Note

nExBot is designed for reliability and performance. Every feature is battle-tested with real game scenarios, optimized for minimal CPU impact, and carefully validated for edge cases.

🚀 Quick Start

Step 1: Installation

Copy nExBot folder to:
```
%APPDATA%/OTClientV8/<your-config>/bot/
```
Example: C:\Users\YourName\AppData\Roaming\OTClientV8\Tibia Realms RPG\bot\nExBot
Load in OTClientV8:
- Open OTClientV8
- Press Ctrl+B to open Bot Settings
- Select nExBot from the bot dropdown
- Click Enable
Verify it loaded:
- Check that the bot panels appear in your tabs
- You should see: Main, Cave, Target tabs

Step 2: Basic Setup

HealBot (Most Important! ⚡)

Warning

Set up HealBot FIRST. Your survival depends on it!

Open the Main tab
Click Healing button
Add your healing spells:
- Formula: exura vita at 50% HP
- Formula: exura at 30% HP
Add healing potions:
- Item: Great Health Potion at 40% HP
Enable HealBot switch
Test by taking damage

CaveBot (Automation)

Open Cave tab
Click Show waypoints editor
Stand at your starting location
Click Add Goto to add waypoints
Repeat for your hunting route
Click Save and name your config
Enable CaveBot switch

TargetBot (Combat)

Open Target tab
Click the + button to add monsters
Set spell and rune attacks
Enable TargetBot switch

Step 3: Start Hunting!

Load your CaveBot config
Enable CaveBot and TargetBot
Click Start (Ctrl+Z)
Watch your hunting data in Hunt Analyzer (Main tab)

✨ Features

🎯 TargetBot - Intelligent Combat System

┌─────────────────────────────────────────────────────────────┐
│  INTELLIGENT TARGETING & COMBAT COORDINATION                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  📊 Weighted Priority Scoring                              │
│  ├─ Health Status (dying targets get priority)             │
│  ├─ Distance (closer = higher priority)                    │
│  ├─ Danger Level (threats evaluated real-time)             │
│  └─ Custom Patterns (!, *, #100-#110)                      │
│                                                             │
│  🧠 Monster Behavior AI                                     │
│  ├─ Pattern Recognition (static/chase/kite/erratic)       │
│  ├─ Attack Prediction (forecasts enemy waves)              │
│  ├─ Confidence Scoring (0-1 reliability metric)            │
│  └─ Behavior Database (learns from observation)            │
│                                                             │
│  ⚡ Advanced Movement                                        │
│  ├─ Wave Attack Avoidance (front-arc detection)            │
│  ├─ Dynamic Reactivity (7+ monsters = more reactive)       │
│  ├─ Tactical Reposition (multi-factor tile scoring)        │
│  ├─ AoE Spell Optimization (calculates best position)      │
│  ├─ Keep Distance (ranged positioning)                     │
│  └─ Anchor System (prevent wandering too far)              │
│                                                             │
│  🛑 Safety Features                                         │
│  ├─ Auto-stop on death                                     │
│  ├─ Low HP warnings                                        │
│  ├─ Trapped detection (no escape routes)                   │
│  └─ Anti-oscillation (stops erratic movement)              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Key Abilities:

✅ Pattern Matching - Use * for any monster, ! to exclude (e.g., *, !Dragon)
✅ Weighted Scoring - Combines health, distance, and danger into smart priority
✅ Wave Detection - Predicts group attacks before they happen
✅ Movement Coordination - Intent-based voting system prevents erratic movement
✅ Spell Optimization - Finds best position for AoE spells automatically
✅ Behavior Learning - Recognizes monster patterns (roaming, chasing, luring)

🗺️ CaveBot - Intelligent Navigation

┌──────────────────────────────────────────────────────────────┐
│  AUTOMATED WAYPOINT NAVIGATION                               │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  🚶 Walking v3.2.0 (Complete Rewrite)                       │
│  ├─ Floor-Change Prevention (never steps on stairs)         │
│  ├─ Field Handling (fire/poison/energy fields)              │
│  ├─ Chunked Walking (15 tiles max per call)                 │
│  ├─ Keyboard Fallback (when autoWalk fails)                 │
│  └─ Stuck Detection (auto-recovery in 3 sec)                │
│                                                              │
│  🛠️ Intelligent Actions                                     │
│  ├─ Auto Door Opening                                       │
│  ├─ Tool Usage (rope, shovel, machete, scythe)             │
│  ├─ Supply Refilling (HP/MP potions)                        │
│  ├─ Loot Depositing (automatic bank routing)                │
│  ├─ Waypoint Jumping (teleporter support)                   │
│  └─ Action Scripting (custom Lua in waypoints)              │
│                                                              │
│  📍 Waypoint Types                                           │
│  ├─ goto (walk to coordinates)                              │
│  ├─ label (mark locations)                                  │
│  ├─ action (custom scripts)                                 │
│  ├─ buy (NPC trading)                                       │
│  ├─ lure (creature pulling)                                 │
│  └─ 15+ more specialized actions                            │
│                                                              │
│  💾 Config Persistence                                       │
│  ├─ Save/Load complete routes                               │
│  ├─ Per-character profiles                                  │
│  ├─ Auto-restore on relog                                   │
│  └─ Multi-floor support                                     │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Smart Features:

✅ Floor-Change Detection - Validates entire path before walking
✅ Field Navigation - Automatically walks through damaging fields with keyboard
✅ Waypoint Recovery - Finds nearest waypoint if stuck
✅ Pull Integration - Pauses navigation during TargetBot pulls
✅ Tool Management - Auto-equips and uses tools
✅ Supply Refilling - Automatically replenishes potions at depots

💊 HealBot - Ultra-Fast Healing

┌───────────────────────────────────────────────────────────┐
│  RESPONSIVE HEALING SYSTEM (75ms response time!)           │
├───────────────────────────────────────────────────────────┤
│                                                           │
│  ⚡ Performance                                            │
│  ├─ 75ms spell response (faster than manual!)             │
│  ├─ Cached health data (1 second revalidation)            │
│  ├─ O(1) condition checking (instant lookups)             │
│  └─ Zero-allocation spell casting                         │
│                                                           │
│  📋 Flexibility                                            │
│  ├─ Multiple healing spells (cascading priority)          │
│  ├─ HP/MP triggered spells                                │
│  ├─ Potion support (no backpack needed)                   │
│  ├─ Support spells (mana shield, haste)                   │
│  └─ Condition handlers (poison, paralyze, burn)           │
│                                                           │
│  🛡️ Safeguards                                            │
│  ├─ Won't heal when already full                          │
│  ├─ Respects PvP protection (check PvP flag)              │
│  ├─ Group healing support (friend healer)                 │
│  └─ Mana waste detection (only casts when needed)         │
│                                                           │
└───────────────────────────────────────────────────────────┘

Advanced Options:

✅ Conditional Spells - Different spells at different HP thresholds
✅ Potion Priority - Mix spells and potions optimally
✅ Food Management - Auto-eat food on timer
✅ Mana Shield - Automatic protection spell casting
✅ Low Mana Handling - Fallback to potions when out of mana

⚔️ AttackBot - Automated Combat

┌────────────────────────────────────────────────────────┐
│  ATTACK AUTOMATION                                     │
├────────────────────────────────────────────────────────┤
│                                                        │
│  🎯 Attack Types                                       │
│  ├─ Single-target spells (targeted attacks)            │
│  ├─ Area spells (group damage)                         │
│  ├─ Runes (no backpack needed!)                        │
│  ├─ Hotkey items (scroll wheels, wands)                │
│  └─ Custom sequences (combo support)                   │
│                                                        │
│  ⚙️ Configuration                                      │
│  ├─ Per-monster spell selection                        │
│  ├─ Mana requirements (won't cast if low)              │
│  ├─ Cooldown management                                │
│  ├─ Danger level thresholds                            │
│  └─ Attack pattern chains                              │
│                                                        │
│  📊 Tracking                                            │
│  ├─ Spell cast counts                                  │
│  ├─ Rune usage tracking                                │
│  ├─ Attack frequency analysis                          │
│  └─ Damage output estimation                           │
│                                                        │
└────────────────────────────────────────────────────────┘

📊 Hunt Analyzer - Real-Time Analytics

┌──────────────────────────────────────────────────────────────┐
│  COMPREHENSIVE SESSION ANALYTICS                             │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  📈 Real-Time Metrics                                        │
│  ├─ XP Rate (XP/hour with peak tracking)                    │
│  ├─ Kill Rate (kills/hour with consistency analysis)        │
│  ├─ Profit Rate (loot value/hour)                           │
│  ├─ Damage Output (damage/hour, efficiency metrics)         │
│  ├─ Stamina Usage (session duration tracking)               │
│  └─ All peaks (best rates achieved)                         │
│                                                              │
│  🎯 Detailed Tracking                                        │
│  ├─ Spell usage counts (individual spells)                  │
│  ├─ Potion usage (ultimate health potion vs regular)        │
│  ├─ Rune usage (sudden death, etc.)                         │
│  ├─ Monster kills (breakdown by type)                       │
│  ├─ Loot items (top 5 drops)                                │
│  └─ Deaths/near-deaths (survivability)                      │
│                                                              │
│  🧠 Intelligent Insights                                     │
│  ├─ Efficiency recommendations                              │
│  ├─ Resource usage analysis                                 │
│  ├─ Survivability warnings                                  │
│  ├─ Equipment suggestions                                   │
│  ├─ Spell selection advice                                  │
│  └─ Confidence scoring (reliability metrics)                │
│                                                              │
│  🏆 Hunt Score (0-100)                                       │
│  ├─ XP Efficiency (25 pts)                                  │
│  ├─ Kill Efficiency (20 pts)                                │
│  ├─ Survivability (25 pts)                                  │
│  ├─ Resource Efficiency (15 pts)                            │
│  ├─ Combat Uptime (10 pts)                                  │
│  └─ Profit Bonus (5 pts)                                    │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Analytics Features:

✅ Trend Analysis - Shows direction indicators (↑ improving, ↓ declining)
✅ Consistency Scoring - Standard deviation of kill rates
✅ Damage Efficiency - Damage per spell/rune cast
✅ Time Tracking - Session duration with stamina breakdown
✅ Economic Analysis - Profit calculation with loot breakdown
✅ Confidence Metrics - Reliability score for each insight

🛡️ Integrated Safety Systems

┌─────────────────────────────────────────────────────────┐
│  PROTECTION & EMERGENCY SYSTEMS                         │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  🚨 Anti-RS (Rapid Skulling)                            │
│  ├─ Detects PvP flag changes                            │
│  ├─ Auto-unequips weapons                               │
│  ├─ Stops all combat                                    │
│  ├─ Exits game safely                                   │
│  └─ Configurable delays                                 │
│                                                         │
│  ⚠️ Condition Handlers                                  │
│  ├─ Poison detection & cure                             │
│  ├─ Burn effect handling                                │
│  ├─ Paralysis recovery                                  │
│  ├─ Silence/mute prevention                             │
│  └─ Automatic antidote usage                            │
│                                                         │
│  🎽 Equipment Management                                │
│  ├─ Auto-equip spell rings                              │
│  ├─ Weapon switching                                    │
│  ├─ Armour optimization                                 │
│  └─ Belt/amulet swapping                                │
│                                                         │
│  🔌 System Health                                        │
│  ├─ Connection monitoring                               │
│  ├─ Logout on disconnect                                │
│  ├─ Crash recovery                                      │
│  └─ Error logging                                       │
│                                                         │
└─────────────────────────────────────────────────────────┘

🏗️ How It Works

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     nExBot Architecture                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  UNIFIED EVENT BUS                                              │
│  ├─ onWalk (waypoint progress)                                 │
│  ├─ onCreatureHealthChange (damage tracking)                   │
│  ├─ onPlayerHealthChange (healing tracking)                    │
│  └─ onContainerOpen (supply management)                        │
│                                                                 │
│           │                                                     │
│           ├──────────────────┬──────────────────┐              │
│           ▼                  ▼                  ▼               │
│      CaveBot            TargetBot            HealBot            │
│  (Navigation)      (Intelligence)        (Protection)           │
│           │                  │                  │               │
│           └──────────────────┴──────────────────┘              │
│                           │                                     │
│                           ▼                                     │
│                    Hunt Analyzer                                │
│              (Session Analytics)                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Execution Flow

GAME TICK (250ms for CaveBot, event-driven for others)
    │
    ├─→ Event Check (health change, creature update)
    │   └─→ HealBot: Evaluate healing need
    │   └─→ TargetBot: Update creature priority
    │   └─→ Hunt Analyzer: Track metrics
    │
    ├─→ CaveBot Tick
    │   ├─ Get next waypoint
    │   ├─ Check walking status
    │   ├─ Validate path (floor-change check)
    │   └─ Execute movement/action
    │
    ├─→ TargetBot Combat
    │   ├─ Evaluate creature threat
    │   ├─ Calculate optimal position
    │   ├─ Predict enemy attacks
    │   └─ Execute movement or spell
    │
    └─→ HealBot Response
        ├─ Check health thresholds
        ├─ Evaluate mana available
        └─ Execute spell or potion

Data Flow & Integration

HealBot Reports Usage        AttackBot Reports Usage
       │                             │
       └─────────────┬───────────────┘
                     │
                     ▼
            Hunt Analyzer Aggregates
                     │
         ┌───────────┼───────────┐
         ▼           ▼           ▼
    Session     Metrics      Insights
    Duration    (kills,      (trends,
    (elapsed)   damage,      recommendations)
               loot)

⚙️ Architecture

Module Organization

nExBot/
├── 📄 _Loader.lua                    # Main entry point - loads everything
│
├── 📁 core/                          # Core libraries & systems
│   ├── lib.lua                       # Utils: Object Pool, Memoization, Shapes
│   ├── event_bus.lua                 # Centralized event dispatcher
│   ├── bot_database.lua              # Unified item/config database
│   ├── HealBot.lua                   # Healing automation
│   ├── AttackBot.lua                 # Attack automation
│   ├── heal_engine.lua               # Healing algorithm
│   ├── Containers.lua                # Backpack/depot management
│   ├── analyzer.lua                  # Loot tracking
│   ├── smart_hunt.lua                # Hunt analyzer v2.0
│   └── 20+ other modules
│
├── 📁 cavebot/                       # Navigation system
│   ├── cavebot.lua                   # Main loop (250ms interval)
│   ├── walking.lua                   # v3.2.0 walking engine
│   ├── actions.lua                   # Waypoint action handlers
│   ├── editor.lua                    # Waypoint editor UI
│   ├── doors.lua                     # Door handling
│   ├── tools.lua                     # Tool management (rope, shovel, etc)
│   └── 10+ extension modules
│
├── 📁 targetbot/                     # Combat system
│   ├── target.lua                    # Creature targeting & UI
│   ├── core.lua                      # Pure utility functions
│   ├── creature_attack.lua           # Movement & combat logic
│   ├── creature_priority.lua         # Target scoring algorithm
│   ├── monster_behavior.lua          # AI pattern recognition
│   ├── spell_optimizer.lua           # AoE position optimization
│   ├── movement_coordinator.lua      # Intent-based movement voting
│   └── 5+ other modules
│
├── 📁 cavebot_configs/               # User waypoint scripts (.cfg)
├── 📁 targetbot_configs/             # User creature configs (.json)
├── 📁 nExBot_configs/                # User bot profiles
│
├── 📁 docs/                          # Complete documentation
│   ├── README.md                     # Main reference
│   ├── CAVEBOT.md                    # CaveBot guide
│   ├── TARGETBOT.md                  # TargetBot guide
│   ├── HEALBOT.md                    # HealBot guide
│   ├── SMARTHUNT.md                  # Analytics guide
│   ├── PERFORMANCE.md                # Optimization guide
│   └── FAQ.md                        # Troubleshooting
│
└── 📄 README.md                      # This file

Design Patterns

Pattern	Purpose	Example
Object Pool	Reuse tables, reduce GC pressure	Path cache entries
LRU Cache	Bounded memory caches	Creature configs (50 max)
Event-Driven	Efficient updates	Health changes trigger HealBot
Pure Functions	Testability & reliability	TargetCore geometry functions
Intent Voting	Coordinated movement	MovementCoordinator resolves conflicts
Behavior Database	Pattern learning	MonsterAI tracks creature types
Multi-Factor Scoring	Smart decisions	Tile evaluation uses 5+ factors

⚡ Performance

nExBot is heavily optimized for:

CPU Efficiency

🚀 250ms CaveBot interval (vs 500ms for other bots)
🚀 Event-driven HealBot (only runs on health change)
🚀 Cached player data (updates once per second)
🚀 LRU cache eviction (prevents memory bloat)

Memory Management

-- Object pooling reduces garbage collection
local pos = nExBot.acquireTable("position")
pos.x, pos.y, pos.z = 100, 200, 7
-- ... use position ...
nExBot.releaseTable("position", pos)  -- Returns to pool

-- Memoization caches expensive function results
local cachedFn = nExBot.memoize(expensiveFunction, 5000)  -- 5s TTL

Startup Time

Sanitization: 15-50ms (fixes sparse arrays)
Style Loading: 10-30ms (batched imports)
Core Modules: 100-200ms (event system, database)
Total: < 1 second for full startup

Benchmarks

Component	Operation	Speed
HealBot	Health check → spell cast	~75ms
CaveBot	Pathfinding + walking	~150ms
TargetBot	Target evaluation	~50ms
Hunt Analyzer	Metric calculation	~20ms
Monster AI	Behavior prediction	~10ms

Tip

All metrics are on a mid-range PC. Modern systems will be 2-3x faster!

📚 Documentation

Complete guides for each system:

Module	Guide	Topics
CaveBot	CAVEBOT.md	Navigation, walking, waypoints, actions
TargetBot	TARGETBOT.md	Targeting, combat, behavior AI, optimization
HealBot	HEALBOT.md	Healing spells, potions, conditions
AttackBot	ATTACKBOT.md	Spells, runes, attack patterns
Hunt Analyzer	SMARTHUNT.md	Analytics, scoring, insights
Performance	PERFORMANCE.md	Optimization, profiling, best practices
FAQ	FAQ.md	Common questions, troubleshooting

🔧 Configuration

HealBot Configuration

-- Format: formula/item, threshold, priority
HealBot Configuration Example:
├─ Healing Spells:
│  ├─ exura vita at 50% HP (Priority 1)
│  ├─ exura at 30% HP (Priority 2)
│  └─ exura gran at 80% HP (Priority 0 - highest)
│
└─ Healing Potions:
   ├─ Great Health Potion at 40% HP
   └─ Health Potion at 20% HP

TargetBot Configuration

Creature Format: MONSTER_NAME or ALL or MONSTER_#ID-#ID
Patterns:       *, !exclusion, #100-#150, Dragon King
Priority:       Health, Distance, Danger

CaveBot Waypoints

Action Types:
├─ goto X,Y,Z           (walk to position)
├─ label LABEL          (mark location)
├─ action SCRIPT        (execute custom code)
├─ buy ITEM,COUNT,NPC   (trade with NPC)
├─ lure MONSTER,COUNT   (pull creatures)
├─ rope/shovel          (use tool)
├─ travel WAYPOINT      (teleport)
└─ 15+ more actions

🎓 Advanced Topics

Custom Scripts in CaveBot

-- Example: Hunt only during green stamina
action() function()
  if Player.staminaInfo().greenRemaining > 0 then
    CaveBot.setOn()
  else
    CaveBot.setOff()
  end
end

Monster Behavior Profiles

-- MonsterAI learns and remembers patterns:
Monster Type    Behavior        Confidence
Dragon          Chase           0.95
Vampire         Static          0.87
Demon           Kite            0.76

Spell Optimizer Usage

-- Finds best position for AoE spells:
local recommendation = SpellOptimizer.recommend(
  configuredSpells,
  nearbyMonsters
)

if recommendation.needsMovement then
  Walk(recommendation.optimalTile)
end

🆘 Troubleshooting

Warning

Bot not loading?

Check file path: %APPDATA%/OTClientV8/<config>/bot/nExBot
Verify _Loader.lua exists
Check OTClientV8 version (must be v8+)
Enable bot debugging: Press Ctrl+Shift+D

Tip

Healing not working?

HealBot shows red when disabled
Check formulas are spelled correctly (exura not exra)
Add potions as fallback
Test manually first

Tip

CaveBot stops moving?

Check if floor-change detection triggered
Verify waypoint coordinates are reachable
Use precision parameter for area waypoints: 1000,1000,7,3
Check fields config: ignoreFields toggle