loader
Introduction to Lua using Cheat Engine: Beginner to Basic Script Writer!

Introduction to Lua using Cheat Engine: Beginner to Basic Script Writer! May 25, 2017

So you want to get started learning Lua and creating scripts, huh? Well you’ve come to the right place, so LET’S DO IT! =)

To note, this article will soon take the form of a video, so if that’s your preferred medium, then just know that’s coming soon and I’ll populate this article with it once it’s done.

I’ll spare you the details about what Lua is and how to generically learn the language in 0.013 seconds, and instead we’ll learn by doing. In Cheat Engine (aka CE). Which is an incredibly powerful tool–not only for purposes of hacking games and reversing software, but also for learning everything from Assembly, to reverse engineering concepts, to Lua, and much more.

If you don’t have Cheat Engine, go install it now (I won’t be blamed if you install bundled offers, so READ THE INSTALLATION PROMPTS CAREFULLY) so you can follow along. You can run all of the code examples I provide directly in Cheat Engine, but don’t just copy them over because CE won’t recognize some of the copied characters! If you do copy/paste, look for the characters you have to fill in.

Hello, World

You knew it was coming, but we have to do it! Let’s make CE’s Lua Engine output “Hello, World”. First, open Cheat Engine. Then, click on Table, then Show Cheat Table Lua Script. You should now see this window:

Introduction to Lua in Cheat Engine: Lua Script Cheat Table

Now, enter the following:

print("Hello, World")

Then click the Execute script button. You should now see the Lua Engine window open with “Hello, World” in the output section, like so:

Introduction to Lua in Cheat Engine: Lua Engine Hello, World

Success! You just ran one of Lua’s native functions, print(). If you want exact text to be printed, use quotes (double ” or single ‘ quotes work). You can also print numbers and all kinds of other stuff like the results of calculations (e.g. print(1 + 2)) and so on. Try playing around with print() to see what else you can you can do! Can you figure out what this does? (Don’t worry if not; I’ll fully explain it in a little bit.)

print(string.upper(string.format("%x", 1 + 0xA)))

As an aside, for those of you who want to dive in a bit deeper right off the bat, click here to check out other native Lua functions.

For those of you who are beginners, functions are just blocks of code that do something for you. Sometimes, a function will just perform a task where you don’t expect anything as a result. Other times, a function needs some data with which to perform its task(s). The print() function takes arguments you provide, then does its magic. If you just ran print(), it wouldn’t do anything because print() is like, “I mean…you didn’t tell me WHAT to print, so I can’t do anything, dawgs.”

More on that in a bit, but let’s shift gears and talk about variables.

Variables

Put simply, variables are just things you store values in (numbers, characters, words, functions, other variables, etc., etc.). First, you think of a name for your variable, then you typically assign it a value. There are rules for how you can name your variables, so you might want to check them out to prevent making a naming error that might confuse you later.

Using our “Hello, World” example from above, let’s modify it slightly to print the same result to the screen, except from a variable instead of directly:

theNameOfYourVariable = "Hello, World"
print(theNameOfYourVariable)

Notice that I didn’t put quotes around the variable name I passed through print(). If I did, then you would have seen that exact variable name printed to the screen as a string of text. Try it for yourself and see:

theNameOfYourVariable = "Hello, World"
print("theNameOfYourVariable")

Now, if you were to really want this as part of a program or script, you’d probably want to make your variable name more reflective of what it’s storing. Take these examples for instance. Can you figure out what each of them do?

Example 1: String

helloWorld = "Hello, World"
print(helloWorld)

Example 2: Math

addTwoNumbers = 2 + 2
print(addTwoNumbers)

Example 3: More Math and More Variable Names

numberOne = 1000
numberTwo = 1674
numberThree = 2
threeNumberMath = (numberOne + numberTwo) / numberThree
print(threeNumberMath)

(Can you figure out how to remove that trailing .0?)

Example 4: Tables

