Daeley presents: How To Make Your Own Rewards

warning! expected reader level:

novice

advanced

expert
 
In this tutorial I will explain some of the basics of using the reward template script I created for the BSC a while ago. This tutorial is for people with some experience in lot modding who want to go a little further and should not be attempted by a novice. Secondly, using the reward template script will require you to put the "BSC essentials" package as a dependency. If you have any problems with this, don't proceed.

First of all, open the reader and open the .sc4lot file of the lot you want to make a reward. Look for the exemplar with the building properties (bulldoze cost, power consumed, pollution, etc.). Here you will need to add a property called "Conditional Building", and set it to 0x01 (displayed as "true"). By doing this, you have marked your building to be a reward building and the game will look for an unlocker script while playing. You can also add another property "City Exclusion Group" with the IID of the lot if you only want one occurrence of the building in a city. (so don't do this if you want to allow the player to build your reward more than once). You will also need to change the first Occupant Group ID to 0x0000150B to place the lot into the Reward menu. There's just one more thing we have to do here: note down the instance id of the exemplar, because you will need it later on.

Now, when a reward becomes unlocked, it will display a popup news message. So the next thing you have to do, is create two LTEXT files: one for the popup title, and one for the popup body text. Try to be a bit inventive here, because a reward loses or gains a lot of flair with a funny popup message. The easiest way to get these LTEXT files is to copy two from a BSC reward and change the IIDs and text. These files need to have a Type ID of 2026960b, a Group ID of 6a231ea4 and a unique IID. Also note down the instance ids of both text messages.

Now comes the real part: we're going to implement the reward script. For this we will be using my reward template script. This script uses a couple of functions I've written myself to make reward modding easier. Look for a file "BSC_reward_essential.dat" and open it in the reader. You'll see it contains two files, the second one is the template we'll be using.

Copy the template to your personal .sc4lot file. Now before we start modding it we'll have to make sure the game recognises it. To do this, change the LUA's group id to "0x4A5E8EF6" and its instance id to a unique number of your choosing - as an experienced modder should know, it's very important this number is unique, or you could end up overwriting somebody else's LUA!
On top of the LUA you should see the following line:
 

--#-package:0xxxxxxxx# -- package signature


Again, replace the 0xxxxxxx with a unique 8-digit number of your choosing (an easy rule for this is to take the instance id and change the first digit to a zero).

Now, copy/paste the entire text into notepad and do a "replace all" to replace TESTREWARD with a unique tag of your choosing. This is best something that reflects your reward building. For example, if your username is Kitten08 and you are creating the New York library, use a tag like KIT08NYLIB (note that this has to start with a letter, but can be any size can contain both letters and numbers).  

Now it's time to fill it in.

TESTREWARD = BSCREWARD.NewRewardStructure()
TESTREWARD.NAME = "test lot X"           -- display name in the reward message
TESTREWARD.HEX_ID = "6ddc79e2"           -- iid of the reward's exemplar
TESTREWARD.NEWS.TITLE = "text@00000000"  -- iid of the LTEXT message containing news title
TESTREWARD.NEWS.BODY = "text@00000000"   -- iid of the LTEXT message containing news body
TESTREWARD.DLD = true                    -- indicates this reward is difficulty level dependant (true/false)
                                         -- if false, definitions of easy are taken for all difficulties.

If you made it here, most of these should be self-explanatory. One note though, for the news title and text, it's very important to leave the text@ tags. One thing you might find curious here is the "DLD" line. This is a little invention of mine which makes it possible for a reward to have different requirements at different difficulty levels. If you don't want this, just set it to false and only define the requirements for easy. In that case, other difficulties will also use the requirements you've defined for easy.

--* easy *--
TESTREWARD.CONDITION[0].CITYR = 1000
TESTREWARD.CONDITION[0].MAYRAT = 40
TESTREWARD.CONDITION[0].NBRP = 3

Again, this should pretty much explain itself. Just add the required tag from the list with tags above and set a minimum level (the exception to this is the CRIME tag, which - naturally - indicates maximum allowed crime). The 0,1,2 tags after CONDITION indicate the difficulty, as is noted in the comment tags.

You can also add plop conditions:

TESTREWARD.CONDITION[2].PLOP[1] = { id = tonumber("dcf52081",16) , n = 1   , text = "The Houston Super Motel" }
TESTREWARD.CONDITION[2].PLOP[2] = { id = tonumber("dcf52156",16) , n = 5   , text = "Small BSC Museum" }

The PLOP tag allow you to add requirements to your building, requiring that you have built a certain amount of a certain kind of lots. If you want to add a special plop here as a requirement, it must also have the standard Maxis "Reward" occupant group 0x0000150B (aka, it must be selectable from the rewards menu). Should you need more then two, just keep the numbering as shown in the template file - PLOP[1], PLOP[2], PLOP[3], PLOP[4], etc. Of course, like the rest of the tags, it's not mandatory to have PLOP requirements. Much like the PLOP tag, the OG tag can, in essence, be used to count if a certain occupant group is present in your city. However, it's a bit more complicated then that and enough material for it's own tutorial. As such, I will discuss this topic another time.


Some of the standard Maxis rewards show greyed when not available and show a little message with the requirements of the reward. If you use my template, you will automatically add such "not available" text to your rewards. However, my reward text is slightly more detailed as the standard Maxis text, as it includes a progress meter and shows the player how many of the requirements they've already met.

When you're done, save your LUA, save your lot file, and go testing ingame. If it works, yay! If it doesn't, chances are you made a typing mistake in the LUA file... remember that LUA is VERY picky (and capital sensitive... TiTLE does not equal TITLE!).


There... I think that's about it... have a nice day and happy modding!


Addendum : the available condition tags

These tags can be found in the template file, but I will list them here for easy reference:

CITYR         
city population
CITYR3
city high wealth population (R$$$)
REGR
region population
CITYC
city commercial jobs
REGC
region comnmercial jobs
CITYI
city industry
CITYIHT
city high tech jobs
REGI
regional industry
EQ
city education
LE
city life expectancy
MAYRAT
mayor rating
NBRP
number of parks
CRIME
maximum city crime
PLOP[#]
ploppable condition { id = exemplar id , n = nbr wanted , text = "display text" } (*)

(*) The exemplar id property should be a decimal. To achieve this, convert the hex id # to a decimal using tonumber(#,16) or hex2dec(#), as displayed in the example code.