[Tutorial] Mission Director basics - using libraries

[Ilintar]

I've decided to share my experiences with using the Mission Director since, as I've noticed, there's quite a lot resources available for modders/scripters, but potential MD users are pretty much left in the dark. Maybe it's worthwhile to start building up some knowledge base regarding MD too...

Anyways, since many people probably don't know about this: there are tutorials and guidelines for the Mission Director leftover from X3:R. This topic holds the X3:R Mission Director questions/answers. Some important basics of MD usage are explained there and there's a link to a Mission Director download package. While the XML schema in there is basically no longer valid for TC (you have to extract your own from the TC .cat/.dat files), there's a nice PDF file there, the Mission Director guide, which contains some useful information. Some of it is no longer valid (there's no special menu for viewing MD states, for example, nor is there any BBS functionality), but it's still a good start.

What has changed very much from the beta MD in X3:R is the massive use of libraries in the mission scripts that come together with TC. The reason is probably that, since all the mission content from TC is written in the MD (including all the plot missions!), some modularity was required. Therefore, although we don't get any new MD tutorial included with TC, we do get a lot of sample scripts plus a lot of reusable libraries that we can use in our missions. This tutorial will focus on the OBS library (the Opponent Balancing System, as it's innocently called), which is basically the main "foe-spawner library" in the set.

I'm assuming you have extracted the entire "director" folder from the game files (for information on how to do that, consult the sticky topics). I will be referring from now on to contents of files within that directory.

The first thing to notice is that the files have a certain hierarchy built upon them. The general idea is this: files without numbers are the most generic libraries (OBS = Opponent Balancing System, SRST = Set Random Ship Type and so on, the descriptions are in the files themselves), files starting with 0. are the "generic mission [part] templates" - they are used as building blocks for constructing real missions. Files starting with 1. (currently only one of them) describe generic mission sets (here, the corporation missions), files starting with 2. - the real missions or plotlines, files starting with 3. - setup procedures for the missions.

Now, if we open a random "level 2" mission, for example "2.145 Scan Asteroids.xml", we will notice the main cue is itself defined as a library cue:

Code: Select all

<cue name="L2M145" library="1" check="cancel" comment="Root Cue for this Mission / Holds all variables" >

In the absence of BBS, the only method of offering missions is to add them to stations/ships manually. However, this is done by level 3 scripts (such as "3.01 Generic Missions.xml"), since the lower level scripts have to be reusable (and keeping them in a single framework also makes it easier to manage which missions are offered). This does not mean we have to adhere to this structure (in fact, it might be a good idea to do something like a "3.101 Custom Missions.xml" which mirrors Generic Missions, but contains only our custom-defined missions), but if we want to recycle the material we've been provided by the game developers (and why shouldn't we? reinventing the wheel isn't exactly fun) or, worse, we want to modify it somehow, we have to get to know the structure well.

The comment in the abovementioned MD file is quite informative, since it shows us a characteristic feature of hierarchical MD code - lots of information is now kept in variables that get passed down to lower-level library scripts. This has two uses - we might want to recycle the same variable for various library files (for example, an opponent's race), or we want a top-level variable to be accessible via a library script.

This second concept requires some detailed explanation. Let's say we have some cue:

Code: Select all

<cue name="A01 Foobar">...

This cue calls some library cue somewhere:

Code: Select all

<cue ref="ALIB01"> ...

Now, let's say the library cue creates some ship group and wants to pass the group on to the creator cue (maybe it's the case that the library cue keeps on running for a longer time and we have to do something with the group immediately, such as highlight it in the sector map, which is not done in the library itself). Normally, this can be done by referring to a higher level variable:

Code: Select all

<set_value name="A01 Foobar.SomeVar" ... />

Here, however, this is not doable since the library does not know what the caller cue is. It might be possible to use "parent", but then again, maybe we want to store the information toplevel and not directly in the calling cue? The elegant way to do this is to pass on the cue which will store the values to the library:

Code: Select all

<cue ref="ALIB01">
 <param name="Cue" value="A01 Foobar">
...
</cue>

This is something which we will see a lot of in the provided MD files.

Now, a case study. As we know, the TerraCorp (and OTAS, and maybe other) escort missions are bugged - they spawn friendly pirates. To check why this happens, we will have to trace the entire library call structure down to the very level of the OBS, which spawns the ship.

First of all, we look at the "3.06 Corporation Missions.xml" file. It does nothing interesting, just call the appropriate corporation missions, with no parameters set, so there's certainly nothing wrong here:

Code: Select all

<cue ref="L2M41" comment="Terracorp"/>

