[Tutorial] The MD - First Contact

[Gazz]

For a first time user this can be quite confusing.
Some very basic information on how the MD "ticks" is simply not there.

There are a few tutorials on how to do particular things.
This here is rather on why it is necessary to do them. Sort of an introduction to the "real" tutorials.

Script Editor (SE) experience is useful only insofar, that it helps understanding what the objects do, once the MD tells them to do something.

This is by no means a complete list but only the issues I... encountered so far.

1. Where are the files?
   Use Doubleshadow's Mod Manager to unpack director\*.* , starting with 01.CAT (provided you want the graphics) or 03.CAT.
   
   
2. Get an XML editor
   You need one. (Yes, you do!)
   Visual Web Developer 2008 is free and it works.
   
   
3. director.htm
   Very important reference file.
   Requires ActiveX so don't try opening it with Firefox.
   
   
4. MD file naming convention
   director\*.xml
   That's it.
   
   If you mess up the XML structure, the whole file is ignored.
   
   
5. When are MD files read / activated / patched?
   To "activate" your script once the game is *modified*:
   Start new game ...or...
   Load game
   
   Once "in" the game, all cues stay loaded and are buffered in the savegame.
   Deleting the *.xml file has no effect.
   
   When loading a game, the buffered code of all cues in the savegame (including those "waiting to fire"!)
   is overwritten by yourscript.xml, provided that the cue names match.
   
   Therefore there is no need to "patch" the MD code itself and no need for a version check.
   All that could require fixing is the state of the cues and which are currently "hot".
   This isn't more or less work than with the SE... just different.
   
   
6. When do Cues unload? How to get rid of them?
   The only way to completely remove cues from your savegame is

   Code:

   <destroy_cue cue="xgz_mdl_setup"/>

   for all cue names you used.
   That's the uninstall script or when you royally screwed up.
   
   No idea if that automatically destroys all subcues with it. I would assume so, but...
   
   
7. Variables
   All variables are assigned on the fly without requiring declaration.
   They are not and cannot be limited to a data type.
   
   
