How to create custom missions

[T.C.]

As requested, here is the tutorial for creating custom missions.

To start off I suggest you visit the NTW Script-o-Rama. From there you will find a basic introduction to scripting, helpful tips and advice on tools to use (mainly notepad ++). This thread assumes you have basic knowledge, all of which is available in the script-o-rama.

Part 1: The function

The function used to create a custom mission is scripting.game_interface:trigger_custom_mission(). This function creates "custom mission" (no points for guessing that one ) and does not need any db entires - it is all controlled via scripts.
It takes 13 arguments, as follows:

1. Name
   
   
   • Type: String
   • Notes: This is the name of the mission. It must be unique, and is used to reference the mission elsewhere.
     
2. Faction key
   • Type: String
   • Notes: This is the faction that the mission will be given to. Remember missions are not given to the AI
3. Mission Activity
   • Type: String
   • Notes: This is one of 15 activities that the mission can involve, as defined in missions_activities_tables. They are:
     • assassination
     • blockade_port
     • build_building
     • capture_city
     • capture_fort
     • duel
     • engage_character
     • engage_faction
     • gain_military_access
     • forge_alliance
     • make_trade_agreement
     • recruit
     • research
     • spy_on_city
4. Turn Limit
   • Type: Integer
   • Notes: This is used to define the amount of time before a mission fails. Setting it to 0 gives it unlimited time.
5. Target Item
   • Type: String
   • Notes: This is the missions "target". It can be a faction, a unit, a character, a technology etc.
6. Heading key
   • Type :String
   • Notes: This must correspond to a text entry in the loc. This is the text that will head the mission pop up. To leave blank, use empty quotes.
7. Description Key
   • Type: String
   • Notes: Same as above, except this will from the main body of the pop up. To leave blank, use empty quotes.
8. unused Key
   • Type: String
   • Notes: This is some form of unused reward key. Always leave blank. To leave blank, use empty quotes.
9. Reward Key (Cash)
   • Type: Integer
   • Notes: Use this to reward sums of cash
10. Reward Key (Faction)
    • Type: String
    • Notes: This is used to reward an entire faction. It's entry must be a valid faction key. To leave blank, use empty quotes.
11. Context
    • Type: Userdata
    • Notes: Must always be "context", without the quotes. Passing other arguments is unnecessary and will cause errors.
12. Unknown argument
    • Type:Boolean
    • Notes:Purpose unknown. Is nearly always false.
13. Reward Key (Misc)
    • Type:String
    • Notes:This is used as an alternative way to give some rewards, and to access rewards not normally available (ie pre NTW using this function). It must be a string and can have multiple values. Internal values must be separated with a comma (,). The types are(with examples):
      • money:1000
      • grant_experience_army:1
      • grant_unit:Inf_Line_Austrian_German_Fusiliers#settlement:eur_baden_wurttemberg:stuttgart
      There are possibly more options available to it.

---

Part 2: Usage examples
The following example assigns a mission to Austria, to ally with Prussia. It gives as a reward 100 cash and the faction of France(bit excessive, I know ). It has unlimited time and is called "TutorialTestMission". It has no heading or body text and is called inside the OnFactionTurnStart() function of scripting.lua.

scripting.game_interface:trigger_custom_mission(
								"TutorialTestMission",
								"austria", "forge_alliance", 0, "prussia",
								"",
								"",
								"", 100, "france", context,
								false, ""
								)

As you can see, the game has loaded appropriate placeholder text for you. You will also notice it doesn't correctly inform the player of all the proper rewards, an annoying issue to say the least.

Spoiler Alert, click show to read: 

It does, however, correctly grant the rewards - as seen here

Spoiler Alert, click show to read: 

There is no mission completed pop-up - these have to be scripted manually. There are oddly enough hardcode issues with them, so I'm not going to post any info on that here just yet as I'm short on time. If anyone wants info desperately just shout and I'll get it up

That's all I can think of off the top of my head. If anyone has any issues or questions feel free to post and I'll do my best to help

[.Mitch.]

Question, without me trying it out for myself cause Im lazy.

Can missions provide nothing as a reward? I see you say that the Reward key can be blank, and you say that the second Reward Key can be an "alternative".

I guess at the very least you could just do "money:1", or even "money:0" providing that wouldn't cause problems, lol

Good work btw, about time you wrote this.

[T.C.]

Question, without me trying it out for myself cause Im lazy.

Can missions provide nothing as a reward? I see you say that the Reward key can be blank, and you say that the second Reward Key can be an "alternative".

I guess at the very least you could just do "money:1", or even "money:0" providing that wouldn't cause problems, lol

Good work btw, about time you wrote this.