Now, the "2.41 Terracorp.xml" file. Here, after some initial setup cues we see two library calls:

Code: Select all

<cue ref="COM01">...</cue>
<cue ref="L0M19">...</cue>

Here we can see how the larger missions are built from smaller "bricks". The "COM01" library is simply a "Mission Director script" that makes ships follow a leader to a destination station and then dock there. Then, we call the L0M19 library. As we recall, the level 0 contains generic mission templates - let's see what's in L0M19:

Code: Select all

<content reference="L0M19" name="Escort Convoy" description="Escort some ships to a destination."/>

Okay, so we're in the generic escort mission code now... let's see how it spawns the enemies:

Code: Select all

<cue name="L0M19 ref OBS">
 <cues>
  <cue ref="OBS">
  ...

Here's our good friend - the Opponent Balancing System, or more simply "generic enemy spawner". Apparently, the bug does not appear just in OBS, since (almost) every mission that spawns enemies uses the OBS. However, OBS is a huge library and takes a lot of parameters. What might seem weird here is that, while OBS takes a lot of parameters, the L0M19 code only provides a few:

Code: Select all

<param name="OBS Cancel Cue" value="L0M19 ref OBS" comment="The cue which is canceled after the OBS finishes"/>
<param name="OBS Fleet Group Name" value="Enemies" comment="The group name where all main ships are saved too"/>
<param name="OBS Support Fleet Group Name" value="Enemy Support" comment="The group name where all support ships are saved too"/>
<param name="OBS Mother Ship Group Name" value="Enemy Carriers" comment="The group name where all ships with owned ships are saved too"/>
<param name="OBSPosition" value="10km" comment="how far away should the OBS ships be from FleetPositionObject"/>
<param name="OBSFleetPositionObject" value="{group.object.random@{param@GroupName}}" comment="The object which will provide the location information"/>
<param name="OBSSector" value="{group.object.random@{param@GroupName}}" comment="The sector where the ships will spawn if OBSFleetPositionObject not set"/>

What is going on here? Where did all the parameters disappear?

To solve the mystery, we have to remember how the parameters work. They are a kind of "local variable definitions" - ones that either have to be passed explicitly to the library script or defined somewhere "up the ladder". In other words - if there is a parameter defined in a top-level library cue and that cue calls a lower level library cue, the parameter is passed on by default. The TerraCorp mission itself does not provide parameters for the OBS script, but it provides some parameters for the L0M19 script, which passes them on to the OBS script.

Indeed, if we look up, we will find out that most OBS parameters are reintroduced as parameters to L0M19 and they are filled out by the call to L0M19 in the TerraCorp mission script. So, why are the pirates friendly?

A good idea is to try to compare the broken call in the TerraCorp mission with one that works. Let's take the station defense script, L0M35. After comparing the parameter lists passed to OBS, we find our possible culprits:

Code: Select all

<param name="OBSRaceSetup" value="1"/>
<param name="OBSFleetRelation" value="-1"/>

Those two are missing from the TerraCorp escort missions. Possible reason? They are not defined as parameters by the L0M19 script, so they're not passed on, and they're not passed directly as parameters to the OBS script. Let's look at the OBS parameter documentation at what they do:

Code: Select all

<param name="OBSRaceSetup" type="boolean" description="If pilot race is neutral/friend/enemy then add pilots and race names to ships when set"/>
<param name="OBSFleetRelation" type="number" description="-1,0,1 OBS fleet relation to the player"/>

Now, since the OBSFleetPilotsRace is actually set to neutral, we probably want the race setup to be done. And last but not least, we certainly want the spawned pirate ships to be hostile and not neutral.

So, how can we fix it? We have to add the OBSRaceSetup and OBSFleetRelation as paramters to L0M19 first, to have them passed on. Alternatively, we could just call OBS from within L0M19 with those two extra parameters. If we decided for the first approach, we have to now put the extra parameters to the L0M19 call from the TerraCorp and the OTAS mission scripts. If we do it on the level of L0M19, we just need to do the change once. The question to ask here is: will we ever need different functionality? Do we want escort missions to spawn non-hostile fleets? Since the answer is probably "no", adding the functionality to L0M19 is probably a better idea - future missions utilizing this library won't have to remember about the two extra parameters to pass.

This concludes the tutorial - I hope I've illustrated some points about MD script file design and ways of using provided code. Hopefully this can help any potential mission writers out there.

[BugMeister]

- there ought to be a "sticky" specifically for the MD..

- and this should be in it, IMO..

[ezra-r]

great!

since there are so.. "none" MD content out there and I could enrich X3 experience a lot if some scripters would use the md too.