table_iLoveCheatEngine = {"I", "love", "Cheat", "Engine", "!"}
print(table_iLoveCheatEngine[1] .. " " .. table_iLoveCheatEngine[2] .. " " ..
table_iLoveCheatEngine[3] .. " " .. table_iLoveCheatEngine[4] ..
table_iLoveCheatEngine[5])

(Don’t worry if you don’t know what tables are; however, if you want to look into them, here you go!)

Example 5: Functions

func_iLoveCheatEngine =
function (a, b, c, d, e)
concatStuffs = a .. " " .. b .. " " .. c .. " " .. d .. e
return concatStuffs
end
print(func_iLoveCheatEngine("I", "love", "Cheat", "Engine", "!"))

(We’re diving into functions next, so come back to this example after that and see if you can figure out what’s going on.)

Example 6: Nil

local emptyVariable
print(emptyVariable)

(Not assigning a value to a variable means that its value will be “nil”, basically meaning there’s nothing in it. Prefixing a variable name with “local” has to do with something called “scope.” Don’t worry about it for the time being, but just be aware that you’ll likely see it used. For those who DO want to worry about it now, here you go.)

The point of those examples is to show that you can store just about anything you want in variables. You might decide to make significantly shorter variable names, or find more elegant ways to write a function, etc., etc., etc. In Lua, there are many ways to achieve the same thing, so just have fun!

Functions

Up to this point, we’ve used a function (print()) and we’ve written our own function (example 5 above). For this section, we’re only going to focus on using functions, so if you want to delve deeper into creating your own functions, take a look at this tutorial.

Again, functions are just blocks of code that do something. Just like Lua has a bunch of its own functions (like print()), so does Cheat Engine! You can find most of them here on the CE wiki; however, it isn’t updated as frequently as CE’s development pace, so you can check out celua.txt on the official CE Github repository for ALL the goodies (like executeCode()).

Remember a little bit ago when I asked if you could figure out what this does?

print(string.upper(string.format("%x", 1 + 0xA)))

There’s a lot going on there, so let me break it down another way.

numOne = 1
numTwo = 0xA
toHex = string.format("%x", numOne + numTwo)
toUpperCase = string.upper(toHex)
print(toUpperCase)

There, I’ve assigned 4 variables:

numOne contains the number 1.

numTwo contains the hexadecimal number A (the 0x prefix lets Lua know that you intend for that number to be treated as a hexadecimal number).

toHex makes use of another Lua function called string.format() through which we’re passing two arguments: "%x", which tells Lua to treat your other arguments as hexadecimal values (you can read about other formats here), and the variables numOne + numTwo.

toUpperCase is using yet another Lua function called string.upper(), which converts lower-case characters to upper-case. For our use, we’re passing it the variable toHex, which is taking the result of our string.format() statement and upper-casing the result if it’s A-F. This is just a matter of personal preference; I hate seeing hexadecimal values represented in lower-case. 😉

Finally, we take all of that and print the result to the screen. Now, remember when I said there are multiple ways to do things in Lua? Those are two different representations of making the same thing happen. But there’s a shorthand way to get the same results still by making one little change to toHex and removing the toUpperCase variable and its assignment altogether! See if you can spot the difference:

print(string.format("%X", 1 + 0xA))

Or:

numOne = 1
numTwo = 0xA
toHex = string.format("%X", numOne + numTwo)
print(toHex)

There’s no right way here, but there are more readable and sometimes performant ways. It’s just whatever you choose to do. Sometimes, less code means less time spent writing that code, but more time trying to go back two months later and figure out what exactly that code does. Other times, a little more time spent writing or refactoring your code can spare you a headache later. That, or just add a comment about what your code is doing. Here’s how you make comments in Lua, which are essentially lines that are ignored by Lua, but that you can read (copying/pasting single-line comments from here into Cheat Engine won’t work, so I’ll only be using the multi-line format for code examples from here, forward):

‐‐This is a one-line comment. Write whatever you want on this line!
‐‐You can do this for as many lines as you like; however, there’s the next option.