I don't see why not. The cash reward is more often than not set to 0 (and the cash handled through the alternative reward arg). If I'm guessing where you are going with this correctly, I can post code that stops the missions notification from popping up. If

[Leoben]

Great guide TC, thanks!

[Admiral Van Tromp]

Thank you. This will help me very much! Here's the rep I saved for now!

[husserlTW]

Question, without me trying it out for myself cause Im lazy.

Can missions provide nothing as a reward? I see you say that the Reward key can be blank, and you say that the second Reward Key can be an "alternative".

I guess at the very least you could just do "money:1", or even "money:0" providing that wouldn't cause problems, lol

Good work btw, about time you wrote this.

In Empire " " is placed instead of the number If you want no money so why not for Napoleon too?

[T.C.]

In Empire " " is placed instead of the number If you want no money so why not for Napoleon too?

In Empire the last two arguments don't exist, if you look carefully. They were introduced in NTW. What you are seeing is a different argument left blank most likely.

[husserlTW]

My point was that Mitch could try to leave it blank (" ") and see if it works.

[T.C.]

My point was that Mitch could try to leave it blank (" ") and see if it works.

Yes that would work also.

[Admiral Van Tromp]

Is that placeholder text on the localization file?

[T.C.]

I presume it is - though it may not be there, it's possible that it's handled in the luac file. I can't tell as I haven't looked.

[Admiral Van Tromp]

I will try to find them.

EDIT: They are on the localization.pack, divided in heading and text.

The ones for Europe campaign are named as:
mission_text_text_eur_faction_mission activity_targetfaction_heading/text

The ones for Egypt and Italy, are the same but replacing "eur" with "egy" or "ita".

The placeholder ones, that appear on the custom ones like the example on the OP, are named:
mission_text_text_main_mission_mission activity_heading/text.

The mission activities text is in:
mission_activities_description_mission activity

The mission rewards text is in:
mission_effects_text_T+x
x being the treasury bonus the player receives.

Note: replace "mission activity" with the ones in the OP, for example "blockade_port".

I also found a promotion mission. I wonder what is the objective. In the text it talks of promoting a notable gentleman. Did you know of any gentleman promotion? Or maybe it's to recruit a general in a certain army?

[husserlTW]

I used first time the T.C.'s custom mission and it's a very good work, +rep!

Allow me a correction so far: "build" mission activity is not functional. Instead you should replace with "build_building" which works fine.

[T.C.]

I used first time the T.C.'s custom mission and it's a very good work, +rep!

Allow me a correction so far: "build" mission activity is not functional. Instead you should replace with "build_building" which works fine.

Thanks for pointing that out, I'll change it now

[husserlTW]

Also make_alliance should be be replaced by forge_alliance and protectorate_region_capture is not a generic mission activity so it must be replaced by capture_city (which exists already in your list).

EDIT: Also I noticed that turn limit is not shown up in mission message. My way is adding a new line at the end of mission description: \n\nTurn Limit = X

(\n\n is for a new paragraph under en empty line and X the number of turns)

[T.C.]

Also make_alliance should be be replaced by forge_alliance and protectorate_region_capture is not a generic mission activity so it must be replaced by capture_city (which exists already in your list).

EDIT: Also I noticed that turn limit is not shown up in mission message. My way is adding a new line at the end of mission description: \n\nTurn Limit = X

(\n\n is for a new paragraph under en empty line and X the number of turns)

Ok, thanks I'll update the list. I just looked at the db table for the activities.

Yes \n is the Lua backslash escape for a new line. You can also use \t for tabbing over. There's a decent list in the script-o-rama if you are interested

[husserlTW]

Just to confirm that agents can be spawned as reward but the appropriate town should be present in region. So if you want to have a gentleman an educational town must be present. Or it can be combined with a building mission (e.g. a college) in a town. In this case this mod is very useful...

[T.C.]

Just to confirm that agents can be spawned as reward but the appropriate town should be present in region. So if you want to have a gentleman an educational town must be present. Or it can be combined with a building mission (e.g. a college) in a town. In this case this mod is very useful...

They are used as rewards quiet frequently in the Spanish Campaign

[md1453]

Tried adding a mission to take a neighboring region. How long does it generally take for the mission to be issued to the player? I've clicked through about three turns and no effect yet

I noticed in the CA missions they start with:

local function take_vienna()
out.ting ("The Fall of Austria")

and end with:
end

local BOOL_vienna_taken = false -- Has Austria fallen?

with the scripting in between. Is this necessary or is this part of the triggering of the mission in game?

thanks!

EDIT: ahh, must be inside the scripting.lua file within the OnFactionTurnStart()

[md1453]

This is awesome. Thank you all for your work on this stuff.