LUA ComonPitfalls

This is not a tutorial page. This is the sort of last ressort page, you will visit when you are knee deep into the swamp. Just bookmark it and forget it if you search for a tutorial.

I will also happily answer your questions in moddev or lua irc-channel. Keep your infolog ready when you approach, and a www.pastebin.com of the code in your pocket. Now on to the pitfalls, were many brave programers have come to death.

1. Silent new Declaration:

Lua doesent recognize your typo.. instead it takes it for a new declared Variable and fills it with nil, and then it marches on without mercy.

How to avoid: Use Spring.Echo("MyVariableName:", variableName) to print out the Variables value. Use assert(variableName) to check for nils and false booleans. Do not use equals sounding Names. Do not allow typos, even in the coments. (Your autocompletion will pick them up and suggest them to you the next time you type - and they are off).

2. Unknown Function:

Unlike Java, Lua expects you to have functions declared ahead (or atleast functionheads to be decleared ahead) otherwise it wont know what to do. This results in a Error-Message, and you will learn to love those, because the real mean errors come like thiefs in the night and murder parts of your programs in silence.

3. Necessary Sleeps:

You need a Sleep(TimeIn1000/s) in every loop. These Sleeps are the "extraction" points, were the engine stops simulating your "thread" (which is a scheduled function, so no need to worry for threadsafety) and takes up another thread. So functions called in the UnitScript also need a Sleep in it, for them to work properly.

4. Overcomplex design:

If its to big for you to understand (who built it), break it down. Do not copy and paste code. Doing that is wrong, wrong - and wrong. Get code out into special functions only dedicated to checking.

if (boolOne == true and x > 3.14) or (foo==bar) thencan be converted into

function checkThem(boolOne,x,foo,bar) if (boolOne == true and x > 3.14) or (foo==bar) then

return true

else

return false

end

end

Delete unecessary stuff.Do not keep code in your work that has reached its exparation date. Plan ahead, it might sound stupid to draw a sketch of a program, but you will come into sitatuion were you coded yourself into a corner, and 2 hours go to waste. So planning if you have a complex task is never wasted time.

5. Use available tools:

You can code Lua Animations by hand. And to learn that, you do good to do that. But if you want to make a whole show, this approach is to slow. You need tools, so get yourself the toolbox and use springposer. It might take some time to setup, but you still will win time in the long run.

6. Step back:

Some Ideas are to good to waste, and some will eat your hours for breakfast.. while resulting in mediocre stuff, that could have been done in half a hour (or worser, has been done by someone else). So if you want to implement a idea, look for some forerunners work, get your hands on it, modfiy it, melt it, bend it and mend it, until you got were you wanted to be.

7. Use Includes:

Parts of your unitscript are used allover again? In diffrent units? Have sort of a function toolkit, you want to reuse, without copy and pasting it?

include "MyToolkit.lua" will add all the functions of the MyToolkit.lua to the program(only used ones). Good way to seperate overcomplex programs into easier understandbalbe pieces.

8. Locals:

The Lua Virtual maschine has 60 slots to store globals for you in a Index (fast), the rest goes into a Hash-table (slower). Variables can be everything, values, booleans and- functions. So if you got timecritical code, set it to local.

9. Check your cases:

If you compare stuff, there is always the possibility of a rare case, you missed to think off. Plan this failure in. Add a Error Message "Exotic Tank does fly-Error" as the case to go in at last.

10. Limit Recursions: Thats actually trivially true for every recursion. But in Spring even a limited recursion with lots of engine calls can be to much. Test it, test it thouroughly under stress. Test it with only that unit, widget..you will know when it goes to pieces.

11. Declaration Horizone: The Scope of your Variable is limited by the braces (then/do/else -end). Everything deeper down can see your variable, everything outside of this scope cant. Check them Twice- if you were the function.. could you see it at the point it is needed? Do not trust your instincts. If a function gets handed a value that has the same name then a global, this local "copy" hides the global variabel till function end. What maybe obvious to the programmer, is invisible to the program.

12. Coments: Every time you have to return to work, and dont know what something does, and you read it again - write it down as a coment above. Coments are not for others, as is indentions, they are for you. Even with a carefully worked out plan, you will looose the overseight with larger projects.

