F.H. / @nirvana on Runeforge (March 28, 2011)
In this howto I will try to cover the very basics about adding new measures to the game. The resulting "mini-mod" will include an icon, it's own name and a new "Hello World" measure.
Although the howto will be very easy to finish, you should have some scripting knowledge, at least the basic syntax of Lua shouldn't be a problem for you.
Also you need a proper editor like notepad++, UltraEdit or similar. What's definitely no proper editor is Word, no matter if it's MS Word or OpenOffice/LibreOffice.
1. The sourcefile of the measure
Create a new file called "ms_helloworld.lua" inside the folder "scripts/measures/".
Copy the following code into this sourcefile:
Now you've added an empty measure. The function Run() is called when the measure starts and the function CleanUp() when the measure is cancelled or finished.
The next step is making the game recognize the new measure.
2. Adding the measure to the measures database
Open the file DB/Measures.dbt
This file is the database file for all of the measures in the game. Every measure you can use in the game is stored in here.
Add the following code at the end of the file:
The most important parameters of this line are:
- The first parameter "12096" is the ID of the measure. Make sure, that it's the highest number in the file and unique (12096 is just a placeholder in this example).
- The second parameter "ms_helloworld.lua" is the path of the script including the measure starting at "scripts/measures/".
- The third parameter isn't used in this example
- The fourth parameter is the name of the measure
- The fifth parameter is the priority of the measure. Measures can only be interrupted by other measures with higher priority.
- The sixth parameter is the path to the button image of the measure starting at "textures/". Because we want our character in game to say something, we use the button "hud/buttons/btn_046_StartDialog.tga".
The game now knows that there's a new measure, but it doesn't know who can start it and who can be the target of the measure.
3. Let the game know who can use the measure
The game needs 3 files to fully define measures:
- DB/Measures.dbt (here the basic measure definitions are stored)
- DB/Filter.dbt (includes all filters that can be applied to sims and objects in the game)
- DB/MeasureToObjects.dbt (includes all relations from measures to filters)
We won't add a new filter to the game since there are already plenty of filters we can use for this example.
So just open the file "DB/MeasureToObjects.dbt" and add the following line to it:
The most important parameters of this line:
- The first parameter is again the ID. As always make sure that the ID is unique.
- The second parameter is the ID of the measure you want to apply this relation to.
- The fourth parameter is the ID of the filter that has to apply to a target of this measure (in this example we don't want the measure to affect anyone other than the sim that starts it, so the targetfilter can be set to zero)
- The fifth parameter is the ID of the filter that has to be true for the object that starts the measure.
- The sixth parameter is the type of object that can start the measue. "6" stands for dynastysim (look into the file "DB/MeasureObjects.dbt" for a complete list)
We want all of our family members to start this measure, so we set the 5th parameter to 10. If you have a look into the file "DB/filter.dbt" you'll find out that this filter applies to all controllable objects.
At this point we should be able to see a measure and to start it, but it doesn't do anything. So we need to add some code to our measure.
4. Let the script do something
Open up your script ms_helloworld.lua again and add the following line of code to the function Run():
Now the script should look like:
The command "MsgNewsNoWait" shows a message immediately and it's parameters are:
- first: The destination of the message. The empty string "" always refers to the object that has called the code, so in this case the message is delivered to our family member who has started the measure.
- second: If you add the second parameter a small portrait of the object that called the method is shown. Because the message is called by the family member we again use an empty string here.
- third: Just leave that empty
- fourth: The message class. "default" shows a standard message.
- fifth: If set to a number greater than zero, the message will be displayed for this amount of time. We want the message to be shown until we click it away, so we set this parameter to -1.
- sixth: The header of the message
- seventh: The body of the message (the actual message)
Because this script should only cover the basics of adding a measure, we've added the text hardcoded. Normally you shouldn't ever do this, but hopefully I can add a new tutorial on how to add proper localized messages with labels.
Also the new measure has no label ingame and the description is missing.
If you have any questions, don't be afraid to ask.