Preface:

I’ve been doing a lot of work to understand the best way to use the lua scripting language in my game, so I’m going to share my findings regarding the usage of the lua stack.  Keep in mind that these are MY findings, so if something here is incorrect, I apologize.  If it’s brought to my attention via comments, I’ll be happy to edit this blog.

What exactly is the lua stack?

Some quick facts about the stack:

• The lua stack is the primary way (the only way, as far as I know) to move data between a lua script and programming code.
• The stack is LIFO.
• Pairs in the stack cannot be directly modified.  Instead, they must be removed and replaced.
• Pairs in the stack are data-type indifferent.  The first pair might contain a string value, while pairs 2-5 might contain integers.
• The stack is script and function independent.  Once a lua state is created, the stack can be accessed.  The stack does not require a script file to be loaded or a function to be used in order to be accessed.

What is the lua stack for?

Primarily, the lua stack is used to exchange data between a programming language and a lua script.  When you call function from a lua script and it has a return value, that value is placed in the stack.  When you call a function from a lua script that requires input values, those input values are pushed to the stack before the function is called.  The stack acts as the primary interchange between the programming language and lua.

The lua stack order annoys me.

For some reason which I have yet to comprehend, some lua stack functions treat the stack order as positive numbers, and some treat the stack order as negative numbers. Here is a quick example of how the stack is represented both ways:

Positive Representation	Negative Representation	Value
1	-4	“hi there”
2	-3	17
3	-2	true
4	-1	“foobar”

If you wanted to manipulate the member of the stack with the value “foobar”, some functions will require you to reference it as 4, while others will require you to reference it as -1. In the documentation it mentions that both negative and positive representation feel natural, depending on the function’s context. Maybe that’s true for some, but to me, this is the most confusing part of understanding the stack. Perhaps someone in the comments can make sense of this for me, but until then, I have simply taken to understanding that elements in the stack are represented both ways. When in doubt, this page uses examples to illustrate which stack operations represent the stack order in negative terms, and which use positive terms (I’ll also do so in this blog).

Why is understanding the stack important?

As the stack is the primary method of data interchange between the programming language and lua, it seems like the easiest point of failure in your lua implementation.  Using the stack is made more complicated by the twin positive-negative representation of it’s order, so understanding the stack’s purpose and usage goes a long way to being able to quickly debug any issues you have with it.

What’s next?

Hopefully the purpose and implementation of the stack is a bit clearer now, although if you’re like me, you want to see some actual code.  In the next part of this series, I’ll post some code that shows the contents of the stack on screen, pushes some values onto the stack, removes some values from the stack, and moves values around on the stack.