13. No wreckage Info/No such Unit If you get this message, spring could finnish parsing the unitdef and skipped it, so it wont show up to the party. Check for missing comata, typos, coment pieces out, until its loaded. [[Something|] , is just a diffrent way of writting "something". So within double braces is just another string.

14.Object Orientated Thinking:

Its way more efficient to bundle data together with objects, then store it en mass in huge tables, getting it together on demand. For example:

for i=1, 9000,1 do

if unit[i] == weapon[i] then doSomething() end

end

is slow. Everytime the first table is called the value is taken, then the second big value is called, rising the chance to push the first table out of memory. Thus a constant loading and writting occurs in the background.

ArmedUnits -- a table that contains the unit and the weapon bundled together

for i=1, 9000,1 do

ArmedUnits[i].unit

weapon=ArmedUnits[i].weapon

if unit== weapon then doSomething() end

end

This approach takes a little time to get used to, but especially for large tables its a big performance safer.

14. Use Text Replacement:

Many beginners use compares like if booleanDeBug ==true then Spring.Echo("Testvalue",blabla) end

Do not leave this useless compares in the code. Instead use the Spring.Echo alone.  Then if the release is closing in use Text Replacement to Replace Spring.Echo with --Spring.Echo.

15. Syntactical Insecuritys?

Spring over tthe time has incoporated scripts from diffrent languages (cob/bos/lua) scripts and some of those calls are rather vague described in the wiki. So how does this COB Get/Set work? Best sollution, google it. Really. Somewhere someone allready has used it, and you can see it, working.

14.Forgotten Globals

Declared aeons ago, forgotten by you and used in the assumption they never existed. And now you fill them with diffent values in a function, wondering at the strange sideeffects.

15. Nil

Nil is Nihilistic. It takes functions with it it, everything that touches it becomes unstable, antimatter. A Variable initialised with nil will resolve in a 0 no matter what you put in through other functions. You know the checks. Use them.

16. BackUP

Not against data loss through hardware failure or viruses, but to have a safecopy should you screw up. There is stuff that will crawl into a overworked tired mind at 4 in the morning that you will find brilliant. And the next moment, you want to go back, all you find is a NeedMoreSleep() function with a lame pun in it. Use a Subversion controll system, use a simple on for the start (like Mecurial). Advanced people will recommend you advanced tools. There is no shame in using the easier option if that one allows you to archieve your goals.

17. Dont Poison the Well Sometimes you need Information for a Unit, and you create a Sensor-Thread such as this.

local function senSoricLoop()

  while(true) do
 info=Spring.GetMyInfo(unitID)
    if info == true then
    --do this
       else 
       --do that
       end
 Sleep(150)
 end

end

Poisoning the well means, instead of writting a second while loop to give in to the temptation to just falsify the sensoric data. In this case making the info global, and setting it to false every Sleep(20). This thing is nasty, it will result in unpredictable behaviour, a unit that seemingly at random sometimes spasms. Avoid at all cost.

18. SignalMasks for Threads (Thx to Tobi for this one)

SIG_ONE=1

SIG_SOMETHING=2

SIG_ANYTHING=4

Threads are Started and if you use SetSignalMask(SIG_SOMETHING) you assing them a unique Number, that must be the power of two(1,2,4,8,16,32...). To understand SignalMasks you need to understand the binary representation of this numbers.

SIG_ONE = 1            SIG_SOMETHING= 10            SIG_ANYTHING= 100

Notice the difference? Every one of this 1s represent a Switch, that can be either on, or off. If you Send a Signal Signal(SIG_ONE) this will find the thread (and its decendants) and pull the plug.  What happens if we would use a uneven number? Signal(3) for example?  It would result into Signal(11) (3 beeing 11 in binary) and pull the plugs of all threads marked by the SignalMasks 2 and 1. Now if you assign a threads decendant thread another number, it becomes independent from the father Thread. Handle with care.

19. A visit to the zoo: Lets visit the Zoo of lua-errors, and lets see what the erorr messages (if you get any actual mean).