mod-ale/docs/USAGE.md

📖 ALE Usage Guide

Learn how to create powerful Lua scripts for your AzerothCore server

---

Important

This guide is for ALE (AzerothCore Lua Engine), which is specifically designed for AzerothCore. Scripts and APIs may differ from other Lua engines.

📋 Table of Contents

• Prerequisites
• Your First Script
• Lua Basics
• ALE Basics
• Script Reloading
• Getting Help

✅ Prerequisites

This guide assumes you have already installed ALE successfully. If you have not, see the Installation Guide or the Installation section in the README.

🚀 Your First Script

Let's create a simple "Hello World" script to get you started.

Creating the Script File

Create a file named hello_world.lua in your scripts folder. By default, this folder is called lua_scripts and is located in your server folder (the folder containing server executables).

local PLAYER_EVENT_ON_LOGIN = 3

local function OnLogin(event, player)
    player:SendBroadcastMessage("Hello world from ALE!")
end

RegisterPlayerEvent(PLAYER_EVENT_ON_LOGIN, OnLogin)

Running the Script

1. Restart your AzerothCore server
2. Log in to the game
3. You should see "Hello world from ALE!" in your chat

What Just Happened?

No core compiling was needed! Your script runs directly from the file you created.

Here's what the script does:

• The file is compiled and run by the Lua engine when the server starts
• The code registers a function to be executed when a player logs in
• When the event triggers, the function sends a message to the player

📚 Lua Basics

Before diving deep into ALE scripting, it's helpful to understand some Lua fundamentals.

Learning Resources

• Lua Users Wiki
  • Lua Directory
  • Tutorial Directory
  • Sample Code
• Programming in Lua - Comprehensive guide
• Lua 5.2 Reference Manual - Official documentation

Essential Concepts

Debugging with Print

The print() function outputs to the server console - perfect for debugging:

print("Debug message here")
print("Player name:", player:GetName())

Control Structures

Learn about loops and conditionals:

• Control Structure Tutorial
• Lua Manual - Control Structures

String Manipulation

Essential for text processing:

• String Library Tutorial
• Pattern Matching

Tables

Tables are Lua's only data structure (arrays and hash maps combined):

• Table Functions
• Table Semantics
• Tables Tutorial
• Programming in Lua - Tables

Variable Scope

Important: Prefer local variables over global variables!

-- Good: Local variable
local playerName = "John"

-- Avoid: Global variable
playerName = "John"

Global variables can create conflicts with other scripts. Local variables outside functions are shared within the same script file (locally global).

⚡ ALE Basics

Documentation Resources

• ALE API Documentation - Complete API reference
• Hooks Documentation - Available event hooks
• Implementation Details - Advanced features and best practices

Error Messages

ALE outputs errors to:

• Server console (real-time)
• Log file in the server folder (persistent)

If your script doesn't work, check the log file for errors. You can configure logging settings in the server configuration file.

Global Functions

Global functions can be called from anywhere without requiring an object.

Besides standard Lua functions like print(), ALE provides its own global functions. Find them in the documentation under the Global class: Global Functions.

-- Example: Get the Lua engine name
print(GetLuaEngine())

-- Example: Get current game time
local time = GetGameTime()

Member Functions (Methods)

Methods require a userdata object to run. Different object types (Player, Creature, GameObject, etc.) have different available methods.

Class Inheritance

Classes inherit from each other. For example:

• Player and Creature both inherit from Unit
• This means both players and creatures can use Unit methods

Calling Methods

Use the : notation to call methods on objects:

-- Get player name
local name = player:GetName()

-- Get creature level
local level = creature:GetLevel()

Example: Creature Combat Script

local entry = 6  -- Creature entry ID
local on_combat = 1  -- Event ID for combat start

local function OnCombat(event, creature, target)
    -- creature is of type Creature
    -- target is of type Creature or Player

    print("Creature level:", creature:GetLevel())
    print("Target level:", target:GetLevel())

    creature:SendUnitYell("You dare challenge me?!", 0)
end

RegisterCreatureEvent(entry, on_combat, OnCombat)

Registering Event Handlers

Scripts work by registering functions to events. When the event occurs, your function executes.

Finding Register Functions

Search for "register" in the ALE documentation to find all available register functions:

• RegisterPlayerEvent
• RegisterCreatureEvent
• RegisterServerEvent
• And many more...

Event IDs

Each register function requires an event ID. Find these IDs in the function's documentation page.

Function Parameters

ALE automatically passes parameters to your registered functions. The parameters are always in the same order, but you can name them anything you want.

Example: PLAYER_EVENT_ON_LOGIN passes:

1. Event ID (number)
2. Player object (Player)

local function OnLogin(event, player)
    -- event = event ID number
    -- player = Player object
end

Return Values

Some events allow your function to return values to modify behavior. Check the event's documentation to see what can be returned.

local function OnChat(event, player, msg, type, lang)
    if msg == "blocked" then
        return false  -- Blocks the chat message
    end
end

🔄 Script Reloading

For quick testing during development, you can reload scripts without restarting:

.reload ale

Warning

Development Only: Use .reload ale only for development. For production or if experiencing issues, always restart the server.

Important Limitations:

• Reloading doesn't trigger events like login for already-connected players
• Some state may not reset properly
• Always do final testing with a full server restart

💬 Getting Help

Support Channels

• GitHub Issues: Report bugs or request features
• Discord Community: Join our Discord server
• AzerothCore Discord: Official AzerothCore support

Additional Resources

• Lua Programming Guide
• AzerothCore Documentation
• Implementation Details - Advanced ALE features

---

🌟 Acknowledgements

ALE is built upon the foundation of the Eluna Lua Engine. We acknowledge and thank the Eluna team for their pioneering work in Lua scripting for World of Warcraft server emulators.

• Original Eluna Repository
• Eluna Discord Community

---

_{Developed with ❤️ by the AzerothCore and ALE community}

⬆ Back to Top