[Teladidrone]

I use the MD - you can indeed do some funny stuff very fast and easy there.

But... and that's a really big but:
Basically the most important "feature" is almost totally missing - you CAN NOT define and add your own conversations in a sane and healthy way (conversations and actors is that what is needed to make those nice and shiny mission icons appear on ships and stations).
There is exactly one "reusable" custom conversation included in vanilla TC and that's all; and this one is just a basic buy thingy - very, very basic...
Unfortunately with the BBS gone, actors/com interface are now the preferred and almost only way to offer missions; and that's exactly what a scripter can not really do atm.

Sure, one can mod t/conversations.xml and add some own conversations there as needed - this is the file which holds every conversation definition of the game.
But if you think about it for a second that is not really an option because having a wrong/incomplete/incompatible t/conversations.xml would break the WHOLE game and as soon as there is more than one scripter trying to mod this file and adding custom conversations fun is over.
Unless there exists some very cleverly hidden other way (which apparently no one has discovered yet and the total absence of any documentation regarding missions/conversations is certainly not helping) there is no need to dump the script editor and change over to the MD...

[jlehtone]

- there ought to be a "sticky" specifically for the MD.

Yes, we should have two pages worth of stickies for the "regular" threads not to disturb our peace.

However, a link in the "Tutorials and Resources" must do for now.

[apricotslice]

Ilintar, can you expand this to include a basic tutorial on how to get a new MD file to run in the game ?

So far, I am unable to get anything to run, that doesnt already exist. Modifying an existing MD file works, but putting a new on in does not.

There does not appear to be a decent tutorial around on how to add a new file, and here seems the appropriate place.

[Ketraar]

There does not appear to be a decent tutorial around on how to add a new file, and here seems the appropriate place.

Download and read the Manual from the X3R MD from this topic, its basically the same procedure, just that in TC there are a lot (and I mean a lot) more commands/options.

Making a tutorial for MD is almost as hard, as to explain the existence of the universe. The possibilities are so many no tutorial would cover them all. Once you get the basics its pretty much up to you how you combine stuff together.

We have set up a MD questions topic in the german S&M Forum, where people can post their specific questions. They get help and learn in same process which is imo the best way to go, doubt that anybody would have that much spare time to make such a large tuto (plus it would probably be missing stuff anyway).

I would say, start asking and I'm sure someone will help, you just need to realise that you'll have to start low and make your way step by step.

MFG

Ketraar

[apricotslice]

Saw that thread, but missed the download link.

I'll check it out.

Thanks.

[SAVOTW]

I have a question about the MD, I hope it's o.k .to post it here;

Several of the functions available in the MD do not seem to have examples in the files of TC itself like run_script and the one I'm having issues with play_movie

Now in Reunion these did not work, but in TC I know from experience that run_script does work and I'm trying to get play_movie to work atm..

SO does play_movie work in the MD now as of TC, if it does what format should the movie/video be and where should it be placed in directory of TC?
Has someone a snippet of code showing this function working?

I know scripts are in scripts folder, but images seem to be in director/images and are .tga format. Should vids/movies be in mov folder and be .dat format?
Thanks

[Carlo the Curious]

It's used in several of the main plots.

[SAVOTW]

Yep, thanks
Bit dumb but I didn't think to use the 'find' option. It appears in the khaak missons;

<play_movie movieid="8130"/>

interestingly this plays the file 00813.dat in the mov folder of TC directory. I also tried using the fade in/out(both) on the vids but I got sound only and no pic.

On another matter, due to my changing my e-mail my account was deactivated, the reactivation e-mail was sent to my spam folder - so I didn't see it. I decided to contact a moderator, however to PM you have to be logged on and to e-mail(by clicking on the link) it tried to activate outlook express that win7 doesn't have.

Thanks again for the reply

[FyreByrd]

Hey just spent ages looking and can't find a link with a direct how-to on extracting the mission director files for TC, can anyone post me up a link?

Cheers

FyreByrd

[Ketraar]

Not sure what you mean by extracting the director files, but I feel that in any case you should do the following:

1. Read my post above and visit the topic linked there.
2. Read topics related to MD, some may be found linked in the stickys.
3. Use X3 Modmanager and/or X3 Editor 2 Cat plug in to extract files, even "director" files.

MFG

Ketraar

[Argonaught.]

All post that had answers/or explanations are combined and posted in the thread linked to in my sig.

It's the best I could do to gather everything to help me and others.

It still needs something special added to it before it will be deemed sticky-able.

Anyway everything can be found in the link below as said.

HTH

Argo.