Equinox

Thanks to Simtropolis member Daeley, who was of invaluable assistance in learning to make my own UI files. This document was intended for a person with minimal to no experience in using the ilive Reader utility. If you have any suggestions as to how I could make it better or easier to understand, you can contact me via email or IM (my email is the same as my MSN address): MSN Messenger: equinox.nls@gmail.com - AIM: Snivets1337 In order to follow this tutorial, you need the following two tools downloaded, setup properly, and configured: This guide will walk you through using them. DatGen4 also works; however, editing the UI files is not quite as easy as the program's current build does not have a UI viewer, nor editor. Part I: Using the UI 'Editor' to Extract the Query Template First off, open up the UI Editor. The only thing we are going to be using this tool for is quick and easy extraction of the UI file we want to use as a template. As an editor goes, it is not nearly complete enough to be used on its own. It is good for first-time coordinate configuration, though (like if you can't get something aligned right and you're not used to the coordinate system the UIs use). Other than that, I'd recommend sticking to the basic Reader for editing and previewing of your queries. That having been said, go to the File menu and choose "Import". Click on the top UI file and scroll through them until you find the one you want. In this tutorial, we will be altering a simple parks and recreation query, adding a goofy stat, text, and an image. Scroll through the Import menu's list of UIs until you find the one shown in the picture below: Press "OK" and you should see your basic Parks and Recreation query in the middle of the window. Go to the File menu and this time choose "Save As". Pick a location (doesn't matter where), and type a filename, and save the file. Exit the UI editor. Now, on to the Reader! Part II: First-Step Editing in the Reader (Generating unique IIDs and linking them to your lots.) Now, open up the Reader and under the File menu, pick "New". First thing we need to do is insert the query we exported previously with the Editor. Right-click somewhere in the left-side white pane and select "Insert File". Locate your UI file and hit "OK". Now you will most likely get a dialogbox asking what type of file you'd like to insert it as. Choose "Not Defined" at the top of the list (the game and the Reader both can figure it out themselves based on the code) and hit OK. A dialogbox most likely will pop up (unless you are working on a DAT file with other files already inserted) asking about you not having selected an entry and prompting whether or not to "append to end?" Choose yes. You should now see "UI file" in the left-hand pane. At this point, go up to the program's Options menu, and choose the "Options" command. Make sure "UI preview" is UNCHECKED. I will explain the reasons for this later, when we add images. This is what the Options dialog in the Reader should look like. (your directories may vary, of course) Before we do any editing, there are two things we need to do. One: assign a unique instance identifier so the game can link lots to your newly-created query and also give it the proper group identifier so the game knows it should index this with the other queries in memory. Two: link the query to a test lot. First off, right-click on your UI file, and select "Generate new Instance". This should give it a unique instance ID (the value in the last column of the left-hand Fileview pane). Now, at the top of the Reader window there is a row of toolbar buttons. Click on the one labelled "File Info". Hit the "Edit" button. You should have the following on-screen: Make sure the "Group" field boxed in red has the same sequence of numbers as in the screenshot. This helps SimCity know that this is a UI file and it should consider it when a building is queried as a potential result. Copy the string of numbers you see in the Instance box, and close the two mini-windows. Save. Now, open up the SC4Lot file correlating to the lot you want to be linked to your custom query window. Find the Building Exemplar. Your screen should look like this (values may be different): As you might have guessed, the only property we need to change to link the query to the lot is the one highlighted in red in the above screenshot. So, double-click on this property and a dialogbox should come up. It should be found in the right-hand pane of the Reader after you click on the correct Exemplar file. In the text field towards the bottom of the dialogbox, type "0x", and then immediately press CTRL + V (the "Paste" command). You should now have the identifier for your query ... for example, if your custom query's Instance ID was 87654321, you'd enter "0x87654321" in the text field. Then press the "Apply" button immediately to the right of the text field, then press the "Apply" below the text field to make your changes to the exemplar. Now save and close the file (File menu > "Close"), then re-open it via the Recently-Loaded Files section of the File menu. Remember, it never hurts to be safe. Part III: Editing the UI File (The basics: text and coordinate layout system) First off, your Reader should be configured so that clicking once on a UI file in the Reader's file list results in a text view of the UI, NOT a preview image. You can attain this preview still; just right-click on the UI file, and select "Preview". Occasionally when you make changes to images within a file, the Reader can crash while previewing the query, so save before previewing, just in case. Bring up the text view of your park-style query. First thing you'll notice is that indeed, there is a LOT of text. Second, the header of the file says something like "# Generated by UIEditor - Reader 0.8.9". I recommend changing this so you know what query you're working on even without previewing. This text is displayed in the image below as the text faded with a gradient. Something like "# Query for (lot name)" works well as a header, or your name, etc. Importantly, you must press "Edit" before making any changes to the query! So, press the "Edit" button at the top of the right pane, make your changes, and do not forget to press "Apply" when you are done! I've lost a lot of work simply by not remembering to press "Apply", so don't make that mistake yourself. A typical UI file looks something like this. Here, various properties are color-coded and will be explained. First thing you should understand is how the coordinate system for a UI file works. On almost every line you'll ever alter or write in a UI file, there is the command area=(#,#,#,#) where # is a number, in pixels. The format is as follows: x-value for top-left corner of the area, y-value for the top-left corner of the area, x-value for the lower-right corner of the area, and y-value of the lower-right corner of the area. So a 200-pixel-wide, 50-pixel-tall image (200x50) placed in the top-middle of a query window 300 pixels wide would be defined as: area=(50,0,250,50) That's quite basic. The image area coordinate system is the same for text areas (IGZWinText). If you are fiddling through a UI file, and wonder what any of the tags mean that are not covered here (either dynamic [changing] or static [constant] properties), you should check out you should check out this link. It details all the various tags, properties, and useable values that have been decoded for use with SimCity 4's UI format, and also goes over the differences between LUA, XML, and the UI format. In addition, there is an LUA decoding thread at Simtropolis in the R&D forum. It's probably best to save looking into these until you finish up this tutorial, though ... it is a bit complex. Moving on, another thing to know about IGZWinText lines is that you can alter the text color by altering the forecolor property. Usually, it is towards the end of a IGZWinText line. There are three values, separated by commas. The format is R, G, B, and - like in most image editing programs - values are from 0 (dark) to 255 (white). The code for black is 0,0,0; the code for solid red is 255,0,0; solid green 0,255,0; solid blue 0,0,255; white 255,255,255. You can open up Microsoft Paint and get these values by going to the "Edit Colors" panel and defining your own and just looking at the numbers in the R, G, and B text areas. Now, if you open up a standard residential, commercial, or industrial query, you'll see IGZWinText lines, some of which have a tag id=0000#### right after the iid tag, where # is a number. Usually the numbers run in the 1000 to 1100 range. The presence of these tags tells you that the text area is a statistic field. It could be anything from the currently-occupied number of jobs in a commercial building, to the number of fire engines in a certain fire station lot. The lines of text without the ID line are simply regular lines of text, that do not change. You may notice that when previewing queries, no caption shows up for the IGZWinText lines with ID tags. You can fix this by going into text view, and adding the tag caption="(stat)", where you put whatever text you want to see in place of (stat). For example, if you wanted to have the text "power?" show up where a text field is, you would add the tag caption="power?". Make sure you keep the quotes there, though; without them, SC4 can really get messed up in places. Generally, you can figure out which lines go with what property by the text immediately proceeding it. In most cases, you'll see something like a line of text labelled "Pollution", and then the line right below it will have an ID ... chances are good that is the text area for the pollution variable. Now, by this point you may have altered some text and tested it out ingame to confirm that indeed, it does not work! This is because almost all text fields in SC4 have a tag called captionres. The format is captionres={#,#}, except with eight-digit numbers in place of the #. This property is merely a group and instance ID of a text file ("LTEXT file" or "Unknown file" in the Reader's file view), which is what shows up in the game. You can have the game display whatever you put in the caption property by deleting the captionres property altogether. However, it is not recommended that you do this, because there are people who may download your lot and its query, and want to translate it into their own language, only to find that the UI files cannot contain accented characters! So, as a general rule, insert a text file just like you inserted the query near the beginning of this tutorial, except in the "Import As" box, specify "XA file". Give it a type ID of "0x2026960B", so the game knows it is a text file, by clicking on the File Info button in the Reader (again, just like you did previously in this tutorial) and pressing Edit. Then right-click on it and generate a new group and instance value (or use your own; it doesn't really matter). You can make any changes you desire to the text file by pressing the "Edit" button in the File View pane (if the file is an "Unknown file"), making your changes, and pressing the "Apply" button; or by simply making your changes and pressing "Apply" (if the file is an "LTEXT file"). Now, go back to your query in the text view, and where the text field you wanted to change is, simply change the captionres property so it is the group and instance ID of your new text file, respectively. Part IV: Basic Image Stuff (Images: inserting, coding, ImageRect ... ) In this section, we're going to insert a simple image with dimensions of 240 (width) by 240 (height) pixels into our parks and recreation query. Open up Photoshop, or IrfanView, or whatever you use for image editing that can export files as PNGs, and find some sort of image ... it does not matter what it is, but for this tutorial I'm going to use an abstract wallpaper I got from deviantArt. Size the image down to 320 wide by 240 tall, and save it as a PNG file. The filename does not matter. Back in the Reader now, preview your query. You can see we need to make it bigger vertically. So, enter Text View and look at the first two lines of code (excluding anything at the top proceeded by "#"). You should find a normal area parameter. The one inside the top IGZWinGen code defines the area of the query in an absolute means. Perhaps the best way to explain this is through an example. On your parks and recreation query, you see "area=(246,202,538,322)". This means the upper-left corner of the query begins at an X value of 246 pixels from the left side of the screen, and at a Y value of 202 pixels from the top of the screen. It extends to 538 pixels from the left side of the screen, and to 322 pixels from the top of the screen. The second IGZWinGen line declares the area of the query from the top-left corner. It always should begin at 0,0 and have dimensions equal to the overall dimensions of your query (or alternatively, the X2 value minus the X1 value from the first line, and the Y2 minus the Y1 also works). Nonetheless, we want to increase the area vertically of our query by about 260 pixels, so our image will fit comfortably. Right now the first area property is set to "(246,202,538,322)". Since we want to make it 260 pixels taller, simply add 260 onto the second Y value. You will get 582, so your new area tag should be "(246,202,538,582)". In the second IGZWinGen line, alter the area command so it reads area=(0,0,292,380). This is the general area of the query window defined starting from 0,0, the top-left corner of the area we already defined as being the query. If you do a preview of your query now, you see that it is the right size, but the "Close" button needs to be moved down. So, in text view again, look at the second-to-bottom line of text, the IGZWinBtn tag. Again, you see an area tag. As you may have guessed, simply add 260 to the second and fourth values, giving you a final area of "(131,339,281,369)". Apply the changes and preview the query. Now, on to adding the bitmap itself ... Insert the image file you generated for this query in the same manner you inserted the UI file originally. This time, in the "File Type" box, specify PNG image. Give it a unique group and instance ID by right-clicking and selecting "Generate new group and instance". Now, we need to find a UI file with a bitmap image code that we can copy, because we don't really want to type it all out ourselves. Open up the UI Editor again, and find any query with a sort of status icon in it ... examples are the power plant icon, the water pump efficiency icon, the fire station efficiency icon, etc. Open them up and save them. Return to the Reader, and insert the UI file you just saved, and go to "Text View". Now, find the line that is the IGZWinBMP and select the whole thing and copy it. Go to the text view of your own query, and paste it right below the IGZWinText lines. First off, delete the ID tag from the line of text, because this bitmap is not going to be a status icon; rather, just a static image. Change the area property to reflect where you want to place the image ... for this example, we will use the values "(26,70,266,310)". Now, plug in your group and instance IDs into the image property. The last thing we need to change is the property towards the end of the line called imagerect. All this property does is define the area of the image from 0,0, much like the second IGZWinGen line does in the query window's definition. So, as you may have guessed, you should enter the value "(0,0,240,240)". Now, save the file, close it, and re-open it. Sometimes the Reader can crash while previewing queries with images you just inserted, so I find it better to be safe and simply re-open the files each time. Once you've done that, preview the query. Here's what you should have so far ... Part V: Adding Some Numbers... (Playing with the "Goofy Stat Responsive Curve" property and your UI) Next thing we are going to do is add some numbers, for statistic purposes. Good examples of this in the game by default include the 'Pidgeons Perched' number for the Mayor Statue, and 'Number of Potatoes Peeled' for the Army Base. To get this property to work, you need to do two things. One is add the exemplar property "Goofy Stat Responsive Curve" to the lot you want to attach it to's Building Exemplar, and two is to add a IGZWinText line into your query with an ID of 0000106b. First, we will go over how to add the exemplar property and what exactly each statistic means. Open up the Reader, and open your SC4Lot file (if it is a ploppable lot), or the SC4Desc file (if it is a growable lot), and find the building exemplar. Recall that this is the one with the non-LotConfigObjectData properties. Right-click in the right-hand pane of the Reader and select "Add Property". Under the dropdown list, scroll down until you find "Goofy Stat Responsive Curve". Press the "Apply" button at the very bottom of that window, and you should see it added to the list of already-present exemplar properties. Now, double-click on that property and the dialog will popup again. This time, press the "Add" button four times. Proceed to edit the values in normal decimal form (10-digit, non-hexidecimal) according to the following constraints: The first value controls the deviation of the value below the median (see note below), the second value controls what the lowest value the statistic can be, the third value controls the deviation of the value above the median (see note below), and the fourth controls the highest it can be. NOTE! Don't worry too much about the first and third values. I believe they have something to do with the deviation of the value from the midpoint of the two numbers you specified ... thus, if you make the first value (the negative one) farther from 0 than the third (the positive one), I would guess the value would be weighted more towards the minimum you specified and making the maximum value less likely to be resultant. If you are confused or this method does not work for you, don't get frustrated; move on with the tutorial. This part is not necessary for basic query-making and is more of just a little extra feature. We are going to make our statistic report the "Visitors Per Month". Of course, this is not reflective of anything occurring in your city, but instead is a randomly-generated number that fits the constraints you set in the "Goofy Stat Responsive Curve" property. For our purposes, the average number of visitors per month will be around 320,000, so we will use a minimum value of about 250,000 and a maximum of 480,000. We want the value to be above the median of the two numbers most of the time, so we will set the first value to "-80000", and the third to "100000". Your values should be, in order, -80000,250000,100000,480000. Now press "Apply" at the bottom of the dialogbox, and save your lot file. Close it, and re-open the query. Back in text view, we know we need to now make the value whose parameters we just set appear in our query. This is quite easy; in fact, it functions exactly the same as the other properties we have dealt with with id tags. Simply take the line of text that correlates to the park's monthly cost, copy it, and paste it right below your code for the PNG image. Change the id tag from "0x00001010" to "0x0000106b". Change the area parameter by moving it down twenty pixels. As you know, this means adding twenty to the second and fourth values. You are also going to want to move your image down 20 pixels so you have room for the text to fit comfortably. The area tag for the IGZWinBMP should now be (26,90,266,330), and the tag for the IGZWinText should be (196,64,278,82). If you add the caption property, you can preview your query to make sure everything looks good so far. Now, all you need to do is copy the IGZWinText line without the id property, and paste it below the one you just edited, and again increase both Y values by 20. Change the caption property to be "Visitors this Month", or whatever you would like. Finally, either set the captionres property to null by using 0,0, or using the group and instance IDs of a text file, inserted as was mentioned earlier in this tutorial. Now, go ingame, and everything should work A-OK. Part VI: Query Backgrounds (Changing between park, R/C/I, utility, etc. appearing query windows) Right now, your query looks like somebody took the default parks and recreation query and altered it, which is exactly what you did. However, if you want to make your query appear to be a different style, you can change the background image. For parks and recreation, it is a nice green tone. For utilities, it is yellow. For residential, it is green again; for commercial, blue; for industrial, yellow, and so on. Changing between these appearances is extremely easy, if you know the right values to plug in. All you need to do is to alter the image property in BOTH IGZWinGen lines to point to a new image. Right now, both of yours should be set to "1ABE787D,14416224". Below is a small table of values you can use for changing background images (and yes, you can make your own, that is the next section of this tutorial ... you can skip ahead if that is what you are interested in doing): Parks and Recreation (1ABE787D,14416224) Landmarks and Rewards (46A006B0,14416225) Utilities (46A006B0,1441622A) Fire Department (46A006B0,14416223) Police Department (46A006B0,14416227) Industrial Building (46A006B0,14416226) Commercial Building (46A006B0,14416222) Mass Transit (46A006B0,14416229) Garbage Disposal (1ABE787D,14416220) (hospital query is the same image as the landmarks') (residential query is the same image as the parks') (education query is the same image as the landmarks') Part VII: Custom Query Backgrounds (Creating your own unique query backgrounds) This is a very easy process if you understand the basic concept of how SimCity 4 takes a 129 by 129 pixel image and turns it into a query window almost 300 pixels wide by a couple hundred tall without obvious distortion. The way it works is remarkably simple ... first, the game divides the image into nine equally-sized pieces, like this: From there, it takes the query and looks at the location of the upper-left corner of the area, and it places the portion of the diagram labelled "1" there. Then, it finds the upper-right corner of the area, places the "3" portion of the diagram there. It does the same for the lower corners, placing the "7" in the lower-left, and "9" in the lower-right. At this point we have something that looks roughly like this: From there, the game fills in the top with section 2, tiled as many times as it takes to fill up the gap. Then it fills the bottom with section 8, again, tiled as many times as it takes to fill in the gap. It does the same for the left and right sides (sections 4 and 6, respectively). Same thing goes for the middle section, except it gets tiled horizontally AND vertically. Based on the way queries work in SC4, you probably have realized you can't make anything really fancy serve as the background image while keeping the image only 129 by 129 pixels. However, whereas it is possible to use images greater than 129 by 129, it is not recommended, even if the size of the image you make matches the size of the query window exactly. Often times, even when the two match, the game will attempt to stretch the image anyway, for reasons I don't know. As a result, you get a nice big stripe running down the middle of your otherwise-perfect query about 80 to 90% of the time. You can always try counteracting this by making either the imagerect property one pixel higher in each direction, or by making the area property one pixel smaller than the actual image ... Here are some examples of query windows that would look pretty good stretched up to size: Thanks to Tragicomicus2004 for the designs. If you want to see some excellent custom queries (and excellent BATs!), check out Cerulean's stuff. Almost all of his stuff (the non-BSC stuff anyways; not sure about those) have custom queries! Also, custom queries can be found in every one of the NDEX series of BATs and lots. (UPDATE: this is no longer true; those queries caused crashes and have mostly been replaced by a standard NDEX query used for all lots of the same type - one for commercial and one for residential.) Part VIII: Current City Statistics (Adding information about the current city's status) This is perhaps the most useful part of being able to make custom queries. Using LUA scripting commands pre-programmed into the game's engine by Maxis, you can call up all sorts of statistics about the city you're playing when you query a lot. For example, look at this screenshot of a modified commercial query (from the RCI query upgrade mod) ... The way to add these items to your queries is remarkably simple. There are two things you must do: one, insert a text file in the XA format (so it shows up as an "Unknown file" in the Reader's file list). Then proceed to edit it and type what you want to see in the query window, with one special change. Where you want the statistic to be, you place one of the many many many values the Maxis programmers allocated to be useable for retreiving statistics ... a few of them are listed below. #game.g_power_plant_count# Total number of power plants in the active city #game.g_power_pole_count# Number of power poles constructed citywide #game.g_unpowered_building_count# Number of unpowered buildings #game.g_water_source_count# Number of water-generating/pumping facilities #game.g_water_pipe_count# Pipe segments constructed #game.g_water_unwatered_building_count# Number of unwatered buildings #game.g_landfill_capacity# Capacity of garbage (in tons) that can be handled #game.g_pothole_count# Low-funding-induced potholes in the road infrastructure #game.g_city_tile_size# Total tiles in the city (4096, 16384, or 65536) #game.g_[value]_tile_count# Number of various types of tiles in the city values: road, rail, subway, highway, street, groundhighway, elevated_rail, monorail, bridge, water, avenue, dirtroad #game.g_city_[V1]_population# Total values reflecting the current city only... #game.g_region_[V2]_population# Total values reflecting the entire region... [V1] - this can be replaced by several values. They are: rci (total residential, commercial, and industrial), r (residential only), c (commercial only), i (industrial only), r1 (R§), r2 (R§§), r3 (R§§§), ir (agricultural), id (dirty industry), im (manufacturing industry), iht (high-tech industry), co2 (CO§§), co3 (CO§§§), cs1 (CS§), cs2 (CS§§), cs3 (CS§§§), workforce (employed citizens) [V2] - this can be replaced by several values. They are: rci (total residential, commercial, and industrial), r (residential only), c (commercial only), i (industrial only), workforce (employed citizens) #game.g_day#, #game.g_month#, #game.g_year# (measured from 2000), #game.g_year_count# (from 0) #game.g_(value)_tile_count# Tiles of the specified type in the current city game.g_current_id_cap game.g_current_im_cap game.g_current_iht_cap game.g_current_co2_cap game.g_current_co3_cap game.g_current_r1_cap game.g_current_r2_cap game.g_current_r3_cap game.g_tax_rate_neutral game.g_num_rzone_ld_tiles game.g_num_rzone_md_tiles game.g_num_rzone_hd_tiles game.g_num_czone_ld_tiles game.g_num_czone_md_tiles game.g_num_czone_hd_tiles game.g_num_izone_r_tiles game.g_num_izone_l_tiles game.g_num_izone_h_tiles Note that values with a "g" after the game. are 'global' values, meaning they are applicable to the whole city. Values with an "a" after the game. are averages. You can also mix these values with a string of regular text. The # symbols signify the beginning (and end) of the variables, so as long as you don't use them outside of the variables, it should work fine. For example, here is a line of code from the NDEX queries depicting the cap status of the current city, for CO§§ and CO§§§, all in one line: CO§§/§§§ Caps: #game.g_current_co2_cap#%/#game.g_current_co3_cap#% Ingame, you get something that looks like this: "CO§§/§§§ Caps: 76%/82%". Pretty simple, eh? It's just a matter of knowing all the various LUA constants! I've listed most of the useful ones here, but in the future I will update this file with more details and more values. This is just intended as a start. If you would like to know some more, and are not intimidated by Maxis' LUA code, then check out the main LUA constant script (51 KB, extracted from SC_1.dat).