Tutorial: Basics of SQF (ACCEPTED)

[Cheetah]

General information (v1.01 - 17th of March):

The goal of this tutorial is to show the potential and basics of SQF. I'll start by describing how to execute SQF scripts, explaining the basic structures and loops used in SQF syntax before proceeding to converting SQS to SQF. Don't expect a thorough tutorial on SQF scripts, if you already master making functions this tutorial may not be written for you. If you already master (to some extend) SQS and want to learn how to use SQF syntax this may be the ideal tutorial to take a step in the good direction.


I'm looking for feedback on this resource, is it any good? What can be improved? More demo material needed in a tutorial?

[Duke]

It seems like a good tut but my issue is that I'm new to .SQS but not new enough to require a basics tutorial. What would help me is a slightly more advanced .SQS tutorial and a decent list of how to properly use commands.

[Cheetah]

Thanks for the feedback.

You're talking about SQS, I don't know if you mean SQF but there will be more tutorials coming in the next few weeks, I'm sure of that. My intention was to get people new to ArmA and scripting in general to understand SQF. If I get positive feedback, I'll do more tutorials, but first I'll be waiting for more feedback.

I think one major feedback point is the tutorial is too basic for many.

[IGWedge]

Hi Cheetah

Just to explain about myself quickly.

I have been playing ofp for the last 5 or so years. My strengths come in the form of moddeling and texture work,I also done alot orf terrain editing in OFP.
Scripting or configs were never my forté

I am absolutly desperate to learn, to even grasp just the basics, so on seeing your tutorial i though that would be a good place to start.

Here is my input.

Your tutorial was well written and explains itself well, What it has done for me is explain the basic layout of the SQF files to the point where i could look at a basic script and break it down to understand the way it is structured. This is a great start.BUT.... i am still unsure of where to start looking for commands
I know we have the awesome ComRef but its still a job to know what commands do what and how to implement them correctly and if their function in the script will work as you want it to. There is sooo much to learn about.

I understand you plan to write more and i cant wait to see them.

The bit that i started to lose it was around the implementation of the script into the game. im sure this would be a whole other tutorial hehe.
For instance it would have been good to maybe see some examples that could be directly implemented into the game to show what your talking about. I did try but nothing worked so maybe it wasnt clear enough how you implement it, who to call what etc..


I am going to try my hand at some kind of timer script later when i get home. I want to have a countdown shown on the screen maybe from 60 mins down to 0. Il see what i can do then maybe post to see if you can give any advice on where ive gone completely wrong!!

overall a really great start keep it up mate. Us scripting noobs need you guys.

All the best

Wedge

[bardosy]

Great job, cheetah! Thank you!

[hoz]

One thing you should mention about the debugging of sqf files is the RPT log file. Its a life saver if you have multiple scripts causing errors all over the place. As many can atest sometimes those errors don't stay around long enough to read it all.
Nice job 

[h-]

Another thing worth mentioning is the fact that you can't execute sqf scripts from triggers, waypoint or init fields with just [stuff] execVM "script.sqf", you need to use either a dummy global variable or call (which I think ye know already )..

Code: [Select]

foo=[stuff] execVM "script.sqf"

Code: [Select]

call {[stuff] execVM "script.sqf"}I myself prefer the latter, no useless variables floating around..

If you mention that already: me sorry, just didn't spot that..

[Cheetah]

Thanks h-, that will be a worthy addition. Knew that you had to use call, but didn't know before you posted it in one of the other topics that you can use call { }. Will update soon.

[Blanco]

Finally bought the game 


Thx, cheetah. Much apreciated 
I understand the sqs format pretty well (but I lost some skils  ) but the sqf is a great mystery to me.
I badly needed this one and I'm looking forward for more. thx.

[h-]

Found more 'faults'.. 

In each of the example scripts you have exit; at the end..
Two things:
- even in OFP scripts (sqs) you did not need the exit at the end, it's only needed when the script is supposed to be terminated in a certain point ('in the middle') when the script is running.
- exit is ignored in (ArmA) sqf scripts thus making it completely useless clutter there, and this can 'infect' any new scripters reading this tutorial into using it and that is a big no no  .. In ArmA scripts are exited either with terminate or exitWith

One minor things is the use of the command comment..
execVM supports the use of the 'real' comments // and /**/
I myself find those much pleasant to use..

[Cheetah]

Thanks for the comments h-, noticed that about the comment and //, I use the // in my scripts too but don't know why I used comment in the tutorial.

Will implement the other stuff in the upcoming 1.01, always thought that you had to terminate a script (with exit).

[geezerjo]

