Right yes forgot about this being a preliminary to the change incoming; so how should people go about this issue if they want to install a mod? Wait until the new launcher and reinstall? Move the files from where they may be installed into the correct folder tree? Pray to the gaming Gods for holy aid?
You could use something like a universally unique identifier (UUID) to make sure that there are no collisions and PA must issue the unique identifier. Probably done by doing a SHA-1 of a individual mod directory inside the mod folder. The benefit from doing it this way is you can have two or more mods name the same thing and have no conflicts. The unique identifier must take priority over the name of the mod. Also could be named planetary annihilation unique identifier or PAUID for short. Example: Code: { "enabled" : true, "name" : "example", "PAUID" : {AE1C6B9B-4DF0-4922-B383-1BD787FC20C8}, "description" : "makes all your wildest dreams come true", "author" : "ooo27", "version" : "1.0", "signature" : "(not yet implemented)" } Reference: see RFC4122 http://en.wikipedia.org/wiki/Universally_unique_identifier (The article has in it some implementations, other the references and external links.)
Hi folks, I'm chiming in here since I'm looking into some of these file system / modding / shadowing issues at the moment. UUIDs can be helpful for some types of conflicts, but they're really opaque, which has its own set of problems when human hand-rolling is involved (which for mods is usually the case). So I'd like to avoid going down that road if at all possible. It's very possible to use human-readable names for reasonably unique identification by following something like a reverse-domain-name lookup, i.e. "com.myawesomepamodsite.badassmods.baconcommander" or whatever. This would be independent of the display name, which could be whatever you want. Would that satisfy your UUID concerns? Now with regards to conflicts due to shadowing files and mod stacking, that's a much more complex problem and there really is no easy solution at file granularity. The best solution will always be to add files rather than replace them (so name your new stuff uniquely please!), but there is a natural limit to that; no matter where we draw the line some mod will want to push the boundary further into shadow territory and this issue will crop up again. So shadowing is always something to be used sparingly, and we'll try to lean mod access points towards addition rather than replacement whenever possible.
The way TES does it is pretty good, with order and so on. Then I think mods can be the same name because they are assigned a position in the load order. That way whichever mod is most prevalent takes higher priority of build order. And the mod developers always seem to sort out conflicts and so on amongst themselves. It's just practically impossible to mod certain stuff that the master file requires.
Yes and human readable would be preferable. I believe it should also be handled by the game. PS: Bacon Commander
Load order has to do with mod dependencies. So if you have mod Y and requires mod N. N must be loaded before Y as well as any DLCs that the mod needs or anything else. Which brings an interesting question how should PA handle dependencies. My suggestion would be somewhat analogous to a package manager. Where you have the dependencies written down in a metadata file. You could also put version number of mod and any DLC, mini expansion, and expansion pack, etc that is required in their. You can warn the user about dependencies so they could download them or mod manager/PA launcher would automatically download them. Code: { "enabled" : true, "name" : "example", "description" : "makes all your wildest dreams come true", "author" : "ooo27", "version" : "1.0", "signature" : "(not yet implemented)" "PAUID" : com.myawesomepamodsite.badassmods.baconcommander, "dependencies" : "mod N", } TES Load order recommendations: http://wiki.tesnexus.com/index.php/Load_order_recommendations
Hi folks! The next build we put up will have an early version of some of the mod support changes mentioned in the first post of this thread, in preparation for the new launcher. While the new launcher itself is not being rolled out with this build, the backing support for a "mods" folder is, and that gives a unique opportunity for you mod developers to give us feedback before the new launcher goes live. Specifically, existing mods that work by replacing original game files will still work for now, but mods using the "mods" folder should also work, and we'd like people to start switching over to the latter approach, and let us know if everything is still behaving okay. Once the new launcher goes up, the "mods" folder will be the only approach, so if there are problems with it, now's the time to tell us! Think of this as a "mods folder RFC". Okay, all that said, the actual implementation of this feature has some slight differences from the first post in the thread (which was still a little theoretical at the time). I'm going to repost that information in its entirety here, but with changes regarding how it's actually been implemented; these will be marked as "NEW 12/9/2013". Modders, please read carefully! ---- Hi modders! The beta launch will contain some modding changes that you all should be aware of. Most of these changes are in preparation for the release of a new cross platform launcher. It'll be a few weeks before the launcher is deployed, but in the mean time here's what's changing: No modifications should be done where official PA files are installed. The new launcher is going to "own" the directory tree where the game is installed. In order for your changes to not be clobbered you will want to move your stuff in to the new mod location specific to your platform. MOD Home Windows: %LOCALAPPDATA%\Uber Entertainment\Planetary Annihilation\mods On a typical install %LOCALAPPDATA% will be C:\Users\<username>\AppData\Local We don't actually use the environment variable but the windows system call SHGetKnownFolderPath with FOLDERID_LocalAppData. OSX: ~/Library/Application Support/Uber Entertainment/Planetary Annihilation/mods This corresponds to a query of NSApplicationSupportDirectory Linux: $HOME/.local/Uber Entertainment/Planetary Annihilation/mods Where $HOME typically maps to something like /home/<username> (Note: These are subject to change. The point is to get custom user files out of the main PA tree.) Consider a virtual file system that has one of the above install paths mounted as /mods. Your mod will live under /mods/<modname> where <modname> must be unique per-machine. (No strategy yet for avoiding collisions). NEW 12/9/2013: The name of the <modname> folder doesn't actually matter, as long as it's unique on a user's machine (since it's a directory). We don't use the folder name for anything internally. However, mod configuration files do have a new identifier string that must be globally unique, and that really does matter (see the next section). Configuration A mod called 'example' would be located at /mods/example. The engine will scan all top level directories under /mods and look for a modinfo.json configuration file under each, e.g. /mods/example/modinfo.json. NEW 12/9/2013: This .json file was originally based on the name of the mod folder. It no longer is, and is now always modinfo.json. The structure of the modinfo.json configuration file is simple: Code: { "context" : "client", "identifier" : "com.mydomain.bereallyspecific.noreallywemeanit.uniquemodname", "display_name" : "Nice Human Readable Mod Name", "description" : "makes all your wildest dreams come true", "author" : "ooo27", "version" : "1.0", "signature" : "(not yet implemented)" } NEW 12/9/2013: There is no more "name" field. Instead we now have a "display_name" (which mod manager UIs can use for displaying a human-readable mod name), and an "identifier" field in reverse-domain-name style syntax, which should be globally unique and immutable. This affects mod mounting order and, in the future, mod interdependencies. So make your identifier string specific and long, and something you never intend to change for the life of your mod! NEW 12/9/2013: There is a new "context" field, at the moment the only supported context is "client". Eventually server mods or mixed mods will have new context values, but for now only client mods are allowed. NEW 12/9/2013: There used to be an "enabled" field in the .json file too; this technically still exists but is optional (defaulting to enabled), and we're leaning away from doing enabling/disabling mods this way, with manual control of mount order being the preferred approach (see below). The mod will not be loaded if the json file does not exist, contains syntax errors, or if 'enabled' (optional) is set to false. NEW 12/9/2013: Everything below here is new. There was some stuff in the original post about file paths and shadowing and a proposed explicit "shadow" directory, but that introduced a lot of problems (e.g. Who are you shadowing? Only the original PA files? Other mods? How do you disambiguate them? Blah blah blah...). So we've gone with a simpler approach which should be more familiar to mod authors from other games: Mod Mounting, Adding and Shadowing Files PA operates under a single virtual file space rooted at '/'. By default, this is mapped to the PA media directory, e.g. "/pa/units/land/..." and "/ui/alpha/...". Mods directly stack on top of this virtual file space, and can either add new files, or shadow (replace) existing files, based on their file names. This means: If you intend to add new files with your mod, name those new files as uniquely as possible If you have a file under your mod at the same relative path as an existing PA (or previously mounted mod) file, you will effectively replace the previous file. e.g. If I have a mod at mods/zomg_metal, then mods/zomg_metal/pa/units/land/metal_extractor/metal_extractor.json will shadow (replace) the original media folder version of /pa/units/land/metal_extractor/metal_extractor.json. Because everything is stacked together, mods can shadow original PA files, or the files from other mods, based on their mount order and the file names they use. This means that care must be given to the order in which mods are mounted. In the root of the mods folder (as a peer to the individual mod folders themselves), you can optionally supply a file called mods.json. This file currently supports a single field "mount_order", containing an array of strings. These strings are the names of the identifier fields of the mods you want mounted, with the first entries taking precedence over later entries. For example: NEW 6/2/2014: The mods.json file is no longer optional. It is now necessary if you want your mods to be mounted. Code: { "mount_order": [ "com.somedomain.thismodgetsfirstdibs", "com.anotherdomain.nextinlineisthisone", "com.yetanotherdomain.yougettheidea", "*" ] } The last string in there is a "*" field, which is optional and says "mount any other mod folders here that I have available which I haven't mounted yet, and I don't care about the order for those". Not sure how practical that is, but I wanted to leave it open (it was helpful during debugging). We don't currently have any means of doing things like expressing explicit mod dependencies, automatic mount ordering of mods based on dependencies, version range checks, etc. I didn't bother implementing that yet because it's a very easy thing to get wrong, and wasn't critical to getting the launcher out the door. So more of that stuff will be coming in the future too, but it'll be added on top to what we're rolling out here. In the meantime, I'm expecting that community-driven mod manager utilities may want to support generation of the mods.json file mount_order, rather than having users have to hand-edit the thing. You all can let me know how realistic that is. Anyways, please experiment with this when the next build goes up, and let me know what you think (I'll edit this post when the build with this support goes live). Have any feedback? Need more details/examples? Just let me know! You're the community I'm writing this for, so I want to make sure it's doing what you need. - Chris
How does this effect the UI-mod system we have used so far? I.e. for PA Stats I currently have this link: http://www.nanodesu.info/stuff/pa/mods/live/pastats/pa_stats_loader.js directly as a global mod in the ui list. It enables me to modify all scenes of the game in a simple matter. Will the scene-array still be present? Will the ui mod list file still be present or where do I need to put that link to the script now?
The UI mod support that WJ added is somewhat independent of this; I haven't messed with that at all (at least not deliberately ). But the UI mod files themselves should go underneath mods/<modname>/ui/mods/..., rather than under the PA media tree's /ui/mods/ itself. That's the main purpose of this change; we're trying to get any mod-related files out of the media tree so that the new launcher can reliably manage its contents.
So the only change for UI mods is that the mod list file and the mods themself will move out of the PA directory? Good. What will happen to what users currently have in the mods directory? Will they be required to move it away by hand or will the new launcher take care of that? It sounds like the PA/ui/mods directoy basically should be empty with the new system. On another note: The new launcher seems to be pretty aggressive about owning that PA file tree. During mod development I often directly modify files, will that be prevented by the new launcher? Will the new launcher be mandatory or can I keep using my direct link to pa.exe?
I will bring up this here also. So in raevn's PAMM thread i brought up some stuff. The main one, the old system requires the ui_mods_list.js. It requires adding that file to /ui/mods and modifying it. If every mod tried to shadow that file you would have tons of different ones all conflicting each other. You would need to make a mod to load existing mods. by shadowing the ui_mods_list.js file.Then add all of the lines into that for all of your mods. Its a bit hackish for now at least to me. unless there were changes on that side of things that haven't been mentioned in these posts. So currently im planning on making a mod which nukes the ui_mods_list.js. Then adds values into the modinfo.json to compensate for that. So that all you would need to do to get a current ui mod going in the new system is add the proper scene into your modinfo.json, and the files to be loaded into it.
I haven't messed with the UI mod support at all; these changes I'm talking about are specifically for the purposes of getting mod files out of the PA install directories. The new launcher (which hasn't been deployed yet, but will be Real Soon Now) has strict control over that folder, and will delete or replace files that don't match its expectations (we need to do this because we've had a lot of issues with installed file mismatches under the old installer). So all the mods gotta get out of there. Once the files are outside of the PA install/media area and into the mods folder, then that problem will taken care of. Now if for UI purposes you all don't want to utilize that stacking feature and want to stick with a common sandbox to take advantage of the existing /ui/mods support (which is separate from this), that's perfectly fine, however that would mean there might need to be a single meta "mod" that hosts all of that, i.e. mods/<whateverthatUIsandboxmodiscalled>/ui/mods/... , or something like that. Maybe the same kind of mod manager that handles mods.json's mount_order could standardize on a good spot for that sandbox, but I'm just thinking out loud at this point. So yeah, don't think of this as a replacement for what you all are currently doing. It's just another axis of mod support; previously we didn't allow stacked replacement of files at all, and now we do. The UI mod support is separate, but the files involved there still have to fold into the mounting logic somehow, 'cause we need to get the files where the PA installer won't stomp them. Make sense?
So essentially, I just need to point the PA Mod Manager's output of ui_mod_list.js into a new "mod", and ensure that mod is always enabled, and UI mods should Just Work (tm)?
I think so, provided the various UI mod files are also included underneath that manager "mod" too, as mentioned above. If you try that in the next build and it doesn't work, let me know and we'll get it sorted out.
