Lua "tutorial" guide..blob thing?

[knorke]

I felt a guide to spring Lua is missing.
Something that explains where to start with a "hello world" widget and where to go from there.
There is this:
http://springrts.com/phpbb/viewtopic.php?f=23&t=16223
which is a bit like that, but the "how to start info" is hidden in 58 pages about various stuff that is now in wiki in better/more complete way.
Otherwise there is only "go unpack some mods" but where to even start looking.

So I started to write short guide about starting with Lua.
It tries to answer the problems that I had and think maybe others face too: Already can program a bit, learning Lua is not so big problem. But start was very hard: where to even put the file, is a gadget better than a widget, how to reload the script etc.

http://springrts.com/wiki/User:Knorke/Sandbox1
Now at http://springrts.com/wiki/Lua:Tutorial_GettingStarted
is not a bit formated or spellchecked.
It is not meant to be full guide, more "If I could go back in time to give younger newb-self an introduction, what would you say?"

Useful? Fail? Suggestions what to add?
At end I want to have list of "examples for further reading" or something. (Gadgets/widgets that are short and interessting to mess around with, without having to type long explainations for them.) Links to threads or files welcome.

[PicassoCT]

Well written tutorial - but end is a little pessimistic.

Basically : "Yeah, you know the basics, but you cant do anything with them. Learn to use GL-API to draw stuff. Also here are some links.

Tutorial was excellent though, especially the pictures explaining what is a widget, gadget, unitscript..

[FLOZi]

Nice tutorial, does need spellcheck though.

Also blah about use of h1.

[gajop]

I appreciate the gesture, here are my comments on the guide.

Critical:
1. Before jumping into a first widget, you should first introduce people to the difference between synced and unsynced, as well as the different Lua states (we have what, 4 with LuaUI, LuaIntro, LuaRules and LuaGaia?)
2. By your forum post I thought you were going to make a guide/manual, but it seems like you are making a 'create-your-first-script' tutorial. We already have a few tutorials, a manual that explains the system/architecture in greater detail is what I feel we need more.

Major:
1. Don't 'optimize' people's workflow in a guide (requirements should be less demanding).
2. Fix misspelling and grammar mistakes
3. Don't use made-up terms like wupdget, this will just confuse players later on

Minor:
1. Remove "what this is" and "what this is not" sections and just have an "Spring Scripting beginner's guide" heading (if that's what you're making).
2. unit scripts: animate units & controll their weapons. also have some gadget power. - What power?
3. There is also 4) functionality provided by the engine. That's obvious, but there's no need to mention it if you are making a scripting guide.
4. All 4 are in a constant fight against each other. - What??
5. The SpringTutorialGame is simple - Needs link
6. .. there's more, i'll wait to see your intentions before reviewing further

[malric]

Indeed I think there is place for new tutorials on gadgets/widgets (I have played a bit with that recently and looked into what is available and it was a bit confusing).

I agree with most of what gajop said. Also (mixing questions with suggestions):

• there should be references for things that are not completely exaplained. Text like "Nobody cares what excactly this does" looks unprofessional.
• this seems a bit unfocused (ex: you write it is not a lua tutorial but then you write "In Lua everything not initialized is nil... etc"). I think it would be much more usefull if it would focus on one of the 2 scenarios (drawing and giving orders), and give a more complete example.
• I do not think you need to start with synced/unsynced explanations, but at least mention them and give a link. Something like. "We discuss here only unsynced widgets, for more info see this"
• you do not describe error scenarios. I would say most of the people will do something wrong at first, it is important they know where to look (ex: syntax error, widget does not show in widget lists)
• isn't there any more automated way to reload a widget than going to the menu? Like pressing a key to reload? I used for example "/luaui reload" because I prefer to use keyboard.

[knorke]

but end is a little pessimistic.

Well, gl graphics is kind of a chapter on its own and takes extra time until one can do something useful with it. And when using Spring.GiveOrderToUnit it quickly gets very "spring specifique."
Since both can be bit frustrating I wanted to show how even without those two one can still "make a useful Lua."

