Addon 'Packaging' Guide - File Structure and mod.cpp

[mordeaniischaos 3]

Why should I listen to you about how to package my addon?

I've downloaded a lot of addons in my days. I visit Armaholic multiple times a day and download and play with most of the stuff that catches my attention. And the one thing I've noticed, especially when trying to get less savvy players set up with addons, has been the lack of standards in addon "packaging." It's fairly small on it's face, but especially with updates and the already somewhat out of the way manner of installing stuff manually, it adds up. Especially when there's more than one "wrong" way addons get packaged. And I see a lot of addon creators not taking advantage of features to make the addon look more professional and being more recognizable in-game.

So I thought I'd write up a guide based on what I've learned from helping new players get onto our server.

A well packaged addon will make troubleshooting simpler for both the creator and the end user, which means less time telling people to "make an addons folder" and more time dealing with actual issues.

That said, I'm not claiming to be an expert and I'm sure I'll make a few mistakes in this but hopefully I can help clarify how addon data is handled based on my own understanding of it, and how to present your addon best.

What do I mean by packaging?

When I say packaging I am talking about the file structure that comes out of an archive. It's the end user's first interaction with the addon as a manual install requires, and with people who aren't used to installing addons it can be confusing when this is the file structure:

addonbyteam\teammascot\@addonname\addons\addon.pbo
// Or even worse (yes, I've really seen this)
addonbyteam\teammascot\addonnamev.1\addonname.pbo

This kind of thing is a little more common than you might think. Addons come with three layers of files that just unstack Russian stacking doll style and serve no point other than to make the user find the useful files and then delete the empty useless husk of folder. And there's no addons folder. And there's no @ to keep things organized in the ArmA 3 directory.

I suspect this comes largely from a lack of understanding on how various programs create archives and a lack of understanding of how this impacts people not intimately familiar with addons.

Getting the right file structure.

All it takes is preparation and knowledge of how both 7zip and ArmA 3 handle files.

Let's start with what you need to have to have a well packaged, standardized, easy to use addon for manual downloading. There will be a few different structures that make sense, and there are probably exceptions and additions I don't know about but I should be able to explain my system in such a way that adding or removing things is easy to do without changing the formula.

Here's the basic, correct file structure that works for me:

@Addonname\addons\addon.pbo

If done like this, without any additional files beyond the actual addon data, ArmA 3 will see this as long as it is in the ArmA 3 directory. By "see" it I mean you should be able to enable the addon through the expansions menu. Technically this isn't required, but it's the closest we have to a standard in the community and it works really well because it clearly marks addon folders and keeps them sorted together under most sorting modes for Explorer.

To get this to be the exact structure that comes from an archive, create that same file structure, right click on "@Addonname" and under 7zip click "Add to '@addonname.zip" or "@addonname.7z"' This is the simplest and easiest way to compress smaller addons. And makes a very easy to use file for the user. They can either unpack it where they downloaded it and just copy that top level folder without having to dig down, or they can unpack directly into steamapps\common\Arma 3.

A slightly less common, more complex structure is when an addon requires files that are outside of the @addonname folder. The most common of these is the "userconfig" data. This one is a bit tricky because there's never a consistent way of doing this "right" because different people unpack archives with different expectations. It is my belief that the safest most universal option is as follows:

addonname\@addonname\addons\addonname.pbo
        \userconfig\addonname

This means that no matter where the archive is unpacked, it's contained in "adddonname", which avoids the issue of "oops I unpacked this archive and now there are 3 files I don't know the name of scattered among my downloads." It can be tempting to use "ArmA 3" so people could just unpack to your steamapps\common directory and just merge automatically with your Arma 3 folder, but most people won't think to do that and as a result you'll have a generic file name which can mess up if someone else's addon has already been unpacked to downloads\Arma 3.

Or better yet, use the new CBA stuff that seems to reduce the need for userconfig usage, allowing you to use the simple structure.

For larger addons that are pushing over 150MB I would probably encourage getting more in-depth with your compression settings to insure a small archive. This makes uploading the addon and any further updates quicker and makes it much easier for users to download your addons. I've posted the settings I use to get very small file sizes at the bottom of this post.

Why is this structure standard important?

