LUA in scenario guidelines

[michaelm75au]

I created a first-cut set of things to help with using LUA in scenarios.
The idea is to help designers not fall into some traps (both known and potential).

[wqc12345]

Thanks Michael for doing this and helping me with my lua concerns.

[ckfinite]

I'd go further on #1:

The use of unit names is strongly discouraged in triggers and events, as it is sensitive to units being renamed. Rather, using unit GUIDs (most easily found by right click -> Scenario Editor -> Copy Unit ID to Clipboard) is suggested, as it is not effected by unit renaming. This also avoids the problem of point #3.

I'd also add the suggestion to use an external editor, like ZeroBrane or Notepad++ or Sublime.

Looks good though, it could help a lot.

[michaelm75au]

ORIGINAL: ckfinite

I'd go further on #1:

The use of unit names is strongly discouraged in triggers and events, as it is sensitive to units being renamed. Rather, using unit GUIDs (most easily found by right click -> Scenario Editor -> Copy Unit ID to Clipboard) is suggested, as it is not effected by unit renaming. This also avoids the problem of point #3.

I'd also add the suggestion to use an external editor, like ZeroBrane or Notepad++ or Sublime.

Looks good though, it could help a lot.

True, renaming can wreck things up. Using the GUID for single ships, etc is okay, but it becomes more difficult if dealing with flight call-signs. That is you want to do something on callsign #1 to #16. Easy enough with names, but for GUID you would need to get the values for each plane.
Would be easier if there was a original name and one for a rename. The rename (or original if none) name could be used in-game while you used the original for such things a scripting.

[michaelm75au]

With a non-LUA trigger (such as unit remains in area), does renaming the unit affect that? Or does it convert the name to the GUID for storing in the event??

[ckfinite]

That is you want to do something on callsign #1 to #16. Easy enough with names, but for GUID you would need to get the values for each plane

The way I typically do this is by using a lua snippet in the editor to find all the GUIDs in one go, then I write those into the event script.

With a non-LUA trigger (such as unit remains in area), does renaming the unit affect that? Or does it convert the name to the GUID for storing in the event??

I think it uses the GUID, though I haven't tried it.

[michaelm75au]

Yea, I suppose you could even do a function at load time to build your own list of GUID/name piars and use that to translate within the action/conditions. Then it would not matter if the player did rename them as you have the original name/GUID pairs.
Using names makes the LUA a bit more understandable. But if people actually comment the code as well, that would help them remember what they programmed.

I'll add something to my notes. It may be an idea to also add a new section with sample code to demonstrate some of the better ways to do thing, like this.

[mikmykWS]

Hi Mike

When you're ready to post this let me know. I'll pin it to the top of forums etc.

Mike

[michaelm75au]

I'll review and update it this weekend, and let you know when complete.
Thanks

[mikmykWS]

Ok. Will be tacking this to the top of my monitor too. I'm a worst offender.

Mike

[mahuja]

I'm late to the party, but oh well.

Command items:
#3 See also [[the other string syntax]]. And [===[ [[]]] '"\ ]]===] and so on.
--[[ and the
multiline
comments]]
Strictly speaking, if you're separating between command and general lua, this belongs in the other section.

#4, #5
Should these be separate?

#6
Is it worth mentioning that the command print function is non-conformant? It should be print ('Event 1: ', unit) but that just gets you a nasty error message.

#7
I believe a better approach will be

Code: Select all

function getAiUnit(side_in, unit_in)
 	local result = ScenEdit_GetUnit({side=side_in, name=unit_in})
 	if result == nil or ScenEdit_GetSideIsHuman('NATO') then                -- not player controlled
 		result = false;
 	end
 	return result
 end

You should then omit your ==true and it will work the same, except this one allows you to store the return value and use it without doing another unit lookup inside the then block. Some functions seem to want a modified version of that return table.

Another benefit of this is that you can build up a library of common functions that you can use in other scenarios just by having it loaded at scenario start.

Before making that recommendation/suggestion, please try actually doing it, and tell us how.
- Trigger on scenario loaded reliably does not fire when loaded in editor.
- When you save+load, all variables, including all your functions, are wiped.