8. Variable Scope
   All variables are global and immediately accessible in all cues of all MD scripts.
   Expect typical name concflict issues.
   
   Only when a variable is used as "mycue.variable" (or in it's home cue, "this.variable"), it is created "semi-local".
   For all practical purposes you just used a longer variable name in doing so, so the name is unique again.
   
   Every local variable can be accessed in all cues of all MD scripts if you reference it as "mycue.variable" so it's not really "local".
   
   Not tested:
   Local variable might be affected by the destroy_cue action while global ones are not tied to a specific cue.
   
   
9. The Local / Global variable ambiguity
   While using the same term, MD and SE use completely incompatible systems.
   
   
10. Objects
    Just like in the SE:
    unless you find/create an object, you have no object.
    You have {player.ship} as a constant.
    Supposedly object="" also defaults to {player.ship} but being verbose is far easier to read and debug.
    
    
11. Timing
    Unless otherwise directed, a cue's actions execute instantly when the conditions are met.
    If there is a delay then it's too small for me to measure.
    So obviously, the conditon is checked every frame or nearly so.
    
    But there ain't no such thing as a free lunch.
    Have 200 unique cues simultaneously waiting for a condition like the distance between 2 objects... and watch your FPS drop.
    
    The MD cannot magically check many things instantly without using CPU time to do that.
    So just like in the SE - use sensible delays to limit how often things are checked.
    
    Some conditons (ship destroyed) are "real" events, that are apparently driven by real hardcoded events/signals like in the SE.
    Those are rather harmless in that regard.
    
    
12. When do Cues fire and what do they fire?
    A cue will always wait patiently until all specified conditions are met.
    Then it executes the <action> and all included subcues.
    

    Code:

    <cue name="cue_test">       <condition> <object_exists object="gzstation"/> </condition>       <action>  <incoming_message popup="1" text="Test for condition: station EXIST"/>  </action>       <cues>         <cue name="subcue_test">           <action>  <incoming_message popup="1" text="Unconditional subcue of    station EXIST"/> </action>         </cue>       </cues>     </cue>

    Both messages fire at the same time.
    
    
13. When do Cues refire?
    They don't.
    Once a (non instanced) cue has run, it's done forever.
    
    You want to keep doing something, you include a failsafe to reset and enable the cue to run again - based on it's conditions.
    

    Code:

    <cue name="xgz_mdl_setup">       <condition> <object_exists negate="1" object="gzstation"/> </condition>       <action>         <do_all>           <reset_cue cue="xgz_mdl_setup_reset"/>           <find_sector name="this.mdl_sector" x="0" y="0" nearest="1"/>           <create_station name="gzstation" safety="0" race="neutral" typename="SS_DOCK_A_TRADE">             <position x="00km" y="00km" z="00km"/>             <sector sector="this.mdl_sector"/>             <equipment loadout="none"/>           </create_station>           <incoming_message popup="1" text="Object not found.  New {object.name@gzstation} created."/>         </do_all>       </action>       <cues>         <cue name="xgz_mdl_setup_reset">           <condition>             <check_all>               <object_exists negate="1" object="gzstation" />             </check_all>           </condition>           <action>             <do_all>               <incoming_message popup="1" text="Setup complete, object  'gzstation'  not found.  Reseting setup script."/>               <reset_cue cue="xgz_mdl_setup"/>             </do_all>           </action>         </cue>       </cues>     </cue>

    
    When the "setup" runs, the subcue starts waiting for it's sole condition - which is that the required station is no longer there.
    If that ever happens, it kicks the main cue back into action.
    Note: The reset automatically applies to all (?) subcues, such as the failsafe cue itself.
    
    (yes, there are other ways to have reoccurring missions and the likes but that's definitely not "basics")
    
    
14. Operators
    There are (+-*/).
    Nothing binary, no SQR, no nothing. Suck it up.
    
    Check_Value can supposedly (not tested) compare a string to exact="xyz".
    That's the complete list of string operations.
    
    
15. Game Data
    Very little is accessible.
    Any remotely intelligent weapon/loadout selection is impossible because the MD cannot read laser damage,
    required ammo, missile damage / flags, or even the range of any weapon at all.
    Whenever the MD selects an enemy ship and a weapon loadout it's deciding based on assumptions, not data.
    
    You can hardcode such data points in your MD script but then your MD script will only work properly in the mod it was written for.
    Since the MD cannot access SE global variables such as 'XTMOD.ACTIVE', it will have a hard time figuring out if a different mod is active.
    Creative workarounds will be required.

[Gazz]

** reserved **

[eldyranx3]

Exactly what I needed! Pouring through the 2.0 Plot XML had me scratching my head for a while. Thank You Sir, you are a GoD among Men.

[ScRaT_GER]

Nice overview Gazz!

[Gazz]

Yah, so the tooltip says but I intentionally glossed over all details like that.
Performance tuning is a long way off from the first script. =P


I'm more interested in generic info on how the system works here.
How does the leg bone connect to the hip bone?

For instance, how do I "do stuff" with every single member (ship) of a group?
The very basic tools already come in a group flavour but what if I need something else?
In the SE I'd loop through the ship array and get all objects single file.
Cake.
How does that work in the MD?

[ScRaT_GER]

[Aro]

[Shush]

Great MD topic, I'll add my own experiences...

You could also do the following with ScRaT_GER's example:

[Gazz]

[Shush]

[Gazz]

That already makes more sense.
The tricky bit with stuff like that usually isn't getting an answer but finding the right question.
Takes a real noob to do that so manuals/tutorials written by experts suck when they don't explain the "obvious" issues.

It's obvious that there must be instances, both from seeing the game work and the "instantiate" property of the cue tag.
Only without a clear understanding of what exact bits of what cues are executed and when, it's not useable.

The SE is easier in that reagard.
You start an action - something happens.
You have it wait until conditions XYZ are met - then it does something.
The sequence of events is always clear.

[ScRaT_GER]

[Shush]

[ScRaT_GER]

Thanks for the info! This is going to be really valuable for later projects I'm planning.

[Shush]