Submenus DLL

[Andreas Roth 607]

The SC4 CLI (commandline) Tool has two different steps for creating submenus. When organizing your lots, you have to decide if you want to move them to one of the predefined submenus that come with the submenu DLL download (i. e. there's a submenu for parks, plazas and sports facilities in the Park Menu), or if you want to create your own new submenu. When using an extended set of lots, I guess you might want to create your own submenu for them (or even a submenu that contains more submenus) most likely, so you have to do both of the following steps (creating the submenu and then assigning the lots to them, so you need to do the second process that I mentioned first).

Let's stick to the basics for a moment, though: moving an existing lot (or several lots that are placed in a subfolder) to one of the predefined submenus. When you go through the process of adding a file (or several files in a folder) to a submenu, the tool will create a file called "submenu_patch.dat". Try to open this file with the Reader, then you'll see that it only contains one Cohort file. This is basically the "patch" that tells the game to move the lot(s) that you picked to a certain submenu. There are two properties, "Exemplar Patch Targets", which is a list of all TGI values of the Exemplar files of the lot(s) in question), and a "Building Submenus" property that contains the ID of the submenu where the lot(s) should show up. By default, the file is saved in the same folder where the original lot(s) reside. The icons of the lots are not touched in any way, so if you want to change these, you'll have to edit the lot files and put your custom icons into those (the easiest way is using LEProp, I think).

The next level is creating your own submenu. For this, you might want to have a custom submenu icon ready, but you can also use any icon you want (such as an icon from the original lot file that represents the set of lots nicely) and use the built-in template in order to create a nice-looking icon for the new submenu. When running the SC4 CLI Tool, it allows you to create a new submenu and asks where this menu should be placed. You can add a name and a description text, and pick an icon for the submenu. It creates a file named "submenu_[name].dat" which is saved in the root of your plugins folder. When you open this file with the Reader, you'll see an Exemplar file that tells the game to create a menu button for the submenu, and there's two LTEXT files with the name and the description of your submenu. There's also the PNG file with the icon that you picked in the process. As mentioned before, this only creates the submenu itself, so you have have to do the steps described in the paragraph above in order to add lots to the new submenu.

As far as I can tell, the loading order for this submenu DAT file doesn't matter, the game will simply read it during startup and create the menu button. For convenience, you can put all submenu DATs into a subfolder of your plugins, or you can put them into the folder with the lots that should be contained in this submenu. The submenu patch file that I mentioned above should be kept with the files that it modifies, and I think it might be necessary that it loads after the file that it affects (but I'm not entirely sure how the game handles Cohort files, maybe it's not that critical). As mentioned above, any custom icons that you created for the lots themselves must be either replaced in the original files, or you must create a DAT file that contains a copy of the original icons (same TGI values), but with the new icon graphics, and this must be loaded after the original lots, so they serve as an override. As I mentioned before, DatPacker might have picked the original icons instead of the new ones, depending how you stored them in the first place.

[Rady 94]

1 hour ago, Andreas Roth said:

The SC4 CLI (commandline) Tool has two different steps for creating submenus. When organizing your lots, you have to decide if you want to move them to one of the predefined submenus that come with the submenu DLL download (i. e. there's a submenu for parks, plazas and sports facilities in the Park Menu), or if you want to create your own new submenu. When using an extended set of lots, I guess you might want to create your own submenu for them (or even a submenu that contains more submenus) most likely, so you have to do both of the following steps (creating the submenu and then assigning the lots to them, so you need to do the second process that I mentioned first).

Let's stick to the basics for a moment, though: moving an existing lot (or several lots that are placed in a subfolder) to one of the predefined submenus. When you go through the process of adding a file (or several files in a folder) to a submenu, the tool will create a file called "submenu_patch.dat". Try to open this file with the Reader, then you'll see that it only contains one Cohort file. This is basically the "patch" that tells the game to move the lot(s) that you picked to a certain submenu. There are two properties, "Exemplar Patch Targets", which is a list of all TGI values of the Exemplar files of the lot(s) in question), and a "Building Submenus" property that contains the ID of the submenu where the lot(s) should show up. By default, the file is saved in the same folder where the original lot(s) reside. The icons of the lots are not touched in any way, so if you want to change these, you'll have to edit the lot files and put your custom icons into those (the easiest way is using LEProp, I think).