Many thanks for the hard work. Very instructive. Now is probably the worst time for a guy to learn Arma scripting since everything you find on the net is for SQS. (I'm one of these guys) You finally adress the problem straight on with your SQF tutorial!

Please keep it comming and do know that your work is appreciated. 

[Mandoble]

Consider also that SQF works perfectly in ArmA. If you want something more "fine" performance wise, go for sqf, else you may keep with SQS. For example, if you want something to be checked every 30 seconds, you will have no gain at all with SQF, if you want something being executed every 0.001 seconds, go with SQF. If you find yourself confortable with SQF programming flow structure, go with SQF forever. There is at least one exception: scripts to be executed every # seconds and at the end of a dropped particle (particle array), still should be SQS.

[Cheetah]

Updated the resource, version 1.01.

- Added information on how to execute SQF scripts
- Added RPT log file information
- Fixed usage of exit

Any comments are still welcome, as well as fixes / improvements.

[geezerjo]

(Cheetah) I have a little question regarding the last example you use in chapter 8, the one destroying MG if their respective Mgunners are dead. Isn't the�  while { enemy_cleared != 1 } do loop endless? You never modify the enemy_cleared value, will it not continue on forever? Shouldnt you add something like this to the loop

if (_gunarray [ 0] != alive && _gunarray [1] != alive) then
{
enemy_cleared=1;
};


I might be wrong .... im just wondering

[Planck]

alive is a command which returns one of two values.

Either true (1) or false (0).

So either fred is alive or he is not alive.

alive is therefore not a variable with a value so nothing can be equal to it, it returns a value depending on the result of the check on whether something is alive or not.


Planck

[geezerjo]

Your right, mayby i should have written my example like this ...

if !(alive _gunarray [ 0]) && !(alive _gunarray [1]) then
{
enemy_cleared=1;
};

[Cheetah]

Sorry, I haven't been too clear on that example. It was more to show how to convert a script from SQS to SQF, it's not meant to be a logical one. Might have to explain what the enemy_cleared variable does.

In short: the variable is set to 1 in a trigger (note that a boolean type would've been better), so outside of the script.

[Tom_Anger]

Cheetah - excellent work bro.  I have no OFP or ArmA pre-experience and  come from a large family of programming language from basic to fortran to pascal to C+ and work for a software company using our own language (over 11 years now - work 3rd shift and love it).  This .sqs, .sqf logic has some similarities so I am able to put your notes into perspective.  Understanding the looping process, variables & how they are assigned, incrementede, etc helps.

Scripts using your tut can help a mission maker understand alot for folks like me who have little to no knowledge of the language.  I see alot of .sqs scripts out there in the community so it seems to me that OFP folks took what they had in OFP and used them to make ArmA missions.  Having said that - I am left to believe that some .sqs scripts may not work, but most probably do.

Being able  to write .sqf, .sqs, or understand it helps.  Knowing the proper way to setup and call them from the mission editor goes a long way.  I stopped half way from reading your tut and wanted to just let you know this is a tremedous help for me.  I am a gatekeeper for my companie's knowledge base system and I write articles in the format for "dummies" for the lack of a better term.  The little things we (you) do now is much appreciated.  Thanks.

[paddy]

Just something that may need clarified, if you want an unconditional exit in a function will ...

Code: [Select]

if (true) ExitWith {}
Work, or does ExitWith NEED an action? 
Great Job on the tut Cheetah, really helped me avoid a load of trial and error work 

[Mandoble]

exitWith exits the execution of a context, which doesnt mean it will exit a script. A context is defined, for example, by while loops, for loops, if blocks, etc. To simplify, if you have code between {}, then you have a context.

Code: [Select]

while {true} do
{
...
   if (!alive player) exitWith {}
...
};
// Previous exitWith will jump here (out of the while context).

// This exitWith will effectively end the script as it is in the top most context level.
if (!alive player) exitWith {}


[paddy]

Absolute legend, thanks Mandoble.  This would be a worthwile inclusion in the comref since it is a definite difference to the 'exit' command in OFP, what do you think?

[Mandoble]

The key point here is to understand that SQF is focused to structured programming, which also means you should not exit loops directly but using the general loop condition (whiles and fors). If you follow some quite basic structured programming rules, you will never need to use exitWith.

More info about exitWith here.

[Planck]

Extra info above added to comref.


Planck

[paddy]

I have a slight grievance with the view that unconditional exits from scripts are unneccssary, if there is no other way to prematurly stop the execution of a function in ArmA then this would be a good addition to the comref.

Sometimes complex functions or functions executed multiple times simultaneously require premature cessation to save processor power and make the game a bit more playable.  I know I had to use this alot in OFP and in my experience of programming having a 'halt execution of script' command is very useful.

I understand many programmers berk at having an exit command but I think the view is a little eliteist as these commands (however inefficent) do make programming easier, and that the whole point of a higher programming language is it not?

EDIT: Thanks Planck, little hints like this are what make the comref a lifesaver for part-timers like myself 

[Mandoble]

Well, if you need many potential exit points in a SQF script with has many blocks and blocks inside blocks and you dont want to mess with exitWith from every block level you may do the following:

Code: [Select]

// CustomExecute.sqf
_params = _this select 0;
_script_name = _this select 1;

my_condition_to_exit_var = false;
_script_handler = [_params, "my_condition_to_exit_var"] execVM _script_name;

waitUntil {scriptDone _script_handler || my_condition_to_exit_var};
if (my_condition_to_exit_var && !(scriptDone _script_handler)) then
{
   terminate _script_handler;
};

To force the termination at any point within your script you first get its params and the name of the variable to flag the immediate termination:

Code: [Select]

_normal_params = _this select 0;
_termination_var_name = _this select 1;

// Now, to terminate at any point the script
call compile {format["%1=true",_termination_var_name]};

This way (call compile {format["%1=true",_termination_var_name]};) you would have the very same functionality as will exit command for SQS scripts.