‐‐[[
This is a multi-line comment, so we can do this all day and
it’s just one comment. This keeps us from having to keep adding
the ‐‐ to the beginning of every line we want to specify as a
comment. w00t!
]]

We’ve learned a lot here so far!

A. How to print a string. For those of you who are new to this concept, the reason it’s called a string is because it’s a string, or a strand, of individual characters grouped together. Imagine you’re making a necklace for your mother that’s going to have her name on it. The necklace is like a string that you’ll slide individual letters onto. So a string is just a collection of characters. There’s more to it all, but that’s the basic gist.

B. How to create variables and assign values to them.

C. How to do math with Lua, how to specify a value’s format, and how to print that result.

D. How to write comments.

E. How to use functions: print(), string.upper(), and string.format().

F. How to write in camelCase!

This is great, because it means we can now start using Lua functions that are native to Cheat Engine–functions like readByte(), writeInteger(), playSound(), pause(), unpause(), and tons more. So with that said, let’s dive into Cheat Engine and roll through an example of how you could use what you now know about Lua to create a script!

Creating a Lua Script in CE

Everyone should be able to follow along from here regardless of their exposure to CE, but if you have no idea how to use Cheat Engine in even the most basic of ways (like how to scan for values), then you might want check out my Cheat Engine Tutorial Series on YouTube!

First, let’s consider a scenario in game where we have a player that has health. The player’s maximum health value is 100. Let’s say that player isn’t at full health, so their current health is at 43. It’s not uncommon that these two values are stored in two memory addresses close in distance.

So, one memory address would have the player’s maximum health value, and another address would have their current health value. Then, you have instructions that look at the values in both addresses so that it knows what to do in various situations. For instance, say you pick up a health vial that gives you 20 points of health. Well, if you’re at 99 of 100, then the game will know not to take your health up to 119. It knows this by saying something like, “Well, I see the player has 99 health in that memory address, and I see the max health that player should be capable of having is 100 in that other memory address, so I’ll only give the player 1 point of health from that vial.”

With that in mind, a very common cheat to create is to find those two memory addresses, then the instruction that updates the player’s health when they lose health, and finally make it to where instead of taking away health, you make the player’s current health equal maximum health. We’re not going to worry about finding that instruction for the time being, though. That’ll be in a future tutorial.

What we want to do now is create a Lua script that will make the player’s current health equal their max health value. Let’s loosely visualize this by creating those variables, assigning values, and simulating the cheat (this is all part of something called “pseudocode,” which is noting small bits of what you want your code to do, then writing actual code to realize those bits).

‐‐[[Get current health and maximum health values]]
maxHealth = 100
currentHealth = 43

‐‐[[Print the value of current health so we can see it before it’s changed]]
print(currentHealth)

‐‐[[Make current health equal maximum health]]
currentHealth = maxHealth

‐‐[[Print current health with its new value so we can verify]]
print(currentHealth)

If you run that in CE, your results should look as follows (I used single-comment lines initially, as you’ll note):

Introduction to Lua in Cheat Engine: Lua Engine Hello, World

Let’s now apply this to a game! I’ll use Terraria as an example. If you’re following along, go ahead and open Terraria’s process with CE.

First, let’s find current player health. I’m starting with current health being full, then scanning for exact value changes after taking damage. Here’s the result:

Introduction to Lua in Cheat Engine: Terraria Script 1

Then, view that memory region to see if something resembling other values like max health are anywhere nearby (using the data/structure dissector is another option, but I’ll cover that in another tutorial). To do that, right-click on the value you found, then click Browse this memory region. Once that window pops up, right-click on any of the bytes in the bottom pane of the memory viewer (the top pane is the disassembler), hover over Display Type, then click 4 Byte decimal. Now scroll up a tiny bit to see values above and below the current health value.

Introduction to Lua in Cheat Engine: Terraria Script 2

Because I’m familiar with the game, I know certain numbers I’m looking for. As you can see, the max health value I’m interested in is in very close proximity to my current health value.

