Announcement

Collapse
No announcement yet.

[ GUIDE ] Mod and Modlet Naming Conventions for A17+

Collapse
X
 
  • Filter
  • Time
  • Show
Clear All
new posts

    [ GUIDE ] Mod and Modlet Naming Conventions for A17+

    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.

    #2
    Please sticky.

    Comment


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

      Comment


        #4
        Originally posted by Buggi View Post
        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.

        Comment


          #5
          Originally posted by sphereii View Post
          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?

          Comment


            #6
            Originally posted by Myrrah View Post
            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.

            Comment


              #7
              Originally posted by sphereii View Post
              Folder, I believe.
              awesome. thank you for the info

              Comment


                #8
                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.

                Comment


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

                  Sounds good to me.

                  Comment


                    #10
                    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.

                    Comment


                      #11
                      +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.

                      Comment


                        #12
                        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.

                        Comment


                          #13
                          Originally posted by Umbrella View Post
                          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.

                          Comment


                            #14
                            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) ?

                            Comment


                              #15
                              Originally posted by Umbrella View Post
                              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.

                              Comment

                              Working...
                              X