gajop:
Yes, it is more a 'create-your-first-script' tutorial rather than a real manual.
That means it only includes what is needed to start out, and leaves out some deeper details.
So it is more "practical." On the "theory" one can read up elsewhere - or pick it up on the way.

"Lua states":
are explained at beginning a bit, with the picture too.
I feel deeper explaination is not needed at that stage.
LuaIntro is kinda special and not relevant for starting out I think.

We already have a few tutorials, a manual that explains the system/architecture in greater detail is what I feel we need more.

Hm, can you link? I did not find any such "start with hell world" tutorial.
There is http://springrts.com/wiki/Chili#Tutorials or http://springrts.com/wiki/LuaTutorials: ... unications but those are on special topics (actually not sure why that 2nd page is named Tutorial?)

1. Don't 'optimize' people's workflow in a guide (requirements should be less demanding).

Hm did not feel it was too demanding.
But it must be aimed at people with bit programming experience, for learning "what is a variable" interweb has enough such guides.
The idea is not to explain "how does a function work" or even "or does a function in Lua work", but instead "this is how functions work in Spring's Lua."
And the other things are more "how to set up your enviroment" tips, like spring in windowed mode etc.

isn't there any more automated way to reload a widget than going to the menu?

Yes, but like that it also explains the colors/functionally of F11 menu.
There is link to http://springrts.com/wiki/TestingYourGame ,a page that lists text commands.

Expanding on error scenarios is good idea.
But maybe as seperate page "How to fix bugs in Spring Lua" or as section in http://springrts.com/wiki/TestingYourGame ?
Because it might be useful on its own, too.

(ex: you write it is not a lua tutorial but then you write "In Lua everything not initialized is nil... etc").

True, bit mixed. Writing full Lua tutorial is of course too big and redundant task, but such small bits are maybe okay, in relevant places?
Or when tables are mentioned then have link to some Lua-tutorial on tables etc

4. All 4 are in a constant fight against each other. - What??

it's true!

[CarRepairer]

Nice tutorial. I agree with the others that there are a lot of knorkisms that could be toned down or removed (even though I enjoy knorkisms in his many posts). I think the majority of it is not so bad, mostly just the beginning section should be rewritten to be less confusing. And stop saying wupdget, that's the worst word ever.

The YOLO part made me laugh.

You have to give congratulations in groups of two or more. If you only give one congratulation it quickly dies in your hand. It's like the game of life.

Don't forget to add an example of a small map.

[Jools]

I like the tutorial and the best part of the tutorial is that it exists. Sure, what Flozi and Car says is true, I don't really like wupgets either.

Thing is, the audience of the tutorial is not us, I think we are too blind to see what it needs or if it makes sense. It should be posted to someone who's new to spring programming and to ask their opinions whether it makes sense.

[FireStorm_]

Some points:

- I like the pragmatic approach I think you used.
- In-game pictures with extra text are good I think.
- And I'm afraid you'll only learn how helpful it is if you receive feedback from someone that is not that familiar to Spring. (It looks helpful to me, but I can't be sure because I already knew a lot of the things mentioned.)

Possible tip:

I think I'd make it more specific (maybe game specific), or in other words I wouldn't give a potential student to much freedom. If one is still learning they might not yet know what to do with that freedom. I think in a tutorial it might help to instead saying "you can do this, or you could do that." to say: "In this tutorial we are going to do this."
(though maybe that will force you to go more into specific details: Don't know if you'd consider that a good thing.)

Personal preference:

Instead of using
Spring\LuaUI\Widgets\myfirstwidget.lua
I think I'd use:
Spring\games\springtutorialgame.sdd\LuaUI\Widgets\myfirstwidget.lua
Not super important I guess but it would have my preference, because it would make a widget game specific.

In any case, I think it can be a helpful tutorial, even as it is now.

[gajop]

"Lua states":
are explained at beginning a bit, with the picture too.
I feel deeper explaination is not needed at that stage.
LuaIntro is kinda special and not relevant for starting out I think.

You don't need to explain each state in detail, but I think telling what they are and creating a link to each of them in the wiki is necessary (even if this is a tutorial). I'd also move the "synced & unsynced" part before the examples.

We already have a few tutorials, a manual that explains the system/architecture in greater detail is what I feel we need more.

Hm, can you link? I did not find any such "start with hell world" tutorial.

Any 'create your game' tutorial counts imo, e.g. this and this. It's still OK if you just want to make a tutorial out of this, an updated and lua-only tutorial could be useful too.

1. Don't 'optimize' people's workflow in a guide (requirements should be less demanding).

Hm did not feel it was too demanding.

What I meant by 'optimizing' was your attempt at perfecting their work environment, or just mentioning things that aren't essential.

PS: Why did you post it here: http://springrts.com/wiki/Lua:Tutorial_GettingStarted ? It's not ready yet, it still has big issues (wupdgets, knorkeism, etc.)

[knorke]

You don't need to explain each state in detail, but I think telling what they are and creating a link to each of them in the wiki is necessary (even if this is a tutorial)

Hm but remember it is for starting. I feel for beginning it is not nessecary to know details about every lua state, that would just disattract from the "bigger picture."
One of the purposes of guide is to filter out everything that is not relevant at the moment.

I was wondering about having more links, but in the end decided against it:
This page touches many subjects (if only superfacially) but is not meant as navigation page. For navi-page there is already
http://springrts.com/wiki/Lua_Scripting ,recreating that in text-form does not have much value. (and keeping links working is much work too)


One of your two linked Lua pages is not about scripting but about unitDefs or other "config" files.
The second is more an introduction that says "Lua scripting exists and can do anything at all."
The author even admitted "I'm just going to point you to the lists of callouts and callins and stand back." It does not really explain how to start etc
So the page is "unique enough" imo.

What I meant by 'optimizing' was your attempt at perfecting their work environment, or just mentioning things that aren't essential.

Hm maybe I'll explain my thinking behind those items:

having played spring game for some days
No use to learn about modding something that you are not at least vaguely familiar with.

text editor with synthax coloring
Can not edit text files without
Programmers will read it as "no compiler or special IDE required"
Players can read it as "oh, no complicated tools needed! My PC already has a texteditor installed, I can try it right now!"

copy of SpringTutorialGame
Can use any game, but then come problems. For example say a mod like zero-K was used, raises more questions:
-Where to download it in non-rapid form? / How to transform the rapid-files into a human-readable archive?
-How to make it allow local widgets?
-Does the chat maybe filter out important messages?
...
and so on. Of course all those problems can be overcome but it would just bloat up the text. And having to worry with so much stuff before even doing "hello world" not doing favor to reader either.

Rest has similiar reasons.
So I feel it is not about perfecting workplace, more about dealing with some very basic pre-start questions.
Would "Before you start" maybe be better title?

It's not ready yet, it still has big issues

I too do not like badly unfinished pages on wiki.
But felt it was kinda okayish state and also brings something new to wiki that previously did not exist there.
Keep it locked away for too long and it never gets used, a dilemma!
The critic in thread did not seem critical enought not to put it from sandbox to real page.

(wupdgets, knorkeism, etc.)

wupdgets:
Indeed in most places the more politcally correct term AddOn can be used. (will edit)
BUT "Wupget and friends" is a superpro heading. In a dictionary it would be wrong of course, but as eye-catcher for tutorial seems ok.

Generally on language:
It is very dry topic. Not exciting to read or write about. As long as it does not bloat up the text, I do not mind a lighter tone. Writing in such way helps to keep paragraphs shorter and avoids long blablabla.

@ CarRepairer, Jools, FireStorm_ :
gajops post was easiest to quote.
hope most points of other posts are adressed along with it.

[code_man]

I wish i had such a tut when i got into spring, wasnt pleasent having gadgeds/widgets to figure out for myself.

What this is

This page explains how to get started making scripts for spring.
What this is not

This page does not explains how to make scripts for spring.

This should be changed.

Otherwise seems fine mostly. Good work.

[knorke]

thanks again for the feedback, there were many good points.

I wrote a second tutorial-text-blob.
Newbies are sometimes told "go unpack some mod and make a simple gadget" - this is supposed to be the guide to that.

http://springrts.com/wiki/User:Knorke/Sandbox2
It assumes previous reading of http://springrts.com/wiki/Lua:Tutorial_GettingStarted
first version, likely has mess-ups and formatting is so-so

The idea behind these texts is to have some pragmatic starting guide.
Sure, some more theoretical background would be nice but newbie can always figure that later.
For start it just gets in the way.
Imagine it is your first driving lesson and you sit in the seat.
What would you like to hear:
a) physic formulas about the combustion engine
b) which pedal to press for going forward



