Developer Guide (Version 1.11)

Working with Lua Scripting

CryLua is deprecated and will be removed in a future version of Lumberyard.

Lumberyard uses Lua for its scripting language.

The Entity system can attach a script proxy to any entity, which is in the form of a table that can include data and functions. AI behaviors are often written in scripts. Additionally, several game systems, including Actor, Item, Vehicle, and GameRules, rely on scripting to extend their functionality.

The advantages of using scripts include:

  • Fast iteration – Scripts can be reloaded within the engine.

  • Runtime performance – Careful usage of available resources can result into scripts that run nearly as fast as compiled code.

  • Easy troubleshooting – An embedded Lua debugger can be invoked at any time.

Most of the systems in Lumberyard expose ScriptBind functions, which allow Lua scripts to call existing code written in C++. See the Lua ScriptBind Referencefor more details.

Running Scripts

You can run scripts either by calling script files directly from code or by using console commands.

In code

Scripts are stored in the \Game\Scripts directory. To invoke a script file, call the LoadScript function from your C++ code. For more information, see Integrating Lua and C++. Another option is to create a script entity, as described in Entity Scripting.

In the Console

Script instructions can be executed using the in-game console. This can be done by appending the # character before the instructions. This functionality is limited to Lumberyard Editor or when running the launcher in dev mode (using the -DEVMODE command-line argument).

Reloading Scripts During Runtime

In Lumberyard Editor it is always possible to reload entities within the user interface. When reloading a script entity, choose the Reload Script button, which is found in the Rollup Bar.

You can also use the following ScriptBind functions to reload scripts.

  • Script.ReloadScript(filename)

  • Script.ReloadScripts()

To invoke these functions from the console, use the following syntax:


The following resources on the Lua language are recommended reading when working with scripts with Lumberyard.