[Admiral MS]

Maybe we should really take a scripting.html from a recent build and comment all the functions, including examples, like you just did, plus common errors or things that look like they were possible with a function but aren't.

Because at the moment a scripting newbie doesn't have it easy. And I am a software developer, I can't even imagine how someone who has no programming/scripting experience yet could do scripts in FS2 based on what documentation we have.

Guess what my programming experience was before starting with LUA maybe one and a half year ago Don't know how many LUA functions I had to test with the good old trial and error method to see how their input syntax has to be and what they actually return or (should) do. When a forum search didn't help I had to ask like in the case of evaluateSEXP(). No one without access to and knowledge about FSO code could have figured out how it works.

So if you say

you can edit the function descriptions in lua.cpp so that the game generates more useful instructions automatically.

I start thinking something like: Huh what's this?? Where do I get this .cpp thing and how the heck do I even edit it, not break it and commit changes?

So if I could I would edit the function descriptions with a better description and even example uses for the functions that lack documentation. But as you said - how can I make sure I understand how it really works without checking the actual code and some decent C knowledge?


Complete lack of documentation gets me to another question: What the hell are hook variables, which do exist and what's the difference to normal objects/variables?

[Nuke]

that was more of a comment for the c coders in here. when somone wants a new function in scripting what you do is get the game source and edit that cpp file and add a function to fetch/write the data from c/lua to lua/c. easiest way is to copy something that does something similar and edit it to operate on the data you need. one of the arguments in this function is, go figure, the documentation that comes out in the scripting.html file. i was basicly stating that when programmers add stuff to it, that they put more than a cryptic line of information into this string. and the same goes for wiki editors who are mostly modders with a minimalist usage of words, or coders without a lot of spare time on their hands.

to be fair scripting.html seems to have pretty good reference info in it. so most of the coders have been making use of the auto-documentation feature there. and through various patches to scripting over the years it seems fairly solid. if your engine is based off of a very old branch then a lot of those scripting functions and documentation fixups just wont be there.

[Aginor]

I think we should do it this way, it ensures that everybody can help:

