FreeSpace Wiki - User contributions [en]

Tutorial - In-Mission Jumps

2018-07-15T19:28:53Z

Axem: Shamlessly plugging :)

Today we're gonna look at how to make in-mission subspace jumps!

They're easy to make and contain 57% of your daily spinning blue content.

All you need is a FreeSpace Open, version 3.6.12 at the very least.

== Capital Ship Micro Jumps ==

=== Setting up the mission ===

First lets set up a super simple mission! Open up FRED and make something like this.

[[File:axm_ingamejumptut_000.jpg|600px]]

Here's a link to the blank mission if you're too lazy to make it yourself.

[[https://sectorgame.com/fsfiles/repo/download/ZGF0YS9BeGVtL090aGVyL0luTWlzc2lvbkp1bXBUdXRvcmlhbC9heGVtX21pY3JvanVtcF9ibGFuay5mczI=/h/c4035bdfe9c8946fbd04ed460d23f7bc Blank Mission]]

Okay, so now let's start some magic. Let's move Aquinas Station about 30 klicks out. Then let's make a new Aeolus cruiser. We're going to name it Ascendant#2. We'll place Ascendant#2 close to Aquinas Station.

[[File:axm_ingamejumptut_001.jpg|600px]]

[[File:axm_ingamejumptut_002.jpg|600px]]

For ship names, FreeSpace will ignore anything past the # sign. Older missions that might have tried this would have used non-ASCII characters, like a "á" or "ó". Since those characters aren't in the font files, they show up as blanks. But if FreeSpace ever gets true TTF support, guess which missions are going to look pretty funny!

NOTE: This happens in wing names too to a certain detriment. Naming a wing Alpha#2 will make the fighter names be Alpha#2 1, Alpha #2 2 and etc. But since anything past the # will be ignored, in game all you're going to see is Alpha, Alpha, Alpha, and Alpha. So its not a good idea to do this for fighters. We'll get around that later.

So for Ascendant#2's arrival cue, we're going to set it to when Ascendant has departed. You can insert a delay, but for these relatively small distances for FTL, its going to be near instant anyway.

[[File:axm_ingamejumptut_003.jpg|600px]]

Then we'll make the Ascendant's depart cue to leave after 5 seconds.

[[File:axm_ingamejumptut_004.jpg|600px]]

Okay, let's go run the mission real quick. We should have the Ascendant warp out and then warp in again, right next to Aquinas Station.

"Gee Axem, I'm not THAT dumb. I could have figured that out by myself!"

I see I have underestimated you. Let's kick it up a notch. Let's increase the depart time for the Ascendant to 30 seconds.

[[File:axm_ingamejumptut_040.jpg|600px]]

Now lets add a hostile cruiser, a Fenris. Let's name it the Gosforth. And since we're going to be lazy with this, lets just tell it to attack the Ascendant.

[[File:axm_ingamejumptut_041.jpg|600px]]

The resulting battle should now damage the Ascendant to a degree. Let's replay this mission now!

[[File:axm_ingamejumptut_005.jpg|600px]]

To no one's surprise, the Ascendant takes out the Gosforth in under 30 seconds. Without beams. With that task finished, the Ascendant warps to Aquinas Station...

[[File:axm_ingamejumptut_006.jpg|600px]]

and is miraculously healed from its injuries...

[[File:axm_ingamejumptut_007.jpg|600px]]

Makes sense, the two ships are technically different to the game. So let's fix this with some events now!

===Using ship-copy-damage===

We're going to make two events. "Make Ascendant Warp Out" and "Copy Damage". Copy Damage will be chained to the warp out event, with a delay of around 3 seconds. Set up the events inside like so. You can see I've basically moved the departure cue to its own event and I'm just referencing that event now.

[[File:axm_ingamejumptut_008.jpg|600px]]

You can find '''ship-copy-damage''' under Change -> Special.

'''ship-copy-damage''' copies the damage stats for one ship and modifies them to any number of ships. The only requirement is that our original ship must present in the mission. It can't have already left. But anyone that is on the receiving end doesn't have to be there yet.

Now why is there a delay? Why not just put ship-copy-damage right with our depart event? Well it takes time for the ship to speed up and actually depart. In that time the ship can take damage. So if we fire it too early, the damage won't be totally accurate. So we'll put up a small delay before we actually copy the damage. Not that it matters here too much... Hey let's add a second hostile Fenris, the Ledberg.

[[File:axm_ingamejumptut_009.jpg|600px]]

Play time!

[[File:axm_ingamejumptut_010.jpg|600px]]

So the Ascdendant was leaving with around 82% hull...

[[File:axm_ingamejumptut_011.jpg|600px]]

and arrives with 81% hull! (Also note the damage on the flak cannon, damage from subsystems carries over too!)

[[File:axm_ingamejumptut_012.jpg|600px]]

Something must have hit it on its way out. Man, if you had had used the ship-copy-damage too early, you would have people calling you names because that ship healed itself by 1%.

Well, now you know how to make larger ships micro-jump! That ends this episode of... Oh, you were here looking for how to do player micro-jumping.

Okay, let's do that too. Why should the Ascendant be the only ship that saves itself 17 minutes by warping there. And here I am using my sub-light drives like a sucker.

== Player In-Game Jumps ==

This is the mission file at this stage. It includes everything for the capital ship micro-jump tutorial.

[https://sectorgame.com/fsfiles/repo/download/ZGF0YS9BeGVtL090aGVyL0luTWlzc2lvbkp1bXBUdXRvcmlhbC9heGVtX21pY3JvanVtcF9wbGF5ZXJibGFuay5mczI=/h/cbeecfcfe112798e9476e9dd8c963126 Blank Player Jump Mission]

===A MUCH EASIER WAY===

This tutorial was originally written in 2011. In 2018, lua scripting has come a long way and the rest of the tutorial can now be one in a single scripted sexp. Please see [https://github.com/AxemP/AxemFS2Scripts this GitHub page] for an in-mission jump script (as well as many others). The rest of the tutorial is left here as a testament to how much work this stuff used to be.

===The Thought Process===

Let's think about how we want the micro jump to work.

Obviously we want to press something and have a warp effect appear, then we have something like a fade to white, maybe a subspace corridor, then another fade to white and we appear at our destination. Sounds simple enough!

Let's go in order here.

"Obviously we want to press something..."

What key? Alt-J? Sounds cool. But wait, that basically ends the mission anyway. Hey can't we just never-warp the player, like in that SOC mission? We can! Problem solved, right?

[[File:axm_ingamejumptut_042.jpg]]

[[File:axm_ingamejumptut_043.jpg]]

Oh, that doesn't look good. It would be kind of odd for that to pop up while you activate your jump drive... and jump.

Ok, let's scrap that event and go to the Misc screen on Alpha 1's Ship Editor. We're going to tick the "No Subspace Drive" box. So now when he hit Alt-J, the game sees that box and goes "You don't have a Subspace drive, so I'm not going to do anything!"

[[File:axm_ingamejumptut_045.jpg|600px]]

===Serious SEXPs are Serious===

Now let's get real serious with events here. Make the following events. Don't worry about the chain delays right now, we'll go through each event one by one.

[[File:axm_ingamejumptut_013.jpg|600px]]

First, "Pressed Alt-J". We're going to use this event to lock the player from his controls. We don't want him moving around and missing the warp vortex. So let's use '''player-use-ai''', clear Alpha 1's goals (Alpha 1 actually receives orders when you tell Alpha or Everyone to do something, so we need to clear those), and tell Alpha 1 to play dead with a priority so high that the player cannot tell himself to do anything. Then let's lock all our weapons and afterburner to make it complete. The AI sexps can be found in AI and IFF and the lock sexps can be found in Subsystems and Cargo.

Now when we tell the ai-player to play-dead, he's going to stop. This might be odd, since ships still have speed when they warp. So let's use '''ship-lat-maneuver'''. It allows us to tell ships to move any way we want, but there is a catch. Any movement from the player or AI can completely stop this. Since the ai is set to play-dead, we shouldn't have any problems. I've set the sexp to make Alpha 1 use 33% forward thrust for 15000 ms (15 seconds, that should be good for our entire sequence). ship-lat-maneuver can be found Coordinate Manipulation.

Also give it some directive text so our player knows he can jump and what button to press. If you didn't already know, the $ signs around a key will change if someone has remapped it. So if I remapped Alt-J to Spacebar, it would show up as "Jump to Aquinas Station, Press Spacebar".

[[File:axm_ingamejumptut_014.jpg|600px]]

Next, Warm Up! We'll use this to play the subspace warm up sound and flash a gauge. Delay here is 0, so it could be put in with the last event, but I got limited space here. '''hud-display gauge''' can be found in Hud and '''play-sound-from-file''' can be found in Music and Sound.

'''hud-display-gauge''' only works with the warpout gauge right now. Basically you put in how long you want it to appear in milliseconds and select warpout. For here we're going to go with 4 seconds.

'''play-sound-from-file''' lets us play... sounds from a file. Madness, I know. We just tell it what sound to play and that's it! The FS2 sound used for subspace drive warm up is called rev1.wav, so we'll put that in. It can play anything from a sounds or music folder, but only one sound at a time. One other thing to remember is that this sexp will make the sound play as music. So if you have your music volume turned down, you won't hear anything from that sexp.

Alternatively, you can make a training message, assign it to play rev1.wav using the training-msg sexp instead, and it will play on the voice channel. This might be required if you are already using play-sound-from-file for something else like music.

'''Cool note from the future:''' In builds 3.6.16 and beyond, you can also use play-sound-from-table using the sound index 50. There are a bunch of coordinates that appear with the sexp, but you can safely ignore them since the sound isn't a true 3d sound (which requires those).

[[File:axm_ingamejumptut_015.jpg|600px]]

===warp-effect and Relative Coordinates===

Now for the fun part. Show Warp 1. Can you find the magical '''warp-effect''' sexp in Special? There's a lot of arguments here! Let's look at what the arguments do for a second.

* 1: Origin X
* 2: Origin Y
* 3: Origin Z

These are where the effect will appear.

* 4: Location X
* 5: Location Y
* 6: Location Z

These are where the effect is going to point.

*7: Radius

This is how big the effect is going to be.

* 8: Duration in seconds (values smaller than 4 are ignored)

Gee, I wonder.

* 9: Warp opening sound (index into sounds.tbl)
* 10: Warp closing sound (index into sounds.tbl)

For reference 45 is a warp sound for fighter arrivals, 46 is a warp sound for fighters departures (45 and 46 are the same sound in FS2, warp_1.wav), 69 is a warp sound for capital ships arriving (warp_open.wav) and 70 is a warp sound for capital ships warp vortices closing (warp_close.wav).

* 11: Type (0 for standard blue [default], 1 for Knossos green)

Self explanatory as well.

* 12: Shape (0 for 2-D [default], 1 for 3-D)

It's probably a good idea to keep this at zero. If its 0 and people have the 3d warp flag on, the game will turn it into a 3d effect anyway.

Ok, so now lets set the Delay to 4 so the effect appears when our hud gauge is finished flashing.

==== Making Mistakes ====

'''''NOW WE ARE GOING TO MAKE SOME MISTAKES.'''''
'''You don't need to do this part unless you like redoing work.'''

Making the warp effect appear infront of the player is easy, but you need to understand WHY some certain sexps act the way they do. To do that, we're going to take chances and make mistakes!

Origin of our effect should be about 100m in front of the player. So you might think X and Y should just be Alpha 1's position, and then we add 100 to the Z coordinate. Let's try that and see what happens. For now we'll just change the Origin and Location and leave the rest as default.

[[File:axm_ingamejumptut_016.jpg|600px]]

Let's try this in game.

[[File:axm_ingamejumptut_017.jpg|600px]]

Hey wait! That worked just like we wanted. Why did I say this was wrong? Let's try it again only move the player a bit.

[[File:axm_ingamejumptut_018.jpg|600px]]

We... missed the warp hole. Why? Because we're using a global coordinate system here. Let's look at what we told FRED.

* Origin X = '''get-object-x''' Alpha 1
* Origin Y = '''get-object-y''' Alpha 1
* Origin Z = '''get-object-z''' Alpha 1 + 100

So if we never move from 0,0,0, then the warp origin appears at 0,0,100. Which as we can see from the pic, is exactly where the player is facing.

[[File:axm_ingamejumptut_019.jpg|600px]]

But if we rotate the player a bit...

[[File:axm_ingamejumptut_020.jpg|600px]]

The player's location didn't change, so the warp effect is still going to appear at 0,0,100. But the player isn't facing 0,0,100 anymore.

Let's take a look at the '''get-object-*''' sexp a little closer...

'''get-object-z'''
* Returns the absolute Z coordinate of a set of coordinates relative to a particular object (or object's subsystem). The input coordinates are the coordinates relative to the object's position and orientation. If no input coordinates are specified, the coordinate returned is the coordinate of the object (or object's subsystem) itself. Takes 1 to 5 arguments...
* 1: The name of a ship, wing, or waypoint.
* 2: A ship subsystem (or "<none>" if the first argument is not a ship - optional).
* 3: The relative X coordinate (optional).
* 4: The relative Y coordinate (optional).
* 5: The relative Z coordinate (optional).

Look at those WORDS. What on Earth do they mean? Well first, if there are no optional arguments, the sexp just returns the global coordinate of the ship or subsystem. Thats what we were going before. But if the relative X Y Z coordinates are there, it will return a coordinate that is X, Y, Z from the ship, taking in account its own position and orientation.

Well that was easy, we just need to do something like this then, right?

[[File:axm_ingamejumptut_021.jpg|600px]]

Let's try it out.

[[File:axm_ingamejumptut_022.jpg|600px]]

We're still off! But why?!

If we look at the sexp, we see we're only changing the Z coordinate. So the sexp is keeping the warp effect on X=0 and Y=0. Here's a pic to show this.

[[File:axm_ingamejumptut_023.jpg|600px]]

Warp Point:1 is where we want our warp effect to appear, but Warp Point:2 is where the game is calculating it to be. The solution is easy. We just tack on the rest the same optional arguments to '''get-object-x''' and '''-y'''! It should look something like this.

[[File:axm_ingamejumptut_046.jpg|600px]]

Basically we tell the game to place a warp effect so that its X, Y, and Z coordinates are 0,0,100 from the player. Easy peasey. Let's try it.

[[File:axm_ingamejumptut_024.jpg|600px]]

Hooray! I moved my fighter so he's facing something totally different, and yet the warp effect still appears directly in front of me.

MISTAKE TIME IS OVER. Add that stuff to your event now! Then lets tweak the size of the effect so it doesn't completely block our view at first. And modify the sounds so they are the fighter style ones, 45, and 46.

[[File:axm_ingamejumptut_025.jpg|600px]]

=== Fading Through Space and Time ===

Now lets move on to the most easiest event ever. Fade Out 1. Chain delay it for 2 seconds. And add in a '''fade-out''' sexp for 1000 ms, set the second argument to fade to white. '''fade-out''' is found in the cutscenes event menu.

[[File:axm_ingamejumptut_026.jpg|600px]]

The fade out will help with our transition into subspace. The subspace corridor is optional, but you might want it there for rule of cool. If you're jumping across the system you might want a quick flash to one. We're going to add one to this example anyway.

So in our next event, Subspace Corridor, we'll put in a Chain Delay of 1, so as soon as the fade out is finished, we'll fade into the subspace corridor. We'll use the '''mission-set-subspace''' sexp to put us in subspace for a bit. The '''mission-set-subspace''' sexp is found in Backgrounds and Nebula. Set it to 1 and we'll be set. And for fun let's turn shields off, those don't work in subspace!

And finally let's move the player far far away so he doesn't see anything that might ruin the experience. Even though we made the background a subspace corridor, everyone is still around fighting. So we're going to move him to 0,50000,0 and make him face 0,50000,1000. So the player will be 50km above everyone and since the controls are still locked, he can't see the battle still going on below him. This is where you would make ships depart if you weren't going to see them for the rest of the mission (such as if you were going from planet to planet in a mission).

[[File:axm_ingamejumptut_027.jpg|600px]]

Ok, so lets make a new Fade Out event for our transition back to normal space. Name it Fade Out 2 and chain delay it by 5 seconds. We're going to cram the last warp effect and fade out sexps together here. Just copy and paste them.

[[File:axm_ingamejumptut_048.jpg|600px]]

Time for Fade In + Move Player. Chain Delay of 1 here people. Now we're going to move and orient the player, make another warp effect and fade back in. We'll do all the moving and stuff first so the fade in only starts after we're finished goofing around. I put a pair of waypoints down to use as an anchor. You can just key in the coordinates yourself, but if you need to move the warp in position, its a lot easier to do by just moving a waypoint. The first waypoint is going to be where we drop Alpha 1 and the second will be what he's going to face.

[[File:axm_ingamejumptut_047.jpg|600px]]

Set up your sexps like so.

[[File:axm_ingamejumptut_028.jpg|600px]]

[[File:axm_ingamejumptut_029.jpg|600px]]

We're going to make our warp effect real short and we'll keep the default sounds so you hear the closing one when the vortex starts to close. You're sick of hearing the normal effect by now, aren't you? This is also where you would set up ships to instantly arrive or change backgrounds if you wanted.

Then finally in Regain Player Control, we set a chain delay of 1 and we remove the locks on weapons and give control back to the player. And shields. Can't forget shields.

[[File:axm_ingamejumptut_030.jpg|600px]]

Let's give it a whirl!

===Finishing It Off===

Cool, wasn't it?

But we left before the battle was over. Command would not look too kindly on this! (If you did stay, then kudos)

Let's set up some events to only allow the player to leave after the two Fenrises have been killed.

[[File:axm_ingamejumptut_031.jpg|600px]]

Boy, that was easy. But we are missing one thing.

The way the key-press sexp works is that as soon as you press a key, a key-pressed check against the key will remain true even if you pressed it once 15 minutes ago. So if we chain "Pressed Alt-J" under Kill Fenrises, and we press Alt-J before the Fenrises are dead, nothing happens. But as soon as those Fenrises die, the game goes down the chain and checks to see if Alt-J was ever pressed. And it was. So it warps you right away! The key-reset sexp will reset the key pressed status. So lets set up this chain.

[[File:axm_ingamejumptut_032.jpg|600px]]

Now what happens if we want to jump out in the end? We don't actually have a subspace drive on our fighter. By using the '''force-jump''' sexp, you can force the player to jump into subspace, even if he doesn't have a subspace drive. Set up the events like we did before. Remember to '''key-reset'''! The only caveat is that you cannot cancel a forced-jump by hitting escape. Oh well...

== Jumping In Other Fighters==

Now what about my fighter friends? They didn't warp. There's a few things you can do here. Fighters are pretty small, so you can modify their position at the same time as the player without too much notice. But if you MUST do all the proper warp effects for your wingmen, we're going to go into AXEM'S PERFECT FRED CLASS.

A degree in conditional arguments is required to make sense of this. If you don't know what those are, then you're done here.

I'm going to fly through this, so hold on to your hats.

[[File:axm_ingamejumptut_033.jpg|600px]]

First we kill the AI in the rest of Alpha wing.

[[File:axm_ingamejumptut_034.jpg|600px]]

Then we make the warp effects appear.

[[File:axm_ingamejumptut_035.jpg|600px]]

Then we move them somewhere safe for a bit. We'll make them go -50000m down so the player won't see them. Collisions shouldn't be a big deal, but we can make them invulnerable if you wish. Just remember to take that off later.

Next we'll need to place them by the player. Let's use waypoints like we did with the player. We won't bother with orientation too much.

[[File:axm_ingamejumptut_036.jpg|600px]]

Now we move them by the player once he's been placed and do a bunch of other stuff, like clear the play dead orders. (Which just got cut off from the last pic :( )

[[File:axm_ingamejumptut_037.jpg|600px]]

[[File:axm_ingamejumptut_038.jpg|600px]]

[[File:axm_ingamejumptut_039.jpg|600px]]

And that, as they say, is that. If you give it a try, the fighters should warp out with you and warp in when you warp in.

Here's a link to the mission file so you can see what the finished product looks like and identify anything you might have done wrong.

[https://sectorgame.com/fsfiles/repo/download/ZGF0YS9BeGVtL090aGVyL0luTWlzc2lvbkp1bXBUdXRvcmlhbC9heGVtX21pY3JvanVtcF9wbGF5ZXJfZmluYWwuZnMy/h/c9069b7c68ece4ef96e3417aaf179ea6 Finished Tutorial Missile File]

[[Category:FRED Examples]][[Category:Tutorials]]

Tutorial - In-Mission Jumps

2018-07-15T19:21:23Z

Axem: Replaced dead links

Today we're gonna look at how to make in-mission subspace jumps!

They're easy to make and contain 57% of your daily spinning blue content.

All you need is a FreeSpace Open, version 3.6.12 at the very least.

== Capital Ship Micro Jumps ==

=== Setting up the mission ===

First lets set up a super simple mission! Open up FRED and make something like this.

[[File:axm_ingamejumptut_000.jpg|600px]]

Here's a link to the blank mission if you're too lazy to make it yourself.

[[https://sectorgame.com/fsfiles/repo/download/ZGF0YS9BeGVtL090aGVyL0luTWlzc2lvbkp1bXBUdXRvcmlhbC9heGVtX21pY3JvanVtcF9ibGFuay5mczI=/h/c4035bdfe9c8946fbd04ed460d23f7bc Blank Mission]]

Okay, so now let's start some magic. Let's move Aquinas Station about 30 klicks out. Then let's make a new Aeolus cruiser. We're going to name it Ascendant#2. We'll place Ascendant#2 close to Aquinas Station.

[[File:axm_ingamejumptut_001.jpg|600px]]

[[File:axm_ingamejumptut_002.jpg|600px]]

For ship names, FreeSpace will ignore anything past the # sign. Older missions that might have tried this would have used non-ASCII characters, like a "á" or "ó". Since those characters aren't in the font files, they show up as blanks. But if FreeSpace ever gets true TTF support, guess which missions are going to look pretty funny!

NOTE: This happens in wing names too to a certain detriment. Naming a wing Alpha#2 will make the fighter names be Alpha#2 1, Alpha #2 2 and etc. But since anything past the # will be ignored, in game all you're going to see is Alpha, Alpha, Alpha, and Alpha. So its not a good idea to do this for fighters. We'll get around that later.

So for Ascendant#2's arrival cue, we're going to set it to when Ascendant has departed. You can insert a delay, but for these relatively small distances for FTL, its going to be near instant anyway.

[[File:axm_ingamejumptut_003.jpg|600px]]

Then we'll make the Ascendant's depart cue to leave after 5 seconds.

[[File:axm_ingamejumptut_004.jpg|600px]]

Okay, let's go run the mission real quick. We should have the Ascendant warp out and then warp in again, right next to Aquinas Station.

"Gee Axem, I'm not THAT dumb. I could have figured that out by myself!"

I see I have underestimated you. Let's kick it up a notch. Let's increase the depart time for the Ascendant to 30 seconds.

[[File:axm_ingamejumptut_040.jpg|600px]]

Now lets add a hostile cruiser, a Fenris. Let's name it the Gosforth. And since we're going to be lazy with this, lets just tell it to attack the Ascendant.

[[File:axm_ingamejumptut_041.jpg|600px]]

The resulting battle should now damage the Ascendant to a degree. Let's replay this mission now!

[[File:axm_ingamejumptut_005.jpg|600px]]

To no one's surprise, the Ascendant takes out the Gosforth in under 30 seconds. Without beams. With that task finished, the Ascendant warps to Aquinas Station...

[[File:axm_ingamejumptut_006.jpg|600px]]

and is miraculously healed from its injuries...

[[File:axm_ingamejumptut_007.jpg|600px]]

Makes sense, the two ships are technically different to the game. So let's fix this with some events now!

===Using ship-copy-damage===

We're going to make two events. "Make Ascendant Warp Out" and "Copy Damage". Copy Damage will be chained to the warp out event, with a delay of around 3 seconds. Set up the events inside like so. You can see I've basically moved the departure cue to its own event and I'm just referencing that event now.

[[File:axm_ingamejumptut_008.jpg|600px]]

You can find '''ship-copy-damage''' under Change -> Special.

'''ship-copy-damage''' copies the damage stats for one ship and modifies them to any number of ships. The only requirement is that our original ship must present in the mission. It can't have already left. But anyone that is on the receiving end doesn't have to be there yet.

Now why is there a delay? Why not just put ship-copy-damage right with our depart event? Well it takes time for the ship to speed up and actually depart. In that time the ship can take damage. So if we fire it too early, the damage won't be totally accurate. So we'll put up a small delay before we actually copy the damage. Not that it matters here too much... Hey let's add a second hostile Fenris, the Ledberg.

[[File:axm_ingamejumptut_009.jpg|600px]]

Play time!

[[File:axm_ingamejumptut_010.jpg|600px]]

So the Ascdendant was leaving with around 82% hull...

[[File:axm_ingamejumptut_011.jpg|600px]]

and arrives with 81% hull! (Also note the damage on the flak cannon, damage from subsystems carries over too!)

[[File:axm_ingamejumptut_012.jpg|600px]]

Something must have hit it on its way out. Man, if you had had used the ship-copy-damage too early, you would have people calling you names because that ship healed itself by 1%.

Well, now you know how to make larger ships micro-jump! That ends this episode of... Oh, you were here looking for how to do player micro-jumping.

Okay, let's do that too. Why should the Ascendant be the only ship that saves itself 17 minutes by warping there. And here I am using my sub-light drives like a sucker.

== Player In-Game Jumps ==

This is the mission file at this stage. It includes everything for the capital ship micro-jump tutorial.

[https://sectorgame.com/fsfiles/repo/download/ZGF0YS9BeGVtL090aGVyL0luTWlzc2lvbkp1bXBUdXRvcmlhbC9heGVtX21pY3JvanVtcF9wbGF5ZXJibGFuay5mczI=/h/cbeecfcfe112798e9476e9dd8c963126 Blank Player Jump Mission]

===The Thought Process===

Let's think about how we want the micro jump to work.

Obviously we want to press something and have a warp effect appear, then we have something like a fade to white, maybe a subspace corridor, then another fade to white and we appear at our destination. Sounds simple enough!

Let's go in order here.

"Obviously we want to press something..."

What key? Alt-J? Sounds cool. But wait, that basically ends the mission anyway. Hey can't we just never-warp the player, like in that SOC mission? We can! Problem solved, right?

[[File:axm_ingamejumptut_042.jpg]]

[[File:axm_ingamejumptut_043.jpg]]

Oh, that doesn't look good. It would be kind of odd for that to pop up while you activate your jump drive... and jump.

Ok, let's scrap that event and go to the Misc screen on Alpha 1's Ship Editor. We're going to tick the "No Subspace Drive" box. So now when he hit Alt-J, the game sees that box and goes "You don't have a Subspace drive, so I'm not going to do anything!"

[[File:axm_ingamejumptut_045.jpg|600px]]

===Serious SEXPs are Serious===

Now let's get real serious with events here. Make the following events. Don't worry about the chain delays right now, we'll go through each event one by one.

[[File:axm_ingamejumptut_013.jpg|600px]]

First, "Pressed Alt-J". We're going to use this event to lock the player from his controls. We don't want him moving around and missing the warp vortex. So let's use '''player-use-ai''', clear Alpha 1's goals (Alpha 1 actually receives orders when you tell Alpha or Everyone to do something, so we need to clear those), and tell Alpha 1 to play dead with a priority so high that the player cannot tell himself to do anything. Then let's lock all our weapons and afterburner to make it complete. The AI sexps can be found in AI and IFF and the lock sexps can be found in Subsystems and Cargo.

Now when we tell the ai-player to play-dead, he's going to stop. This might be odd, since ships still have speed when they warp. So let's use '''ship-lat-maneuver'''. It allows us to tell ships to move any way we want, but there is a catch. Any movement from the player or AI can completely stop this. Since the ai is set to play-dead, we shouldn't have any problems. I've set the sexp to make Alpha 1 use 33% forward thrust for 15000 ms (15 seconds, that should be good for our entire sequence). ship-lat-maneuver can be found Coordinate Manipulation.

Also give it some directive text so our player knows he can jump and what button to press. If you didn't already know, the $ signs around a key will change if someone has remapped it. So if I remapped Alt-J to Spacebar, it would show up as "Jump to Aquinas Station, Press Spacebar".

[[File:axm_ingamejumptut_014.jpg|600px]]

Next, Warm Up! We'll use this to play the subspace warm up sound and flash a gauge. Delay here is 0, so it could be put in with the last event, but I got limited space here. '''hud-display gauge''' can be found in Hud and '''play-sound-from-file''' can be found in Music and Sound.

'''hud-display-gauge''' only works with the warpout gauge right now. Basically you put in how long you want it to appear in milliseconds and select warpout. For here we're going to go with 4 seconds.

'''play-sound-from-file''' lets us play... sounds from a file. Madness, I know. We just tell it what sound to play and that's it! The FS2 sound used for subspace drive warm up is called rev1.wav, so we'll put that in. It can play anything from a sounds or music folder, but only one sound at a time. One other thing to remember is that this sexp will make the sound play as music. So if you have your music volume turned down, you won't hear anything from that sexp.

Alternatively, you can make a training message, assign it to play rev1.wav using the training-msg sexp instead, and it will play on the voice channel. This might be required if you are already using play-sound-from-file for something else like music.

'''Cool note from the future:''' In builds 3.6.16 and beyond, you can also use play-sound-from-table using the sound index 50. There are a bunch of coordinates that appear with the sexp, but you can safely ignore them since the sound isn't a true 3d sound (which requires those).

[[File:axm_ingamejumptut_015.jpg|600px]]

===warp-effect and Relative Coordinates===

Now for the fun part. Show Warp 1. Can you find the magical '''warp-effect''' sexp in Special? There's a lot of arguments here! Let's look at what the arguments do for a second.

* 1: Origin X
* 2: Origin Y
* 3: Origin Z

These are where the effect will appear.

* 4: Location X
* 5: Location Y
* 6: Location Z

These are where the effect is going to point.

*7: Radius

This is how big the effect is going to be.

* 8: Duration in seconds (values smaller than 4 are ignored)

Gee, I wonder.

* 9: Warp opening sound (index into sounds.tbl)
* 10: Warp closing sound (index into sounds.tbl)

For reference 45 is a warp sound for fighter arrivals, 46 is a warp sound for fighters departures (45 and 46 are the same sound in FS2, warp_1.wav), 69 is a warp sound for capital ships arriving (warp_open.wav) and 70 is a warp sound for capital ships warp vortices closing (warp_close.wav).

* 11: Type (0 for standard blue [default], 1 for Knossos green)

Self explanatory as well.

* 12: Shape (0 for 2-D [default], 1 for 3-D)

It's probably a good idea to keep this at zero. If its 0 and people have the 3d warp flag on, the game will turn it into a 3d effect anyway.

Ok, so now lets set the Delay to 4 so the effect appears when our hud gauge is finished flashing.

==== Making Mistakes ====

'''''NOW WE ARE GOING TO MAKE SOME MISTAKES.'''''
'''You don't need to do this part unless you like redoing work.'''

Making the warp effect appear infront of the player is easy, but you need to understand WHY some certain sexps act the way they do. To do that, we're going to take chances and make mistakes!

Origin of our effect should be about 100m in front of the player. So you might think X and Y should just be Alpha 1's position, and then we add 100 to the Z coordinate. Let's try that and see what happens. For now we'll just change the Origin and Location and leave the rest as default.

[[File:axm_ingamejumptut_016.jpg|600px]]

Let's try this in game.

[[File:axm_ingamejumptut_017.jpg|600px]]

Hey wait! That worked just like we wanted. Why did I say this was wrong? Let's try it again only move the player a bit.

[[File:axm_ingamejumptut_018.jpg|600px]]

We... missed the warp hole. Why? Because we're using a global coordinate system here. Let's look at what we told FRED.

* Origin X = '''get-object-x''' Alpha 1
* Origin Y = '''get-object-y''' Alpha 1
* Origin Z = '''get-object-z''' Alpha 1 + 100

So if we never move from 0,0,0, then the warp origin appears at 0,0,100. Which as we can see from the pic, is exactly where the player is facing.

[[File:axm_ingamejumptut_019.jpg|600px]]

But if we rotate the player a bit...

[[File:axm_ingamejumptut_020.jpg|600px]]

The player's location didn't change, so the warp effect is still going to appear at 0,0,100. But the player isn't facing 0,0,100 anymore.

Let's take a look at the '''get-object-*''' sexp a little closer...

'''get-object-z'''
* Returns the absolute Z coordinate of a set of coordinates relative to a particular object (or object's subsystem). The input coordinates are the coordinates relative to the object's position and orientation. If no input coordinates are specified, the coordinate returned is the coordinate of the object (or object's subsystem) itself. Takes 1 to 5 arguments...
* 1: The name of a ship, wing, or waypoint.
* 2: A ship subsystem (or "<none>" if the first argument is not a ship - optional).
* 3: The relative X coordinate (optional).
* 4: The relative Y coordinate (optional).
* 5: The relative Z coordinate (optional).

Look at those WORDS. What on Earth do they mean? Well first, if there are no optional arguments, the sexp just returns the global coordinate of the ship or subsystem. Thats what we were going before. But if the relative X Y Z coordinates are there, it will return a coordinate that is X, Y, Z from the ship, taking in account its own position and orientation.

Well that was easy, we just need to do something like this then, right?

[[File:axm_ingamejumptut_021.jpg|600px]]

Let's try it out.

[[File:axm_ingamejumptut_022.jpg|600px]]

We're still off! But why?!

If we look at the sexp, we see we're only changing the Z coordinate. So the sexp is keeping the warp effect on X=0 and Y=0. Here's a pic to show this.

[[File:axm_ingamejumptut_023.jpg|600px]]

Warp Point:1 is where we want our warp effect to appear, but Warp Point:2 is where the game is calculating it to be. The solution is easy. We just tack on the rest the same optional arguments to '''get-object-x''' and '''-y'''! It should look something like this.

[[File:axm_ingamejumptut_046.jpg|600px]]

Basically we tell the game to place a warp effect so that its X, Y, and Z coordinates are 0,0,100 from the player. Easy peasey. Let's try it.

[[File:axm_ingamejumptut_024.jpg|600px]]

Hooray! I moved my fighter so he's facing something totally different, and yet the warp effect still appears directly in front of me.

MISTAKE TIME IS OVER. Add that stuff to your event now! Then lets tweak the size of the effect so it doesn't completely block our view at first. And modify the sounds so they are the fighter style ones, 45, and 46.

[[File:axm_ingamejumptut_025.jpg|600px]]

=== Fading Through Space and Time ===

Now lets move on to the most easiest event ever. Fade Out 1. Chain delay it for 2 seconds. And add in a '''fade-out''' sexp for 1000 ms, set the second argument to fade to white. '''fade-out''' is found in the cutscenes event menu.

[[File:axm_ingamejumptut_026.jpg|600px]]

The fade out will help with our transition into subspace. The subspace corridor is optional, but you might want it there for rule of cool. If you're jumping across the system you might want a quick flash to one. We're going to add one to this example anyway.

So in our next event, Subspace Corridor, we'll put in a Chain Delay of 1, so as soon as the fade out is finished, we'll fade into the subspace corridor. We'll use the '''mission-set-subspace''' sexp to put us in subspace for a bit. The '''mission-set-subspace''' sexp is found in Backgrounds and Nebula. Set it to 1 and we'll be set. And for fun let's turn shields off, those don't work in subspace!

And finally let's move the player far far away so he doesn't see anything that might ruin the experience. Even though we made the background a subspace corridor, everyone is still around fighting. So we're going to move him to 0,50000,0 and make him face 0,50000,1000. So the player will be 50km above everyone and since the controls are still locked, he can't see the battle still going on below him. This is where you would make ships depart if you weren't going to see them for the rest of the mission (such as if you were going from planet to planet in a mission).

[[File:axm_ingamejumptut_027.jpg|600px]]

Ok, so lets make a new Fade Out event for our transition back to normal space. Name it Fade Out 2 and chain delay it by 5 seconds. We're going to cram the last warp effect and fade out sexps together here. Just copy and paste them.

[[File:axm_ingamejumptut_048.jpg|600px]]

Time for Fade In + Move Player. Chain Delay of 1 here people. Now we're going to move and orient the player, make another warp effect and fade back in. We'll do all the moving and stuff first so the fade in only starts after we're finished goofing around. I put a pair of waypoints down to use as an anchor. You can just key in the coordinates yourself, but if you need to move the warp in position, its a lot easier to do by just moving a waypoint. The first waypoint is going to be where we drop Alpha 1 and the second will be what he's going to face.

[[File:axm_ingamejumptut_047.jpg|600px]]

Set up your sexps like so.

[[File:axm_ingamejumptut_028.jpg|600px]]

[[File:axm_ingamejumptut_029.jpg|600px]]

We're going to make our warp effect real short and we'll keep the default sounds so you hear the closing one when the vortex starts to close. You're sick of hearing the normal effect by now, aren't you? This is also where you would set up ships to instantly arrive or change backgrounds if you wanted.

Then finally in Regain Player Control, we set a chain delay of 1 and we remove the locks on weapons and give control back to the player. And shields. Can't forget shields.

[[File:axm_ingamejumptut_030.jpg|600px]]

Let's give it a whirl!

===Finishing It Off===

Cool, wasn't it?

But we left before the battle was over. Command would not look too kindly on this! (If you did stay, then kudos)

Let's set up some events to only allow the player to leave after the two Fenrises have been killed.

[[File:axm_ingamejumptut_031.jpg|600px]]

Boy, that was easy. But we are missing one thing.

The way the key-press sexp works is that as soon as you press a key, a key-pressed check against the key will remain true even if you pressed it once 15 minutes ago. So if we chain "Pressed Alt-J" under Kill Fenrises, and we press Alt-J before the Fenrises are dead, nothing happens. But as soon as those Fenrises die, the game goes down the chain and checks to see if Alt-J was ever pressed. And it was. So it warps you right away! The key-reset sexp will reset the key pressed status. So lets set up this chain.

[[File:axm_ingamejumptut_032.jpg|600px]]

Now what happens if we want to jump out in the end? We don't actually have a subspace drive on our fighter. By using the '''force-jump''' sexp, you can force the player to jump into subspace, even if he doesn't have a subspace drive. Set up the events like we did before. Remember to '''key-reset'''! The only caveat is that you cannot cancel a forced-jump by hitting escape. Oh well...

== Jumping In Other Fighters==

Now what about my fighter friends? They didn't warp. There's a few things you can do here. Fighters are pretty small, so you can modify their position at the same time as the player without too much notice. But if you MUST do all the proper warp effects for your wingmen, we're going to go into AXEM'S PERFECT FRED CLASS.

A degree in conditional arguments is required to make sense of this. If you don't know what those are, then you're done here.

I'm going to fly through this, so hold on to your hats.

[[File:axm_ingamejumptut_033.jpg|600px]]

First we kill the AI in the rest of Alpha wing.

[[File:axm_ingamejumptut_034.jpg|600px]]

Then we make the warp effects appear.

[[File:axm_ingamejumptut_035.jpg|600px]]

Then we move them somewhere safe for a bit. We'll make them go -50000m down so the player won't see them. Collisions shouldn't be a big deal, but we can make them invulnerable if you wish. Just remember to take that off later.

Next we'll need to place them by the player. Let's use waypoints like we did with the player. We won't bother with orientation too much.

[[File:axm_ingamejumptut_036.jpg|600px]]

Now we move them by the player once he's been placed and do a bunch of other stuff, like clear the play dead orders. (Which just got cut off from the last pic :( )

[[File:axm_ingamejumptut_037.jpg|600px]]

[[File:axm_ingamejumptut_038.jpg|600px]]

[[File:axm_ingamejumptut_039.jpg|600px]]

And that, as they say, is that. If you give it a try, the fighters should warp out with you and warp in when you warp in.

Here's a link to the mission file so you can see what the finished product looks like and identify anything you might have done wrong.

[https://sectorgame.com/fsfiles/repo/download/ZGF0YS9BeGVtL090aGVyL0luTWlzc2lvbkp1bXBUdXRvcmlhbC9heGVtX21pY3JvanVtcF9wbGF5ZXJfZmluYWwuZnMy/h/c9069b7c68ece4ef96e3417aaf179ea6 Finished Tutorial Missile File]

[[Category:FRED Examples]][[Category:Tutorials]]

Game settings.tbl

2015-06-14T23:40:25Z

Axem: /* #GRAPHICS SETTINGS */ Adding new pain flash factors

{{SCP_table}}

{{TableVersion|11089}}

The '''game_settings.tbl''', also known as mod.tbl, defines options that can be changed globally.

This table is one of the [[Modular Tables]] and can be extended with xxx-mod.tbm

[[Tables|List of Tables]]

==#CAMPAIGN SETTINGS==
Optional. This group contains various Campaign related settings and overrides. 

===$Default Campaign File Name:===
Defines which campaign will be selected by default for new pilots. A file extension is not needed and, if present, is removed by the code.
*Syntax: '''''String''''' 

===#Ignored Campaign File Names===
Optional. Defines which campaigns, if present, will not appear in the Campaign Room. Only single-player campaigns can be ignored. ''File extensions are required.''
{{Table371|As of 3.7.1, file extensions are not required and, if present, are removed by the code.}}
====$Campaign File Name:====
File name of the campaign to ignore. Multiple entries may exist.
*Syntax: '''''String''''' 

===$Red-alert applies to delayed ships:===
Controls whether red-alert saved statistics (hitpoints, weapons, subsystem strengths) will be restored for ships that are not present at mission start.
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

==#HUD SETTINGS==
Optional. This group contains various HUD behavior settings and overrides 

===$Directive Wait Time:===
*Defines how long the game will wait before displaying a directive.
*Syntax: '''''Integer''''' 
*Values: '''''Greater than or equal to 0 ms'''''

===$Cutscene camera displays HUD:===
Show the HUD when the cutscene camera is enabled.
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

In earlier versions of the code, this option was controlled by $Cutscene camera disables HUD: and had a default of YES.

===$Full color head animations:===
Enables full-color head ANIs. Normal head ANIs will appear in gray.
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

In earlier versions of the code, this option was controlled by $Color head animations with hud colors: and had a default of YES.

==#SEXP SETTINGS==
Optional. This group contains SEXP settings and overrides. 

===$Loop SEXPs Then Arguments:===
Flips how when-argument settings loop. See: [http://www.hard-light.net/forums/index.php?topic=79602.0 SEXP Argument changes via mod.tbl]
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

===$Use Alternate Chaining Behavior:===
When set, this makes the event chaining behavior act as people expected it to be in [http://scp.indiegames.us/mantis/view.php?id=82 Mantis #82].
*Syntax: '''''Boolean''''' 
*Default Value: '''''NO'''''

==#GRAPHICS SETTINGS==
Optional. This group contains settings related to graphics. 

===$Enable External Shaders:===
Enables the use of external shader files. By default, the engine will use the built-in shaders.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO''''' 

===$Default Detail Level:===
{{Table3615|
Determines which graphics detail level preset (low, medium, high, very high) acts as the default for new pilots.
*Syntax: '''''Integer''''' (0-3)
*Default Value: '''''3''''' (very high) }}

===$Briefing Window FOV:===
{{Table371|
Determines the FOV in the briefing Icon window. Retail default for this is 0.29375, previous versions of FSO used a value of 0.5.
*Syntax: '''''Float''''' (0.0 to 1.0)
*Default Value: '''''0.29375''''' }}

===$Generic Pain Flash Factor:===
{{Table373|
Determines the intensity of the pain red flash when the player is hit.
*Syntax: '''''Float'''''
*Default Value: '''''1.0''''' }}

===$Shield Pain Flash Factor:===
{{Table373|
Determines the intensity of a pain flash when the player's shields are hit. Color will match the current ships shield color defined in ships.tbl. A value of 0 will give retail behavior (no shield effect). Positive values will cause the effect to start at full intensity at full shields and go to next to no intensity at zero shields. Negative values will cause no effect at full shields and full effect at no shields. Values should be kept between -1.0 and 1.0 for good pilot visibility.
*Syntax: '''''Float'''''
*Default Value: '''''0.0''''' }}

==#SOUND SETTINGS==
Optional. This group contains sound-related settings 

===$Default Sound Volume:===
{{Table371|
*Defines the default sound fx volume for new pilots.
*Syntax: '''''Float''''', between 0.0 and 1.0 
*Default Value: '''''1.0'''''}}

===$Default Music Volume:===
{{Table371|
*Defines the default music volume for new pilots.
*Syntax: '''''Float''''', between 0.0 and 1.0 
*Default Value: '''''0.5'''''}}

===$Default Voice Volume:===
{{Table371|
*Defines the default voice volume for new pilots.
*Syntax: '''''Float''''', between 0.0 and 1.0 
*Default Value: '''''0.7'''''}}

==#FRED SETTINGS==
Optional. This group contains settings for FRED. 

===$Disable Hard Coded Message Head Ani Files:===
{{table371|
If set, FRED will not fill the head ani selection in the Event Editor with the retail head ani filenames.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO''''' }}

==#OTHER SETTINGS==
Optional. This group contains miscellaneous settings. 

===$Fixed Turret Collisions:===
Makes all hits to a turret's barrels count as hits to the turret subsystem. By default, this does not happen unless the point of impact falls inside the model radius of the turret's base.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO''''' 

===$Damage Impacted Subsystem First:===
If set, a hit to a physical subsystem will always deal damage to that subsystem first, even if another subsystem is closer to the point of impact. By default, the closest subsystem will always receive damage first.
*Syntax: '''''Boolean'''''
*Default Value: '''''NO''''' 

===$Default ship select effect:===
{{Table3615|
*This specifies which effect to use for ship select animations when no .ani can be found, or the -ship_choice_3d commandline flag is active. This will default to the FS2 effect.
*Possible options are "FS2", "FS1", and "off"}}

===$Default weapon select effect:===
{{Table3615|
*This specifies which effect to use for weapon select animations when no .ani can be found, or the -weapon_choice_3d commandline flag is active. This will default to the FS2 effect.
*Possible options are "FS2", "FS1", and "off"}}

===$Weapons inherit parent collision group:===
{{Table3615|
*When set to true, Weapons fired by a ship will inherit their parents' collision group setting. Default is false.}}

===$Flight controls follow eyepoint orientation:===
{{Table371|
*Specifies that if the player ship's eyepoint happens to rotate into a non-standard orientation, pitch and yaw axes should stay relative to the eyepoint orientation, not the ship. Note that this does not affect the pitch/yaw turning speed, which always remains relative to the ship. Default is false.}}

===$Beams Use Damage Factors:===
{{Table371|
*Specifies that beam weapons will use the tabled damage factors for Armour, Shields and Subsystems. Default is false (i.e. all factors are treated as 1.0)}}

==#END==
Required. The last line of the table must be #END

==Sample Entry==

#CAMPAIGN SETTINGS
$Default Campaign File Name: NewCampaignFile

#Ignored Campaign File Names
$Campaign File Name: FreeSpace2.fc2

#HUD SETTINGS
$Directive Wait Time: 5000

#SEXP SETTINGS
$Loop SEXPs Then Arguments: True

#OTHER SETTINGS
$Self Praise Percentage: 75

#END

[[Category:Tables]]

Scripting.tbl

2015-06-14T23:32:54Z

Axem: /* Actions */ Adding new Afterburner and Beam Fire conditionals

{{SCP_table}}

{{TableVersion|11242}}

The '''scripting.tbl''' is used for scripting special features like alternate HUDs or ship viewer into the game.

This table is one of the [[Modular Tables]] and can be extended with xxx-sct.tbm

[[Tables|List of Tables]]

==General Info==
*Scripting table consist of several sections identified by a hash mark preceeding the section name (i.g. #Global Hooks)
*All sections ''must'' end with #'''End'''
*All sections are optional
*Most entries are optional
*Scripting hooks are '''not''' executed on a separate thread (at least as of this writing). They are executed at given points in the code, and all other execution will not take place until a scripting hook has finished. Therefore, large and complicated scripts will most likely cause noticeable lag or slowdown when executed.
{{Template:Note|1=Information on this page does not apply to pre-3.6.10 builds}}
 

==Useful references==
*'''[[FS2 Open Lua Scripting]]'''
*'''[[Scripting API]]'''

*'''[[Scripting functions]]'''
*'''[[Command-Line_Reference#-output_scripting|Command-Line Reference for creating scripting.html]]'''
*'''[http://lua-users.org/wiki/ Lua-Users Wiki]'''
*'''[http://www.lua.org/manual/5.0/ Reference manual for Lua 5.0]'''

==Prerequisites==

===Frames===
One of the most important things to understand when reading this guide is the concept of "frames". (Experienced modders can probably skip this part) In gameplay, motion is achieved by making incremental changes every fraction of a second. A ship will be moved slightly, and then drawn to the screen. This happens 30-120 times a second; anything lower, and the game will become choppy and difficult to play.

There is also a difference in the moving of objects in-game, and the moving of objects onscreen. All ships are first "moved", in memory. This probably consists of physics calculations, that change the ship's position based on if their engines are turned on, or if they run into another object. After this, the game then renders the now-moved ships to what is referred to as a "backbuffer" - a place in memory that takes the place of the computer screen. Once rendering has finished, the backbuffer is instantly drawn to the screen. This prevents objects from flickering as they are drawn. You do not have to worry about flipping the backbuffer in scripting; FS2_Open will take care of that for you.

For scripting, '''it is important to understand that each block of code will therefore be executed several times a second, but only once per frame'''. However, the exact number of times per second will depend on how much work the computer has to do (And therefore how much time it takes) for each frame. To determine how much time you should consider to have passed, you must use the ba.getFrametime() function; which will return the approximate time the frame will take, in seconds. In addition, if you "move" a ship after it has already been rendered, the change will not become apparent until the next frame.

This does mean that if you want to make a block of text move across the screen, at a rate of 5 pixels per second, all you have to do is multiply the speed by the frametime:
<pre>#Global Hooks
$Global: [
--If the g_WheeXPosition variable does not exist,
--it means we are on the first frame.
--If that is the case, set it to zero.
if not g_WheeXPosition then
g_WheeXPosition = 0
end

--Move the text
g_WheeXPosition = g_WheeXPosition + (5 * ba.getFrametime())

--Draw "WHEE!!!"
gr.drawString("WHEE!!!", g_WheeXPosition, 10)
]
#End</pre>
 

===Hooks===
Scripting "hooks" form the basis of the scripting system. A "hook" simply refers to a point in the code where code to execute scripting has been added. The hook may then be added to a table, or added to a SEXP. In general usage, "hook" refers to an entry in scripting.tbl.

All hooks take the form of an identifer (such as $Global:), followed by brackets to determine what type of scripting is being executed. A lack of brackets also indicates a type of scripting execution. All current bracket configurations are listed below. Note that "$Hook:" is used merely as a placeholder, and should be replaced with the actual hook name ($Global:, $HUD:, $On Frame:, etc).
#<pre>$Hook: scripting</pre>Specifies one line of LUA scripting. In addition, the return value of that line will be passed to the interpreter and used (if applicable). Specifying a variable or value on this line will result in it being returned, as well.
#<pre>$Hook: [scripting]</pre>A single set of brackets specifies a block of LUA scripting. Does not return a value unless explicitly specified. (Explicit specification is not possible at this time; but may be implemented in the future if/when more future hooks take a return value.)
#<pre>$Hook: [[scriptfilename.lua]]</pre>Double brackets specify a file. This file is read out of the data/scripts directory, and must include the file extension. You may specify a compiled lua file as a target as well; this may result in crossplatform issues for a mod, however.
 

====+Override====
Some hooks additionally take a +Override: field. This field uses the same bracket configurations as above. If a hook includes a +Override field, this hook always determines whether the default FS2_Open behavior that the hook is associated with will function, or will be disabled. This should be used in cases where scripting will replace the original FS2_Open behavior. For example:
<pre>$HUD: [
gr.setColor(255, 255, 255, 255)
gr.drawString("HUD Disabled", 50, 50)
]
+Override: true</pre>

Additionally, override hooks are (by convention) executed before FS2_Open behavior. The HUD hook override, for example, is executed before any part of the HUD is actually drawn.
 

==Sections==

===#Global Hooks===
Global hooks are the simplest form of scripting hooks available. They are at preset locations in the code, and are generally executed every time that point is reached. Exceptions to this rule (such as the HUD hook) only depend on one or two variables to determine execution. All other scripting execution is determined by the modder.
Note that, as with other tables, the game expects these entries in precisely the order given here; if this is not followed, the parser will throw an error.
 

====$Global:====
Script in this section is executed almost immediately before each frame is drawn. This means that any scripting elements will be drawn, or take effect, after everything else, except for the "On Frame" conditional hook. It is not used with the standalone server. In addition, note that use of this hook should generally be avoided, since all scripting will have to be processed every frame.
 

====$Splash:====
This hook is executed once, when the splash images (PreLoad and PreLoadLogo) would be drawn. This hook should generally be used only for drawing the splash screen; any initialization could should be placed in GameInit. This hook is executed before virtually any other subsystem has been loaded, aside from the graphics and filesystem subsystems, so scripting elements such as the table and mission libraries will be nonfunctional.
 

=====+Override:=====
Executed just before default splash images are loaded and displayed. Note that the frame is still drawn regardless; it is not necessary to flip the backbuffer manually.
 

====$GameInit:====
This hook is executed once, after all of the Freespace2 subsystems have been initialized. It is executed before the game switches to the main hall or, in the case of standalone server mode, begins the game.
 

====$Simulation:====
This hook is executed only during missions. It is executed after all damage, movement, physics, SEXPs, and other "physical" in-game changes have been applied. It is executed before anything has been rendered. This hook should be used only for damage, movement, and physics related scripting, as if the game needs to be rendered without any in-game time having been passed, this function will not be called.
 

====$HUD:====
The HUD hook is executed after the HUD has been drawn. Note that if the HUD is turned off, this hook will be disabled as well, until the HUD is turned back on.
 

=====+Override:=====
Executed immediately before anything on the HUD is drawn, and controls whether the default FS2_Open is drawn.
 

===#State Hooks===
In Freespace2, a "state" more or less refers to a room. It may also refer to a separate mode - playing a mission is the GS_STATE_GAME_PLAY state. The main menu is the GS_STATE_MAIN_MENU state. This section should only exist in 3.6.9. It is included here for the sake of documentation; it has since been removed (Dec 2006) and superseded by the conditional hook system.
 

=====$State:=====
Specifies the state name. A full list of states is located here: ''[[List of Game States]]''

=====$Hook:=====
Executed after all of the state code has been executed, but before the game frame is actually drawn.

======+Override:======
Determines whether the specified state is handled at all by Freespace. If true, then none of the loading or exit code for the state will be specified as well.

===#Conditional Hooks===
Scripting hooks have been available since Sep 2006. They consist of any number of conditions, followed by any number of actions. All available conditions and actions are located in the file generated by -output_scripting.

One way to think of conditional scripting is like this: The condition specifies the object that the action will apply to, or the place that the action will occur in. All conditions must be met for their associated actions to execute. Actions are associated with a set of conditions by simply adding them after that set of conditions. (Obviously, you may want to space out each pair of action/condition sets in the TBL to make it easier to read.)

The flexibility of conditional scripting comes in due to its inherent scalability. If you specify a mission and ship condition with a warpin action, that script will only be executed when the ship warps in on that particular mission. Removing the mission field will make that warpin scripting apply to the ship for all missions; or removing the ship field will make the warpin scripting apply to all ships in that mission.

This prompts the question: if this is all conditional scripting does, why not just use the global hook?
#Organization - conditional scripting is generally easier to read and modify because it is grouped in a standardized manner.
#Speed - All conditions can be evaluated by FS2_Open itself, without invoking the Lua interpreter at all.
#Scalability - As of the time of this writing, you can only have one global hook. Modular tables will simply replace it. With conditional scripting, if you want to specify additional actions for a set of conditions in a modular table file, you may do so.

;Format

;'''$Condition:''': Where "$Condition:" is one of several conditions specified in scripting.html, such as $State: or $Ship:. Takes a value representing the object the condition should be checked against (such as a state, ship, or mission name)
;'''$Condition:''': ...
;'''...''':
;'''$Action:''': Where "$Action:" is one of several actions specified in scripting.html, such as $On Frame or $On Warp In. Takes a scripting hook, using the bracket configuration outlined at the top of this article.
;'''$Condition:''': ...
;'''...''':

A brief description of all Conditions and Actions at the time of this writing:

====Conditions====

=====$State:=====
Controls execution based on what state FS2_Open is in, such as the main hall, options screen, or in a mission.
*The full list of states can be found here: ''[[List of Game States]]''

=====$Campaign:=====
Controls execution based on the current campaign's filename. (It is under consideration to change this to the campaign's name, instead).

=====$Mission:=====
Controls execution based on the filename of the last mission to have started. This condition will remain true even after the mission has been exited until another mission is started.

=====$Object Type:=====
Defines a specific object type that the action will apply for, such as a "Ship", "Asteroid", or "Jump Node".

=====$Ship:=====
Defines a specific ship (name) that the action will apply for.

=====$Ship class:=====
Defines a specific ship class (name) that the action will apply for.

=====$Ship type:=====
Defines a specific ship type (name) that the action will apply for.

=====$Weapon class:=====
Defines a specific weapon class (name) that the action will apply for.

=====$KeyPress:=====
Defines a specific key that the action will apply for.
*Experimental.

=====$Action:=====
{{Table371|
Defines a specific control that the action will apply for. For example "Fire Primary Weapon" or "Match Target Speed".
}}

====Actions====

=====$On Game Init:=====
Executes immediately after game has been started.
::* No associated hook variables.

=====$On Splash Screen:=====
Executes when initial game splash screen is shown
::* No associated hook variables.

=====$On State Start:=====
Executed when specified game state starts
::* No associated hook variables.

=====$On Frame:=====
Executes immediately after the global scripting hook, which is right before the frame is drawn.
::* No associated hook variables.

=====$On Key Pressed:=====
Executed when specified key is pressed
::* '''Key''', The pressed key

=====$On Key Released:=====
Executed when specified key is released
::* '''Key''', The released key

=====$On Mouse Moved:=====
Executed when mouse is moved
::* No associated hook variables.

=====$On Mouse Pressed:=====
Executed when mouse button is pressed
::* No associated hook variables.

=====$On Mouse Released:=====
Executed when mouse button is released
::* No associated hook variables.

=====$On State End:=====
Executed when specified game state ends
::* No associated hook variables.

=====$On Mission Start:=====
Executed when mission starts
::* No associated hook variables.

=====$On Gameplay Start:=====
{{Table3615|
Executed when the gameplay part of a mission starts
::* No associated hook variables.}}

=====$On HUD Draw:=====
Executed after the HUD has been drawn. Note that if the HUD is turned off, this hook will be disabled as well, until the HUD is turned back on
::* '''Self''', the viewer (object)

=====$On Ship Collision:=====
Executes when the specified object collides with a ship. Sets a handle in the HookVariables library with the name of the object type ("Weapon", "Debris", and so on) with the type of the object. If both objects are ships, the other object gains the name "ShipB". (If both ship objects define a collision hook, the variables will be swapped for the other ship, so the ship that the script is executing for will always be called "Script".) The override will disable FS2_Open code, as well as the other object's collision code. If both objects have an override set, only one of the objects' hooks will be used (Chosen arbitrarily). Note that the override receives the same variables.
::* When colliding something other than other ship:
::** '''Ship''', the ship (object)
::** '''Debris''', '''Asteroid''', '''Weapon''', depending what it collided with (object)
::** '''Self''', the object referred by the condition (object)
::** '''Object''', the ship (object)
::* When colliding with other ship:
::** '''Ship''', the ship (object) referred by the condition (object)
::** '''ShipB''', the other ship (object)
::** '''Self''', the ship (object) referred by the condition (object)
::** '''Object''', the other ship (object)

=====$On Weapon Collision:=====
Like the ship collision hook, but for weapons.
::* When colliding something other than other weapon:
::** '''Weapon''', the weapon (object)
::** '''Debris''', '''Asteroid''', '''Ship''', depending what it collided with (object)
::** '''Self''', the object the weapon collided with (object)
::** '''Object''', the weapon (object)
::* When colliding with other weapon:
::** '''Weapon''', the weapon (object) referred by the condition
::** '''WeaponB''', the other weapon (object)
::** '''Self''', the weapon (object) referred by the condition
::** '''Object''', the other weapon (object)

=====$On Debris Collision:=====
Like the ship collision hook, except for debris.
::* '''Debris''', the debris (object)
::* '''Weapon''', '''Ship''', depending what it collided with (object)
::* '''Self''', the object the debris collided with (object)
::* '''Object''', the debris (object)

=====$On Asteroid Collision:=====
Like the ship collision hook, only for asteroids.
::* '''Asteroid''', the asteroid (object)
::* '''Weapon''', '''Ship''', depending what it collided with (object)
::* '''Self''', the object the asteroid collided with (object)
::* '''Object''', the asteroid (object)

=====$On Object Render:=====
Executes when the specified object is rendered. The override is run before the object is rendered, and both the hook and its override receive an "Object" variable of the object to be rendered.
::* '''Self''', the object rendered (object)

=====$On Warp In:=====
Run when a ship has begun warping in, immediately after everything has been set up for per-frame processing. This hook is only executed once, when the ship begins warping in. An override will disable _all_ behavior related to warpin. Both the hook and an override receive an "Object" handle in the HookVariables library, with the type of the object that is warping in.
::* '''Self''', the object warping in (object)

=====$On Warp Out:=====
Same as warping in, except for warping out.
::* '''Self''', the object warping out (object)

=====$On Death:=====
*Currently only valid for ships.
Receives "Self" and "Killer" variables of the object and killer, respectively. Overriding it will override all default death behavior.
::* For asteroids:
::** '''Self''', the asteroid (object)
::* For ships:
::** '''Self''', the ship (object)
::** '''Killer''', the other object (object) - NOTE, not guaranteed to exists

=====$On Mission End:=====
Run on mission end.
::* No associated hook variables.
=====$On Weapon Equipped:=====
{{Table3613|
Runs once each frame, for every ship that has the weapon defined in the $Weapon class condition equipped.
::* '''User''', the ship carrying the weapon
::* '''Target''', the ships' current target
}}

=====$On Weapon Fired:=====
{{Table3613|
Runs once when a ship fires a weapon defined in the $Weapon class condition
::* '''User''', the ship carrying the weapon
::* '''Target''', the ships' current target
}}

=====$On Weapon Selected:=====
{{Table3613|
Runs once when a bank with a weapon defined in the $Weapon class condition is selected
::* '''User''', the ship carrying the weapon
::* '''Target''', the ships' current target
}}

=====$On Weapon Deselected:=====
{{Table3613|
Runs once when a bank with a weapon defined in the $Weapon class condition is deselected
::* '''User''', the ship carrying the weapon
::* '''Target''', the ships' current target
}}

=====$On Turret Fired:=====
{{Table3615|
Executed when a turret fires.
::* '''Ship''', the parent ship
::* '''Weapon''', the weapon which was fired
::* '''Target''', the intended target
}}

=====$On Ship Arrive:=====
{{Table371|
Executed when a ship arrives.
::* '''Ship''', the arriving ship
::* '''Parent''', the ship acting as the anchor when arrival location is "in front of ship", "near ship" or "docking bay"; nil or invalid handle otherwise
}}

=====$On Action:=====
{{Table371|
Executed when an action is triggered, regardless of which key or button it is bound to. Does currently not trigger on mouse or joystick movements.
::* '''Action''', the textual description of the action (for example "Fire Primary Weapon" or "Match Target Speed")
}}

=====$On Action Stopped:=====
{{Table371|
Executed when a continuous action is released (for example "Fire Primary Weapon", "Turn Left" or "Afterburner").
::* '''Action''', the textual description of the action
}}

=====$On Message Received:=====
{{Table371|
Executed when the player receives a message.
::* '''Name''', the message name that was received. The message handle can be accessed with mn.Messages[hv.Name]
::* '''Message''', the message text that would be displayed on the message gauge. Takes in account scrambled messages and variable replacements.
::* '''SenderString''', the displayed string that shows the origin of the message.
::* '''Builtin''', boolean, true if the message was a builtin message (eg: automatic messages from Command or wingmen)
::* '''Sender''', object handle of the ship that sent the message. This might not always be valid, so check is :isValid() if you need to use it
}}

=====$On HUD Message Received:=====
{{Table371|
Executed when the HUD should display a message. This is similar to $On Message Received but it will also receive messages that were not generated by a message (e.g "Firing artillery" for SSM strikes).
::* '''Text''', the plain text of the message
::* '''SourceType''', a number representing the type of the sender. The number can be one of the following:
:::* ''0'' A message sent by the computer
:::* ''1'' A training message
:::* ''2'' A message from a hidden source
:::* ''3'' An important message (this type is currently unused)
:::* ''4'' An failed message (this type is currently unused)
:::* ''5'' An satisfied message (this type is currently unused)
:::* ''6'' An message sent by (Terran) command
:::* ''7'' A multiplayer message
:::* ''≥8'' When the type is grater or equal to 8 then the source is one of the teams in the mission. You can get a team handle using mn.Team[hv.SourceType - 7] (as lua uses 1 based indexes)
}}

=====$On Afterburner Engage:=====
{{Table373|
Executed when a ship engages its afterburner.
::* '''Ship''', the ship object of the ship engaging its afterburner
}}

=====$On Afterburner End:=====
{{Table373|
Executed when a ship stops its afterburner.
::* '''Ship''', the ship object of the ship stopping its afterburner
}}

=====$On Beam Fire:=====
{{Table373|
Executed when a beam is fired. This will occur after warm up is complete, as the beam starts to render and give damage.
::* '''Beam''', the beam object being fired
::* '''User''', the parent ship object firing the beam
::* '''Target''', the target object that the beam is trying to hit. Not guaranteed to exist!
}}

==Misc. Hook Variables:==

===Viewer===
*Active if (non-player) viewing object is valid

===Player===
*Active if player obj is valid
 

==Examples==

See [[:Category:Scripting Examples|Scripting Examples category]]

[[Category:Tables]]

Tutorial - FSOpen and LUA 3 - Conditional Actions and Hooks

2014-12-02T01:12:31Z

Axem: Another new LUA tutorial!

So we have the basics on how the scripts in FreeSpace work. A script gets called, and we modify things, commonly with handles of objects within FreeSpace. So far we've only really called our scripts through the script-eval*. But there are so many other ways to call a script. Probably the best way will be through conditional hooks.

(Technically we run part of our script in On Game Init where we define the actual functions)

As I alluded to in the first tutorial, conditional hooks only occur when a certain action happens. You can look at the [[scripting.tbl | page]] on the wiki for a complete list of conditional hooks and any hook variables and are associated with it. So we can use that fact to introduce some real fun with the game. Before these would require actual code requests, but with the magic of Lua, we can just script it!

Instead of this tutorial being overbearing with me rambling on for paragraphs, I'm just going to post some excessively documented scripts and hopefully it should be enough for you to see how and why certain things are done.

The two scripts I'm going to cover is a healing beam and remote activated warheads (think like the Infyrno/Piranha, only the detonation would happen after impact).

First, we will need some new weapons...

== Weapons Table ==
(These two entries require assets from the 2014 mediavps)
<pre>#Primary Weapons

$Name: HealBeam#Tutorial
$Model File: none
@Laser Bitmap: laserglow01
@Laser Color: 0, 255, 54
@Laser Length: 0.0
@Laser Head Radius: 0.3
@Laser Tail Radius: 0.3
$Mass: 100.0
$Velocity: 1600.0
$Fire Wait: 30.0
$Damage: 50
$Armor Factor: 0.0
$Shield Factor: 0.0
$Subsystem Factor: 0.0
$Lifetime: 25.0
$Energy Consumed: 0.30
$Cargo Size: 0.0
$Homing: NO
$LaunchSnd: 124
$ImpactSnd: 88
$Flags: ("Big Ship" "huge" "beam")
$Impact Explosion: ExpMissileHit1
$Impact Explosion Radius: 60.0
$BeamInfo:
+Type: 0
+Life: 7.5
+Warmup: 3500
+Warmdown: 3500
+Radius: 120.0
+PCount: 20
+PRadius: 5.0
+PAngle: 60.0
+PAni: particle_green
+Miss Factor: 1.0 1.1 1.1 1.7 1.4
+BeamSound: 115 ;; the looping beam-firing sound
+WarmupSound: 154 ;; associated warmup sound
+WarmdownSound: 158 ;; associated warmdown sound
+Muzzleglow: beamglow3
+Shots: 0
+ShrinkFactor: 0.0
+ShrinkPct: 0.0
$Section:
+Width: 45.0
+Texture: TerBeam1Core
+RGBA Inner: 255 255 255 255
+RGBA Outer: 150 150 150 10
+Flicker: 0.0
+Zadd: 4.0
+Translation: 10
$Section:
+Width: 70.0
+Texture: TerBeam2Core
+RGBA Inner: 160 160 0 255
+RGBA Outer: 60 60 0 10
+Flicker: 0.45
+Zadd: 3.0
+Translation: 7
$Section:
+Width: 80.0
+Texture: TerBeam2Glow
+RGBA Inner: 255 255 255 255
+RGBA Outer: 150 150 150 10
+Flicker: 0.4
+Zadd: 2.0
+Translation: 5
$Section:
+Width: 100.0
+Texture: TerBeam2GlowHaze
+RGBA Inner: 255 0 0 255
+RGBA Outer: 60 0 0 10
+Flicker: 0.5
+Zadd: 0.0
+Translation: 2

#End

#Secondary Weapons

$Name: Harpoon-RC#Tutorial
+Title: XSTR("GTM-19c Harpoon-Claymore", -1)
+Description:
XSTR(
"Standard Issue
Fast Target Lock
Remote Control Detonate", -1)
$end_multi_text
+Tech Title: XSTR("GTM-19c Harpoon-Claymore", -1)
+Tech Anim: Tech_Harpoon
+Tech Description:
XSTR(
"A modified version of the Harpoon missile. This variant has an armor piercing nosecose that embeds itself in the hull of an enemy ship, allowing the pilot to detonate the warhead at their discretion. While it has a limited role in an active combat zone, it is a favorite for cloak and dagger types in Special Operations.", -1)
$end_multi_text
$Model File: crossbow.pof
$Mass: 15.0
$Velocity: 250.0
$Fire Wait: 2.0
$Damage: 100 ;; damage applied when within inner radius
$Blast Force: 60.0
$Inner Radius: 20.0 ;; radius at which damage is full (0 for impact only)
$Outer Radius: 40.0 ;; max radius for attenuated damage
$Shockwave Speed: 0 ;; velocity of shockwave. 0 for none.
$Armor Factor: 0.0
$Shield Factor: 0.0
$Subsystem Factor: 0.0
$Lifetime: 5.0
$Energy Consumed: 0.0 ;; Energy used when fired
$Cargo Size: 2.5 ;; Amount of space taken up in weapon cargo
$Homing: YES
;; the following indented fields are only required when $Homing is YES
+Type: ASPECT ;; Legal: HEAT, ASPECT
+Turn Time: 1.0
+Min Lock Time: 2.0 ;; Minimum lock time (in seconds)
+Lock Pixels/Sec: 70 ;; Pixels moved per sec while locking
+Catch-up Pixels/Sec: 100 ;; Pixels moved per sec while catching up
+Catch-up Penalty: 30 ;; Extra pixels to move after catching up
$LaunchSnd: 91 ;; The sound it makes when fired
$ImpactSnd: 88 ;; The sound it makes when it hits something
$FlyBySnd: -1
$Rearm Rate: 2.0 ;; number of missiles/sec that are rearmed
$Flags: ( "player allowed")
$Trail:
+Start Width: 0.3
+End Width: 0
+Start Alpha: 1.0
+End Alpha: 0.0
+Max Life: 2.5
+Bitmap: missiletrail06
$Icon: iconCrossbow
$Anim: cross
$Impact Explosion: ExpMissileHit1
$Impact Explosion Radius: 9.92
$Piercing Impact Explosion: exp06
$Piercing Impact Radius: 4.96
$Piercing Impact Velocity: 20
$Piercing Impact Splash Velocity: -5
$Piercing Impact Variance: 0.1
$Piercing Impact Particles: 5
$Thruster Flame Effect: missilethruster06
$Thruster Glow Effect: missileglow06

#End</pre>

== Healing Beam Script ==
<pre>#Conditional Hooks
$Application: FS2_Open
$On Game Init:
[
function BeamHeal(ship) --We're expecting a ship type handle to be passed through

if ship:isValid() then --Always check to see if these things are valid to be used!

local healStep = ship.HitpointsMax * 0.002 --The heal rate is proportional to max health, so all ships heal to the max within the same amount of time. Alternatively healStep could be the damage of the weapon.
--I'll leave that as a fun excercise for you to try! (Hint: you'll need an additional argument to get passed through in the function)

if ship.HitpointsLeft <= ship.HitpointsMax then --It would be a good idea to only try to heal ships that have less than max health!

--The ship in question will get its HP healed by healStep, so we should take what the end result would be after healing and make sure it won't go over the maximum amount of HP. If it doesn't we can just heal like normal, but if it does go over, we should just make it cap at max HP.

--Mind you we could just heal and check afterwards if HP is over MaxHP, but it's probably better to ensure we touch ship properties as little as possible.

if ship.HitpointsLeft + healStep <= ship.HitpointsMax then
ship.HitpointsLeft = ship.HitpointsLeft + healStep
else
ship.HitpointsLeft = ship.HitpointsMax
end

end

--In a ship's handle, there are all the normal attributes, but if we use [] indices on the ship handle, we get the subsystem handles.
--So ship["communications"] should give us the communications subsystem. But does our ship have engine or engine01 and engine02?
--Instead of explicitly going after the names of subsystem, we can just go through the whole thing with numerical indices.

--for you people with some lua knowledge already, "for k,v in pairs()" won't work for these "virtual indexed" type of tables (they are slow for real time actions, so don't use them if you can avoid it!)
--the best way is to go through these type of tables is to get the size of the table, assign it to a variable, then do a for loop through everything
--real time looping should always be done with a numerical loop!

local numSubsys = #ship --#ship is the number of subsystems on the ship that we should heal

for i=1, numSubsys do

--We'll do the same type of checks on HP here as we did with the main health.

if ship[i].HitpointsLeft <= ship[i].HitpointsMax then
if ship[i].HitpointsLeft + healStep <= ship[i].HitpointsMax then
ship[i].HitpointsLeft = ship[i].HitpointsLeft + healStep
else
ship[i].HitpointsLeft = ship[i].HitpointsMax
end
end

end

end

end
]

$Weapon class: HealBeam#Tutorial
$On Ship Collision:
[
--[[
Here the the conditional hook is Weapon Class, and we've defined it to only look at the HealBeam#Tutorial class.
We change the $Weapon class: to weapons to make other weapons heal.
Our action is On Ship Collision, and one of the hook variables for that action is hv.Object, which is the Object that has been collided with. So this bit of code will only run with HealBeam#Tutorial collides with a ship!
]]--

BeamHeal(hv.Object)

]
#End</pre>

==Remote Activated Warhead Detonation Script==
<pre>#Conditional Hooks
$Application: FS2_Open
$On Game Init:
[

RCD = {} --Empty table object to get us started. Read up on Lua's Object Oriented flavored methods for more info on this sort of thing.

function RCD:Init()

--But just a quick FYI, when we're within a function using that special colon operator, like we are right now, "self" is a special local variable that fills in for the parent object. So if we do "self.Enabled = true" this is the same as "RCD.Enabled = true"

--The colon operator also inserts self into the first argument of the function. Again, check out the lua documentation for more on that!

--We don't need to worry about defining variables as local if we're defining variables that are members of a larger table object. These variables are already local to just this table/object/class/whatever anyway!

self.Enabled = true --We may wish to stop our script, so let's have an enabled variable
self.List = {} --List will contain the list of ships that we hit and the local offsets of the hit.
self.ExecuteKey = "D" --When we hit the ExecuteKey, we will detonate all charges
self.CheatKey = "5" --Cheating to give ourselves the weapon... for test purposes of course!

end

function RCD:AddToList(weapon, object)

--We're expected to get a weapon and the object that the weapon has hit

local t = {} --t is going to be our temporary table before we officially insert it into self.List

t.Damage = weapon.Class.Damage --Damage taken from the weapon, note that in the table the hull/shield/subsystem factors are all zero, so the initial hit will do no damage, but the actual damage will still get stored in here

--Time for some 3d math, folks!
--Small 3d math function reference
--To go from a local relative offset to a global world vector:
--globalVector = referenceOrientation:unrotateVector(localVector)

--To go from a global world vector to a local relative offset:
--localVector = referenceOrientation:rotateVector(globalVector)

--weapon.Position is a global world vector, and because our target is going to be flying around a lot, when we choose to detonate, that position will be too far away to damage our target. So we will use those functions to discover the local relative position to the hit object, and when we want to detonate we'll run the function in reverse to get the global world coordinates again.

t.Offset = object.Orientation:rotateVector(weapon.Position) - object.Position

t.Object = object:getSignature() --Rather than saving an entire ship handle, which can get big and clumsy, we'll just grab the object signature

self.List[#self.List+1] = t --table[#table+1] is a easy build up a continous numerical table

end

function RCD:CauseDamage()

--There is no createExplosion() function, so we'll have to use the SEXP with mn.runSEXP()

local listLength = #self.List --First find out how many charges we've got to blow up

for i = 1, listLength do

local boom = self.List[i] --self.List[i] is so tedious to type
local target = mn.getObjectFromSignature(boom.Object) --We need this to get the global position
local pos = target.Position + target.Orientation:unrotateVector(boom.Offset) --And now we unrotate the offset from last time

--Boom!
mn.runSEXP("( explosion-effect " .. pos.x .. " " .. pos.y .. " " .. pos.z .. " " .. boom.Damage .. " 10 100 10 100 0 0 7 )")

end

--After we've gone through the entire list, we will revert the list back to an empty object
self.List = {}

end
]

$On Gameplay Start:
[
--On Gameplay Start will only occur right after the briefing is done, as gameplay begins.
RCD:Init()
]

$Weapon class: Harpoon-RC#Tutorial
$On Ship Collision:
[

--For the Harpoon-RC#Tutorial, upon hitting a ship we should...
--Add it to a list!
if RCD.Enabled then
RCD:AddToList(hv.Weapon, hv.Object)
end

]

$State: GS_STATE_GAME_PLAY
$On Key Released:
[

--During gameplay, when any key is released, this block of code will be run. The important hook variable here is hv.Key, so we check that to see if it matches any keys and if so, we'll do run some functions.

if RCD.Enabled then
if hv.Key == RCD.ExecuteKey then
RCD:CauseDamage()
end

--Comment out this part if we want to not allow cheating, this is only for testing anyway...
if hv.Key == RCD.CheatKey then
hv.Player.SecondaryBanks[1].WeaponClass = tb.WeaponClasses["Harpoon-RC#Tutorial"]
end
end
]

#End</pre>

Here's a [http://lazymodders.fsmods.net/files/LuaTutorial.rar link to a complete sample mod] with a test mission.

If you're unfamiliar with anything I did, check out the [http://www.lua.org/docs.html Lua Documentation website] or shoot me (Axem) a PM on the hard-light forums.

If you're curious about the fastest methods to do certain things in Lua during time-critical events (such as during On HUD Draw or On Frame), check out [http://springrts.com/wiki/Lua_Performance these benchmarks] done on some various methods.

Hopefully this gets you on your way to crafting fun and amazing scripts for FreeSpace!

User:Axem

2014-12-02T00:54:08Z

Axem: /* Tutorials */ Another fun tutorial

==About Axem!==
Hello! I am Axem, friendly administrator on the HLP forums. I can FRED (make missions), model, UVMap, texture, script and make rough effects. Just don't ask me to do any of it for you, I've got enough to do! But I can help guide you to the right path. Below you'll find some of the stuff I've done here over the years.

==My Campaigns==
*[[Shadows of Kraken]]
*[[Just Another Day]]
*[[Just Another Day 2: Electric Boogaloo]]
*[[Just Another Day 3: Shivans on a Plane]]
*[[Vassago's Dirge]]
*[[Just Another Day 2.21: You Are (Not) Alpha 1]]

==Projects I Help With==
*[[Diaspora]]
*[[Blue Planet]]
*[[Wings of Dawn]]

==My Ships==

*[[GTC Cretheus]]
*[[SC Lamia]]
*[[SGs Asura]] (textured by Nighteyes)
*[[UES Aranyaka]]

Other WIPS can be seen on my [http://p3d.in/u/Axem p3d page]

==Helpful Pages I've Done==
===Tutorials===
*[[Tutorial - Conditional Arguments]]
*[[Tutorial - Directive-is-variable SEXP]]
*[[Tutorial - Mission Infrastructure]]
*[[Tutorial - PCS2 Kitbashing]]
*[[Tutorial - Custom HUD Gauges]]
*[[Tutorial - Fun with Simulated Hull]]
*[[Tutorial - Bitwise Operations]]
*[[Tutorial - FSOpen and LUA #1 - SEXP Library]]
*[[Tutorial - FSOpen and LUA 2 - Hook Variables and Handles]]
*[[Tutorial - FSOpen and LUA 3 - Conditional Actions and Hooks]]

===SEXP Reference===
*[[Advanced Cutscene SEXP Reference]]
===Script Reference===
*[[Script - Journal/Fluff Viewer]]
*[[Script - System Viewer]]
*[[Script - Interface Monitor]]
*[[Script - Scripted Message Gauge]]

Tutorial - FSOpen and LUA 2 - Hook Variables and Handles

2014-11-03T01:33:10Z

Axem: New LUA tutorial!

In the last tutorial, we concerned ourselves with a very simple sexp library that really requires next to no real Lua knowledge at all. We're going to take one of the examples from the last tutorial and actually add a few Lua specific things.

<pre>function Lockdown(name)

mn.runSEXP("(lock-primary-weapon !" .. name .. "! )")
mn.runSEXP("(lock-secondary-weapon !" .. name .. "! )")
mn.runSEXP("(lock-afterburner !" .. name .. "! )")
mn.runSEXP("(disable-ets !" .. name .. "! )")
mn.runSEXP("(player-use-ai )")
mn.runSEXP("(add-goal !" .. name .. "! ( ai-play-dead 200 ) )")
mn.runSEXP("(lock-perspective ( true) )")

end</pre>

Remember that? That's the function we were using to lock the player's ship down so we could do cutscene stuff. But couldn't we do something where it could just automatically affect the player's ship without needing us to input the player's ship name? It could save me like 5 seconds!

== Hook Variables ==

Of course there is. And we can do this through what is called a hook variable. Hook variables are variables that hook on to a well-defined situation or action. Most hook variables are specific to an $Action, but there are two that are nearly always valid in a gameplay setting. Player and Viewer. Player will return the player's object (or ship) if it is valid, and Viewer will return the non-player ship we are viewing from (when using target camera commands). We're just interested in the Player hook variable. All hook variables are part of the hv library, so we would refer to the player's ship with hv.Player.

A complete listing of hook variables and which $Action they apply to can be found here, on the [[Scripting.tbl#Actions| scripting.tbl page.]]

So on a line before we start the mn.runSEXPs let us add…

<pre>local player = hv.Player</pre>

Whoa, there I go again, adding new things without warning. What's local player and why are we assigning it as hv.Player?

Adding the word local in front of a variable declaration will make that variable local (which means it can only be used in the current block of code). It is good practice to use local variables whenever possible. By default, variables are global in Lua (in contrast to C related languages where variables are already local by default). By making the variable local, we can assign it a generic name without worrying that it might conflict with something else in another script. Also Lua accesses local variables faster than a global variable, so we're doing this not only for us, but for our precious CPU cycles!

== Handles ==

Okay, so we have this player variable. What can we do with it? Remember that scripting.html we might have generated in the last tutorial? (If not, open your launcher, go to the Dev Tool section, tick generate scripting.html, run the game, quit, and there should be a scripting.html in your root FreeSpace directory). Navigate over to it and open it up. Player is a "ship" type handle. A handle is our fancy name for these special variables that contain a lot of "user data", or what is specific to FreeSpace. If we scroll down a bit, in the types listing, we will find a ship type link.

If we click it we'll get jumped to ship:object. The :object part means that ship is sort of a sub-type of object. Everything in object also applies to ship. But that's not important now. Look at all of these fun properties we can use and abuse. Most of these properties are bi-directional. You can read a property or assign something a new value on the fly.

The listings here tell you what type of data will get returned if you try and read data from it, and what type of data is expected when you try and assign it a value. 99.999% of the time, those two are the same thing.

So what were we doing here again? Oh, right. We want to get the player's ship's name. Why look, here is a Name property. (Name is one of the few properties that I would highly highly super strictly never write to, missions aren't going to take the name change very nicely!) So how do we access the property? Just like this…

<pre>player.Name</pre>

So let's just add this stuff to our script from last time.

<pre>function Lockdown(name)

local player = hv.Player
name = player.Name

mn.runSEXP("(lock-primary-weapon !" .. name .. "! )")
mn.runSEXP("(lock-secondary-weapon !" .. name .. "! )")
mn.runSEXP("(lock-afterburner !" .. name .. "! )")
mn.runSEXP("(disable-ets !" .. name .. "! )")
mn.runSEXP("(player-use-ai )")
mn.runSEXP("(add-goal !" .. name .. "! ( ai-play-dead 200 ) )")
mn.runSEXP("(lock-perspective ( true) )")

end</pre>

Hey hold on, why doesn't name have local in front of it? Well, because name was defined as an argument to the function, the variable name is already local to the function. Adding local in front of name would just confuse Lua anyway.

So now when the function runs, it take the player's handle, throws it into this local variable, then when we're constructing the string for runSEXP to use, we're using the Name property from the player's handle. So wait, why do we even need that name argument? Couldn't we just modify the function declaration to be

<pre>function Lockdown()</pre>

And then make name a local variable to keep it simple?

Sure, but let's add some intelligence to this function. Let's say if we leave the argument blank, the function will lockdown the player, but if we have a ship name in there, we mean THAT ship (maybe we want to lock down an AI friend?)

So remember what I said last tutorial about empty arguments?

"NOTE: If the argument is empty and does NOT have anything in it, the argument will then "contain" a special value called nil. Nil is Lua's version of null (or empty), it basically means it does not exist. Using something that is nil will result in errors everywhere! In a later tutorial we'll do checks for nil, for now just be mindful of the arguments you pass through functions."

So we'll check if name is nil or not. For that we need an if statement! There's a few ways we can check to see if a variable is carrying something useful for us to use. Generally if its "carrying" nil, then it's not useful. To find out if we entered something into name we could go…

<pre>if name ~= nil then</pre>

So if name is not nil then we do stuff. But there's a slightly easier way to type that…

<pre>if name then</pre>

When an if statement evaluates just a lone variable, no comparisons attached or anything it will only return false if the variable is nil or false. So if name contains useful, it would pass the logic test and go through. But we don't want to know if a variable contains something useful, we're interested in the opposite.

<pre>if not name then</pre>

So now with the not operator, we've flipped the logic around. Now we'll only pass the logic test if name is nil or false. And so we will write…

<pre>if not name and hv.Player:isValid() then
local player = hv.Player
name = player.Name
end</pre>

Yeesh, what's this new stuff again? Well, we want to make sure the player is actually a valid handle to use. Otherwise, we get errors. But we couldn't just do the same thing as we did with name. hv.Player won't be nil or false if a player dies. The handle just becomes invalid, so while it would pass that logic test, but the data inside is all messed up and wrong. So many handles have a :isValid() check to it that determines if the handle is safe to use.

Well I hope this guides you on your way to lua scripting. The next tutorial will conditional actions and keeping your scripts efficient.

Final Script:

<pre>function Lockdown(name)

if not name and hv.Player:isValid() then
local player = hv.Player
name = player.Name
end

mn.runSEXP("(lock-primary-weapon !" .. name .. "! )")
mn.runSEXP("(lock-secondary-weapon !" .. name .. "! )")
mn.runSEXP("(lock-afterburner !" .. name .. "! )")
mn.runSEXP("(disable-ets !" .. name .. "! )")
mn.runSEXP("(player-use-ai )")
mn.runSEXP("(add-goal !" .. name .. "! ( ai-play-dead 200 ) )")
mn.runSEXP("(lock-perspective ( true) )")

end

function UnLockdown(name)

if not name and hv.Player:isValid() then
local player = hv.Player
name = player.Name
end

mn.runSEXP("(unlock-primary-weapon !" .. name .. "!)")
mn.runSEXP("(unlock-secondary-weapon !" .. name .. "!)")
mn.runSEXP("(unlock-afterburner !" .. name .. "!)" )
mn.runSEXP("(enable-ets !" .. name .. "!)")
mn.runSEXP("(player-not-use-ai)")
mn.runSEXP("(clear-goals !" .. name .. "!)")
mn.runSEXP("(lock-perspective ( false ) )")

end</pre>

User:Axem

2014-11-03T01:19:28Z

Axem: /* Tutorials */

==About Axem!==
Hello! I am Axem, friendly administrator on the HLP forums. I can FRED (make missions), model, UVMap, texture, script and make rough effects. Just don't ask me to do any of it for you, I've got enough to do! But I can help guide you to the right path. Below you'll find some of the stuff I've done here over the years.

==My Campaigns==
*[[Shadows of Kraken]]
*[[Just Another Day]]
*[[Just Another Day 2: Electric Boogaloo]]
*[[Just Another Day 3: Shivans on a Plane]]
*[[Vassago's Dirge]]
*[[Just Another Day 2.21: You Are (Not) Alpha 1]]

==Projects I Help With==
*[[Diaspora]]
*[[Blue Planet]]
*[[Wings of Dawn]]

==My Ships==

*[[GTC Cretheus]]
*[[SC Lamia]]
*[[SGs Asura]] (textured by Nighteyes)
*[[UES Aranyaka]]

Other WIPS can be seen on my [http://p3d.in/u/Axem p3d page]

==Helpful Pages I've Done==
===Tutorials===
*[[Tutorial - Conditional Arguments]]
*[[Tutorial - Directive-is-variable SEXP]]
*[[Tutorial - Mission Infrastructure]]
*[[Tutorial - PCS2 Kitbashing]]
*[[Tutorial - Custom HUD Gauges]]
*[[Tutorial - Fun with Simulated Hull]]
*[[Tutorial - Bitwise Operations]]
*[[Tutorial - FSOpen and LUA #1 - SEXP Library]]
*[[Tutorial - FSOpen and LUA 2 - Hook Variables and Handles]]

===SEXP Reference===
*[[Advanced Cutscene SEXP Reference]]
===Script Reference===
*[[Script - Journal/Fluff Viewer]]
*[[Script - System Viewer]]
*[[Script - Interface Monitor]]
*[[Script - Scripted Message Gauge]]

User:Axem

2014-11-03T01:19:02Z

Axem: /* Tutorials */ Adding a new tutorial

==About Axem!==
Hello! I am Axem, friendly administrator on the HLP forums. I can FRED (make missions), model, UVMap, texture, script and make rough effects. Just don't ask me to do any of it for you, I've got enough to do! But I can help guide you to the right path. Below you'll find some of the stuff I've done here over the years.

==My Campaigns==
*[[Shadows of Kraken]]
*[[Just Another Day]]
*[[Just Another Day 2: Electric Boogaloo]]
*[[Just Another Day 3: Shivans on a Plane]]
*[[Vassago's Dirge]]
*[[Just Another Day 2.21: You Are (Not) Alpha 1]]

==Projects I Help With==
*[[Diaspora]]
*[[Blue Planet]]
*[[Wings of Dawn]]

==My Ships==

*[[GTC Cretheus]]
*[[SC Lamia]]
*[[SGs Asura]] (textured by Nighteyes)
*[[UES Aranyaka]]

Other WIPS can be seen on my [http://p3d.in/u/Axem p3d page]

==Helpful Pages I've Done==
===Tutorials===
*[[Tutorial - Conditional Arguments]]
*[[Tutorial - Directive-is-variable SEXP]]
*[[Tutorial - Mission Infrastructure]]
*[[Tutorial - PCS2 Kitbashing]]
*[[Tutorial - Custom HUD Gauges]]
*[[Tutorial - Fun with Simulated Hull]]
*[[Tutorial - Bitwise Operations]]
*[[Tutorial - FSOpen and LUA #1 - SEXP Library]]
*[[Tutorial - FSOpen and LUA #2 - Hook Variables and Handles]]

===SEXP Reference===
*[[Advanced Cutscene SEXP Reference]]
===Script Reference===
*[[Script - Journal/Fluff Viewer]]
*[[Script - System Viewer]]
*[[Script - Interface Monitor]]
*[[Script - Scripted Message Gauge]]

Tutorial - FSOpen and LUA

2014-10-05T16:24:33Z

Axem: Oops forgot a pic

One of the coolest things that's been added to FreeSpace Open is the Lua scripting language. It allows a certain amount of freedom that SEXPs don't allow, but on the other hand Lua is a lot more, let's say, risky. FreeSpace has a lot of error checking and can handle any dumb SEXP efforts with a shrug. Lua runs a more unregulated campaign and, if you're not careful, can spew out baffling error messages that leave you clueless even after an hour on Google.

There's a lot of basic Lua tutorials around the internet, so I'm not going to get into the specifics too much. Read up on them if you're curious. There's just very little in the way of how FreeSpace and Lua interact with each other. If I want to do X with Lua, how would you even begin?

First we need a few tools. First is a good text editor, I suggest Notepad++! You should also generate a scripting.html file from FreeSpace. Go into your launcher and in the Dev Tool section, tick the "Output scripting to scripting.html" box. Run FreeSpace and then just quit. In your FreeSpace directory will be a scripting.html file. This will be very valuable to us, it lists all of the game accessible information we can use for our nefarious purposes.

So what is our first project going to be? A super lame "Hello World" script? Those are so overdone. Let's do something that is still simple but is also something you could actually use in your campaign, a SEXP library.

The concept of a SEXP library is simple: we have some SEXPs that we want to use in multiple missions, and instead of copy and pasting them in multiple missions, we will store them in a Lua function that can be called upon in any mission and be executed.

The SEXP library we make will contain 2 groups of SEXPs: 1. Lockdown the player's fighter's for in-game cutscenes and 2. Properly cloaking a ship (linking the stealth with the visual effect).

== 1. In-game Cutscene Lockdown ==

We've all been there haven't we? Make an in-game cutscene. Watch it, and accidently slip and press primary fire and hear your Subachs fire. Press an ETS key and hear that immersion breaking sound. It's terrible. So what do you do? Add 5 sexps that lock player weapons, afterburner, ETS etc etc. Such a pain, right? Let's rectify this by allowing us to combine all the sexps we would use into a single Lua function. That way we can just use a single script-eval function and, presto! Those sexps will all get run, no muss, no fuss.

There's quite a few ways you can run Lua scripts. This will not be the only correct way to do things, but it’s a way that I feel is easily readable and accessible. You could stuff all your scripts into a single scripting.tbl, but it might get pretty large and unwieldy if you add a lot of Lua. I like to just create smaller modular scripting tables.

Below is the basic framework of a script, saved as sexplibrary-sct.tbm. The -sct.tbm will clue FreeSpace in that this is a Lua scripting file.

<pre>#Conditional Hooks
$Application: FS2_Open
$On Game Init:
[

]
#End</pre>

First we need to tell the game what type of hook we're going to run. There are Global Hooks, State Hooks, and Conditional Hooks. Global Hooks run regardless of state or condition. I'd advise staying away from Global Hooks unless you really know what you're doing. State Hooks aren't really used anymore, the Conditional Hooks are more flexible and better. Conditional Hooks will only check actions that we define later if the condition is met. There's also other game-wise benefits to using Conditional Hooks, [[Scripting.tbl#.23Conditional_Hooks|this part]] from the scripting.tbl wiki page sums it up well enough.

So I put down ''#Conditional Hooks'', and the condition is ''$Application: FS2_Open'', and our action is ''$On Game Init:''. So basically when our application is FS2_Open (which will be… always), during game initialization do this stuff between the square brackets. And then of course our ''#End'' token.

I like to put down any function definitions in ''$On Game Init''. That way all the functions will be ready for any script to use right away. If you're really paranoid about memory usage, you could move it to an initialization function, but you still need to define it somewhere!

So next we should define the Lua function that will house our SEXPs.

<pre>function Lockdown(name)

end</pre>

Function will define Lockdown as the function and the () is where we would put in any additional arguments. Our additional argument here is just name, it will be the name of the ship that we lockdown. And the Lua interpreter needs to know when to stop the function, so that's where the end comes in.

Now we need to think what sexps we would call for ''Lockdown()''.

*Lock-primary-weapon
*Lock-secondary-weapon
*Lock-afterburner
*Disable-ETS
*Player-use-AI
*Add-Goal ai-play-dead on the player
**(alternatively ship-immobile if you're not going to use the player's ship in the cutscene)
*Lock-perspective

That's 7 sexps, surely this will increase our FREDding power by 700%!

If we look in the scripting.html and go into the mission library section, we'll find this cute little function.

''boolean '''''runSEXP'''(''string'')
:Runs the defined SEXP script
:'''Returns''': if the operation was successful

''runSEXP'', as the name implies, allows us to run a SEXP as if it was being called by a mission event. Which is funny because this function will get called by a mission event anyway! The argument to ''runSEXP'' (the part that goes in the ()) is the same text that FRED writes to events. If we make an event that is just lock-primary-weapon and look at it in a text editor, it looks like…

<pre>$Formula: ( when
( true )
( lock-primary-weapon "Alpha 1" )
)
+Name: Lock Primary Weapon
+Repeat Count: 1
+Interval: 1</pre>

But all we're really interested in is...
<pre>(lock-primary-weapon "Alpha 1")</pre>
If your sexps have line breaks in them, be sure to take those out so they are all on one line. Lua would think we're done with the sexp long before we actually are.

So our first runSEXP function would look like…

<pre>mn.runSEXP("(lock-primary-weapon !" .. name .. "!)")</pre>

Wait, hold on. What's this extra stuff I just sprung in front of you? Why is that mn there? And why are there EXCLAIMATION MARKS!! AND DOTS!

''runSEXP'' is a function that is part of a larger library, the mission library. The mission library's internal name is just mn. Anytime we want to use a function inside a library, we need to add mn. in front of it so the Lua interpreter knows where to look.

Now the argument for ''runSEXP'' is a string, and Lua sees everything between two " as a string. So if we were to just run
<pre>mn.runSEXP("(lock-primary-weapon "Alpha 1")")</pre>
The Lua Interpreter would see "lock-primary-weapon" and "". It doesn't see the Alpha 1 because it's in the middle of two pairs of "s. So there's a bit of sly substitution that goes on, all !s are replaced with "s during evaluation. So if you're using the ''runSEXP'' or ''evaluateSEXP'' functions, replace those "s in the SEXP with !s.

''name'' is a variable that has the argument that we specified before in the function definition. If we were to go...
<pre>Lockdown('Alpha 1')</pre>
Then ''name'' inside the function will be replace with "Alpha 1". The ''..'' is called a concatenation operator. Concatenation is when you combine two strings together. So we combine the "lock-primary-weapon !" string with the name variable, and then combine that with the last "!".

'''NOTE:''' If the argument is empty and does NOT have anything in it, the argument will then "contain" a special value called nil. '''Nil''' is Lua's version of null (or empty), it basically means it does not exist. Using something that is nil will result in errors everywhere! In a later tutorial we'll do checks for nil, for now just be mindful of the arguments you pass through functions.

So that's one line, let us do the same thing to other lines. It would probably be a good idea to create the sexps first in a mission, save the mission and then copy and paste the relevant lines into your script. The game expects SEXPs to be without syntax errors because FRED knows how to do it without any reminders. We fleshy humans aren't that good, so take all precautions!

So here's the full function, plus another function that undoes the SEXPs.

<pre>function Lockdown(name)

mn.runSEXP("(lock-primary-weapon !" .. name .. "! )")
mn.runSEXP("(lock-secondary-weapon !" .. name .. "! )")
mn.runSEXP("(lock-afterburner !" .. name .. "! )")
mn.runSEXP("(disable-ets !" .. name .. "! )")
mn.runSEXP("(player-use-ai )")
mn.runSEXP("(add-goal !" .. name .. "! ( ai-play-dead 200 ) )")
mn.runSEXP("(lock-perspective ( true) )")

end

function UnLockdown(name)

mn.runSEXP("(unlock-primary-weapon !" .. name .. "!)")
mn.runSEXP("(unlock-secondary-weapon !" .. name .. "!)")
mn.runSEXP("(unlock-afterburner !" .. name .. "!)" )
mn.runSEXP("(enable-ets !" .. name .. "!)")
mn.runSEXP("(player-not-use-ai)")
mn.runSEXP("(clear-goals !" .. name .. "!)")
mn.runSEXP("(lock-perspective ( false ) )")

end</pre>

To use these functions within the game, we need to call the script-eval sexp. And it would look something like…

[[file:Lockdown.png]]

Notice how I used a single quotation mark instead of a double one. The reason for this is pretty much the same as using the ! before. It’s a way to define the boundaries of a string without actually breaking the string in the process.

It's sort of hard to show these functions off with screenshots, so you'll just have to try them yourself.

== 2. Cloaking Ships + Stealth ==

There's a neat sexp in the special-effects category, ship-effect. Some of the options are cloak and decloak. The only problem is that if you cloak a ship, the effect is only visual! You can still target it. How lame is that? Sure we could just do a lot of ship-effects + ship-stealthy, but why couldn't we just do both at the same time like the Lockdown functions?

<pre>function Cloak(name)

mn.runSEXP("(ship-effect !Cloak! 1000 !" .. name .. "!)")
mn.runSEXP("(ship-stealthy !" .. name .. "!)")
mn.runSEXP("(friendly-stealth-invisible !" .. name .. "!)")

end

function Decloak(name)

mn.runSEXP("(ship-effect !Decloak! 1000 !" .. name .. "!)")
mn.runSEXP("(ship-unstealthy !" .. name .. "!)")
mn.runSEXP("(friendly-stealth-visible !" .. name .. "!)")

end</pre>

See how easy that was? Especially without me having to explain every detail?

So this is a good start into Lua with FreeSpace without actually needing to know Lua. In the next tutorial, we'll actually get into things like object handles and unique Lua magic.

== Full Table use for Tutorial ==

<pre>#Conditional Hooks
$Application: FS2_Open
$On Game Init:
[

function Lockdown(name)

mn.runSEXP("(lock-primary-weapon !" .. name .. "!)")
mn.runSEXP("(lock-secondary-weapon !" .. name .. "!)")
mn.runSEXP("(lock-afterburner !" .. name .. "!)")
mn.runSEXP("(disable-ets !" .. name .. "!)")
mn.runSEXP("(player-use-ai)")
mn.runSEXP("(add-goal !" .. name .. "! ( ai-play-dead 200 ))")
mn.runSEXP("(lock-perspective (true))")

end

function UnLockdown(name)

mn.runSEXP("(unlock-primary-weapon !" .. name .. "!)")
mn.runSEXP("(unlock-secondary-weapon !" .. name .. "!)")
mn.runSEXP("(unlock-afterburner !" .. name .. "!)" )
mn.runSEXP("(enable-ets !" .. name .. "!)")
mn.runSEXP("(player-not-use-ai)")
mn.runSEXP("(clear-goals !" .. name .. "!)")
mn.runSEXP("(lock-perspective (false))")

end

function Cloak(name)

mn.runSEXP("(ship-effect !Cloak! 1000 !" .. name .. "!)")
mn.runSEXP("(ship-stealthy !" .. name .. "!)")
mn.runSEXP("(friendly-stealth-invisible !" .. name .. "!)")

end

function Decloak(name)

mn.runSEXP("(ship-effect !Decloak! 1000 !" .. name .. "!)")
mn.runSEXP("(ship-unstealthy !" .. name .. "!)")
mn.runSEXP("(friendly-stealth-visible !" .. name .. "!)")

end

]
#End</pre>

File:Lockdown.png

2014-10-05T16:23:29Z

Axem: For LUA tutorial

For LUA tutorial

Tutorial - FSOpen and LUA

2014-10-05T16:23:16Z

Axem: FreeSpace Lua Tutorial!

One of the coolest things that's been added to FreeSpace Open is the Lua scripting language. It allows a certain amount of freedom that SEXPs don't allow, but on the other hand Lua is a lot more, let's say, risky. FreeSpace has a lot of error checking and can handle any dumb SEXP efforts with a shrug. Lua runs a more unregulated campaign and, if you're not careful, can spew out baffling error messages that leave you clueless even after an hour on Google.

There's a lot of basic Lua tutorials around the internet, so I'm not going to get into the specifics too much. Read up on them if you're curious. There's just very little in the way of how FreeSpace and Lua interact with each other. If I want to do X with Lua, how would you even begin?

First we need a few tools. First is a good text editor, I suggest Notepad++! You should also generate a scripting.html file from FreeSpace. Go into your launcher and in the Dev Tool section, tick the "Output scripting to scripting.html" box. Run FreeSpace and then just quit. In your FreeSpace directory will be a scripting.html file. This will be very valuable to us, it lists all of the game accessible information we can use for our nefarious purposes.

So what is our first project going to be? A super lame "Hello World" script? Those are so overdone. Let's do something that is still simple but is also something you could actually use in your campaign, a SEXP library.

The concept of a SEXP library is simple: we have some SEXPs that we want to use in multiple missions, and instead of copy and pasting them in multiple missions, we will store them in a Lua function that can be called upon in any mission and be executed.

The SEXP library we make will contain 2 groups of SEXPs: 1. Lockdown the player's fighter's for in-game cutscenes and 2. Properly cloaking a ship (linking the stealth with the visual effect).

== 1. In-game Cutscene Lockdown ==

We've all been there haven't we? Make an in-game cutscene. Watch it, and accidently slip and press primary fire and hear your Subachs fire. Press an ETS key and hear that immersion breaking sound. It's terrible. So what do you do? Add 5 sexps that lock player weapons, afterburner, ETS etc etc. Such a pain, right? Let's rectify this by allowing us to combine all the sexps we would use into a single Lua function. That way we can just use a single script-eval function and, presto! Those sexps will all get run, no muss, no fuss.

There's quite a few ways you can run Lua scripts. This will not be the only correct way to do things, but it’s a way that I feel is easily readable and accessible. You could stuff all your scripts into a single scripting.tbl, but it might get pretty large and unwieldy if you add a lot of Lua. I like to just create smaller modular scripting tables.

Below is the basic framework of a script, saved as sexplibrary-sct.tbm. The -sct.tbm will clue FreeSpace in that this is a Lua scripting file.

<pre>#Conditional Hooks
$Application: FS2_Open
$On Game Init:
[

]
#End</pre>

First we need to tell the game what type of hook we're going to run. There are Global Hooks, State Hooks, and Conditional Hooks. Global Hooks run regardless of state or condition. I'd advise staying away from Global Hooks unless you really know what you're doing. State Hooks aren't really used anymore, the Conditional Hooks are more flexible and better. Conditional Hooks will only check actions that we define later if the condition is met. There's also other game-wise benefits to using Conditional Hooks, [[Scripting.tbl#.23Conditional_Hooks|this part]] from the scripting.tbl wiki page sums it up well enough.

So I put down ''#Conditional Hooks'', and the condition is ''$Application: FS2_Open'', and our action is ''$On Game Init:''. So basically when our application is FS2_Open (which will be… always), during game initialization do this stuff between the square brackets. And then of course our ''#End'' token.

I like to put down any function definitions in ''$On Game Init''. That way all the functions will be ready for any script to use right away. If you're really paranoid about memory usage, you could move it to an initialization function, but you still need to define it somewhere!

So next we should define the Lua function that will house our SEXPs.

<pre>function Lockdown(name)

end</pre>

Function will define Lockdown as the function and the () is where we would put in any additional arguments. Our additional argument here is just name, it will be the name of the ship that we lockdown. And the Lua interpreter needs to know when to stop the function, so that's where the end comes in.

Now we need to think what sexps we would call for ''Lockdown()''.

*Lock-primary-weapon
*Lock-secondary-weapon
*Lock-afterburner
*Disable-ETS
*Player-use-AI
*Add-Goal ai-play-dead on the player
**(alternatively ship-immobile if you're not going to use the player's ship in the cutscene)
*Lock-perspective

That's 7 sexps, surely this will increase our FREDding power by 700%!

If we look in the scripting.html and go into the mission library section, we'll find this cute little function.

''boolean '''''runSEXP'''(''string'')
:Runs the defined SEXP script
:'''Returns''': if the operation was successful

''runSEXP'', as the name implies, allows us to run a SEXP as if it was being called by a mission event. Which is funny because this function will get called by a mission event anyway! The argument to ''runSEXP'' (the part that goes in the ()) is the same text that FRED writes to events. If we make an event that is just lock-primary-weapon and look at it in a text editor, it looks like…

<pre>$Formula: ( when
( true )
( lock-primary-weapon "Alpha 1" )
)
+Name: Lock Primary Weapon
+Repeat Count: 1
+Interval: 1</pre>

But all we're really interested in is...
<pre>(lock-primary-weapon "Alpha 1")</pre>
If your sexps have line breaks in them, be sure to take those out so they are all on one line. Lua would think we're done with the sexp long before we actually are.

So our first runSEXP function would look like…

<pre>mn.runSEXP("(lock-primary-weapon !" .. name .. "!)")</pre>

Wait, hold on. What's this extra stuff I just sprung in front of you? Why is that mn there? And why are there EXCLAIMATION MARKS!! AND DOTS!

''runSEXP'' is a function that is part of a larger library, the mission library. The mission library's internal name is just mn. Anytime we want to use a function inside a library, we need to add mn. in front of it so the Lua interpreter knows where to look.

Now the argument for ''runSEXP'' is a string, and Lua sees everything between two " as a string. So if we were to just run
<pre>mn.runSEXP("(lock-primary-weapon "Alpha 1")")</pre>
The Lua Interpreter would see "lock-primary-weapon" and "". It doesn't see the Alpha 1 because it's in the middle of two pairs of "s. So there's a bit of sly substitution that goes on, all !s are replaced with "s during evaluation. So if you're using the ''runSEXP'' or ''evaluateSEXP'' functions, replace those "s in the SEXP with !s.

''name'' is a variable that has the argument that we specified before in the function definition. If we were to go...
<pre>Lockdown('Alpha 1')</pre>
Then ''name'' inside the function will be replace with "Alpha 1". The ''..'' is called a concatenation operator. Concatenation is when you combine two strings together. So we combine the "lock-primary-weapon !" string with the name variable, and then combine that with the last "!".

'''NOTE:''' If the argument is empty and does NOT have anything in it, the argument will then "contain" a special value called nil. '''Nil''' is Lua's version of null (or empty), it basically means it does not exist. Using something that is nil will result in errors everywhere! In a later tutorial we'll do checks for nil, for now just be mindful of the arguments you pass through functions.

So that's one line, let us do the same thing to other lines. It would probably be a good idea to create the sexps first in a mission, save the mission and then copy and paste the relevant lines into your script. The game expects SEXPs to be without syntax errors because FRED knows how to do it without any reminders. We fleshy humans aren't that good, so take all precautions!

So here's the full function, plus another function that undoes the SEXPs.

<pre>function Lockdown(name)

mn.runSEXP("(lock-primary-weapon !" .. name .. "! )")
mn.runSEXP("(lock-secondary-weapon !" .. name .. "! )")
mn.runSEXP("(lock-afterburner !" .. name .. "! )")
mn.runSEXP("(disable-ets !" .. name .. "! )")
mn.runSEXP("(player-use-ai )")
mn.runSEXP("(add-goal !" .. name .. "! ( ai-play-dead 200 ) )")
mn.runSEXP("(lock-perspective ( true) )")

end

function UnLockdown(name)

mn.runSEXP("(unlock-primary-weapon !" .. name .. "!)")
mn.runSEXP("(unlock-secondary-weapon !" .. name .. "!)")
mn.runSEXP("(unlock-afterburner !" .. name .. "!)" )
mn.runSEXP("(enable-ets !" .. name .. "!)")
mn.runSEXP("(player-not-use-ai)")
mn.runSEXP("(clear-goals !" .. name .. "!)")
mn.runSEXP("(lock-perspective ( false ) )")

end</pre>

To use these functions within the game, we need to call the script-eval sexp. And it would look something like…
[PIC]

Notice how I used a single quotation mark instead of a double one. The reason for this is pretty much the same as using the ! before. It’s a way to define the boundaries of a string without actually breaking the string in the process.

It's sort of hard to show these functions off with screenshots, so you'll just have to try them yourself.

== 2. Cloaking Ships + Stealth ==

There's a neat sexp in the special-effects category, ship-effect. Some of the options are cloak and decloak. The only problem is that if you cloak a ship, the effect is only visual! You can still target it. How lame is that? Sure we could just do a lot of ship-effects + ship-stealthy, but why couldn't we just do both at the same time like the Lockdown functions?

<pre>function Cloak(name)

mn.runSEXP("(ship-effect !Cloak! 1000 !" .. name .. "!)")
mn.runSEXP("(ship-stealthy !" .. name .. "!)")
mn.runSEXP("(friendly-stealth-invisible !" .. name .. "!)")

end

function Decloak(name)

mn.runSEXP("(ship-effect !Decloak! 1000 !" .. name .. "!)")
mn.runSEXP("(ship-unstealthy !" .. name .. "!)")
mn.runSEXP("(friendly-stealth-visible !" .. name .. "!)")

end</pre>

See how easy that was? Especially without me having to explain every detail?

So this is a good start into Lua with FreeSpace without actually needing to know Lua. In the next tutorial, we'll actually get into things like object handles and unique Lua magic.

== Full Table use for Tutorial ==

<pre>#Conditional Hooks
$Application: FS2_Open
$On Game Init:
[

function Lockdown(name)

mn.runSEXP("(lock-primary-weapon !" .. name .. "!)")
mn.runSEXP("(lock-secondary-weapon !" .. name .. "!)")
mn.runSEXP("(lock-afterburner !" .. name .. "!)")
mn.runSEXP("(disable-ets !" .. name .. "!)")
mn.runSEXP("(player-use-ai)")
mn.runSEXP("(add-goal !" .. name .. "! ( ai-play-dead 200 ))")
mn.runSEXP("(lock-perspective (true))")

end

function UnLockdown(name)

mn.runSEXP("(unlock-primary-weapon !" .. name .. "!)")
mn.runSEXP("(unlock-secondary-weapon !" .. name .. "!)")
mn.runSEXP("(unlock-afterburner !" .. name .. "!)" )
mn.runSEXP("(enable-ets !" .. name .. "!)")
mn.runSEXP("(player-not-use-ai)")
mn.runSEXP("(clear-goals !" .. name .. "!)")
mn.runSEXP("(lock-perspective (false))")

end

function Cloak(name)

mn.runSEXP("(ship-effect !Cloak! 1000 !" .. name .. "!)")
mn.runSEXP("(ship-stealthy !" .. name .. "!)")
mn.runSEXP("(friendly-stealth-invisible !" .. name .. "!)")

end

function Decloak(name)

mn.runSEXP("(ship-effect !Decloak! 1000 !" .. name .. "!)")
mn.runSEXP("(ship-unstealthy !" .. name .. "!)")
mn.runSEXP("(friendly-stealth-visible !" .. name .. "!)")

end

]
#End</pre>

User:Axem

2014-10-05T16:06:10Z

Axem: /* Tutorials */ Nu tutorial

==About Axem!==
Hello! I am Axem, friendly administrator on the HLP forums. I can FRED (make missions), model, UVMap, texture, script and make rough effects. Just don't ask me to do any of it for you, I've got enough to do! But I can help guide you to the right path. Below you'll find some of the stuff I've done here over the years.

==My Campaigns==
*[[Shadows of Kraken]]
*[[Just Another Day]]
*[[Just Another Day 2: Electric Boogaloo]]
*[[Just Another Day 3: Shivans on a Plane]]
*[[Vassago's Dirge]]
*[[Just Another Day 2.21: You Are (Not) Alpha 1]]

==Projects I Help With==
*[[Diaspora]]
*[[Blue Planet]]
*[[Wings of Dawn]]

==My Ships==

*[[GTC Cretheus]]
*[[SC Lamia]]
*[[SGs Asura]] (textured by Nighteyes)
*[[UES Aranyaka]]

Other WIPS can be seen on my [http://p3d.in/u/Axem p3d page]

==Helpful Pages I've Done==
===Tutorials===
*[[Tutorial - Conditional Arguments]]
*[[Tutorial - Directive-is-variable SEXP]]
*[[Tutorial - Mission Infrastructure]]
*[[Tutorial - PCS2 Kitbashing]]
*[[Tutorial - Custom HUD Gauges]]
*[[Tutorial - Fun with Simulated Hull]]
*[[Tutorial - Bitwise Operations]]
*[[Tutorial - FSOpen and LUA #1 - SEXP Library]]

===SEXP Reference===
*[[Advanced Cutscene SEXP Reference]]
===Script Reference===
*[[Script - Journal/Fluff Viewer]]
*[[Script - System Viewer]]
*[[Script - Interface Monitor]]
*[[Script - Scripted Message Gauge]]

Tutorial - Bitwise Operations

2014-08-03T14:34:31Z

Axem: Bitwise operations tutorial for FRED

Get wise with bitwise!

If you have any sort of computer science background, the term bitwise should come second-nature to you. If you're not, then here's a quick rundown.

==Bitwise Basics==

Computer programs don't store numbers as the numbers we know in base-10, they store them as bytes. What's a byte? A byte is a bunch of 1s and 0s bunched together. The single element (the 1 or 0) is just called a bit. The computer program looks at the bits in the byte and reconstructs the number we're looking for by using each bit's place value as a power of two.

Huh?!

In our traditional base-10 math, if we have the number 150, we could break it up into 100 + 50 + 2. We could then express each of those numbers as a number times a power of ten. So 152 = 100 + 50 + 2 = (1 x 10^2) + (5 x 10^1) + (0 x 10^0). To express that we can just go 1 5 0. Which is stupidly obvious.

What if we're restricted to base 2 (aka binary, just a 1 or 0, like computers) and have the number 12? Powers of 2 are 1, 2, 4, 8, 16, 32, 64 … etc etc. So to get 12 out of that we could just go 8 + 4. So our base 2 number would look like (1x2^3) + (1x2^2) + (0x2^1) + (0x2^0). Or just 1 1 0 0. That 12 is actually being store as 1100 inside the computer program.

==Using in FRED==

Imagine we have a campaign going with 4 persistent ships.

[[file:Bitwise1.png|600px]]

Our wonderful fleet.

How could we easily keep track if they are alive or dead? (Let's pretend that the health of each ship doesn't matter, just if they're alive or dead.) is-previous-event-false ShipAWasDestroyed? Sure, but if our campaign is going to be long, you're going to be checking a lot of previous events. Put its status in a variable? This is good, but updating 4 variables throughout a campaign? What a… pain.

Hey, look at that bitwise example above. If our variable's bits corresponded to the status of our ships, that could work. So 1 1 1 1 would be all four ships are alive. 1 0 1 0 would be 2 ships alive, 2 dead, 0 1 0 1 would be the other 2 ships alive and the other 2 dead. Let's see how we could accomplish this.

When we make a new integer variable in FRED, a common default value is 0, but inside FRED there's quite a few more zeroes. An integer variable inside FRED is 4 bytes, or 32 bits. This means FRED really is storing 0000 0000 0000 0000 0000 0000 0000 0000 for the default value of 0 (spaces added to help with readability). So we could theoretically store 32 ships with this system, but we'll just stick to 4 for the time being.

So when we store our ship's status, we want 1 1 1 1 since they are all alive. We would NOT just type in 1111, because in binary that is actually 0100 0101 0111. Not quite what we're looking for. Constructing the number in binary and be tricky for people unfamiliar with binary (FYI its 15). So maybe instead of making each bit "is this ship alive?" we could just think of each bit as "is this ship dead?" That way we can just keep our initial value at zero.

Now how do we modify our variable properly if a ship dies? This nifty set-bit sexp. Now the set-bit operator only returns the value of a variable after a specific bit is set. Set-bit by itself doesn't modify the variable, we still need to use the modify-variable sexp first. But it's still simple enough to use.

[[file:Bitwise2.png|600px]]

"Modify FleetStatus to be FleetStatus with Bit Index 0, 1, 2 or 3 set" (Quick note, computers love to start counting at 0, so index 0 is technically the first bit)

Then at the beginning of each mission (or the arrival cue) we just check a bit's status with is-bit-set to see if it should arrive.

[[file:Bitwise3.png|600px]]

Yes, using bit-wise operations with integer variables allows you to cram 32 true/false variables into that single variable.

To get into some real advanced things, you can also play with bitwise AND, OR and XOR operators. Check out [http://en.wikipedia.org/wiki/Bitwise_operation this wikipedia article] for more great info on those.

If you need more than true or false, you could do similar things with string-get/set-substring. It works similar to the bitwise operators, it only affects a desired section of the variable. For instance you could store things like morale levels for a squad of fighters, a rough health status for turrets, or responses when a player was asked a question. Things can get pretty complicated though, so take things nice and slow.

[[Category:FRED Examples]][[Category:Tutorials]]

File:Bitwise3.png

2014-08-03T14:30:36Z

Axem: Part of bitwise operation tutorial

Part of bitwise operation tutorial

File:Bitwise2.png

2014-08-03T14:30:28Z

Axem: Part of bitwise operation tutorial

Part of bitwise operation tutorial

File:Bitwise1.png

2014-08-03T14:30:16Z

Axem: Part of bitwise operation tutorial

Part of bitwise operation tutorial

User:Axem

2014-08-03T14:28:18Z

Axem: /* Tutorials */ Bitwise stuff

==About Axem!==
Hello! I am Axem, friendly administrator on the HLP forums. I can FRED (make missions), model, UVMap, texture, script and make rough effects. Just don't ask me to do any of it for you, I've got enough to do! But I can help guide you to the right path. Below you'll find some of the stuff I've done here over the years.

==My Campaigns==
*[[Shadows of Kraken]]
*[[Just Another Day]]
*[[Just Another Day 2: Electric Boogaloo]]
*[[Just Another Day 3: Shivans on a Plane]]
*[[Vassago's Dirge]]
*[[Just Another Day 2.21: You Are (Not) Alpha 1]]

==Projects I Help With==
*[[Diaspora]]
*[[Blue Planet]]
*[[Wings of Dawn]]

==My Ships==

*[[GTC Cretheus]]
*[[SC Lamia]]
*[[SGs Asura]] (textured by Nighteyes)
*[[UES Aranyaka]]

Other WIPS can be seen on my [http://p3d.in/u/Axem p3d page]

==Helpful Pages I've Done==
===Tutorials===
*[[Tutorial - Conditional Arguments]]
*[[Tutorial - Directive-is-variable SEXP]]
*[[Tutorial - Mission Infrastructure]]
*[[Tutorial - PCS2 Kitbashing]]
*[[Tutorial - Custom HUD Gauges]]
*[[Tutorial - Fun with Simulated Hull]]
*[[Tutorial - Bitwise Operations]]

===SEXP Reference===
*[[Advanced Cutscene SEXP Reference]]
===Script Reference===
*[[Script - Journal/Fluff Viewer]]
*[[Script - System Viewer]]
*[[Script - Interface Monitor]]
*[[Script - Scripted Message Gauge]]

Scripting.tbl

2014-07-19T16:58:14Z

Axem: /* Actions */ Added On Message Received

{{SCP_table}}

{{TableVersion|4500}}

The '''scripting.tbl''' is used for scripting special features like alternate HUDs or ship viewer into the game.

This table is one of the [[Modular Tables]] and can be extended with xxx-sct.tbm

[[Tables|List of Tables]]

==General Info==
*Scripting table consist of several sections identified by a hash mark preceeding the section name (i.g. #Global Hooks)
*All sections ''must'' end with #'''End'''
*All sections are optional
*Most entries are optional
*Scripting hooks are '''not''' executed on a separate thread (at least as of this writing). They are executed at given points in the code, and all other execution will not take place until a scripting hook has finished. Therefore, large and complicated scripts will most likely cause noticeable lag or slowdown when executed.
{{Template:Note|1=Information on this page does not apply to pre-3.6.10 builds}}
 

==Useful references==
*'''[[FS2 Open Lua Scripting]]'''
*'''[[Scripting API]]'''

*'''[[Scripting functions]]'''
*'''[[Command-Line_Reference#-output_scripting|Command-Line Reference for creating scripting.html]]'''
*'''[http://lua-users.org/wiki/ Lua-Users Wiki]'''
*'''[http://www.lua.org/manual/5.0/ Reference manual for Lua 5.0]'''

==Prerequisites==

===Frames===
One of the most important things to understand when reading this guide is the concept of "frames". (Experienced modders can probably skip this part) In gameplay, motion is achieved by making incremental changes every fraction of a second. A ship will be moved slightly, and then drawn to the screen. This happens 30-120 times a second; anything lower, and the game will become choppy and difficult to play.

There is also a difference in the moving of objects in-game, and the moving of objects onscreen. All ships are first "moved", in memory. This probably consists of physics calculations, that change the ship's position based on if their engines are turned on, or if they run into another object. After this, the game then renders the now-moved ships to what is referred to as a "backbuffer" - a place in memory that takes the place of the computer screen. Once rendering has finished, the backbuffer is instantly drawn to the screen. This prevents objects from flickering as they are drawn. You do not have to worry about flipping the backbuffer in scripting; FS2_Open will take care of that for you.

For scripting, '''it is important to understand that each block of code will therefore be executed several times a second, but only once per frame'''. However, the exact number of times per second will depend on how much work the computer has to do (And therefore how much time it takes) for each frame. To determine how much time you should consider to have passed, you must use the ba.getFrametime() function; which will return the approximate time the frame will take, in seconds. In addition, if you "move" a ship after it has already been rendered, the change will not become apparent until the next frame.

This does mean that if you want to make a block of text move across the screen, at a rate of 5 pixels per second, all you have to do is multiply the speed by the frametime:
<pre>#Global Hooks
$Global: [
--If the g_WheeXPosition variable does not exist,
--it means we are on the first frame.
--If that is the case, set it to zero.
if not g_WheeXPosition then
g_WheeXPosition = 0
end

--Move the text
g_WheeXPosition = g_WheeXPosition + (5 * ba.getFrametime())

--Draw "WHEE!!!"
gr.drawString("WHEE!!!", g_WheeXPosition, 10)
]
#End</pre>
 

===Hooks===
Scripting "hooks" form the basis of the scripting system. A "hook" simply refers to a point in the code where code to execute scripting has been added. The hook may then be added to a table, or added to a SEXP. In general usage, "hook" refers to an entry in scripting.tbl.

All hooks take the form of an identifer (such as $Global:), followed by brackets to determine what type of scripting is being executed. A lack of brackets also indicates a type of scripting execution. All current bracket configurations are listed below. Note that "$Hook:" is used merely as a placeholder, and should be replaced with the actual hook name ($Global:, $HUD:, $On Frame:, etc).
#<pre>$Hook: scripting</pre>Specifies one line of LUA scripting. In addition, the return value of that line will be passed to the interpreter and used (if applicable). Specifying a variable or value on this line will result in it being returned, as well.
#<pre>$Hook: [scripting]</pre>A single set of brackets specifies a block of LUA scripting. Does not return a value unless explicitly specified. (Explicit specification is not possible at this time; but may be implemented in the future if/when more future hooks take a return value.)
#<pre>$Hook: [[scriptfilename.lua]]</pre>Double brackets specify a file. This file is read out of the data/scripts directory, and must include the file extension. You may specify a compiled lua file as a target as well; this may result in crossplatform issues for a mod, however.
 

====+Override====
Some hooks additionally take a +Override: field. This field uses the same bracket configurations as above. If a hook includes a +Override field, this hook always determines whether the default FS2_Open behavior that the hook is associated with will function, or will be disabled. This should be used in cases where scripting will replace the original FS2_Open behavior. For example:
<pre>$HUD: [
gr.setColor(255, 255, 255, 255)
gr.drawString("HUD Disabled", 50, 50)
]
+Override: true</pre>

Additionally, override hooks are (by convention) executed before FS2_Open behavior. The HUD hook override, for example, is executed before any part of the HUD is actually drawn.
 

==Sections==

===#Global Hooks===
Global hooks are the simplest form of scripting hooks available. They are at preset locations in the code, and are generally executed every time that point is reached. Exceptions to this rule (such as the HUD hook) only depend on one or two variables to determine execution. All other scripting execution is determined by the modder.
Note that, as with other tables, the game expects these entries in precisely the order given here; if this is not followed, the parser will throw an error.
 

====$Global:====
Script in this section is executed almost immediately before each frame is drawn. This means that any scripting elements will be drawn, or take effect, after everything else, except for the "On Frame" conditional hook. It is not used with the standalone server. In addition, note that use of this hook should generally be avoided, since all scripting will have to be processed every frame.
 

====$Splash:====
This hook is executed once, when the splash images (PreLoad and PreLoadLogo) would be drawn. This hook should generally be used only for drawing the splash screen; any initialization could should be placed in GameInit. This hook is executed before virtually any other subsystem has been loaded, aside from the graphics and filesystem subsystems, so scripting elements such as the table and mission libraries will be nonfunctional.
 

=====+Override:=====
Executed just before default splash images are loaded and displayed. Note that the frame is still drawn regardless; it is not necessary to flip the backbuffer manually.
 

====$GameInit:====
This hook is executed once, after all of the Freespace2 subsystems have been initialized. It is executed before the game switches to the main hall or, in the case of standalone server mode, begins the game.
 

====$Simulation:====
This hook is executed only during missions. It is executed after all damage, movement, physics, SEXPs, and other "physical" in-game changes have been applied. It is executed before anything has been rendered. This hook should be used only for damage, movement, and physics related scripting, as if the game needs to be rendered without any in-game time having been passed, this function will not be called.
 

====$HUD:====
The HUD hook is executed after the HUD has been drawn. Note that if the HUD is turned off, this hook will be disabled as well, until the HUD is turned back on.
 

=====+Override:=====
Executed immediately before anything on the HUD is drawn, and controls whether the default FS2_Open is drawn.
 

===#State Hooks===
In Freespace2, a "state" more or less refers to a room. It may also refer to a separate mode - playing a mission is the GS_STATE_GAME_PLAY state. The main menu is the GS_STATE_MAIN_MENU state. This section should only exist in 3.6.9. It is included here for the sake of documentation; it has since been removed and superseded by the conditional hook system.
 

=====$State:=====
Specifies the state name. A full list of states is located here: ''[[List of Game States]]''

=====$Hook:=====
Executed after all of the state code has been executed, but before the game frame is actually drawn.

======+Override:======
Determines whether the specified state is handled at all by Freespace. If true, then none of the loading or exit code for the state will be specified as well.

===#Conditional Hooks===
Scripting hooks are only available in HEAD builds. They consist of any number of conditions, followed by any number of actions. All available conditions and actions are located in the file generated by -output_scripting.

One way to think of conditional scripting is like this: The condition specifies the object that the action will apply to, or the place that the action will occur in. All conditions must be met for their associated actions to execute. Actions are associated with a set of conditions by simply adding them after that set of conditions. (Obviously, you may want to space out each pair of action/condition sets in the TBL to make it easier to read.)

The flexibility of conditional scripting comes in due to its inherent scalability. If you specify a mission and ship condition with a warpin action, that script will only be executed when the ship warps in on that particular mission. Removing the mission field will make that warpin scripting apply to the ship for all missions; or removing the ship field will make the warpin scripting apply to all ships in that mission.

This prompts the question: if this is all conditional scripting does, why not just use the global hook?
#Organization - conditional scripting is generally easier to read and modify because it is grouped in a standardized manner.
#Speed - All conditions can be evaluated by FS2_Open itself, without invoking the Lua interpreter at all.
#Scalability - As of the time of this writing, you can only have one global hook. Modular tables will simply replace it. With conditional scripting, if you want to specify additional actions for a set of conditions in a modular table file, you may do so.

;Format

;'''$Condition:''': Where "$Condition:" is one of several conditions specified in scripting.html, such as $State: or $Ship:. Takes a value representing the object the condition should be checked against (such as a state, ship, or mission name)
;'''$Condition:''': ...
;'''...''':
;'''$Action:''': Where "$Action:" is one of several actions specified in scripting.html, such as $On Frame or $On Warp In. Takes a scripting hook, using the bracket configuration outlined at the top of this article.
;'''$Condition:''': ...
;'''...''':

A brief description of all Conditions and Actions at the time of this writing:

====Conditions====

=====$State:=====
Controls execution based on what state FS2_Open is in, such as the main hall, options screen, or in a mission.
*The full list of states can be found here: ''[[List of Game States]]''

=====$Campaign:=====
Controls execution based on the current campaign's filename. (It is under consideration to change this to the campaign's name, instead).

=====$Mission:=====
Controls execution based on the filename of the last mission to have started. This condition will remain true even after the mission has been exited until another mission is started.

=====$Object Type:=====
Defines a specific object type that the action will apply for, such as a "Ship", "Asteroid", or "Jump Node".

=====$Ship:=====
Defines a specific ship (name) that the action will apply for.

=====$Ship class:=====
Defines a specific ship class (name) that the action will apply for.

=====$Ship type:=====
Defines a specific ship type (name) that the action will apply for.

=====$Weapon class:=====
Defines a specific weapon class (name) that the action will apply for.

=====$KeyPress:=====
Defines a specific key that the action will apply for.
*Experimental.

=====$Action:=====
{{Table371|
Defines a specific control that the action will apply for. For example "Fire Primary Weapon" or "Match Target Speed".
}}

====Actions====

=====$On Game Init:=====
Executes immediately after game has been started.
::* No associated hook variables.

=====$On Splash Screen:=====
Executes when initial game splash screen is shown
::* No associated hook variables.

=====$On State Start:=====
Executed when specified game state starts
::* No associated hook variables.

=====$On Frame:=====
Executes immediately after the global scripting hook, which is right before the frame is drawn.
::* No associated hook variables.

=====$On Key Pressed:=====
Executed when specified key is pressed
::* '''Key''', The pressed key

=====$On Key Released:=====
Executed when specified key is released
::* '''Key''', The released key

=====$On Mouse Moved:=====
Executed when mouse is moved
::* No associated hook variables.

=====$On Mouse Pressed:=====
Executed when mouse button is pressed
::* No associated hook variables.

=====$On Mouse Released:=====
Executed when mouse button is released
::* No associated hook variables.

=====$On State End:=====
Executed when specified game state ends
::* No associated hook variables.

=====$On Mission Start:=====
Executed when mission starts
::* No associated hook variables.

=====$On Gameplay Start:=====
{{Table3615|
Executed when the gameplay part of a mission starts
::* No associated hook variables.}}

=====$On HUD Draw:=====
Executed after the HUD has been drawn. Note that if the HUD is turned off, this hook will be disabled as well, until the HUD is turned back on
::* '''Self''', the viewer (object)

=====$On Ship Collision:=====
Executes when the specified object collides with a ship. Sets a handle in the HookVariables library with the name of the object type ("Weapon", "Debris", and so on) with the type of the object. If both objects are ships, the other object gains the name "ShipB". (If both ship objects define a collision hook, the variables will be swapped for the other ship, so the ship that the script is executing for will always be called "Script".) The override will disable FS2_Open code, as well as the other object's collision code. If both objects have an override set, only one of the objects' hooks will be used (Chosen arbitrarily). Note that the override receives the same variables.
::* When colliding something other than other ship:
::** '''Ship''', the ship (object)
::** '''Debris''', '''Asteroid''', '''Weapon''', depending what it collided with (object)
::** '''Self''', the object referred by the condition (object)
::** '''Object''', the ship (object)
::* When colliding with other ship:
::** '''Ship''', the ship (object) referred by the condition (object)
::** '''ShipB''', the other ship (object)
::** '''Self''', the ship (object) referred by the condition (object)
::** '''Object''', the other ship (object)

=====$On Weapon Collision:=====
Like the ship collision hook, but for weapons.
::* When colliding something other than other weapon:
::** '''Weapon''', the weapon (object)
::** '''Debris''', '''Asteroid''', '''Ship''', depending what it collided with (object)
::** '''Self''', the object the weapon collided with (object)
::** '''Object''', the weapon (object)
::* When colliding with other weapon:
::** '''Weapon''', the weapon (object) referred by the condition
::** '''WeaponB''', the other weapon (object)
::** '''Self''', the weapon (object) referred by the condition
::** '''Object''', the other weapon (object)

=====$On Debris Collision:=====
Like the ship collision hook, except for debris.
::* '''Debris''', the debris (object)
::* '''Weapon''', '''Ship''', depending what it collided with (object)
::* '''Self''', the object the debris collided with (object)
::* '''Object''', the debris (object)

=====$On Asteroid Collision:=====
Like the ship collision hook, only for asteroids.
::* '''Asteroid''', the asteroid (object)
::* '''Weapon''', '''Ship''', depending what it collided with (object)
::* '''Self''', the object the asteroid collided with (object)
::* '''Object''', the asteroid (object)

=====$On Object Render:=====
Executes when the specified object is rendered. The override is run before the object is rendered, and both the hook and its override receive an "Object" variable of the object to be rendered.
::* '''Self''', the object rendered (object)

=====$On Warp In:=====
Run when a ship has begun warping in, immediately after everything has been set up for per-frame processing. This hook is only executed once, when the ship begins warping in. An override will disable _all_ behavior related to warpin. Both the hook and an override receive an "Object" handle in the HookVariables library, with the type of the object that is warping in.
::* '''Self''', the object warping in (object)

=====$On Warp Out:=====
Same as warping in, except for warping out.
::* '''Self''', the object warping out (object)

=====$On Death:=====
*Currently only valid for ships.
Receives "Self" and "Killer" variables of the object and killer, respectively. Overriding it will override all default death behavior.
::* For asteroids:
::** '''Self''', the asteroid (object)
::* For ships:
::** '''Self''', the ship (object)
::** '''Killer''', the other object (object) - NOTE, not guaranteed to exists

=====$On Mission End:=====
Run on mission end.
::* No associated hook variables.
=====$On Weapon Equipped:=====
{{Table3613|
Runs once each frame, for every ship that has the weapon defined in the $Weapon class condition equipped.
::* '''User''', the ship carrying the weapon
::* '''Target''', the ships' current target
}}

=====$On Weapon Fired:=====
{{Table3613|
Runs once when a ship fires a weapon defined in the $Weapon class condition
::* '''User''', the ship carrying the weapon
::* '''Target''', the ships' current target
}}

=====$On Weapon Selected:=====
{{Table3613|
Runs once when a bank with a weapon defined in the $Weapon class condition is selected
::* '''User''', the ship carrying the weapon
::* '''Target''', the ships' current target
}}

=====$On Weapon Deselected:=====
{{Table3613|
Runs once when a bank with a weapon defined in the $Weapon class condition is deselected
::* '''User''', the ship carrying the weapon
::* '''Target''', the ships' current target
}}

=====$On Turret Fired:=====
{{Table3615|
Executed when a turret fires.
::* '''Ship''', the parent ship
::* '''Weapon''', the weapon which was fired
::* '''Target''', the intended target
}}

=====$On Ship Arrive:=====
{{Table371|
Executed when a ship arrives.
::* '''Ship''', the arriving ship
::* '''Parent''', the ship acting as the anchor when arrival location is "in front of ship", "near ship" or "docking bay"; nil or invalid handle otherwise
}}

=====$On Action:=====
{{Table371|
Executed when an action is triggered, regardless of which key or button it is bound to. Does currently not trigger on mouse or joystick movements.
::* '''Action''', the textual description of the action (for example "Fire Primary Weapon" or "Match Target Speed")
}}

=====$On Action Stopped:=====
{{Table371|
Executed when a continuous action is released (for example "Fire Primary Weapon", "Turn Left" or "Afterburner").
::* '''Action''', the textual description of the action
}}

=====$On Message Received:=====
{{Table371|
Executed when the player receives a message.
::* '''Name''', the message name that was received. The message handle can be accessed with mn.Messages[hv.Name]
::* '''Message''', the message text that would be displayed on the message gauge. Takes in account scrambled messages and variable replacements.
::* '''SenderString''', the displayed string that shows the origin of the message.
::* '''Builtin''', boolean, true if the message was a builtin message (eg: automatic messages from Command or wingmen)
::* '''Sender''', object handle of the ship that sent the message. This might not always be valid, so check is :isValid() if you need to use it
}}

==Misc. Hook Variables:==

===Viewer===
*Active if (non-player) viewing object is valid

===Player===
*Active if player obj is valid
 

==Examples==

See [[:Category:Scripting Examples|Scripting Examples category]]

[[Category:Tables]]

Script - Scripted Message Gauge

2014-07-06T19:08:49Z

Axem: Correcting some minor terminology

The Scripted Message Gauge is a LUA script that enables messages to be displayed in a different fashion. Instead of the default way of a message line appearing right away with a backlog, the message will be drawn one character at a time with a background that enables messages to be seen more easily against a bright background.

The script requires code added in rev 10756 or 3.7.2 RC3 or later.

This page will assist modders to install it, configure it, and use it.

=Download Link=

[http://www.mediafire.com/download/d5nplmsz43d32ip/ScriptedMessagev1.2.rar Download Link]

=Required File=

All required files are included in the above download.

*/config/
**axmessage.cfg
*/interface/
**messagebox.png
*/scripts/
**dkjson.lua [[http://dkolf.de/src/dkjson-lua.fsl/home]]
*/tables/
**axmsg-mod.tbm
**axmsg-sct.tbm
**parsecfg-sct.tbm
**zLoadFirst-sct.tbm (written by Nuke)

=Configuration Files=

axmessage.cfg is a JSON configuration file

==Default==
===TitleFont===
Integer or String, Font index or name used for the displayed sender's name. Default is 3.

===TextFont===
Integer or String, Font index or name used for the displayed message text. Default is 1.

===Image===
Filename, Image to use as the background for the message text. Default is messagebox.

===Speed===
Integer, The time it will take 1 character to draw in seconds. Default is 0.03.

===Length===
Integer, The script uses length to guess how long a message should be displayed for. Normal behavior will have a message be displayed for (Length * Number of characters in message) seconds. Default is 0.07.

===AfterVoice===
Integer, If a non-generic voice file is used in a message, this is the amount of extra time the message will be visible for after the voice file is over. Default is 1.5.

===TitleColor===
RGBA, If monochrome is false, this is the RGBA color the sender's name will be.

===TextColor===
RGBA, If monochrome is false, this is the RGBA color the message text will be.

==Position==
===Origin===
Percent, Percent, Percent based positioning similar to how the new hud positioning works.
===Offset===
Integer, integer, The offset in pixels from the origin, similar to how the new hud positioning works.
===HeadAni===
Integer, integer, The offset in pixels for the talking head message gauges. This does not work (yet).

==Backlog==
===Enabled===
Boolean, activates the backlog feature. Previously received messages will have a similar behavior to the old message gauge.
===Origin===
Percent, Percent, Percent based positioning similar to how the new hud positioning works.
===Offset===
Integer, integer, The offset in pixels from the origin, similar to how the new hud positioning works.
===Height===
Integer, How height of the area that the backlog will be confined to. The message backlog will start at the bottom and gradually work its way up.

==Offsets==
===Sender===
X,Y offset where the Sender text will be drawn from the position
===Text===
X,Y offset where the message text will be drawn from the position

==Monochrome==
Boolean, turns monochrome on or off. See behavior for a detailed explanation

==GenericFiles==
Array, filenames, A list of files (minus the file extensions) that will cause the script to use generic guessing for the message length and not the actual voice file length. These are the message beeps and alarms when there's no voice acting.

==MinVertRes==
Integer, optional, the vertical resolution must be at least this for the script to activate.

=Behavior=
==Message Length==
There are a few ways the script calculates how long a message should be visible. If there is no voice file or the voice file is in the generic list, the message will be displayed for (Length * Number of Characters in Message). If a modifier makes the message longer, the length will be extended as well (but it will not be shortened).

If there is a VoiceFile attached to the message, the message will be displayed for (VoiceFile Length + AfterVoice).

==Changing the Text Draw Speed in FRED==
By putting !s and .s at the beginning of messages names in FRED, the text draw speed will be modified.

*!!! = Draws instantly
*!! = Draws 66% faster
*! = Draws 33% faster
*. = Draws 33% slower
*.. = Draws 66% slower
*... = Draws 100% slower

The characters must be at the start of the message. So <pre>!!!Holley says sup</pre> would work. <pre>Holley says sup!!!</pre> would not.

==Monochrome Mode==

If monochrome mode is false, the image is drawn as-is in full color without any game added-transparency. TitleColor and TextColor will be used to color the sender name and text.

If monochrome mode is true:
*The image will be colored the same color as the talking head hud gauge. An additional dark gray copy of the image is drawn underneath to minimize washout.
*The text will be colored the same as the default message lines hud gauge. The alpha is increased to max for maximum readability.
*If the talking head hud gauge and message lines hud gauge are the same color (eg you selected Amber/Green/Blue in the HUD config) the text will be brightened so its slightly easier to read.

=Limitations=

The gauge does not brighten or dim with the Increase HUD Contrast command (L key).

The text doesn't scale like the rest of the retail hud. So using <pre>$Scale Gauges: No</pre> in a hud gauges table will do nothing. This may change in the future.

=Using In-Game=

The script needs no special activation. When the script initializes in a mission, it turns off the retail message lines gauge.

In order for the scripted messages gauge to be visible during in-game cutscenes where the disable-hud-except-messages is used, you need to use the included -mod.tbm file. It puts the control of HUD visibility on manual FREDder control, so the HUD may be visible during cutscenes where a camera sexp is used without any disable-hud sexps. Just add disable-hud or disable-hud-except-messages.

Tutorial - Fun with Simulated Hull

2014-06-30T16:28:16Z

Axem: Forgot a small link

Let us suppose we have a daring mission idea here. You, a pirate, needs some cash. Well there's this mostly abandoned container depot that might have credits. To make things nice and random, let's have each container have a random amount of credits. When we send a transport to dock with the container, it'll take those credits from the container and add them to a stockpile. And maybe after docking with like 4 containers, the GTVA notices us and sends some goons out to take care of us.

So how would we do this? There's a few ways we could do this. One is make variables for each container and link them to containers by careful use of arguments and *-variable-by-index sexps. Or we could just set the cargo of each container to be a value and just grab that info with things like string-to-int sexps. But I think we should stick with something a little more simpler, sim-hits.

Just what is sim-hits? It’s a special, mostly invisible subsystem that all ships have. Way back in semi-ancient history, simulated hull was added so you could have a mock dogfight outside of a simulator setting. Weapons with a "training" flag wouldn't do real damage, just damage to your sim-hits subsystem. Though the oddest part about the simulated hull subsystem is that it starts at 0%, unlike anything else sane at 100%.

Since its invisible to the player and isn't affected by 99.9% of all weapons, I find it a great ship-specific variable to use for fun and profit.

==Invisible Variable==

So here is how we will use sim-hits in our scenario:

When the mission starts, we give each container a random amount of sim-hits integrity, from 1 to 100.
Since sim-hits is a subsystem and is limited to 0 - 100, we set the cargo for each container to be (sim-hits-left * 10) to give a nice healthy amount of credits. Using string concatenate we'll add on CR as well to make it look nice.
When we order a freighter to dock, we'll take that sim-hits total, multiply it by 10 and add it to our stock of credits.
Then we set the sim-hits of the container to zero and mark its cargo as empty. This way we can go something like "2350/891200 credits stolen" at the end to help the player know how well he did.

Okay, let's get to it!

Here's our mission space. Just the player, a Posedion-class freighter, and a bunch of containers.

[[File:Simhits1.jpg|600px]]

Here's the setup to making the containers get the sim-hits value and setting the cargo with a properly scaled number. All of the containers are in that in-sequence sexp, I make the event repeat 15 times so I can hit each one with a unique sim-hits (Though if you have this [[Game_settings.tbl#.24Loop_SEXPs_Then_Arguments:|game settings]] flag on, you could do it in just one pass).

[[File:Simhits2.png|600px]]

The dummyNumber variable is a string variable that gets the scaled amount from us doing sim-hits-left * 10. Then dummyNumber gets concatenated with " CR" and is set as the cargo for the player to scan.

And now for the event where our freighter docks with a container. Again we'll need to make this one trigger 15 times, once for each container.

[[File:Simhits3.png|600px]]

It's similar to setting that first event up. When Cohort docks, add (sim-hits-left * 10) to the total number of credits, use that to generate a new cargo string and then set the container as empty with no sim-hits left. And we also send a message so we've got an update on our scavenging right there too. That collapsed modify-variable near the bottom just increments a variable called numDocked by 1 so we know when to send in the GTVA.

And that's it! Just 2 events that generates a number specific to each container and then accesses it for us to use elsewhere.

Of course there's so much more you can use sim-hits for.

==Flag Variables==

If you're making a complex conversation with the prompt box, you might want to ask a question or two to a ship and also have that question you asked exhaust itself so you don't ask the same thing twice. Here in a future mission for JAD, you can see how I used it. When I select an option with the Prompt Box, proBoxValue returns the line number that I selected. So when its 1, I selected line 1, and it sets that bit within the sim-hits of my target. Since sim-hits only goes up to 100, I only have room for 5 bits, but that’s still good enough for me.

In the event that decides what lines to draw, it checks to see if those bits are active within that target.

[[File:Simhits4.png|600px]]

You could also use it for other things like to decide which fighters go renegade, or if a ship likes you or anything else you might need to store simple yes/no information in.

==State Variables==

In JAD:XA, the gauntlet has a boss trio, Trinitiel, that has a teamwork system built into them. To kill all three, you need to destroy each one's weakpoint core. When you destroy the core on one of them, that one goes to sleep for a bit, and one of other two goes into a heal mode to restore their sleeping brother. Then when he's healed, they go back to attacking you.

Sounds sort of simple when you just plan it out like that, but to make sure everyone is doing what they are supposed to, we need to keep track of their state. We could do that with a normal variable, but by embedding it into their sim-hits subsystem, we can just go "whoever has sim-hits 50 and this happens to them, do this then".

[[File:Simhits6.png|600px]]
[[File:Simhits5.png|600px]]

You can see in this pic the different "Modes" the boss has. Everything from attacking the player, to healing a brother, to playing dead or self-destructing. (Keen players who see this may notice that they never teleported or tried to avoid the player, that is what we in the business call, cut content.)

Hopefully this will help assist you in any weird missions you might be planning, or maybe even inspire you!

Tutorial - Fun with Simulated Hull

2014-06-30T16:23:46Z

Axem: Fun with simulated hull tutorial!

Let us suppose we have a daring mission idea here. You, a pirate, needs some cash. Well there's this mostly abandoned container depot that might have credits. To make things nice and random, let's have each container have a random amount of credits. When we send a transport to dock with the container, it'll take those credits from the container and add them to a stockpile. And maybe after docking with like 4 containers, the GTVA notices us and sends some goons out to take care of us.

So how would we do this? There's a few ways we could do this. One is make variables for each container and link them to containers by careful use of arguments and *-variable-by-index sexps. Or we could just set the cargo of each container to be a value and just grab that info with things like string-to-int sexps. But I think we should stick with something a little more simpler, sim-hits.

Just what is sim-hits? It’s a special, mostly invisible subsystem that all ships have. Way back in semi-ancient history, simulated hull was added so you could have a mock dogfight outside of a simulator setting. Weapons with a "training" flag wouldn't do real damage, just damage to your sim-hits subsystem. Though the oddest part about the simulated hull subsystem is that it starts at 0%, unlike anything else sane at 100%.

Since its invisible to the player and isn't affected by 99.9% of all weapons, I find it a great ship-specific variable to use for fun and profit.

==Invisible Variable==

So here is how we will use sim-hits in our scenario:

When the mission starts, we give each container a random amount of sim-hits integrity, from 1 to 100.
Since sim-hits is a subsystem and is limited to 0 - 100, we set the cargo for each container to be (sim-hits-left * 10) to give a nice healthy amount of credits. Using string concatenate we'll add on CR as well to make it look nice.
When we order a freighter to dock, we'll take that sim-hits total, multiply it by 10 and add it to our stock of credits.
Then we set the sim-hits of the container to zero and mark its cargo as empty. This way we can go something like "2350/891200 credits stolen" at the end to help the player know how well he did.

Okay, let's get to it!

Here's our mission space. Just the player, a Posedion-class freighter, and a bunch of containers.

[[File:Simhits1.jpg|600px]]

Here's the setup to making the containers get the sim-hits value and setting the cargo with a properly scaled number. All of the containers are in that in-sequence sexp, I make the event repeat 15 times so I can hit each one with a unique sim-hits (Though if you have this game_settings.tbl flag on, you could do it in just one pass).

[[File:Simhits2.png|600px]]

The dummyNumber variable is a string variable that gets the scaled amount from us doing sim-hits-left * 10. Then dummyNumber gets concatenated with " CR" and is set as the cargo for the player to scan.

And now for the event where our freighter docks with a container. Again we'll need to make this one trigger 15 times, once for each container.

[[File:Simhits3.png|600px]]

It's similar to setting that first event up. When Cohort docks, add (sim-hits-left * 10) to the total number of credits, use that to generate a new cargo string and then set the container as empty with no sim-hits left. And we also send a message so we've got an update on our scavenging right there too. That collapsed modify-variable near the bottom just increments a variable called numDocked by 1 so we know when to send in the GTVA.

And that's it! Just 2 events that generates a number specific to each container and then accesses it for us to use elsewhere.

Of course there's so much more you can use sim-hits for.

==Flag Variables==

If you're making a complex conversation with the prompt box, you might want to ask a question or two to a ship and also have that question you asked exhaust itself so you don't ask the same thing twice. Here in a future mission for JAD, you can see how I used it. When I select an option with the Prompt Box, proBoxValue returns the line number that I selected. So when its 1, I selected line 1, and it sets that bit within the sim-hits of my target. Since sim-hits only goes up to 100, I only have room for 5 bits, but that’s still good enough for me.

In the event that decides what lines to draw, it checks to see if those bits are active within that target.

[[File:Simhits4.png|600px]]

You could also use it for other things like to decide which fighters go renegade, or if a ship likes you or anything else you might need to store simple yes/no information in.

==State Variables==

In JAD:XA, the gauntlet has a boss trio, Trinitiel, that has a teamwork system built into them. To kill all three, you need to destroy each one's weakpoint core. When you destroy the core on one of them, that one goes to sleep for a bit, and one of other two goes into a heal mode to restore their sleeping brother. Then when he's healed, they go back to attacking you.

Sounds sort of simple when you just plan it out like that, but to make sure everyone is doing what they are supposed to, we need to keep track of their state. We could do that with a normal variable, but by embedding it into their sim-hits subsystem, we can just go "whoever has sim-hits 50 and this happens to them, do this then".

[[File:Simhits6.png|600px]]
[[File:Simhits5.png|600px]]

You can see in this pic the different "Modes" the boss has. Everything from attacking the player, to healing a brother, to playing dead or self-destructing. (Keen players who see this may notice that they never teleported or tried to avoid the player, that is what we in the business call, cut content.)

Hopefully this will help assist you in any weird missions you might be planning, or maybe even inspire you!

File:Simhits5.png

2014-06-30T16:22:49Z