The next level is creating your own submenu. For this, you might want to have a custom submenu icon ready, but you can also use any icon you want (such as an icon from the original lot file that represents the set of lots nicely) and use the built-in template in order to create a nice-looking icon for the new submenu. When running the SC4 CLI Tool, it allows you to create a new submenu and asks where this menu should be placed. You can add a name and a description text, and pick an icon for the submenu. It creates a file named "submenu_[name].dat" which is saved in the root of your plugins folder. When you open this file with the Reader, you'll see an Exemplar file that tells the game to create a menu button for the submenu, and there's two LTEXT files with the name and the description of your submenu. There's also the PNG file with the icon that you picked in the process. As mentioned before, this only creates the submenu itself, so you have have to do the steps described in the paragraph above in order to add lots to the new submenu.

As far as I can tell, the loading order for this submenu DAT file doesn't matter, the game will simply read it during startup and create the menu button. For convenience, you can put all submenu DATs into a subfolder of your plugins, or you can put them into the folder with the lots that should be contained in this submenu. The submenu patch file that I mentioned above should be kept with the files that it modifies, and I think it might be necessary that it loads after the file that it affects (but I'm not entirely sure how the game handles Cohort files, maybe it's not that critical). As mentioned above, any custom icons that you created for the lots themselves must be either replaced in the original files, or you must create a DAT file that contains a copy of the original icons (same TGI values), but with the new icon graphics, and this must be loaded after the original lots, so they serve as an override. As I mentioned before, DatPacker might have picked the original icons instead of the new ones, depending how you stored them in the first place.

Thanks for clarification. I'm creating my own submenus, that's why I organize my lots (in addition to the games plugin folder) in a separate folder structure that resembles the content of the different submenus. As for the custom icons, I modified the original lots and replaced the icon file with my custom made icon file (at first - unaware of the LEProp tool - I used the Reader, but I have meanwhile switched to LEProp toll for obvious reasons).

[memo 1,444]

On 2/23/2025 at 1:21 PM, Rady said:

What I don't understand is where the Submenu DLL retrieves the icon from.

The icon is referenced in the respective Exemplar file. If you have multiple copies of the Exemplar, only the last one loading should have an effect. If you have Exemplar Patches that contain the Item Icon property, they override the icon reference. The load order of the patches is independent of the load order of the Exemplars.

[Panda 209]

On 1/18/2025 at 7:02 PM, Andreas Roth said:

@Panda: I've also added the last three icons that you made; they look excellent in the game alright. I noticed some minor bugs, though: several icons have a slight "pixel shift" when you hover over them with the mouse. This includes the "deluxe police station", "sports facilities" in the park menu and also the new "government" button. I fixed the aforementioned icons and included them into the zip file below. I think some of the ploppable R/C/I icons are also affected, but I cannot test this properly since I don't use those a lot, hence the menu spots in the game are empty for me.

Here are fixes for the misaligned icons:

[Andreas Roth 607]

Thanks for these, working with the source files is definitely better than me fiddling with the pixels.  I hope you'll find some time for checking the icons for the R/C/I ploppables, and I'm looking forward to the rest of the set, so the default submenus are complete.

[simster007 370]

Short question: How can I change the menu position of existing submenus, like from parks to landmarks?

[Andreas Roth 607]

From what I can see, you have to edit the "Item Submenu Parent ID". To move a submenu from "Parks" to "Landmarks", change the ID from 0xDEFFD960 to 0x09930709, at least that's what seems to be different when I compare submenus in those menus.

Try to open the DAT files in the "submenus" folder in your game's Plugins folder (where the DLL is installed) with the Reader and look up the "Item Submenu Parent ID" of those.

[simster007 370]

1 hour ago, Andreas Roth said:

From what I can see, you have to edit the "Item Submenu Parent ID". To move a submenu from "Parks" to "Landmarks", change the ID from 0xDEFFD960 to 0x09930709, at least that's what seems to be different when I compare submenus in those menus.

