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
Tip
Container Panel v6 (Event-Driven Rewrite) — The container auto-opener was fully rewritten to an event-driven approach (ContainerOpener v6) using the OTClient API and EventBus. Major improvements include:
Other notable fixes:
-
Fixed
g_clocknil error in core modules -
Friend Healer UI: add/remove spells support
-
Walking smoothing parameters fine-tuned to reduce jitter and improve pathing
-
Uses direct item references and unique slot keys (parentId_slot) to reliably open nested and sibling backpacks
-
Reactive queuing via
onAddItemandonContainerOpenfor near-instant detection and processing -
Eliminated duplicate legacy code and fixed critical queue entry bug (missing
itemfield) -
Proper quiver support for paladins (auto-open quiver from right-hand slot on login/reopen)
[!WARNING]
If you previously had custom scripts relying on the old container internals, please review the Developer Notes in docs/CONTAINERS.md — the public API remains similar but the internals, event timing and emitted events are more reliable now.
[!TIP] See full changelog: ./CHANGELOG.md
- What is nExBot?
- Quick Start
- Core Features
- How It Works
- Architecture
- Configuration
- Performance
- Advanced Topics
- Troubleshooting
- Contributing
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.
-
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+Bto 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
Warning
Set up HealBot FIRST. Your survival depends on it!
- Open the Main tab
- Click Healing button
- Add your healing spells:
- Formula:
exura vitaat 50% HP - Formula:
exuraat 30% HP
- Formula:
- Add healing potions:
- Item: Great Health Potion at 40% HP
- Enable HealBot switch
- Test by taking damage
- 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
- Open Target tab
- Click the + button to add monsters
- Set spell and rune attacks
- Enable TargetBot switch
- Load your CaveBot config
- Enable CaveBot and TargetBot
- Click Start (Ctrl+Z)
- Watch your hunting data in Hunt Analyzer (Main tab)
┌─────────────────────────────────────────────────────────────┐
│ 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)
┌──────────────────────────────────────────────────────────────┐
│ 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
┌───────────────────────────────────────────────────────────┐
│ 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
┌────────────────────────────────────────────────────────┐
│ 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 │
│ │
└────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────┐
│ 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
┌─────────────────────────────────────────────────────────┐
│ 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 │
│ │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ 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) │
│ │
└─────────────────────────────────────────────────────────────────┘
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
HealBot Reports Usage AttackBot Reports Usage
│ │
└─────────────┬───────────────┘
│
▼
Hunt Analyzer Aggregates
│
┌───────────┼───────────┐
▼ ▼ ▼
Session Metrics Insights
Duration (kills, (trends,
(elapsed) damage, recommendations)
loot)
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
| 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 |
nExBot is heavily optimized for:
- 🚀 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)
-- 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- 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
| 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!
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 |
-- 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% HPCreature Format: MONSTER_NAME or ALL or MONSTER_#ID-#ID
Patterns: *, !exclusion, #100-#150, Dragon King
Priority: Health, Distance, DangerAction 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
-- Example: Hunt only during green stamina
action() function()
if Player.staminaInfo().greenRemaining > 0 then
CaveBot.setOn()
else
CaveBot.setOff()
end
end-- MonsterAI learns and remembers patterns:
Monster Type Behavior Confidence
Dragon Chase 0.95
Vampire Static 0.87
Demon Kite 0.76-- Finds best position for AoE spells:
local recommendation = SpellOptimizer.recommend(
configuredSpells,
nearbyMonsters
)
if recommendation.needsMovement then
Walk(recommendation.optimalTile)
endWarning
Bot not loading?
- Check file path:
%APPDATA%/OTClientV8/<config>/bot/nExBot - Verify
_Loader.luaexists - 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 (
exuranotexra) - 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:
ignoreFieldstoggle
Note
Performance issues?
- Reduce TargetBot creature count
- Lower CaveBot interval (not below 100ms)
- Disable Hunt Analyzer if not needed
- Clear old configs (takes memory)
[!TIP]
Container/Panel errors (e.g. attempt to call global 'isExcludedContainer' (a nil value) or minimizeContainer nil errors):
- Ensure you have the updated
core/Containers.lua(v6). Partial or out-of-order edits may cause missing helpers. Replace and restart the client to load the full module. - Check logs for
containers:open_all_completeor missingcontainer:openevents.
See FAQ.md for more solutions.
We welcome contributions! Please follow these guidelines:
- DRY - Don't Repeat Yourself
- KISS - Keep It Simple & Stupid
- SRP - Single Responsibility Principle
- SOLID - Object-oriented design principles
- Test on multiple servers/servers
- Check edge cases (low mana, trapped, etc)
- Profile performance (use
nExBot.loadTimes) - Document changes clearly
- Fork and create feature branch
- Write clear commit messages
- Test thoroughly
- Update relevant docs
- Submit PR with description
MIT License - See LICENSE file
Copyright © 2025 nExBot Contributors
- Architecture: Advanced event-driven design with unified decision systems
- Performance: Optimized for minimal CPU/memory impact
- Reliability: Battle-tested across multiple servers with edge-case handling
- Community: Built with feedback from thousands of botters
- 📖 Documentation: Read docs/ folder
- ❓ FAQ: Check docs/FAQ.md
- 🐛 Bug Report: Document the issue clearly and include logs (
client logs,lua stack) and steps to reproduce; attach yourcore/Containers.luaversion if reporting container-related issues - 💡 Feature Request: Describe use case and implementation ideas
Tip
For OSS contributions: open a small, focused PR and include tests or manual QA steps where possible.
Made with ❤️ for the Tibia Community
nExBot - High-Performance, Intelligent, Reliable ⚡🤖