We take the scripting.html the E posted on page 1 of this thread (http://blueplanet.fsmods.net/E/scripting.html)
and put it into a wiki article (tbh I never worked with a wiki so I don't know how to create or edit a page, but this is a good reason to learn it I guess)
Then we can edit around in it, discuss, and when we have some descriptions someone (meaning someone who knows how not to break the CPP file) has to just take the stuff and put it into the file.
That's not much work but a huge improvement of the documentation.

Any objections? If not: Someone has to tell me how creating a wiki account works. Now!

[Nuke]

at least that way you dont have to be a coder to fix documentation shortcomings. so long as our documentation quality is smack dab in between totally vague and outright wankery (like linux man pages).

[Admiral MS]

Taking the scripting.html to Wiki and edit it there sounds like a good idea. I guess I should create an account there as well and learn how a wiki works.

to be fair scripting.html seems to have pretty good reference info in it. so most of the coders have been making use of the auto-documentation feature there. and through various patches to scripting over the years it seems fairly solid. if your engine is based off of a very old branch then a lot of those scripting functions and documentation fixups just wont be there.

Without scripting.html it would have been impossible for me to create any useful script and fortunately a lot of functions (especially newer ones or ones that have been edited recently) do have a proper description in there.

[Aginor]

Ok, then let's do this!
(and hey, Linux man pages are cool!)


Another question related to my scripting problems:
When a ship is destroyed, does it get erased from the Ships[] array or does it stay in? If it is erased: Do the rest of the indices stay the same? Same goes for a ship that is spawned later. Is it in the array all the time (like in the mission file where it has an index already of course) or is mn.Ships[] only an array of ships that are active in the mission at the moment?

I'm asking because I did a loop through the Ships array and use the ship name at the index i for my other array. And somehow my function doesn't work anymore as soon as one ship in the mission is destroyed...

[Admiral MS]

It gets removed a bit later or I wouldn't have to do this one:

Code: [Select]

if (ship:isValid() and (ship:hasShipExploded() == 0)) then It is still within Ships[] during most of the explosion part.

When it is done exploding, has warped out or is vanished it gets removed from Ships[] and all the other ships may get a different index number. Same may happen when new ships arrive.
So mn.Ships[] is only an array of what is currently active in the mission and every index number up to the number of ships in mission represents one of them. If you need a specific ship save its name rather than its index number and use mn.Ships[shipname].

[Nuke]

i should also point out that therews

Ok, then let's do this!
(and hey, Linux man pages are cool!)

the idea is cool, the writing talen of those that fill them in, not so much. linux documentation i find is an atrocious read at best.

Another question related to my scripting problems:
When a ship is destroyed, does it get erased from the Ships[] array or does it stay in? If it is erased: Do the rest of the indices stay the same? Same goes for a ship that is spawned later. Is it in the array all the time (like in the mission file where it has an index already of course) or is mn.Ships[] only an array of ships that are active in the mission at the moment?

I'm asking because I did a loop through the Ships array and use the ship name at the index i for my other array. And somehow my function doesn't work anymore as soon as one ship in the mission is destroyed...

use the ship:isValid() function to determine if the handle is still good. i think when a ship is destroyed the handle is marked as invalid. i could be mistaken though. almost all the object handles have this feature so use it when you cant be sure about the validity of something.

[Aginor]

Ah thanks, that makes it a bit more clear.

...but it seems like I have destroyed my script completely now
I'll need some precise help on the following topic:  (I guess I didn't get the meta thing completely after all)


I want to create a list (table? array?) of ships that are capable of cloaking. I'll trigger a function that creates that list based on the ship class at the start of the mission.
I also need the information when the ship last cloaked, when it last decloaked, and what its cloaking state is now (visible =0, cloaking=1, cloaked = 2, decloaking=3)

Then I want to loop through those ships every frame to check whether each ship was cloaking for three seconds and set it to cloaked.
The same goes for decloaking. three seconds later it is cloaked.

I had that working already with single variables for each ship (so you could only have 4 cloakable ships you knew the names of) but I just don't get it to work now.

Take your time, I'll go to bed now. It is 01:00h here and my boss wants me to work tomorrow

[Nuke]

you can call ship:getSignature() to get a unique neumeric identifier for that ship. id suggest iterating through the ships. get the signature and then look inside a table to see if it has a key with that value, if it doesnt, then create it (init your list, set default values for sutt, etc) and add it to the table, otherwise pull up the data which was saved on a previous loop. it does help to clean up the table periodically. iterate through it (use a k,v in pairs() loop because the values probibly wont be in sequential order and there will be gaps) look up the objects the table key with mn.getObjectFromSignature(), test if its valid, if it is skip it, otherwise set that table key to nil, this will allow it to be garbage collected. i tend to do this every 10 or so seconds.

[Alan Bolte]

I think we should do it this way, it ensures that everybody can help:

We take the scripting.html the E posted on page 1 of this thread (http://blueplanet.fsmods.net/E/scripting.html)
and put it into a wiki article (tbh I never worked with a wiki so I don't know how to create or edit a page, but this is a good reason to learn it I guess)
Then we can edit around in it, discuss, and when we have some descriptions someone (meaning someone who knows how not to break the CPP file) has to just take the stuff and put it into the file.
That's not much work but a huge improvement of the documentation.

Any objections? If not: Someone has to tell me how creating a wiki account works. Now!

Go to the Freespace Wiki. Click sign in in the upper right. Create an account. Go to, e.g., the scripting.tbl page. Click 'edit' at the top of the page. The syntax should be easy enough to learn if you can learn lua. To create a new page, your best bet would be to create a link from an established page like that one to a page that doesn't yet exist, then follow that link.

I'd be very grateful if those in-the-know could expand on the existing hook descriptions and improve upon scripting.html. For example, I see that in January zookeeper listed 'on turret fired' as a 3.6.15 feature, but it shows up in the scripting.html posted above, which identifies itself as produced by a 3.6.13 build. Does that mean the feature exists, but isn't yet ready? Or is the wiki page out of date? Furthermore, while i see a hook variable for the ship as a whole, I'm not clear on whether I can use that to tell which turret was fired. I suppose I could run through the whole ship using hasFired() but I don't know if  that would fit for every use case I might come up with.

Anyway, I don't mean to derail Aginor's thread with my questions, I just wanted to give an example of what another scripting noob would find helpful.

[Aginor]

Thanks for your explanation, Nuke!

it does help to clean up the table periodically. iterate through it (use a k,v in pairs() loop because the values probibly wont be in sequential order and there will be gaps)

Ah! I think that's what I did wrong. At least it would explain the errors.


@Alan Bolte:
Ok, thanks. I think we should call the page "scripting functions" and also redirect to it if someone searches for scripting.html, because the page will basically look like a scripting.html (but hopefully better documented )

[Nuke]

thats why the generic loop format exists. to accomidate the potentially wonkyness that comes with non-sequential use of indices, named keys get iterated through as well. you also can define your own iterator function here to make your loop smarter, but most of the time pairs() just works fine.

[Aginor]

Ok guys, I just created a page in the wiki. It is called "Scripting functions" and one page already links to it (scripting.tbl)

And before you read it: YES, it looks like crap. And YES, it is only a scripting.html C&P'd into the wiki. And YES, I don't have any clue how work on a wiki normally goes. Free feel to correct me.
EDIT: Also I'm not a design guy. So I would be happy if someone else did that kind of stuff with hierarchy and hints in pretty green boxes and warnings in red and such stuff. Also I think the hierarchy is broken. There are suddenly boxes randomly around stuff in the page. I think it is because of the empty lines or something....

I just wanted to have a point where we could start from. To prove I'm not only talking but actually doing something. Now we can start editing the hell out of this thing.

Here it is:
http://www.hard-light.net/wiki/index.php/Scripting_functions
preparing for edit war / ****storm now

[Aginor]

Ok, sorry for asking again, but I'm stuck somehow. Here's my code:

at mission start a event calls the following function:

Code: [Select]

p_InitCloakTimers = function(x)

-- set everything to null
naCloakableShips = {} -- table that contains cloakable ships. Index is the Signature, value is the name
naCloakingTimers = {} -- cloaking timer table. Index is the Signature, value the time when the ship cloaked
naDecloakingTimers = {} -- decloaking timer table. Index is the Signature, value the time when the ship decloaked
naCloakStatus = {} -- Status. 0=visible, 1=cloaking, 2=cloaked, 3=decloaking

--loop through ships, get their names and signatures
for i=1, #mn.Ships do
i_ship = mn.Ships[i]
ishipName = tostring(i_ship.Name)
nshipSig = i_ship:getSignature()
-- if they are cloakable (only Strakha for now) set their status and add them to the CloakableShips list
if (i_ship.Class.Name == "Strakha") then
naCloakableShips[nshipSig] = ishipName
naCloakingTimers[nshipSig] = 0
naDecloakingTimers[nshipSig] = 0
naCloakStatus[nshipSig] = 0
end
end

PlayerCloakable = 1 -- I should rename this variable, it has nothing to do with the player

-- HUD color for player cloaking
orgHUDR, orgHUDG, orgHUDB = hu.getHUDGaugeColor(9) -- get HUD colors on mission start
end



The CloakOrder function triggers the cloaking functions based on the first parameter,
the ship name is the second one. Orders 1 and 3 are called by key-pressed events, and they work.
The other two are triggered OnFrame (see code further below)

Code: [Select]

p_CloakOrder = function(par_order, nship)
destr = mn.evaluateSEXP("(is-destroyed-delay !0! !".. nship .. "!)")
nshipSig = mn.Ships[nship]:getSignature()

if (not destr) then

if (par_order == 1) then
p_Cloaking(nship)
naCloakingTimers[nshipSig] = mn.getMissionTime()
naCloakStatus[nshipSig]  = 1
end

if (par_order == 2) then
p_Cloaked(nship)
naCloakStatus[nshipSig]  = 2
end

if (par_order == 3) then
p_Decloaking(nship)
naDecloakingTimers[nshipSig] = mn.getMissionTime()
naCloakStatus[nshipSig]  = 3
end

if (par_order == 0) then
p_Decloaked(nship)
naCloakStatus[nshipSig]  = 0
end
end

return 0
end



The following function should check whether a ship is cloaking or decloaking for 3 seconds,
change the status to cloaked and trigger the cloak functions 2 and 0. The cloak functions themselves work

Code: [Select]

$On Frame:
[
if PlayerCloakable == 1 then
-- here I loop through my table of cloakable ships to see whether the cloaking or decloaking timers have reached 3 already
for i_shipSig,i_shipName in pairs(naCloakableShips) do
o_ship = mn.getObjectFromSignature(i_shipSig)
if ((i_shipname ~= nil) and (o_ship:isValid()) and (o_ship:hasShipExploded() == 0)) then
if ((mn.getMissionTime() - naCloakingTimers[i_shipSig]) == 3 and naCloakStatus[i_shipSig] == 1) then
p_CloakOrder(2, i_shipName)
elseif ((mn.getMissionTime() - naDecloakingTimers[i_shipSig]) == 3 and naCloakStatus[i_shipSig] == 3) then
p_CloakOrder(0, i_shipName)
else
end

end
end
end
]



I can't find the error. The ships start cloaking when I press the key, and go to decloaking when I press it again,
but they are never cloaked or decloaked. So they newer reach CloakStatus 0 or 2 again.
So I think the first or last block I posted is the problem.

Take your time, I'll work on my campaign missions in the meantime.

[Admiral MS]

Code: [Select]

mn.getMissionTime() - naCloakingTimers[i_shipSig]) == 3Well this one will never get true unless you are really lucky. Mission time is exact down to a lot of decimal places.
Do it like this:

Code: [Select]

mn.getMissionTime() - naCloakingTimers[i_shipSig]) > 3and add a true/false variable that is true after the initial cloaking/decloaking and is set false when the second event is activated to prevent repeated activation.

[Aginor]

Ah, ok. I thought missionTime was like in FRED, an integer value. This part of the code is a remnant of the time when I did the whole thing by events.
The repeated activation should be no problem I think, since the CloakStatus is immediately set by the function p_Cloak order when it is activated.

I'll try it tomorrow, though. Gotta go to bed now.
Thanks for your help!

[Nuke]

lua doesnt understand integers unfortunately

[Aginor]

I changed the time thing. But it didn't change the bahaviour. But then I corrected a wrong-case variable name and now it works better.
...better meaning I was back to the situation where everything worked until a ship in the mission is destroyed. As soon as that happens the cloaking was broken.


...and then I realized I am indeed an idiot. Maybe I should read what I write for a change. It happens every time a ship dies. MAYBE it has something to do with what I do OnDeath!
I have a small script that checks OnDeath if it is the player who dies. If he is the script sets the HUD color back to the original one (otherwise it could happen that when a player dies while cloaked the black&white HUD color I use as a cloaking indicator stays.
In that part of the script I used a variable in the wrong IF block. It was set to zero everytime some ship was killed. I corrected it and now the script seems to work

I still have a bug though, maybe there is a scripting way to do this:
When the player is using the afterburner and then hits the cloaking button the afterburner sound loops until the player hits the afterburner again. I assume this is a sound thing since there is also a cloaking sound. Maybe they interfere with each other. Does anyone know a solution for that? (except locking the afterburner of course.)