Try to open the DAT files in the "submenus" folder in your game's Plugins folder (where the DLL is installed) with the Reader and look up the "Item Submenu Parent ID" of those.

Thx, I'll give that a try. Can I find somewhere a list of these ID's?

[memo 1,444]

On 3/3/2025 at 9:06 PM, simster007 said:

Can I find somewhere a list of these ID's?

Yes. Have you checked the Readme file included with the download yet?

[Andreas Roth 607]

Thanks for pointing out that there's a list in the Readme file. Looking at the IDs, I see that I made a slight mistake above, I looked up the IDs of random submenus that I've created myself and saw that I mentioned the ID of the "Paths and Modular Park sets" submenu (0xDEFFD960) instead of the actual Park menu (0x3, which is the same as 0x00000003, I think).

[Simizen 1,098]

curious, and maybe I've missed it earlier in the thread, but I'm wondering, is it possible to setup a separate file for lots you want to sort?

like, say for example, I have KloudKicker's transformer lots, and I wanted to give them a submenu, would it be possible for me to give them one and only upload a seperate file for them without having to reupload the selection? Or is it required to have a reupload to make it submenu compatible?

[kergelen 727]

5 hours ago, Simizen said:

curious, and maybe I've missed it earlier in the thread, but I'm wondering, is it possible to setup a separate file for lots you want to sort?

like, say for example, I have KloudKicker's transformer lots, and I wanted to give them a submenu, would it be possible for me to give them one and only upload a seperate file for them without having to reupload the selection? Or is it required to have a reupload to make it submenu compatible?

You don't need to reupload the lots. You only need to create the submenu and upload only the seperate submenu file (both button and patches or all together in the same .dat file)

[simster007 370]

11 hours ago, memo said:

Yes. Have you checked the Readme file included with the download yet?

Yes, I found these infos yesterday during my fiddling with the menus. Thx for the info!

 

10 hours ago, Andreas Roth said:

Looking at the IDs, I see that I made a slight mistake above, I looked up the IDs of random submenus that I've created myself and saw that I mentioned the ID of the "Paths and Modular Park sets" submenu (0xDEFFD960) instead of the actual Park menu (0x3, which is the same as 0x00000003, I think).

Don´t worry about that. Your answer gave me the important hint.

All in all: my problem is solved! Thank you

[Ulisse Wolf 4,412]

11 hours ago, Simizen said:

curious, and maybe I've missed it earlier in the thread, but I'm wondering, is it possible to setup a separate file for lots you want to sort?

like, say for example, I have KloudKicker's transformer lots, and I wanted to give them a submenu, would it be possible for me to give them one and only upload a seperate file for them without having to reupload the selection? Or is it required to have a reupload to make it submenu compatible?

Direct submenu insertion is done only when the lots requires maintenance for bad modding as is happening with SC4E content

[Rady 94]

Forget the following. I found out that I was missing the tropod_Properties.xml.

 

I started editing my MMP lots IOT show up in a custom menu. When opening the .dat files with the Reader, I have a lot of "Unknown" entries. I already loaded the submenu_properties.xml into the Reader. There are also some more files loaded, however I'm unable to find out which, as the "Options" window of the reader trunctates the file names.

So two questions arise:

1. how can I find out which xml property files there are installed?
2. Which xml property files need to be installed to get rid of the "unknown" entries?

Thank you!

 

  Edited March 6, 2025 by Rady  
FOund out by myself :-)

[Simizen 1,098]

curious: what kind of file type does this allow, regarding the menu icons?

like, the template is xcf, but is png acceptable? or is there another type to work with?

[Simizen 1,098]

new plan: i'm gonna need the whole "make a new menu" thing and the patch thing ELI5, cause I'm not understanding the readme file to this mod.