It's important to maintain a consistent structure, specifically this one, because it insure a minimal amount of knowledge on how addons work on the part of the end-user and ensures a high level of compatibility across various distribution sources. @Addonname\addons\addonname.pbo should work when acquired from Armaholic, Steam Workshop, PlayWithSix, etc. It also makes sure that the addon is readily compatible with the Expansions Menu. Some of us prefer this manual method but would like to avoid trying to change launch options every time we change addons. Don't knock the expansions menu!

How do you add neat features to make your addon show up in cool ways in the game?

Probably the coolest thing I discovered when making an "addon cocktail" for my group that puts all of the addons we use in one easily toggleable addon was the magical mod.cpp file. This is basically a text file that works a lot like a description.ext for your addon, mostly interacting with the Expansions menu and the main menu of Arma 3. This file is pretty simple to use and allows you to do things like show a proper name in the Expansions menu (instead of just showing the file name, for example it could be Addon Name V.1), show an icon, even give a link to a BI Forum Thread dedicated to your addon. This guide should cover all of the big stuff and a couple of little known touches that add to the presentation of your addon.

name = "Name";
// This is the name that shows up in the Expansions menu

picture = "picture.paa";
// This is the logo that shows up when the addon is selected on the Expansions menu. This will be a fairly large display of the logo, so I encourage an image approximately 512x512.

actionName = "actionName";
// This is the text that shows up on the extremely useful action button when you have an addon selected in the Expansions menu.

action = "http://www.google.com";
// This is the URL that the action button directs to. Link to a page that helps users keep up to date. I suggest your BI Forum Thread, which can link to all of your distribution methods from there.

logo = "logo.paa"; 
// This is the logo that shows on the main menu of ArmA 3 along the bottom. This is fairly small so I encourage you to at least downsample your logo so it looks better.

logoOver = "logoover.paa"; 
// This is the image that shows when you mouse over your logo on the menu. You can add a glow, a shadow, or any number of other effects. It gives it a more polished feel and is a neat effect.

tooltip = "tooltop"; 
// This is the text that pops up when you mouse over your logo in the menu

overview = "overview"; 
// This is the description of your addon as shows in the Expansions menu

author = "author";
// Doesn't seem to do anything at the moment. I just keep it there because it puts another mark on your addon. Pretty sure this used to show up somewhere...

Here's what all of that stuff looks like:

7zip high compression settings:

Hopefully that all helps out when you're releasing your addons.

And of course if anyone has any other tips, post them and I would be happy to implement them into the original post and credit whoever brings new tips to our attention :)

[da12thMonkey 1943]

Using class CfgMods inside your addon's config.cpp may be better than a mod.cpp if you're releasing works in a number of separate addons all under the same project banner (like several weapons as different downloads).

I'd imagine installing several mods with the same cfgMods classname would just overwrite that mods class with whatever parameters were written in the last addon to load, and it'd probably stop the menu screen showing tons of duplicate mod logos for the different folders each addon is installed in (each having a separate mod.cpp) when d/led via PWS or something.

[mordeaniischaos 3]

Using class CfgMods inside your addon's config.cpp may be better than a mod.cpp if you're releasing works in a number of separate addons all under the same project banner (like several weapons as different downloads).

I'd imagine installing several mods with the same cfgMods classname would just overwrite that mods class with whatever parameters were written in the last addon to load, and it'd probably stop the menu screen showing tons of duplicate mod logos for the different folders each addon is installed in (each having a separate mod.cpp) when d/led via PWS or something.

I agree, but for many, many addons this isn't needed and this is mostly a "basics" guide on how to get a functional, well presented addon bundled up in a user-friendly way. Even if you use cfgMods, many of the lessons in the guide are applicable I should think :)

And in my experience, addons don't tend to be split up like that very often. It certainly happens (see HLC as an example) but it's fairly rare, and this is more for getting the basics right anyway.

I'd be happy to try and do some digging but at the moment I'm not super familiar with CfgMods, which is why I didn't touch too much on it. But I believe it pretty much operates as the mod.cpp does, so that stuff in the guide should still be useful.

EDIT: This is untested and all, but this forum thread seems to suggest that you'd still want a mod.cpp for the Expansions menu. Or at least that that was the case with ArmA 2. And the cfgMods stuff may not work if the addon folder doesn't start with "@" which to me seems like a bit of a flaw, as that "@" keeps the ArmA directory nice and organized.

I'll look into cfgMods at some point to see if I can learn enough to add to the guide.