ESO API → LuaLS Generator

If you use Visual Studio Code to develop ESO addons and have the Lua Language Server and Error Lens extensions installed, you have likely encountered situations where valid ESO API globals appear as undefined.

These values exist at runtime because the ESO client injects them into Lua's global environment. However, Visual Studio Code only analyzes the files in your workspace. Without separate API definitions, LuaLS has no way to know that ESO provides these globals, functions, constants, objects, and UI controls.

The result is a large number of false warnings such as:

Undefined field `GetCurrentMapIndex`
Undefined field `GetNumPOIs`
Undefined field `MAP_PIN_TYPE_POI_COMPLETE`

What this tool does

1. So many undefined ESO API globals and functions!

2. Run the batch script to create LuaLS definition files

3. Copy the generated-eso-api folder into your project directory, then add generated-eso-api/ to your .gitignore file so the generated files are not committed to Git. You can also look at .vscode/settings.json example to see how to incorporate it into your settings.

4. ESO API globals and functions no longer flagged as undefined 🙂👍

Please note, this is not perfect. There may be some that slip through, but is is designed to catch most.

How this tool works

This tool processes locally downloaded UESP ESO API exports and generates editor-only LuaLS definition files.

It creates definitions for:

• ESO global values
• global functions
• local function definitions found in the UI source
• normalized inventories of discovered names and signatures

The generated files are then added to Lua Language Server's workspace library. Once LuaLS can see those definitions, many of the false undefined warnings disappear.

How it helps

Using the generated definitions gives you:

• cleaner Error Lens output
• fewer false-positive diagnostics
• better autocomplete
• improved hover information
• easier code navigation
• safer refactoring
• better context for AI coding assistants
• a clearer distinction between real addon errors and missing editor knowledge

Instead of the editor treating _G.GetPOIInfo as unknown, it can recognize that GetPOIInfo is part of the ESO runtime API.

Important distinction

The generated files are only for your editor.

They do not replace the ESO client, and they should not be included in the addon manifest. ESO still provides the real functions and objects when the addon runs in the game.

The tool teaches Visual Studio Code about the environment that ESO creates at runtime.

Why local UESP files are used

Some UESP API exports are extremely large—the global-object page alone may exceed 170 MB.

Processing downloaded local files provides several advantages:

• avoids repeatedly downloading large files
• keeps the generator independent of website availability
• reduces network load
• allows incremental streaming with modest memory usage
• makes generation faster and reproducible
• lets source files be archived by ESO API version

The generator reads the files incrementally and displays progress, build stages, deduplication statistics, and the size of the generated LuaLS output.

Updating for a newer ESO API version

1. Download the latest UESP text exports.
2. Replace the files inside eso-api-download.
3. Run run_generator.bat again.
4. Reload the VS Code window.

The generated output will be rebuilt from the new local source files.

Use

This utility converts locally downloaded UESP ESO API text exports into editor-only LuaLS definition files for Elder Scrolls Online addon development.

It does not contact or scrape the UESP website. Download the source files first, then run the generator locally.

Features

• Processes very large UESP text exports incrementally
• Shows real byte-based progress bars
• Displays clear build stages and elapsed time
• Generates LuaLS global declarations and function stubs
• Combines global and local function definitions
• Removes duplicate function signatures
• Writes inventory files for inspection
• Reports detailed build statistics
• Uses only the Python standard library
• Includes an optional batch launcher for Windows

Example progress display:

[███████████░░░░░░░░░░░░░░░] 46.0%

Required files and folders

Place the following files together:

ESO_Definition_LuaLS/
├─ eso_api_luals.py
├─ generate_all.py
├─ run_generator.bat
└─ eso-api-download/
   ├─ functioncalls.txt
   ├─ globalfuncs.txt
   ├─ globals.txt
   └─ localfuncs.txt

The four UESP exports are processed as follows:

functioncalls.txt → inventory only
globalfuncs.txt   → function definitions
globals.txt       → global declarations
localfuncs.txt    → function definitions

globalfuncs.txt and localfuncs.txt are combined and deduplicated before the final eso-functions.lua file is written.

Running the generator

Recommended: Windows batch launcher

Double-click (Or run it from Command Prompt):

run_generator.bat

The batch file only launches the Python build script.

Run Python directly

python .\generate_all.py

Build stages

The generator displays seven build stages:

1. Validate Environment
2. Load Generator Core
3. Prepare Output
4. Parse UESP Exports
5. Combine and Deduplicate
6. Generate LuaLS Definitions
7. Build Summary

Each large source file is processed with a live progress bar based on the number of bytes read.

Output

The generated files are written to:

generated-eso-api/
├─ inventory/
│  ├─ functioncalls.txt
│  ├─ globalfuncs.txt
│  ├─ globals.txt
│  └─ localfuncs.txt
└─ luals/
   ├─ eso-globals.lua
   └─ eso-functions.lua

Inventory files

The inventory files contain normalized names and function signatures extracted from each UESP source file. They are useful for inspection, validation, and future generator improvements.

LuaLS files

• eso-globals.lua contains editor-only global declarations.
• eso-functions.lua contains combined and deduplicated basic function stubs.

These files are for Lua Language Server only.

$\color{Orange}\large{\textbf{Do not add generated LuaLS files to an ESO addon manifest.}}$

VS Code / LuaLS setup

Add the generated LuaLS folder to your workspace settings and generated-eso-api/ to your .gitignore.

Create or update:

.vscode/settings.json

{
    "Lua.runtime.version": "Lua 5.1",
    "Lua.workspace.library": [
        "${workspaceFolder}/generated-eso-api/luals"
    ],
    "Lua.workspace.checkThirdParty": false
}

Then reload VS Code:

Ctrl+Shift+P
Developer: Reload Window

LuaLS should then recognize generated ESO globals and functions in the workspace.

Build statistics

At the end of each run, the generator reports information such as:

Input files processed
Input data processed
Names parsed
Signatures parsed
Unique global names
Unique function signatures
Function duplicates removed
Lua globals generated
Function stubs generated
Inventory files written
Elapsed time

Important limitations

UESP exports are generated reports, not native LuaLS type-definition files.

The current generator intentionally avoids guessing:

• parameter types
• return types
• object inheritance
• userdata control types
• table field structures
• missing owner tables
• event argument signatures
• XML control relationships

The generated stubs are conservative by design. They improve global recognition, basic autocomplete, navigation, and AI code context without pretending to know types that are not available in the source data.

Future versions can add richer definitions for:

• ESO events
• enumerations and constants
• UI controls
• object methods
• XML controls
• documented parameter and return types
• inheritance relationships
• API-version comparisons

Python requirements

• Python 3.10 or newer is recommended
• No third-party packages are required

Verify Python is available:

python --version