The text is quite long and the gadget quite short.
However it tries to explain how gadgets are made. Not only the programming-part, but more the general spring-stuff.

I thought long time what could be good first gadget after "Hello World"?
I wanted something that..
..does not get into the spring-specifique-horror-areas (like commands, or teamID-vs-allyID confusion or sync/unsync)
..does not break with /luarules reload
..does something interessting in the game-world.

[PicassoCT]

I always thought you the best tutorial writer around here. Funny Pictures and easy explanations, focusing on the bare minima without unleashing a textbook avalanche (and now lets take a day or two- to explain the whole API)

Also- while your at it, make it a suicide unit or something.. not just a volcanNOOooooooo.
The idea is to have something with which junior can run to his friends bragging - look what i made.

Oh tuck it, make a gadget that makes for chain explosions with nearby units.

Show him the joys of moddev.

"His first unit and bam- way to pro allready. So i flamed him. To reeducate him at the start, about what to expect from players."

[FLOZi]

* Volcano.

Otherwise, I think it's great - I especially appreciate the 'how I found the next bit of info I needed on the wiki' bits, a great 'teach a man to fish' idea.

[knorke]

Oh. Was 50-50 whether to check spelling of that.

'teach a man to fish'

yes, excactly.

New text is about more gadget and a bit widget and how to use that to make a Pfffp who puts features onto a map. Think that is somewhat often asked question and code is still relatively simpe, so makes good topic to write about.
So guess from mapping perspective it is interessting too, one can just skip the boring parts.
http://springrts.com/wiki/User:Knorke/Sandbox3

For the "Initialize() vs GamePreload()" I was not quite sure, as I see it the only difference is that matters here is that GamePreload() will only trigger once at start of game, so it will not trigger again after /luarules reload

Guess LuaGaia could be mentioned too, but no idea what is the difference to LuaRules and iirc on answers.page it stayed without answer. (imo they are both the same except can be reloaded seperately and one is "more commonly" used in maps)

/edit
somehow I find those pages visually quite ugly. Think it is the combination of running text mixed with code lines and images, which tends to look less tidy than structured lists of things.
With more text everything would maybe wrap nicer Maybe image resizing can help it a bit too.

[FLOZi]

Maps should exclusively use LuaGaia

[knorke]

That was my thinking too, however it always seemed more like a "guide line" than strict requirement.

Last I tried I had iirc to include two files with map like:

Code: Select all

draw.lua:
VFS.Include("LuaGadgets/gadgets.lua",nil, VFS.BASE)

main.lua:
if AllowUnsafeChanges then AllowUnsafeChanges("USE AT YOUR OWN PERIL") end
VFS.Include("LuaGadgets/gadgets.lua",nil, VFS.BASE)

[FLOZi]

Of course you do, LuaGaia is a separate lua environment - which is why maps should use it exclusively. Just because other maps / older maps don;t doesn't mean people should continue to.

Also, no need for AllowUnsafeChanges rubbish since like 0.83 or something.

[knorke]

yea, without AllowUnsafeChanges. It just survived in so many places :/
---
Having LuaRules / LuaGaia as two seperate Lua states is nice, but could also be used for different purposes...like I dont know, the AI in LuaGaia, so one can reload it without messing up rest of the game.

Is it possible to have more than the usual 3 Lua states? I think not but here is three dots at end that give some hope? I mean for normal gadgets, not something totally different like LuaIntro.
[quote]Script.GetName
( ) -> string luaInstanceName (e.g. "LuaUI", "LuaRules", "LuaGaia", ...)[/quote]