How to create Puzzle Pieces?
A basic tutorial about making Puzzle Pieces in SimCity 4
Original written by Joris (jmvl), NAM member
Edited and translated by Maarten (mrtnrln), NAM member
1st edition (Dutch): August 2009
1st edition (English): August 2010
2. What's a Puzzle Piece?
- 3.1. What does SimCity 4 need?
- 3.2. What do I need?
- 3.3. Reserving ID's
4. Creating textures
- 4.1. Creating PNG files for your textures
- 4.1.1. Transparency
- 4.1.2. Cut you texture down to size
- 4.2. Convert PNG to FSH
5. Fill up the DAT-files
- 5.1. General
- 5.2. Empty tiles
6. Creating paths
- 6.1. Where are paths saved
- 6.2. The structure of a SimCity 4 Path File.
- 6.2.1. General
- 6.2.2. Header
- 6.2.3. Paths
- 6.2.4. Stoppoints
- 6.2.5. Other important notices
- 6.3. Pieces without paths
- 6.4. The SC4 Path Creator
- 6.4.1. Introduction
- 6.4.2. Single Frame View & Multi Frame View
- 6.4.3. The "Path View"
- 6.4.4. Saving path files
7. The RUL 0x10000000 file
- 7.1. What is the RUL 0x10000000 file
- 7.2. Where can I find the RUL 0x10000000 file
- 7.3. Editing the RUL 0x10000000 file
- 7.3.1. Important notice before editing the RUL0x10000000 file
- 7.4. The structure of the RUL 0x10000000 file
- 7.4.1. Introduction
- 7.4.2. The TAB-Ring section
- 7.4.3. The "IntersectionInfo" section
- 22.214.171.124. The Header
- 126.96.36.199. The Layout section
- 188.8.131.52. The Defenitions section
- 184.108.40.206. Rotating/Mirroring your Puzzle Piece
- 7.5 Defining rotated/mirrored versions of your Puzzle Piece
- 7.5.1. The Basics
- 7.5.2. Be creative!
8. Mirroring Puzzle Pieces Horizontally
9. Creating New Menu Buttons
- Pathing problems
- RUL 0x10000000 problems
- Other problems
11. Further details
This tutorial mainly handles the technical aspect of "flat" puzzle pieces. "Flat" pieces are two-dimenstional objects, for example the RHW ramp interfaces, the NWM transistion pieces and the Smooth Curves. "Non-flat" pieces are for example the elevated networks and the Maxis Highways. The only difference between the two is creating models for the pieces. "Flat" pieces are far more easier to create than "non-flat" pieces.
Why did we write this tutorial? Joris (jmvl): "When I was learning how to make puzzle pieces in SimCity 4 back in March 2009, I discovered that the available information about this subject was scatterd and not clear enough at some places. Therefore, I wrote some notes about creating puzzle pieces back then. However, I learned more about puzzle pieces and applied my knowledge immediatly, I had no time and motivation to keep up my notes. Therefore I decided to write a document for myself (and maybe for others too) in May 2009. However, I didn't write a thing until june 2009, when Maarten (mrtnrln) asked me by PM at SC4 Devotion what technical aspects there where for creating puzzle pieces. I said to myself: 'It's now or never!' Then I wrote this document about how to create puzzle pieces for Maarten, for others and for myself. Thanks to this manual we shall never forget the procedures for creating puzzle pieces."
Maarten (mrtnrln): "This tutorial was really helpful to me at the time. Back then I made a few puzzle pieces for the RHW v4.0, like the B-style RHW Splitters and the Cosmetic Pieces, that are now used a lot by people. In June 2010 people ask how to create puzzle pieces. I have this tutorial around on my harddisk for months, but it's in Dutch, so the majority of the community isn't able to read it. Therefore, I translated the whole document and posted the translation at SC4 Devotion, so anyone can read it. We'll never have enough tutorials, and never enough custom content creators either."
I hope you find this tutorial usefull. If the document contains any mistakes, unclear or missing information, please send me an PM. I will correct these issues as soon as possible. You can also contact me for any questions or suggestions.
Notice about the Y and Z co-ordinates
In this tutorial, the Y-axis or Y-co-ordinates are always used as the height-axis of an object. This is because in the Reader, the Y-axis is also the height-axis. However, in gMax and the SC4 Model Tweaker, the Z-axis is the height axis. See table below:
Reader axis:gMax axis:XXYZZY2. What's a Puzzle Piece?
A puzzle piece is a ploppalbe (placed manually) transit object. It's fully fuctional for traffic and UDI vehicles. Because puzzle pieces have their own paths, you can determine how traffic is going to move over these pieces. Sometimes, a more technical term for puzzle pieces is used: "Interchange-base Related Item" (IRI). Puzzle pieces often used for objects you can't just simply drag some sort network to create it. Puzzle pieces can be placed in TAB-rings, which contain rotation rings. Thanks to TAB-rings, more than one puzzle piece can be accessed by one menu button. Technical speaking, all puzzle pieces are 3D-models; each section of a puzzle piece is one S3D model. The puzzle pieces and their location in TAB-rings can be determined by codes in the RUL 0x10000000 file.
Puzzle pieces should not be confused with Transit Enabled LOTs (TE-LOTs). Both have their own paths, and both pieces can be accessed by traffic. However, there's a big difference between a TE-LOT and a puzzle piece. Puzzle pieces are ploppable sections of transport networks, whereas TE-LOTs are LOT-based. TE-LOTs are ment to look like transport networks, but in fact they aren't transport networks at all. TE-LOTs are often used for toll boths and "Transit Switches" (like stations). In the Zones View, TE-LOTs are invisible, whereas the puzzle pieces are completely visible.
3.1. What does SimCity 4 need?
In order to make a puzzle piece working in SimCity 4, the following is required:
- New codes in the RUL 0x10000000 file.
- One S3D model for every tile of the puzzle piece.
- One S3D model for the preview model of the puzzle piece, containing all models from every tile.
- One path file for every tile of the puzzle piece.
- One EffDir file for the preview of the puzzle piece.
- One LTEXT file for the description (shown in-game) of the puzzle piece.
- FSH-files for textures. (Without textures, you would barely notice the puzzle piece. That would be a waste http://sc4devotion.com/forums/Smileys/JasonSmilies/wink.gif )
3.2. What do I need?
In this section, you can find software and web applications you can use to create your SimCity 4 puzzle pieces. Some programs (marked in bold text) are essential, others are mere tools that make creation of puzzle pieces easier. All of the following applications are used in this tutorial. There's a difference between software and web applications. Software requires to be installed on your computer, whereas webapplications can be used by a webbrowser (Internet Explorer, Google Chrome, Mozilla Firefox, etc.)
- SimCity 4 + Rush Hour or SimCity 4 Deluxe. Without this program, creating puzzle piece has no use.
- iLive's Reader 0.93 (or higher)
- SC4 Path Creator 1.60 (or higher)
- Batch PNG to FSH Tool
NOTE: After installing the PNG to FSH tool, open the directory where you installed the tool and open groupid.txt. Replace the entire content of the file by 1ABE787D and save the file.
- A text editor, like Notebook.
- JMVL SimCity 4 Online Transit Modding Tools
3.3. Reserving ID's
To prevent any conflict with other pieces and NAM plugins, you require to reserve unique ID's for each puzzle piece you make. We always reserved our ID's for the RHW Mod by contacting Alex (Tarkus). In fact, it's quite unclear in the NAM Team who can be contacted for reserving unique ID's. The best place you can request for free ID's is at the corresponing topic in the NAM Creations section. The ID's you have the reserve are Instance IDs (IIDs) and HighwayIntersectionInfoID (HIIID or H3ID).
IIDs are used for identifying the files packed in DAT files. IIDs have to be unique, because otherwise they overwrite eachother. You'll need a whole range of IID's, because your puzzle piece contains more than one model or texure. It's important that you reserve a start-IID and a end-IID. Every puzzle piece has a AutoTileBase IID. This is the first IID from the tile in the upper left corner of your puzzle piece. The size of the IID range depends on the size of your puzzle piece. You can easily dertermine your IID by using the IID Grid Table Maker. You simply fill in the AutoTileBase IID, the width and the heigth of your puzzle piece and after clicking "Show IID Grid Table", a table appears on the screen.
H3IDs are used in the RUL 0x1000000 file. These IDs are required for linking the technical layout of the puzzle piece to the models, paths, etc. and for placing puzzle piece in different rotations (and mirrored versions). Usually 4 H3ID's are required (one for each rotation), but when puzzle pieces can be mirrored, you require 8 H3IDS, and ever 16 H3ID's when one way traffic is involved. Please check first how much H3ID's you actually require before reserving them.
Most of the times, the IDs are assigned projectwise. All NAM features and related mods have an IID that start with a 5, since this whole IID range isn't used by Maxis plugins. Each project has their own IID range. The RHW Project for instance has an IID of 5C###### to 5E######. The H3IDs are also assigned projectwise in a simillar way. Also, before reserving IDs, it's wise to say what you're creating. Maybe someone else is making something simmilar and we can try to fit the piece into the existing IID scheme.
A third thing that has to be unique is the name of the Effect Dir (EffDir). This links the correct preview model to the RUL 0x1000000 code. In theory, this name ought to be reserved, but in reality this is not the case. There's a huge combinations of names that can be used, and the chance that someone uses your EffDir name is very small. One syntax you can use for your EffDir name is:
EffDir Name:Puzzle Piece Name:preview_rhw4misrampsstyleaxdlRHW-4 to RHW-6C with 2 MIS sections leftpreview_rhw4misrampsstyleaxdrRHW-4 to RHW-6C with 2 MIS sections rightpreview_rhw2_to_2misRHW-2 to 2 MIS sections
As you can see, there's a logical connection between the EffDir and the puzzle piece name
4. Creating Textures
4.1. Creating PNG files for your textures
A puzzle piece is nothing without textures. It's quite important to create the textures before starting to make the rest of your puzzle pieces.
After you have reserved IDs you can start making textures. You can use any advanced image editing program (not MS Paint, but PhotoShop or the GIMP) to create textures. It's also wise to make a dedicated directory where you can save your textures. Then you can easily find them. All textures should be eventually saved in PNG-format (you may want to keep an multi-layered PSD-file or something similar for later texture editing). Depending on the quality of the texture, one tile has the following size in pixels:
Quality:Size (in pixels):SD128 x 128HD256 x 256
Usually, SD textures are used, due to smaller filesize. Also, the difference between end results of HD and SD textures is not that big.
FSH-files are the texture files of SimCity 4. FSH-files contain two layers: the colored texture layer and the black-and-white transparency layer. White parts of the transparency layer show the color image of the texture in SimCity 4, while the black parts are invisible. Technically speaking, you need two images of your puzzle piece for your textures. However, PNG-files can contain transparent pixels. If you want to have transparent parts in your PNG-image, do the following:
1. Open your texture with an Image editing program.
2. Fill in the transparent surface with a color that's unique in the image (only the transparent surface has this color). Try to make it similar to the puzzle piece, so any errors later are less visible.
3. Check the RGB value of the background color and note it somewhere. If you can find a hexadecimal code (a numbering system that goes from 0-9-A-F), skip the following two steps.
4. Open the Windows Calculator and enable the Scientific Mode (View/Scientific),
5. Fill in every value separately in decimal mode (Dec) and convert it into a hexadecimal value by selecting "Hex". Note the values down.
6. Open the Alpha/Color Blender from your web browser.
7. Click on "Browse" button next to "Alpha/Color Blended image file" and select your puzzle piece PNG file.
8. Open the "Advanced settings" tab and change both hexadecimal values to the Hex values you noted down.
9. Click on "Get Color PNG" and overwrite the puzzle piece PNG file you just edited.
10. Presto! You now have a PNG file with an transparent background.
4.1.2. Cut you texture down to size
Puzzle pieces can be no bigger than 16 x 16 tiles due to the limitations of SimCity 4. Also, a puzzle piece texture must be 1 x 1 tile big. Fortunately, the Image Cutter can do the job for you:
1. Click on "Browse" button next to "Image" and select your puzzle piece PNG file
2. Fill in the AutoTileBase IID
3. Fill in the resultion in "Maximum height per image" "Maximum width per image" (default settings: 128 x 128)
4. Click on "Get Cut Images" and save the ZIP-file.
5. Unpack the ZIP-file, and there you have it: Your puzzle piece cut into pieces with a size of one SC4-tile.
4.2. Convert PNG to FSH
PNG files can't be used for textures in SimCity 4. Therefore, these files should be converted into FSH files. The
Batch PNG to FSH Tool converts PNGs to FSH textures and saves them into DAT-files. The Batch PNG to FSH Tool recognises transparancy in PNG images and uses them to build the transparency layer of the FSH file. Let's create some textures:
1. Open the Batch PNG to FSH Tool
2. Click on "Add" and select the textures you want to convert:
3. Check if your PNGs are really transparent. If you see this, your image is really transparent:
4. Fill in the corresponding Instance IDs and set the End format to A-E. This prevents the "Sidewalk Bug" to occur.
5. When you are finished, select "Save dat" to save your DAT-file. IMPORTANT NOTE: create a dummy DAT-file where you save your new textures (give it a name like "Textures_Add.dat" or something simmilar). Otherwise the Batch PNG to FSH Tool overrides the complete contents of the file.
6. Copy your textures into the DAT-file where you save your final puzzle pieces somewhere in the NAM folder.
7. Save the file and you're done!
5. Fill up the DAT-Files
Now our DAT-file only contains FSH-files. But there are more things required to make a puzzle piece working in-game. We are going to generate some S3D, EffDir, Exemplar, LTEXT and some dummy-SC4Path files (we are going to define the paths in the SC4Path-files in the next chapter).
The Puzzle Piece Maker generates all the files you need for "flat" puzzle pieces. The Puzzle Piece Maker currently has no support for "non-flat" puzzle pieces. The only thing you can do when creating these pieces, is copy the models from another file, re-index it and edit it manually in the Reader, but this method is not recommended for beginners. We simply start with creating a "flat" puzzle piece with the Puzzle Piece Maker:
1. Fill in the AutoTileBase IID in the "AutoTileBase IID"-field
2. When the textures have another AutoTileBase IID (which is often the case for mirrored pieces), fill in the AutoTileBase IID from textures in the "AutoTileBase IID textures "-field.
3. Fill in the width and the height (in tiles) of your puzzle piece in the "Width"- and "Height"-field.'
4. In case you make a mirrored version of your puzzle piece, check the "Mirrored version"-checkbox
5. Select "A-E" at "End Format IID"
6. Choose 0 or 3 at "Resource Key Type". RKT 0 uses one model for all zoom levels, while RKT 0 uses a different model for each zoom level.
7. Fill in the text that's shown in-game (when placing the puzzle piece) in the "Description (LTEXT)"-field.
8. Fill in the EffDir name in the "Effect Dir name"-field. This must be an unique name. You'll need this name later when creating the RUL 0x10000000 code for your puzzle piece. If you forgot the name of your EffDir, you can find it in the EffDir file under Section 13.
9. Fill in the Exemplar name (the name each exemplar of your puzzle piece gets) in the "Exemplar Name"-field. You can use the EffDir name for this (without "preview_")
10. Make sure that "Use 'default' SC4Paths" is selected in the "SC4Paths"-section.
11. Make sure every file type is selected.
12. Fill in the download location in the "Download Location"-field. This is the location where your ZIP-file is saved.
13. Click on "Build DAT Entries". A ZIP-file is now generated.
14. Extract the ZIP-file. Make sure it's extracted in a directory with the same name as the ZIP-file.
15. Open the Reader and open the DAT-file where you saved your textures.
16. Select "Edit/Insert (Batch Method)". A new screen appears
17. Click on "Browse" and go to the location where you extracted your ZIP-file and select "batch.txt"
18. Click on "Insert." You get a message all files where succesfully imported.
19. Don't forget to save the DAT-file!
5.2. Empty tiles?
Often you don't want a square puzzle pieces. Some tiles of your puzzle piece may be empty. If they are, please follow these steps:
1. Find the S3D files you don't want to use and note down their IIDs
2. Now also select the SC4Path and Exemplar files.
3. Right-click on the selection and select "Delete Entries."
6. Creating paths
Finally we have our DAT-file filled with the required files. But it's not finished yet; The SC4Path-files should be defined, as said before in chapter 5. Since we've selected "Use 'default' SC4Paths" in the Puzzle Piece Maker, all path-files have dummy paths. In this chapter we're going to change that.
6.1. Where are paths saved?
Paths are defined per tile, just like the S3D-models of the puzzle piece. Paths are saved in ASCII text in SC4Path-files. The IID of these files correspond with the S3D-model with the same IID (these two are linked together). With the IID Grid Table Maker you can make a table with all the IID's of your puzzle piece, which may help you to find the right IID for your SC4Path files.
6.2. The structure of a SimCity 4 Path File
A SC4Path-file has in general the following structure:
- Path 1, path 2, path 3, etc.
- Stoppoint 1, stoppoint 2, stoppoint 3, etc.
SimCity 4 always reads the SC4Path-file one line at the time. Commentaries always start with "--". This line will be skipped by Simcity 4.
The header defines properties that will have effect for the whole SC4Path-file. The header is the only section in the SC4Path-file that should not contain commentaries. Only in this tutorial, I'll ignore this rule just to explain what everything does. The structure of the header of a SC4Path-file looks like this:
Code: (SC4Path-file Header)
SC4Paths -- Introduction line. All SC4Path-files start with this line.
1.2 -- Version number of the SC4Path-file (1.0, 1.1 or 1.2)
1 -- Number of paths in this SC4Path-file.
0 -- Number of stoppoints this SC4Path-file contains.
1 -- The "3D-Key" (0 or 1)
- SC4Path version 1.0 and 1.1 don't give as much support as version 1.2 does. Also, the structure of version 1.0 and 1.1 is different compared to version 1.2. It's recommended to use version 1.2 for your path files to prevent any confusion.
- The "3D-Key""defines if you can choose your own path in the U-Drive-It mode. "0" enables this option, while "1" disables this option. It's advised to use "1". Technically speaking, "1" stands for 3D network pieces and "0" for draggable network pieces.
Depending on the number of paths, the SC4Path-file has a seperate section for each path. The paths define how people and vehicles move on a puzzle piece. The structure of one path section looks like this:
Code: (SC4Path-file Path Section)
-- car_1_2_a -- This comment is used for the name of the path by several modding programs
1 -- "Transportation Type Identifier"
1 -- Path ID. This must be unique!
1 -- Entering wind direction
3 -- Leaving wind direction
0 -- "Junction key (0 or 1)
2 -- Number of path co-ordinates.
2.5,8,0 -- Path co-ordinates no.1 (x,z,y)
4,-8,0 -- Path co-ordinates no.2 (x,z,y)
- The path name has the following structure: -- ___. You can leave the path name out of your path-files, but it's advised to use them anyway, because you can easily have an overview of your path files.
- The "Transportation Type Identifier" tells SimCity 4 which vehicle will be using this path. There are six known "Transportation Type Identifiers":
- 1. "car" (all road-based traffic, except for pedestrians and GLR)
- 2. "sim" (pedestrians)
- 3. "rail" (heavy rail vehicles)
- 4. "subway"
- 6. "el-rail" (elevated rail and GLR)
- 7. "mono" (monorail and (G)HSR)
- The Entering and Leaving Wind Direction tells SimCity which direction a vehicle enters the tile and which direction it leaves. The wind directions are:
- 0. West
- 1. North
- 2. East
- 3. South
- 255. Special (Neighbour connections, dead ends, etc.)
Fortunately, the SimCity 4 Path Creator has these wind direction IDs on the sides of the screen, so you can easily what the Entering and Leaving Wind Direction of a path is. For instance, the red path in the image below enters the tile at the south (3) and leaves the tile at the north (1).
- The "Junction Key" determines if a switch appears for this path in the UDI mode (1) or not (0). Although this feature is only used for rail networks, it should always be present in the SC4Path-file!
- Every path should start and end at the edge of the tile, except if the Entering and/or Leaving Wind Direction is 255. Otherwise, this path will not appear in SimCity 4.
6.2.4. Stop points
Depending on the number of stop points, the SC4Path-file has a seperate section for each stop points. The paths define where vehicles stop to prevent colisions. It's very important that the stop points are defined after all paths. Otherwise SimCity will crash. The structure of one stop section looks like this:
Code: (SC4Path-file Path Section)
-- stop_car_1_2_a -- This comment is used to recognise the stop points for users.
1 -- Left Hand Drive (2) or Right Hand Drive (1)
1 -- "Transportation Type Identifier"
1 -- Stop point ID. This must be unique!
1 -- Entering wind direction
255 -- Leaving wind direction
3,6,0 -- Stop point co-ordinates (x,z,y). There's always one stop point co-ordinate!
- The path name has the following structure: -- stop____. You can leave this note out of your path-files, but it's advised to use them anyway, because you can easily have an overview of your path files.
- Stop points also determine which vehicles give way to other vehicles and controls which traffic flows may go at stoplight intersections.
6.2.5. Other important notices
- Paths that contain errors don't show up or are red flashing when using the "ShowPaths"-cheat from ExtraCheats.dll.
- The Path and Stop Point IDs are 1 or higher.
- The Path IDs and Stop Points IDs don't depend on each other. That means you can use an ID twice: one for a path and one for a stop point. They both will have an unique ID.
6.3. Unpathed pieces/Dummy Paths
Sometimes there's no need for a puzzle piece tile to have paths. Unfortunatly, when a tile has no SC4Path-file, SimCity4 will be laggy during the construction of the puzzle piece. To prevent this from happening, you can make a Pathfile only containing a header and a dummy path. Fortunately, the Puzzle Piece Maker makes these dummy path files, so you don't have to edit the SC4Path-files for the tiles you don't want to contain paths.
6.4. SC4Path Creator
In the early days of SimCity 4 Transit Modding, we didn't have any visual application for editing path files. Fortunately, one of our members, Daeley, has created a Java-application for this job, the SC4Path Creator. This tool significantly simplifies the creation of paths. The program also contains some very useful functions, such as flipping and mirroring paths, the ability to see multiple SC4Path-files at once and using a texture as background, which makes the creation of paths even easier.
6.4.2. The Single Frame View and the Multi Frame View
The Single Frame View contists out of a Path Editor, which I'll explain in detail in the next section. The Multi Path View is ment for puzzle pieces that contain more than one tile. When your piece only constists out of only one tile, you can skip the next paragraph.
In the Multi Frame View, you can see all the path files at once. You first have to define the size of the grid to the size of your puzzle piece. It's advised to use '128' as rect size instead of the standard value '150', so you have the right scale. Every tile opens a new Single Frame View window when you click on it, so you can edit the paths.
NOTE: When you open a Single Frame View window of a tile and then return to the Multi Frame View, you can add or delete pathing co-ordinates by simply clicking on the tile.
6.4.3. The Path Editor
With the Path Editor you can edit any path in any desired tile. Each path has it's own color, so they can easily be recognised. In the menu "Path Options\Select Texture", you can select a texture image as background, to simplify the path creation. Most other functions are speaking for themselves. Still I want to bring some other things to notice:
- When you have more than 6 paths at one tile, some paths will appear in the same color.
- When you flip or mirror a path, the Entering and Leaving Wind Direction aren't changed automaticly. You need to edit those manually.
- When you create a new path, the Path ID is set to 0 of that path. You need to set this ID manually to an unique number.
- When you add some pathing code into the Code Editor, check the header if it's set to the right number of paths. If not, the path you just added will be deleted when clicking on the "update"-button.
- When you've added some code and clicked on "update"-button and you see no change, then there is a bug in your code.
- Although SC4Path files can contain notes, the SC4Path Creator only allows it at the first line of a new path. When you make notes at any other place, you'll see no change when you hit the "update"-button.
- The SC4Path Creator 1.60 doesn't support stoppoints. Any stoppoints made will be deleted. It's advised to make the stoppoints at the end.
- The SC4Path Creator 1.60 unfortunatly has no save function. When you shut down the SC4Path Creator and didn't save the code anywhere else, you can start all over agian.
6.4.4. Saving path files
Of course, you'll need to save your paths somewhere! When you finished creating paths with the SC4Path Creator, you can save them with the Reader in a DAT-file by following these steps:
- Select the text from the Code Editor in the SC4Path Creator. You can use CTRL+A (Select All) to be sure everything is selected.
- Copy the code (CTRL+C).
- Select the corresponding SC4Path-file in the Reader.
- Click on "Edit".
- Select the code that's already in the SC4Path-file to override it (NOTE: CTRL+A doesn't work in the Reader).
- Paste the new code (CTRL+V).
- Hit "Apply"
- Save the DAT-file when you're done.