External Script Help

[ben_s 11]

Im not new to mission editing or simple ingame scripts and animations.

But i dont even know where to begin with External scripts. Is there a tutorial or can someone help with anything.

i.e.

Where do i put it?

How do i activate it ingame?

Whats the syntax for it?

ive searched forums but got nothing. Help.

[nomdeplume 0]

My favourite reference is the Biki: http://community.bistudio.com/wiki/Category:Scripting_Commands_ArmA2

There's a few ways to get started. Maybe the easiest is with a repeating radio trigger and execVM, which lets you modify your script and re-run it as much as you like. So, to do that:

Make a new mission and slap yourself down somewhere. I recommend using Utes since it loads fast.

Add a radio trigger - presumably you know how to do this. Set the "on activation" command to:

nul = [] execVM "myFirstScript.sqf"

Save your mission with a name you'll remember (e.g. ScriptTest) and then find its folder. It probably lives in your "My Documents" or "Documents" folder under "Arma 2" or "Arma 2 Other Profiles" ... "Missions". The folder will be named "ScriptTest.Utes" or similar, depending on what you named it and which island you're using. Inside you'll find a file "mission.sqm", which is generated by the editor.

Create a new text file and rename it to "myFirstScript.sqf". Note that if you have Explorer set to hide file extensions (which it does by default), it won't let you do this; you'll end up with a file called myFirstScript.sqf.txt. Go to Tools -> Folder Options and turn off the option to "Hide extensions for known file types". Then you can rename it properly.

Open myFirstScript.sqf in a text editor such as Notepad or whatever your favourite is (just don't use a word processor like Word - needs to be kept as plaintext).

Add some kind of scripting command. How about:

hint "My first external script!";

Then save it, preview your mission, activate the radio command, and you should get the hint dialog pop up.

If you're more familiar with SQS syntax, you'll want to use

[] exec "myFirstScript.sqs"

and get rid of the semi-colon in the script.

It might also be worth mentioning that "execVM" creates a kind of thread of execution in which your script is run, asynchronously. So you can add "sleep 5; hint 'My next hint!';" and you'll get a second hint coming 5 seconds later. You can't use things like "sleep" and "waitUntil" within the editor fields, so it's very handy to be able to do that.

---------- Post added at 02:55 AM ---------- Previous post was at 02:47 AM ----------

Just as a quick addendum/explanation,

nul = [] execVM "myFirstScript.sqf"

The "nul = " part is just assigning the return value to a variable we don't care about. There's a magical variable called "nil" which can be used to delete variables, but if you assign a value to it its magic is lost. So make sure you don't mistype "nul", or use some other name instead ("null" is often used).

The return value from "execVM" is a kind of a "thread handle" which you can use to determine when it's finished running... I very rarely use them and thus don't care about the handle. But if you don't do something with the returned value, the editor will complain that it's expecting nothing and you're giving it a "script".

The [] before the execVM is an empty array. It likes to have something passed to it, it can be a single variable such as "nul = player execVM ..."; or to pass multiple values, you need to use an array. If you have nothing to pass, it seems to be common practice to pass an empty array.

The script name is fairly self-explanatory. You can use subdirectories to organise your mission folder, in that case it'll be something like

nul = [] execVM "scripts\ascript.sqf"

. Also worth noting is that paths are ALWAYS relative to the mission root, so if your "ascript.sqf" also runs "execVM" and wants to run a script that's located in the "scripts" folder, it also has to use "scripts\scriptname.sqf".

Within the script, you can access the passed value by using the "_this" variable. Any variables starting with an underscore are local to that particular script, anything else is global. You can't use local variables within the editor (you get an error "Local variable in global space"). Local variables are also scoped, so if you have a script like:

if (vehicle player != player) then
{
 _car = vehicle _player;
};
hint format["You're in a %1", typeOf _car];

the hint won't work properly, because _car will always be undefined. If you change it to:

_car = "healthy state of mind";
if (vehicle player != player) then
{
 _car = vehicle _player;
};
hint format["You're in a %1", typeOf _car];

then it'll do what you expect: if you're on foot, it'll say you're in a healthy state of mind, but if you're in a vehicle, it'll say you're in a... whatever.

You can also use private to explicitly declare variables (they start with a value of nil), which makes them local to the scope they're declared in.

_car = "healthy state of mind";
if (vehicle player != player) then
{
 private ["_car"];
 _car = vehicle _player;
};
hint format["You're in a %1", typeOf _car];

Will result in you being in a healthy state of mind regardless of if you're in a vehicle or not, because the _car assigned the vehicle of the player isn't the same _car as in the top scope.

Okay, I'll stop rambling now... Have fun!

---------- Post added at 02:59 AM ---------- Previous post was at 02:55 AM ----------

Wait, one more ramble: you can also plop down a file called init.sqf (or init.sqs, if you insist), which is automatically run before the mission starts. This is a good place to do any general initialisation tasks which either don't make sense to put in a unit's init field, or which are too long to comfortably work on in the editor.

There's a few other magical "event scripts": http://community.bistudio.com/wiki/Event_Scripts

[Reimann 10]

Im not new to mission editing or simple ingame scripts and animations.

But i dont even know where to begin with External scripts. Is there a tutorial or can someone help with anything.

i.e.

Where do i put it?

How do i activate it ingame?

Whats the syntax for it?

ive searched forums but got nothing. Help.

Which forums were those? Because I know of a certain forum that has all these questions answered in a stickied thread at its very start. Just below the 'new thread' button. But its a secret.

[ben_s 11]

Looked through those, its all syntax and commands and what they can do, nothing explains where they go, how to activate them, the basis really.

[nomdeplume 0]

Was my post at all helpful? I'm not really sure what you mean by "nothing explains where they go" - they go in text files, by convention using a .sqf or .sqs suffix (depending on the script syntax used in it), and you run them with execVM, exec, or call (for functions).

You said you've used simple ingame scripts by which I assume you mean putting scripts into unit init fields, waypoint and trigger activations. So... it's exactly the same as that, and you use them for exactly the same purposes; having them in an external file just makes them easier to write/read/edit, plus if you're spawning a new execution thread via execVM you can do things you can't do within the editor script fields (e.g. sleep).

I do agree that the list of articles stickied seems mostly useful to people who already know the basics, i.e. where the script files go and how to invoke them. Did you read the first part of my post above? What was difficult to follow? What would make it easier?

[ben_s 11]

Your post was excellent. I was just saying to him that the posts already out there are for people who already know basis of External Scripting and just need some ideas to do things.

I have done ingame scripting, but nothing too complex can be done with ingame features. Thank you very much.

[Murklor 10]

plus if you're spawning a new execution thread via execVM you can do things you can't do within the editor script fields (e.g. sleep).

You can do [] spawn { sleep X; }; inside the editor too.

[CptBBQ 10]

Gotta say, really awesome post, some_kind_of_guy. I´ve started editing a few weeks ago and this info would´ve made the first steps much easier for me. Still learned something from it, though =)

Cheers,

CptBBQ.

[Jat Goodwin 10]

Thanks for that awesome post, I've been wracking my brain over this for a few days now plowing through documentation trying to get it figured out how to launch scripts so I gave up and googled "start a sqf script when the mission starts" and got this.