Presuming a 'scenario loaded' trigger in a repeatable event loads every time the user loads outside of the editor, a special action for editor mode may solve the problem. Just... remember to update the event action too.

#8
This is all opinion:
Ideally, the fact that you are using lua is an implementation detail. The action name should describe what the action does, and what it does under the covers - lua or not - should not matter.
With that said, given the bug-prone nature of flexible scripting, marking them with lua (aka "bugfixing attention here") isn't a bad idea, but I'm keeping that at the end of the name.

#9 has me asking what audience you are writing this for. Perhaps setting the expectations in a preface of sorts?

Lua general:
#1
--[[You say to use comments, and through all your examples use comments in a way that is generally considered worse than not having any comments.

When I say "generally" I mean "among programmers". The assumption is that you know, or will learn, how to read code. The code should say what, and the comments should say why. When comments say what, changing it will require changing two things. So when (not if) that does not happen,
for i=1,24 do -- scan thru numbers 1 to 16
I hope you don't rely on the comments to know what's going on there!

Again, who are your audience? If they are beginners, and I believe most are, they may look at the comments shown by the guy who just told them to use comments, and think it's good.

If your guide needs an emphasis on what, it may be better to include separate pseudocode. Or "just" write it more readably.
]]

#2 It gets worse - even if you store a variable globally, you cannot rely on it being there after your script exits. If the user saved and loaded in between, it's gone. So when you actually want to do that, ScenEdit_SetKeyValue and ScenEdit_GetKeyValue appears to be required.

It is possible to make creating (writing) or reading a global variable an error, letting you spot these cases. Misspelled names included. Or make these automatically call setkeyvalue and getkeyvalue when used.
It'll be a piece of code that needs to be run in the lua console before code it will be checking for.

#3
When the user doesn't have control over his display (e.g. a text file displayed in a web browser...) tabs may expand to 8 spaces, which can make it look very messy. I'm generally a fan of tabs for indentation precisely because it is customizable, but for this particular purpose I would recommend you use two spaces.

#4, in its first example, does not follow #3.
Also, to follow up my criticism in #1

Code: Select all

-- all aircraft of the squadron
 for i=1,16 do
   local unit = {Side='Germany', Name="Steinhoff #"..i,}
 
 	-- must be alive
 	if ScenEdit_GetUnit(unit) then
 		ScenEdit_SetUnitSide(unit, newside='NATO'})
 
 		-- Human side doesn't have this mission
 		if not ScenEdit_GetSideIsHuman('NATO') then
 			ScenEdit_AssignUnitToMission("Steinhoff #"..i, "NATO CAP")
 		end
 	end 
 end

And the mandatory nitpick: Lua is a word (translates moon) and supposed to be capitalized as such. Lua or lua. LUA implies an acronym.

[michaelm75au]

I have uploaded the latest text file.
I also intend to try create a sample file of various actions to complement this.

[michaelm75au]

I have added a new item to the checks. I thought I had something like this in the list, but it didn't really state it as such.

11. Validate your Lua script
When building a script, copy the script into the Console and run it to 1) make sure it actually runs without error, and 2) that the unit references you are using are valid (eg that name of the unit is actually what you expect it to be). Often you can't exercise every action while playing a scenario especially if so actions are random or timed.

[thewood1]

Should this be on the public forum. I would think the broader exposure would be better.

[mikmykWS]

Yeah looks great.

Mike give me the go ahead and i'll post this where it needs to be. Probably a good thing to add to Baloogan's LUA Wiki as well.

Mike

[michaelm75au]

Yea, I think I have covered most stuff. If we come across more in the future, we can add to it.

[mikmykWS]

Ok sent a copy to Baloogan. If you could also post it to our main forum I'll sticky the thing.

Thanks!

Mike

[mikmykWS]

Okay Baloogan put it up

https://wiki.baloogancampaign.com/index.php/CommandLua

Mike

[michaelm75au]

Done
fb.asp?m=4145529

[mikmykWS]

Stickied and FAQ'd.

Thanks Mike this will help a lot. You've gone well above and beyond helping out. I hope you know the team really appreciates that!

Mike