Like, at some point I figured out how to add lots to already existing submenus (which is good, and that's pretty straightforward), but I'm rereading this file several times trying to comprehend what I am reading, and my understanding of it seems to be getting worse not better (which is not something that's often done, especially since i graduated school)

and, I see stuff regarding IDs, but everything's just saying "make it unique" without any explanation on how to actually do that, so, now I'm stuck with a high possibility of just reusing IDs (especially since there's already a massive issue within the community using the same IDs on so many lots everywhere else that it's created project conflicts)

I was originally expecting it to be a bit more straightforward, much like adding them to pre-existing submenus, but that doesn't seem to be the case

was aiming to do a quick test, and found out nothing was making sense from what I originally understood, so I went to a set that I had moved to a submenu to try and see if I could get info on it, and that's not helping, as I'm not getting anything past how to put them into a pre-existing submenu.

[Andreas Roth 607]

The game only supports PNG files. XCF is the native file format of the free image-editing program GIMP,  so you can modify the template to your likings easily.

As for making unique IDs, I suggest to use the internal routines of the modding tools. IIRC, these IDs are based on some algorithm that takes the actual time and date into account, so it shouldn't be possible to create the same ID at another time. Doing this manually isn't really possible, since nobody would be able to check all IDs that are around. For creating textures, buidling families and stuff, there are lists with ID ranges that are given out, which makes it relatively save that every ID is unique, but naturally, there is a slight chance that some of those IDs might be used in the game already, or someone else who isn't aware of those lists picks the very same ID by chance. The human brain prefers "readable" patterns like 0x12345678, which is of course not random at all, and there might be a higher chance that somebody else might pick the very same ID.

You don't really have to pick "unique" IDs for the submenus manually, though. The SC4 Commandline Tool makes creating submenus and adding lots to them pretty straightforward, and even though it's name "Commandline", you don't have to type commands yourself, but select menu options that are displayed as text with the cursor keys rather than using a mouse-driven GUI. If you want to move around stuff to another submenu manually, you don't need to create new IDs anyway, but rather pick those of the submenu in question (check "Item Submenu Parent ID", as mentioned above).

[Null 45 3,041]

2 hours ago, Andreas Roth said:

The game only supports PNG files.

Maxis used PNG files, but there are a few other formats that could potentially be used. Not that it matters for such a small image.

One thing to watch out for is that the game can only read 24-bit and 32-bit PNG images. As documented in this topic, using an indexed color PNG will result in a blank icon when the game fails to load that format.

2 hours ago, Andreas Roth said:

IIRC, these IDs are based on some algorithm that takes the actual time and date into account, so it shouldn't be possible to create the same ID at another time.

I suspect that most modding tools are generating a random Uint32 number without a date/time portion.

The date/time scheme is not foolproof, it can create duplicate ids by either having them generated too quickly or when the date/time window rolls over. Based on its documentation, the algorithm Maxis likely used rolled over in 2014.

[Wiimeiser 444]

I've had an idea floating in my head for a little bit about submenu icon standards that I forgot to post until now:

Category submenus (Modular Parks, Rail Sidings, Canals, etc) should have the round icons, while set submenus (PaengParks, PPonds, etc) should have the image with a small (and preferably contrast-visible) burger icon in the corner.

What do people think of this?

[Dono 178]

27 minutes ago, Wiimeiser said:

I've had an idea floating in my head for a little bit about submenu icon standards that I forgot to post until now:

Category submenus (Modular Parks, Rail Sidings, Canals, etc) should have the round icons, while set submenus (PaengParks, PPonds, etc) should have the image with a small (and preferably contrast-visible) burger icon in the corner.

What do people think of this?

If you are using the Sc4cli tool in conjunction with the submenu.dll, it already has that option, to create your own submenu or submenu within a submenu with the burger icon, obviously it's not a "set" standard but user defined.

It would be cool though if for example you just downloaded PaengsParks, it got "Burgered" when placed into it's set parks menu.

[Rady 94]

I'm still confused with regard to the possible values for the Item Order. I already figured out that "0" converts to "0xffffffff", which I used for every submenu I created. However, this doesn't necessary lead to the desired effect of the submenu showing up at the top level of the respective (vanilla) menu.

As I'm using the sc4 tool for creating my submenus, as of lately at the point of entering the Item Order, it reads:

Enter the item order: (number between -2,147,483,648 and 2,147,483,647):

But as far as I know, there are no negative hex numbers? So, how am I supposed to enter a negative number? Or, if 0 is the lowest, why don't the submenus show up at the top?

Or, to take a different approach, how could I determine the item order of the vanilla icons?

 

 

[CorinaMarie 29,605]

7 minutes ago, Rady said:

I already figured out that "0" converts to "0xffffffff"

Whatever is doing that conversion is incorrect. 0xffffffff = -1 in  Hex signed 2's complement.

 

9 minutes ago, Rady said:

But as far as I know, there are no negative hex numbers?

There is. You use the leftmost digit to indicate positive or negative.

I use this site and look at the value in the Hex signed 2's complement box. When it doesn't give all 8 hex digits, just add Fs to the left of it's answer to pad it out to 8 characters.

[Rady 94]

I just misremembered this .. yes, it's actually -1 .. and thanks for the HEX conversion link!

[Gn_leugim 853]

Hello there! Nice work on this wonder of a new thing (at least for me )

I can easily add new lots to exiting submenus alright, but I am struggling to create new ones. I am always getting an error:

sc4 0.2.17

√ What do you want to do? Create a new submenu
√ What is the name of the submenu? Rivers
√ Enter the description of the submenu (leave open to use the default) Rivers and Water Bodies
√ Select the parent menu Civics > Parks
√ Select the icon to be used for the button: <icon>
√ Enter the item order: (number between -2,147,483,648 and 2,147,483,647): 10
ERROR Error: ENOENT: no such file or directory, open 'G:\Documents\SimCity 4\ Plugins\submenu-rivers.dat'
    at async open (node:internal/fs/promises:638:25)
    at async Object.writeFile (node:internal/fs/promises:1212:14)
    at async cb (dist/sc4.js:251:19136)
    at async xb (dist/sc4.js:255:6702)
    at async value (dist/sc4.js:254:2464)
    at async f2e (dist/sc4.js:255:198)
    at async r.bz (dist/sc4.js:254:1892) {
  errno: -4058,
  code: 'ENOENT',
  syscall: 'open',
  path: 'G:\\Documents\\SimCity 4\\ Plugins\\submenu-rivers.dat'
}

I have left this also as a problem in github btw.

 

Help would be appreciated 

Best! GnL

[smf_16 1,835]

@Gn_leugim The problem is probably that your plugins folder isn't configured correctly. Can you open up a command prompt in the folder where the sc4.exe is located (type cmd in the address bar of Windows explorer, hit enter), and then type "sc4 config edit". You should then be able to manually correct your plugins folder.

[Gn_leugim 853]

@smf_16 that did the trick! thank you very much!

[kergelen 727]

I'm trying to modify manually a patch for submenus I created with sc4cli Tool, in order to add 1 more lot to it, but somehow the patch become corrupted and no longer show the lots in the submenu.

I copy the hex code of the PluginID pack of the Lot exemplar and add it into the Exemplar Patch Target on the cohort file of the patch.

Then I save the patch file. Don't know why but after doing this the patch somehow get corrupted or something else because I do not see all lots added to the submenu (both the lots I had before plus the new lots added).

I've did the same process before and it worked. Dont' know why it's not working now

I have installed submenu_essential to Reader

And I've try it several times with Reader 0.93 and with reader 1.5.4

Any tips?

 

[memo 1,444]

On 3/24/2025 at 9:07 PM, kergelen said:

I copy the hex code of the PluginID pack of the Lot exemplar and add it into the Exemplar Patch Target on the cohort file of the patch.

Use the Building Exemplar instead of the Lot Exemplar. Also note that the "Exemplar Patch Targets" property is an alternating list of Group IDs and Instance IDs, so add both the Group ID and Instance ID of the Building Exemplar.

[CahosRahneVeloza 385]

Is requesting submenus.dll support for a specific set of Custom content allowed to be asked on here?

If it's not I hope I won't get in trouble for asking this...

But I would just like to ask for submenus.dll support for PEG Streams, Ponds and the SPAM Irrigation Canals as these items are just all over the place. And if possible I'd like them to be placed in the Waterways sub menu, just like the BSC Canal sets.

Again if this is not allowed just kindly disregard this comment of mine.