Jump to content
Sign in to follow this  
sphereii

[ GUIDE ] Mod and Modlet Naming Conventions for A17+

Recommended Posts

With the introduction of modlets and the ability to mix and match mods together, it's been discussed that there may be conflicts that will arise if proper care is not taken. These guidelines are based around the modlet concept, where the code is distributable and can be re-used in many different mods.

 

With the id system for items and blocks dropped, uniqueness is now based on the block and item name. The system may not throw an error when a duplicate name occurs, but it appears that the last item and block loaded with the shared name, will take priority over earlier references.

 

This post will outline some best practices to help modders avoid possible mod conflicts.

 

Here are some of the guidelines to help you come up with a unique naming convention for your mods. Some mods may be able to use one method, while others would use another.

 

1) Use the mod name as a unique identifer. This identifier should carry forward through your folder name, and a prefix to items, recipes, windows, and asset bundles

 

Example:

Mods/ScrapMetalTools/

<item name="scrapMetalTools_Axe">

<item name="scrapMetalTools_Pickaxe">

<item name="scrapMetalTools_Shovel">

 

This goes for adding new XUI elements as well.

Mods/ScrapMetalTools/

<window name="ScrapMetalTools_windowJournalList" />

<window name="ScrapMetalTools_windowTrader" />

 

Asset Bundles and item icons as well

Mods/ScrapMetalTools/Resources/scrapMetalTools_Axe.unity3d

Mods/ScrapMetalTools/ItemIcons/scrapMetalTools_Axe.png

 

Folder name examples:

Mods/SphereII_WinterProject/

Mods/RyanJames_WinterProject/

Mods/SMXmainMenu/

Mods/SMXhud/

 

2) Avoid using excessive abbreviations

Some mods will be expected to be used a lot in other mods, with some tweaks done each time. It's best to be clear on your named values to make these changes easier. The less questions you have to deal with, with regards to your naming convention, the easier your support efforts will be.

 

3) Avoid removing nodes, or changing them drastically, unless its critical to your mod design

 

Avoid making assumptions that make changes beyond the expectations of the mod. For example, if you are adding scrap tools, don't make the assumption that stone tools need to be removed, or that iron and steel tools need to be radically adjusted to allow them to fit. Nor would we expect food values change in a scrap tool modlet.

 

If you are designing a UI, avoid making an assumption that your UI may be the only one installed. Some may want the menu system to look different than your design. In this case, make two mods: One for the UI, and one for the menu.

 

4) Avoid prefacing the mod name by using numbers

 

The load order of the mods is currently alphabetical, with the bottom of the list taking priority over any previous changes. A player or modder applying a modlet would be responsible for adding any kind of numeric number or changing the mod's folder to change the load order they so desire.

 

Example:

Mods/AnotherFakeClub/ - Changes stone axe to be a club

Mods/FakeClub/ - Changes stone axe to be a torch

 

Result: The stone axe will be a torch.

 

Another Example:

Mods/0_FakeClub/ - Changes stone axe to be a torch

Mods/1_AnotherFakeClub/ - Changes stone axe to be a club

 

Result: The stone axe will be a club.

Share this post


Link to post
Share on other sites

I would also suggest using the mod name as the root node tag for all your xml xpath entries.

Share this post


Link to post
Share on other sites
I would also suggest using the mod name as the root node tag for all your xml xpath entries.

 

I've heard this, but I haven't seen any solid examples of it being long term viable and flexible enough for people.

 

If you have a mod with a space in it, you'd have to remove the spacing. <SphereIILootContainerOverhaul> is kind of wordy, for no real benefit. I don' t even think the game sees or uses the root node for anything other than conforming to XML standards.

 

I've always felt it was more natural to have a consistent node structure, which reduces possible typos in your root nodes.

Share this post


Link to post
Share on other sites

4) Avoid prefacing the mod name by using numbers

 

The load order of the mods is currently alphabetical, with the bottom of the list taking priority over any previous changes. A player or modder applying a modlet would be responsible for adding any kind of numeric number or changing the mod's folder to change the load order they so desire.

 

Example:

Mods/AnotherFakeClub/ - Changes stone axe to be a club

Mods/FakeClub/ - Changes stone axe to be a torch

 

Result: The stone axe will be a torch.

 

Another Example:

Mods/0_FakeClub/ - Changes stone axe to be a torch

Mods/1_AnotherFakeClub/ - Changes stone axe to be a club

 

Result: The stone axe will be a club.

 

For this to apply in game (alphabetical rules) do you need to just change the name of the mod folder or the name of the mod itself to load last if you are wanting to be sure a certain mod takes priority over any other mod that may alter the same item/entity?

Share this post


Link to post
Share on other sites
For this to apply in game (alphabetical rules) do you need to just change the name of the mod folder or the name of the mod itself to load last if you are wanting to be sure a certain mod takes priority over any other mod that may alter the same item/entity?

 

Folder, I believe.

Share this post


Link to post
Share on other sites

Has anyone given any thought about how modlet dependencies will be handled?

 

