Creating a Mission: The Basics

What is a mission?
If you don't know what a mission is... you should probably play more Simpsons Hit and Run.

A mission is simply a mission... There are 4 types of missions in The Simpsons Hit and Run: story missions, street races, wager races, and bonus missions.

Creating a Mission File
There are two different ways to create a mission - using a .mfk file or using a .lua file.

To create a mission using a .mfk file, create a new folder in your Mod's root folder and title it CustomFiles (must include the capital letters). In this folder, create another new folder, titled scripts (all lowercase). In the scripts folder, create another new folder, titled missions (all lowercase). Finally, in the missions folder, create another folder titled level0X (all lowercase; replace X with a number from 1 to 7). In the level0X folder, you can create a new text file by Right Clicking > New > Text Document. Title the file mYi.mfk (where Y is a number from 1 to 7, or 0 to 7 in level01). This is the information file that the game reads when a mission is loading. In the same folder, you'll need to create another .mfk file - title it mYl (lowercase L, and again Y is a number from 1 to 7, or 0 to 7 in level01). This is the file that tells the game what objects/persons to load for the mission.
NOTE: You can also title the text file srYi for street races (where Y is a number from 1 to 3), gr1i for the Wager Race, and bm1i for the bonus mission. These files must also have a corrosponding srYl, gr1l, or bm1l file.
NOTE2: To edit the pre-mission file, create a text file titled mYsdi (and mYsdl) (Y is a number from 1 to 7) in the correct folder. For example, m1sdi is the pre-mission info for level0X's first mission.

To create a mission using a .lua file, create a new folder in your Mod's root folder and title it Resources (must be capitalized). In the Resources folder, there will be two things - a file titled mfk.lua (click here to download it) and a new folder, titled missions (all lowercase). In the missions folder, create another folder - titled levelX (where X is a number from 1 to 7). In the levelX file, create a new folder - which will be titled mY for a story mission (where Y is a number from 1 to 7; or 0 to 7 in level1), rY for a race (where Y is a number from 1 to 4; and 4 is the Wager Race) or bm for the bonus mission. In the mission folder, there will be 5 files - 4 text files and one .p3d file. Create the text files and title them mYinfo.lua, mYload.lua, mYpreinfo.lua, and mYpreload.lua. These replace the mYi.mfk, mYl.mfk, mYsdi.mfk, and mYsdl.mfk files, respectively. For the .p3d file, see the Using .p3d Files section below.

Differences Between .mfk and .lua Files
Before I explain how to create a basic mission, there are a few differences between .mfk and .lua format for missions.

In .mfk mission files, you must include a ; (semi-colon) symbol at the end of each line. For example:

AddStage();
   AddObjective();
      SetDestination( "simpsons_house", "carsphere" );
   CloseObjective();
   SetStageTime(45);
CloseStage();

In .mfk load files, you must use a single \ when typing out directories, like this:

LoadP3DFile("art\missions\level02\monkey.p3d")

In .mfk mission files, if you want a part of the mission to be "ignored" by the game, use \\ as shown below:

AddObjective( "goto" )
   SetDestination( "simpson_house", "carsphere" )
\\ This line will be ignored by the game.
CloseObjective()
\\ This line too!
SetStageTime(75)
\\ So many double backslashes!

In .lua mission files, the ; (semi-colon) symbol is not used at the end of ANY lines. So, the above .mfk example would look like this in .lua:

AddStage()
   AddObjective()
      SetDestination( "simpsons_house", "carsphere" )
   CloseObjective()
   SetStageTime(45)
CloseStage()

In .lua load files, you must use a double \\ when typing out directories, like this:

LoadP3DFile("art\\missions\\level02\\monkey.p3d")

In .lua mission files, if you want a part of the mission to be "ignored" by the game, use -- as shown below:

AddObjective( "goto" )
   SetDestination( "simpson_house", "carsphere" )
-- This line will be ignored by the game.
CloseObjective()
-- This line too!
SetStageTime(75)
-- So many double dashes!

Keep this in mind as you work to create a basic mission.

Creating a Basic Mission
Now it's time for the purpose of this forum... creating a basic mission. To create a basic mission, first you'll need to tell the game what to do before the mission - the pre-mission info file will be used for this.

Create a text file titled m1sdi.mfk or m1preinfo.lua (depending on the route you chose when creating a mission file). Open the file. First, you'll need to tell the game what mission we are working with... so, in this case, we are working with the pre-mission 1 info. At the top of the text file, type the following:

SelectMission( "m1sd" )

This tells the game to only load this file before mission 1 of level0X (or levelX). (Remember: In .mfk files, you must put a semi-colon at the end of the line.)

The next thing you'll type depends on the level you're working in. To find out what comes next, you'll need to look at the mission files of the original Simpsons Hit and Run. (These files can be found in the following directory: /VivendiUniversalGames/TheSimpsons***&Run/scripts/missions - or, if you have a shortcut to the game on your desktop, right-click it and choose Open File Location > scripts > missions.) Open the level and mission file that corrosponds to the mission file you are making. In this case, we'll open level01 and open the m1sdi.mfk file. Copy all the lines between SelectMission( "m1sd" ); and AddStage(); and paste them into your new text file. (Remember, if you're using a .lua file, remove the semi-colon from the end of each line!)

After pasting those lines, we'll create our first Mission Objective - or "stage" - in the mission.

Create a new line after the last one and type this:

AddStage()

There should be nothing in the parenthesis - however, if it's the last stage in the mission file, it should say: 

AddStage( "final" )

These tell the game that a new objective is being added. For this "stage", we'll simply make this objective: Drive to the Simpsons' House.

To create this stage, first you'll need to add an objective. To add an objective, type this:

AddObjective( "goto" )
CloseObjective()

When adding an objective, you'll need to specify what that objective is. For example, "goto" means Go To this Location, "talkto" means Talk to this Person, "race" means Race to Here, etc. In this example, we'll begin with a "goto" objective.

Next, you'll need to specify where to go to. For the Simpsons' House, the destination is "m2_simpsonhouse_sd", which you type like this:

AddObjective( "goto" )
   SetDestination( "m2_simpsonhouse_sd", "carsphere" )
   SetCollectibleEffect( "wrench_collect" )
CloseObjective()

The "carsphere" is basically the checkpoint marker used in Checkpoint Races, but it can also be used as a destination marker. The "wrench_collect" effect makes the carsphere disappear correctly. If this is not included, the carsphere will disappear in a large cloud of yellow sparkles.

Next is the HUD icon. This is the icon used in the top-left corner of the screen to remind the player of the current objective. For this objective, we'll use the Simpsons House icon, which can be added like this:

SetHUDIcon( "simpsons" )

The last thing to add to this objective is the mission objective text. For this example, the mission objective text is "Drive to the Simpsons' House." You can add it yourself using the CustomText file (tutorial here), or use the game's default text, which is objective 217. It can be added like this:

SetStageMessageIndex(217)

Upon finishing the stage, type this line:

CloseStage()

If done correctly, the stage should look like this:

AddStage()
   AddObjective( "goto" )
      SetDestination( "m2_simpsonhouse_sd", "carsphere" )
      SetCollectibleEffect( "wrench_collect" )
   CloseObjective()
   SetHUDIcon( "simpsons" )
   SetStageMessageIndex(217)
CloseStage()

Next, we'll create a "talkto" stage. In these stages, the objective is: Talk to Marge, Talk to Lisa, etc.

To create a talkto stage, first create a new stage as before.

AddStage()

CloseStage()

When creating the new objective for this stage, type "talkto", "both" instead of "goto", like this:

AddStage()
   AddObjective( "talkto", "both" )

   CloseObjective()
CloseStage()

In this case, we want to talk to Marge. You'll need to look at the game's original file for this mission to see what the dialogue is coded as... because it is too advanced for this tutorial. When creating this talkto objective, type this: 

AddStage()
   AddObjective( "talkto", "both" )
      AddNPC("marge", "m1_marge_sd")
      AddObjectiveNPCWaypoint( "marge", "marge_walk_1" )
      AddObjectiveNPCWaypoint( "marge", "marge_walk_2" )
      SetTalkToTarget( "marge", 0, 0.2 )
   CloseObjective()
CloseStage()

The "AddNPC" command adds the NPC (Marge, in this case) in a location (m1_marge_sd) mentioned in the .p3d file of this level/mission. The "AddObjectiveNPCWaypoint" commands tell the NPC (Marge) where to walk to (marge_walk_1 and marge_walk_2), which is used for when the NPC needs to walk back and forth (as seen in-game). The "SetTalkToTarget" command tells the game which character the player will talk to (Marge, in this case).

Remember to set a HUD icon and a Mission Objective text when creating this stage, as shown below:

AddStage()
   AddObjective( "talkto", "both" )
      AddNPC("marge", "m1_marge_sd")
      AddObjectiveNPCWaypoint( "marge", "marge_walk_1" )
      AddObjectiveNPCWaypoint( "marge", "marge_walk_2" )
      SetTalkToTarget( "marge", 0, 0.2 )
   CloseObjective()
   SetHUDIcon( "marage" )
   SetStageMessageIndex(00)
CloseStage()

After this stage, copy the dialogue from the game's original file and paste it into your new file. Make sure it includes EVERYTHING between the AddStage() and CloseStage() lines. Also, because it is the final stage, make sure the first line of the stage reads:

AddStage( "final" )

This will tell the game that there are no more stages after this one. When you finished creating the mission file, you'll need to type this closing line at the end:

CloseMission()

Creating a Mission Load File
This section is Coming Soon!

Using .p3d Files in Missions
This section is Coming Soon!

Other Useful Text Strings in Mission Files
There are many more basic text strings you can use for each stage. Here is a list of them, with a description:

RESET_TO_HERE()

If the player selects "Restart Mission," the game will reload the mission starting with the stage that contains this line. If this is used in a pre-mission file, the game will load the mission from this point when selected from the "Mission Select" menu.

SetStageTime(30)

This is used for a time limit in a stage. The number (in SECONDS) tells the game how much time to give the player. It can be set anywhere from 1 to 999 (*). If this is used in a mission, the stage it's used in must also include the following:

AddCondition("timeout")
CloseCondition()

This tells the game that if the TIME runs OUT, the player will fail the mission and have to start over.

TurnGotoDialogOff()

This MUST be used along with an AddObjective( "goto" ) stage. It will turn off all dialogue of the player when they arrive at their destination.

DisableHitAndRun()

This will disable Hit and Run in the stage it is used in. It will not carry over through the entire mission/level.

AddCondition( "outofvehicle" )
   SetCondTime(10000)
CloseCondition()

This tells the game that if the player is out of their vehicle for 10,000 MILLISECONDS (10 seconds), they will fail the mission. The Condition Time can be any number in milliseconds.

ShowStageComplete()

This will cause the "Task Complete!" text to appear on-screen when a stage is completed. It is recommended to NOT use this at the end of a mission, as it will display the Task Complete and Mission Complete text at the same time on-screen.

AddCondition( "damage" )
   SetCondMinHealth ( 0.0 )
   SetCondTargetVehicle( "current" )
CloseCondition()

This will tell the game that if the player destroys their vehicle, they will fail the mission. The Condition Min. Health is the lowest amount of health that the player's vehicle can be in during that stage (must be a decimal, such as 0.0). The Condition Target Vehicle is the vehicle that must be destroyed in order to fail the mission. Current is the player's current vehicle that they are driving.

StartCountdown( "count" )
   AddToCountdownSequence( "3", 1000 )
   AddToCountdownSequence( "2", 1000 )
   AddToCountdownSequence( "1", 1000 )
   AddToCountdownSequence( "GO", 400 )

This will trigger the countdown used at the start of Street Races. The "3", "2", "1", and "GO" must be in quotes, because they are the names of the text used in the CustomText file. The number after it (1000, as shown above) is the time, in MILLI-seconds, that the number will be on-screen for.

AddStageTime(45)

This will tell the game how much time, in seconds, to add to the time remaining from the previous stage. Again, it can be set to any number from 1 to 999 (*) and must include the "timeout" condition with it.

NOTE: When setting Stage Time, using 0 will make the game default the timer to 1. Using -1 (yes, you can use -1) will not spawn the timer, and there will be no time limit.



CREDITS
legomariofanatic - Created Tutorial
Donut Team - Created the mfk.lua file

Other Mission Tutorials
Creating a Item-Collecting Mission
Creating a Follow Mission
Coming Soon: Creating a Destroy Mission
Coming Soon: Creating a Follow-and-Collect Mission
Coming Soon: Creating an Avoid Mission
Coming Soon: Creating a Simple Race Mission
Coming Soon: Creating a Checkpoint Race
Coming Soon: Creating a Race with Laps
Coming Soon: Creating a Hit-and-Collect Mission
Coming Soon: Creating a Wager Race

Hopefully, I can create them all within the next few weeks...

The only problem is that I have NO idea how the Follow-and-Collect missions work... so, I'll just leave that up to the Donut Team to create... :)

"Again, it can be set to any number from 0 to 999"

Fun fact about AddStageTime. If you set a stage to AddStageTime(0), it'll actually add a second onto the stage anyway. We found that if you change it  to AddStageTime(-1), it'll not add any time onto the stage, and instead just use time from when you last used SetStageTime, like you have said.

EDIT: I'd also like to add that this is a fantastic beginner's tutorial. It is clear, concise and very well laid out. It's better than anything I could do too, since i'm terrible at making tutorials like this lol

Oh, and you've forgotten a couple of differences between .lua and .mfk files.
1.
Lines that are commented out (so they don't activate in the mission or if you just want to say something that isn't coding) are "//" in .mfk files and "--" in .lua files.
eg

//Hit Snake's car and colllect the last of the stolen donuts 

--Hit Snake's car and colllect the last of the stolen donuts 

That has to be changed, otherwise you'll get an error.

2.
When you are loading vehicles in the game, the file location's slashes must be changed as well.
eg

"art\frontend\dynaload\images\msnicons\location\school.p3d"

^.mfk files

"art\\frontend\\dynaload\\images\\msnicons\\location\\school.p3d"   

^ .lua files
Although the 2nd one might not apply to the tutorial because nothing is being loaded, if people where to edit a mission already in the game, this would also through up an error.
apart from that, this is a great tutorial!

Yet again, another excellent tutorial legomariofanatic! Seems pretty through even though I haven't read all of it yet. I couldn't help but notice that you were talking about the Follow and Collect Missions.

Those are a bit odd, so I'll try to explain that to the best of my ability. You can thank Loren for figuring these out and teaching them to me.

BindCollectibleTo(1, 2);

You might have noticed this string in these follow and collect missions. These things basically tell where the game to dump the items.

The first variable (the 1 seen above in the example) is the item that is going to be dumped, while the second variable (the 2) is the waypoint that the item is going to be dumped at. The game starts counting items at 0 with BindCollectibleTo, so let's say you add this item to the dump objective:

AddObjective("dump");
SetObjTargetVehicle("cKenny");
AddCollectible("m1_crate_1","cola");

m1_crate_1 is the first item listed and the one we want to dump. Since it's the first one listed, it's defined as 0. The next item (say m1_crate 2) would be 1, and so forth. The same applies to the waypoints the AI car follows. So the first waypoint you put in the mfk file will be 0, the second will be 1, and so forth.

So let's say you wanted to dump the fifth item you put in the script at the 8th waypoint. In that case, you'd put this:

BindCollectibleTo(4, 7);

If you're still confused, please let me know. 

Edit because Chris mentioned something I should've put here earlier:

Much like the items you have to hit a truck for and collect, you DO NOT have to define their locations in the P3D file. In short, the items locations can be anything, and they'll appear near the waypoint. Much like how if you hit a car to grab items, it's locators can be random and it'll appear right near where the car was hit.

@JustinBoy159 - Oh... You're right! One second... *makes quick edit* Added to the list!

@bomberman333 - Thanks for the tips! I've added them to the tutorial in the appropriate spots! Thanks!

@Kenny Giles - So THAT'S how the Follow-and-Collect Missions work! Thanks! I'll make that tutorial soon, now!

Also, I find it funny that this tutorial was created THREE WEEKS AGO, and you guys are just now noticing it...

Things I spot which are wrong:
1. The \\ are actually unnecessary, and also incorrect (you're supposed to use // if you want to dummy a line out).
2. Since this is a pre-mission stage, remove the SetStageTime from the first objective. Timers in pre-mission stages can cause glitches in the game.
3. You do NOT need to put blank lines in between the stages (although, the \\ are incorrect, a blank line will not be read by the game either).

If those three tips still cause it to crash, let me know!  :)

i solved that one yesterday its just my follow mission im having problems with now.

AddStage(0);
 SetHUDIcon( "wiggu_v" );
 SetMaxTraffic(1);
 SetStageMessageIndex(271);
 AddObjective("goto");
  AddStageVehicle("cPolice","eddie_race","NULL","Missions\level06\sr3_1st.con", "eddie");
  SetDestination("m4_wiggum_carstart","triggersphere");
  SetCollectibleEffect("wrench_collect");
//  MustActionTrigger();
 CloseObjective();
CloseStage();AddStage(0,"final");
 ActivateVehicle("cPolice","NULL","race");
 SetMaxTraffic(3); 
 SetStageMessageIndex(70);
 SetHUDIcon( "dmv" );
 //PutMFPlayerInCar();  // This makes the play auto reset into their car for this stage.
//SetStageAIRaceCatchupParams( 
// STAGEVEHICLENAME,
//      ALONGROADDISTFROMPLAYER_TO_APPLYMAXCATCHUP, // default = 80
//      FRACTIONPLAYERSPEED_MINCATCHUP,   // default = 0.5
//      FRACTIONPLAYERSPEED_NOCATCHUP,    // default = 1.1
//      FRACTIONPLAYERSPEED_MAXCATCHUP )  // default = 1.7 AddStageWaypoint( "m7_smithers_race1" );
 //SetStageAIRaceCatchupParams("wiggu_v", 80, 0.5, 1.1, 1.7); 
 SetStageAIRaceCatchupParams("cPolice", 80, 0.9, 1.5, 2.3); 
 SetVehicleAIParams( "cPolice", 50, 51 );   // no shortcuts
//  AddStageWaypoint( "waypoint1" );  
 AddStageWaypoint( "waypoint2" );
 AddStageWaypoint( "waypoint3" );
 AddStageWaypoint( "waypoint4" );
 AddStageWaypoint( "waypoint5" );
 AddObjective( "race" );
  AddCollectible("waypoint5", "finish_line");
//  SetCollectibleEffect("finish_line_col");
 CloseObjective();
 AddCondition("race");
  SetCondTargetVehicle("cPolice");
 CloseCondition();
 AddStageMusicChange();
CloseStage();CloseMission();

load file:

LoadP3DFile("art\missions\level05\m4.p3d");LoadDisposableCar("art\cars\wiggu_v.p3d","wiggu_v","AI");
LoadDisposableCar("art\cars\cPolice.p3d","cPolice","AI");
LoadP3DFile("art\missions\level04\donut.p3d");LoadP3DFile( "art\frontend\dynaload\images\msnicons\object\donuts.p3d" );
LoadP3DFile( "art\frontend\dynaload\images\msnicons\vehicle\wiggu_v.p3d" );
//LoadP3DFile( "art\frontend\dynaload\images\msnicons\char\lisa.p3d" );
//LoadP3DFile( "art\frontend\dynaload\images\msnicons\object\tomoto.p3d" );
LoadP3DFile( "art\frontend\dynaload\images\msnicons\location\dmv.p3d" );
LoadP3DFile("art\missions\generic\fline.p3d");

soo many questions (my questions obviously)
what is wrong with my m4.p3d file?
obviously this is only a part of the misión ,since is the part which is crashing

First of all, I'm assuming that this is Level 5 Mission 4. Also, for some reason, in .mfk files, if the file size is more than 10KB, the game crashes (for some reason).


You can remove all lines starting with // since the game ignores those.

In the first stage, nothing seems incorrect... but if the game crashes there, let me know.

In the final stage, you MUST put the ActivateVehicle line right before the SetStageAIRaceCatchupParams and the SetVehicleAIParams lines.

Also, the AddStageWaypoint( "m7_smithers_race1") line probably should exist in this mission at all. You should get rid of it.

Finally, if you're going to use the AddStageMusicChange line, you must also use the SetStageMusic( ) line as well.

If the game still crashes, let me know!

CORRECT FINAL STAGE:

AddStage(0,"final");
   SetMaxTraffic(3);
   SetStageMessageIndex(70);
   SetHUDIcon( "dmv" );
   //AddStageWaypoint( "m7_smithers_race1");   // This line does not seem to belong here.
   ActivateVehicle("cPolice","NULL","race");   // This is the correct spot for this line.
   SetStageAIRaceCatchupParams("cPolice", 80, 0.9, 1.5, 2.3);
   SetVehicleAIParams( "cPolice", 50, 51 );
      AddStageWaypoint( "waypoint2" );
      AddStageWaypoint( "waypoint3" );
      AddStageWaypoint( "waypoint4" );
      AddStageWaypoint( "waypoint5" );
   AddObjective( "race" );
      AddCollectible("waypoint5", "finish_line");
   CloseObjective();
   AddCondition("race");
      SetCondTargetVehicle("cPolice");
   CloseCondition();
   //SetStageMusic();   //Add this line here, and put the music you wish to use inside the ().
   AddStageMusicChange();   // This line requires a SetStageMusic line to go with it.
CloseStage();
CloseMission();