Home

NecroLua

Welcome to the NecroLua wiki! This is a work-in-progress, so everything here is subject to change and information might be missing or outdated. If you have any question, it's best to open an issue.

API reference

IMPORTANT Any method here documented is subject to change.

necrolua.enumsymbols and necrolua.enumtypes

Enumerate all symbols/types that match a pattern.

necrolua.enumsymbols(mask, cb)
necrolua.enumtypes(mask, cb)

Arguments

• mask A string that is matched against the name. Can contain the * and ? wildcards. Matching is case sensitive.
• cb A Lua function that receives symbol information.

Remarks

The callback function receives two arguments:

• A SYMBOL_INFO structure. It has the additional "magic" property NameLuaStr that has a Lua string.
• The symbol/type size (may be 0). The callback function can return false to halt the enumeration. You can retrieve the full type definition of symbol with typedef:

print( necrolua.typedef(Info.Index, Info.NameLuaStr) )

Example

-- List all symbols related to the Player class.
necrolua.enumsymbols("c_Player::*", function(symbol_info)
  print(symbol_info.NameLuaStr)
  return true
end)

-- List all types that contain "Stair".
necrolua.enumtypes("*Stair*", function(symbol_info)
  print(symbol_info.NameLuaStr)
  return true
end)

(The return true at the end of these callbacks is necessary at the moment; see #3)

necrolua.hook

necrolua.hook(symbol, handler)

Arguments

• symbol The fully qualified name of a function symbol.
• handler A Lua function that serves as the hook handler. Must return a compatible value.

Remarks

The handler function receives the original function, followed by all arguments it received. The handler can then handle the call in any way it chooses, and may or may not call the original function. The same symbol can be hooked multiple times. The handler will receive the next function in the chain.

Examples

-- Invert the "electrified" state.
necrolua.hook("c_Player::p_GetElectricStrength", function(func, self)
  return 1 - func(self)
end)

-- Turn all items to glass instead of using bombs.
necrolua.hook("c_Player::p_UseBomb", function(func, self)
  self:p_TurnAllItemsToGlass()
  return false -- return func(self) -- to preserve original behaviour
end)

Internals

NecroLua uses three main components:

• LuaJIT – An interpreter / JIT for the Lua programming language.
• Detours – Allows runtime patching of functions (eg, for instrumenting purposes).
• Dbghelp – A library to read PDB symbol files.

Launching process

The launcher (NecroLua.exe) uses DetourCreateProcessWithDlls to launch NecroDancer.exe with a custom DLL (NecroLuaAPI.dll) injected. When the DLL is loaded in the NecroDancer process, it does a bit of initialization, attaches itself to its parents console (for debugging purposes), opens a Lua VM and runs some pre-compiled Lua bytecode. This code leverages the powerful LuaJIT FFI so we're able to interact with the game's code from within Lua.