Now let’s make note of the memory addresses those values are in. You can right-click on any value there in the memory viewer and select Add this address to the list. It’s also sometimes worth bearing in mind the distance (aka the offset) between the current health and max health addresses. In the right scenario, it’s a great way to reference one memory address from another that you find.

Introduction to Lua in Cheat Engine: Terraria Script 3

We now have what we need to create our script! We’ll be using a couple of CE’s Lua functions as well. Let’s start by looking at the value type of our values.

Introduction to Lua in Cheat Engine: Terraria Script 4

As you can see, they’re 4 bytes, so we can use CE’s functions that are related to integers. (Technically speaking, a float is a 4-byte value as well, but that’s part of a lesson for another day.) Click here to see some of CE’s memory-related functions. We’re going to use readInteger() and writeInteger(). I’m going to use comments in the script below to explain what’s going on throughout it.

‐‐[[
Store the memory address for max health
]]
maxHealthAddress = 0x20B496E8

‐‐[[
Store the memory address for current health, which is 0x4 bytes
away from the max health address. That means we can specify
current health as being maxHealthAddress – 0x4 (resulting in
0x004587C0 being the value in currentHealthAddress)
Note: 0x4 is the same as saying 0x00000004 in this case
]]
currentHealthAddress = maxHealthAddress + 0x4

‐‐[[
Store the value found inside the max health memory address
]]
maxHealthValue = readInteger(maxHealthAddress)

‐‐[[
Store the value found inside the current health memory address
]]
currentHealthValue = readInteger(currentHealthAddress)

‐‐[[
Print both values
]]
print(“Max health is: ” .. maxHealthValue)
print(“Current health is: ” .. currentHealthValue)

‐‐[[
Write the value from the max health memory address
to the current health memory address
]]
writeInteger(currentHealthAddress, maxHealthValue)

‐‐[[
Refresh the value of health stored in the currentHealthValue variable
]]
currentHealthValue = readInteger(currentHealthAddress)

‐‐[[
Print the new value residing in the current health memory address
]]
print(“Current health is now ” .. currentHealthValue)

After running that script, voila! The player’s current health is now the same value as max health, and the Lua Engine output reflects our change (click/tap the image for full size).

Introduction to Lua in Cheat Engine: Terraria Script 4a

Now, unfortunately, this isn’t really a reusable script due to the fact that the memory addresses will change after the game is restarted (and if you followed along, your memory addresses were most likely different from mine). That’s something I’ll focus on in another tutorial, but for the time being, this script touches on most of the points I wanted to touch on.

You now know just enough to be somewhat dangerous. Go looking through other CE Lua scripts out there, and don’t freak out if you don’t know something you see! It takes time.

Also of note, you may run across people saying that, comparatively, a Lua script is slower than an Assembly script; however, don’t worry about that. Technically, it’s true, but most of you will never, ever, ever get to a point where you need to worry about eeking out performance on that level. So play around, have fun, and get your learn on! =)

Stephen Chapman

Twitter // Email // YouTube // GitHub

Hi! I'm Stephen. I'm a developer, reverse engineer, and former investigative journalist. DSASMBLR is my outlet for each of those facets--everything from video game exclusives, to reverse engineering and programming tutorials, to security-related articles and much more. Feel free to reach out and say hello via any of the avenues above!


  1. Jason Blount • May 26, 2017

    Awesome Stephen, i am looking forward to more on this subject Reply


  2. Panda • June 1, 2017

    Wow, thank you for making this througly explained, Stephen! You are always exceeding my expectations Reply


  3. Yaseen Ahmad • June 29, 2017

    You were always my favorite one, You are my favorite one and You will be! But the most amazing thing is that I never knew you're a hacker too... Now I'm your fan Sir (I don't provide cooling, though) You're UNbeatable! ;) Reply


  4. Meizhi Qi • August 21, 2017

    Thanks a lot for this detailed article. I can't find enough information and explanation but just some examples about CE&lua in chinese , then i find your article in the CE forum. Hope for this series. Reply


Leave a Reply

DSASMBLR | 2016