For example, I'm hoping that someone will restore the A16 NPCs in a modlet. But, let's say I wanted to alter the behavior of that modlet, say by adding additional AI.

 

My modlet would be dependent upon the other modder's NPC modlet, but I'm not sure how that would be represented.

Share this post


Link to post
Share on other sites

Either include it, following the mod rules posted, or specify that it requires the prior modlet?

 

Sounds good to me. :)

Share this post


Link to post
Share on other sites

My suggestion would be that if you are modding someone else's mod, name your mod directory after theirs, and append your own name...

 

so if I named my mod AvimodsAI, you could name yours AvimodsAIKHZModlet or something like that. it would ensure it gets loaded after without having to be too contrived, so people don't name all their mods ZZZMod or something like that just to create priority.

Share this post


Link to post
Share on other sites

+1 for making this thread sticky.

 

Also - I didn't realize this, but in the mod.xml and/or ModInfo.xml files, it is a requirement that the "name"/"Name" values exactly match the name of your modlet's folder. (If you want more human-readable text, use "description".)

 

Otherwise, the mod won't be picked up by the Mod Launcher and/or SDX/Harmony. I guess it uses the "Name" value to determine the modlet's folder name, it doesn't directly examine the file system.

Share this post


Link to post
Share on other sites

Hi, just 2 random remarks:

 

1) What about scripts and harmony ?

- For scripts, I dunno if prefixing class name with the mod name is a great idea, but it would avoid potential name conflicts. Should we instead locate our classes in subfolder (prefixed by mod name) ?

- For harmony, I feel the problem is deeper. What happens when 2 mods use harmony to patch the same method ?

 

2)

4) Avoid prefacing the mod name by using numbers

The DMT tool should offer the option to order mods. It would add the n_ prefix before copying to the game folder, depending on an order selected by the user in the tool.

Share this post


Link to post
Share on other sites
Hi, just 2 random remarks:

 

1) What about scripts and harmony ?

- For scripts, I dunno if prefixing class name with the mod name is a great idea, but it would avoid potential name conflicts. Should we instead locate our classes in subfolder (prefixed by mod name) ?

- For harmony, I feel the problem is deeper. What happens when 2 mods use harmony to patch the same method ?

 

2)

The DMT tool should offer the option to order mods. It would add the n_ prefix before copying to the game folder, depending on an order selected by the user in the tool.

 

1) Usually the name of the scripts and patches are not that important, especially for load order. I'd do sub-folders only if it makes sense for your project. If you just have a few scripts, then putting them in folders may just add extra clicks when you are exploring them, and doesn't add value.

 

2) The DMT tool does not do this because the game does not have any fixed order. It just so happens that the default behaviour is reading it numbers / characters first.

 

I've broken both of these rules with 0-SphereIICore. It's my intention to direction load my Core first, so that things other mods may depend on is available. I also use a lot of sub-folders in my Harmony and Scripts.

 

For folders, I'll usually sub-divide them by context. For example, a Dialog folder will contain changes to the dialog system. Entities will change those. etc.

 

For Script and Harmony patches, I'll usually try to name them after the class I'm targetting. This becomes a bit impractical when some kind of feature requires changes to multiple classes to work; In those cases, I'll try to name the class .cs after the feature I'm adding.

Share this post


Link to post
Share on other sites

Thank you Sphereii !

 

1)

Usually the name of the scripts and patches are not that important, especially for load order

I was thinking more of 2 mods each defining a class with the same name. Then some code in mod #2 will end up referring to a class of mod #1, and anything could happen. But maybe c# import mechanism handles this case and starts looking within the same folder (I doubt it though) ?

Share this post


Link to post
Share on other sites
Thank you Sphereii !

 

1)

I was thinking more of 2 mods each defining a class with the same name. Then some code in mod #2 will end up referring to a class of mod #1, and anything could happen. But maybe c# import mechanism handles this case and starts looking within the same folder (I doubt it though) ?

 

Probably an appropriate namespace would protect it. I use fairly descriptive and long namespaces in my changes to avoid conflicts.

Share this post


Link to post
Share on other sites
My suggestion would be that if you are modding someone else's mod, name your mod directory after theirs, and append your own name...

 

so if I named my mod AvimodsAI, you could name yours AvimodsAIKHZModlet or something like that. it would ensure it gets loaded after without having to be too contrived, so people don't name all their mods ZZZMod or something like that just to create priority.

 

I know this is an old post, but ran into this issue myself....

If there is a mod[let] on github, and you fork it (make your own copy) the mod[let] name does not change (just a different repository). Depending on the nature of the need for forking/copying/updating, I just appended my name into the "Version" tag in ModInfo.xml, e.g and bumped the version number up.

 

<Version value="2.0.0-doughphunghus" />

 

This likely will work well if the mod[let] being forked is no longer being used or both mod[let]s are not intended to be used together (which is highly likely) Otherwise, I'd recommend starting a new repository with a name as you suggest (adding your name to the original mod[let] name).

 

I don't know if any of the ModInfo.xml tags are standardized, like the "Version" is *supposed* to or intended to be a special format, or something.

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now
Sign in to follow this  

×
×
  • Create New...