Making a mod package: Difference between revisions
m (→Package format 2.0: I'm pretty sure this is what was meant, but not 100% sure) |
m (Divhide makes the section unreachable from the TOC if it encloses the section header) |
||
Line 172: | Line 172: | ||
The folder ''plain/'' is for non-mod files, whether executables, text files, etc. Files/folders within "plain/[platform]/" are relative to the base folder of the AE, so this example would put the file in "AE/Tools/OniSplit.exe" on both platforms. | The folder ''plain/'' is for non-mod files, whether executables, text files, etc. Files/folders within "plain/[platform]/" are relative to the base folder of the AE, so this example would put the file in "AE/Tools/OniSplit.exe" on both platforms. | ||
==Package format 1.1 (deprecated)== | ==Package format 1.1 (deprecated)== | ||
{{Divhide|}} | |||
This is the format of package that was preferred by the Installer that came with the 2010-05 AE. Format 1.0 is not explicitly documented here, but the differences between 1.0 and 1.1 are summarized below; 1.0 was the format used for packages when the AE 2009-07 was released. | This is the format of package that was preferred by the Installer that came with the 2010-05 AE. Format 1.0 is not explicitly documented here, but the differences between 1.0 and 1.1 are summarized below; 1.0 was the format used for packages when the AE 2009-07 was released. | ||
Line 273: | Line 272: | ||
41000 - a mod that tweaks animations | 41000 - a mod that tweaks animations | ||
41100 - this mod might be related to mod 41000, or else you are just looking for another free number and | 41100 - this mod might be related to mod 41000, or else you are just looking for another free number and 42000, 43000 ... 48000, 49000 are taken | ||
41010 - probably someone's addition or improvement to mod 41000 | 41010 - probably someone's addition or improvement to mod 41000 |
Revision as of 17:38, 26 March 2015
The Anniversary Edition installs mods that are made in a certain format -- the mod files must be placed in a specified hierarchy of folders with a text file that provides additional information. This arrangement of folders and files is simply called the mod package format.
Package format 2.0
The AEI 2 prefers the new 2.0 package format, but will also read 1.1 packages.
You can start your package by copying an existing AE package and modifying it to save time. To create a new mod package from scratch, use Vago's package wizard or follow these seven easy steps:
1. Create a new folder with a name corresponding to your mod.
2. Pick a number for your mod. The five digit number corresponds to where in the load order your mod will be, but it also indicates the type of mod. Please leave some numeric space between your mod and other AE mods. See the numbering section below to know how to number your mod.
3. Create a plain-text file named "Mod_Info.cfg" inside your new folder. See section "Mod_Info.cfg" under the Mods or Tools section to learn what to put in the config file for that kind of package.
4. If you have .oni files in your mod, you make a folder named "oni" inside your package folder. If you have .bsl files, make a folder named "bsl". If you have XML patches (.oni-patch files), make a folder named "patches". If you have other kinds of files, place them in a folder called "plain" (this is done for tool packages, not mods). See section "Folder structure" under the Mods or Tools section for an illustration of the required hierarchy.
5. Make a folder called "common" inside the oni/, bsl/, patches/ or plain/ folder for files will work on both Windows and Intel Macs. Make a folder called "win_only" or "mac_only" if you have files intended for only one platform or if certain files need to be in one format for Windows and one for OS X (such as sounds).
6. If your mod modifies the AE's globalized data in level0_Final, make a "level0_Final" folder inside oni/, patches/, or plain/. For every level that your mod uses, make a "levelX_Final" (e.g. "level1_Final") folder inside oni/, patches/, or plain/. However, a BSL mod uses the names of the IGMD subfolders the script(s) will go into, e.g. a script that is meant for Chapter 1 goes in bsl/EnvWarehouse/. If you include a subfolder in oni/ that does not exist in AE Oni's GameDataFolder, or a subfolder in bsl/ that does not exist in AE Oni's GameDataFolder/IMGD/, the folder will be created, thus allowing a mod to add a a new level.
7. Put the appropriate types of files inside their respective levelX_Final/ directories. Check the section "Folder structure" again to make sure you did it right! Zip up the package. Make sure you use a zip program that respects the executable bit when packaging a tool. The name of the zip file does not matter to the AEI, as it will give it its own name based on the name you provide to the Oni Mod Depot when uploading.
Special note: Be very careful when replacing (not adding) M3GM, TRAC and OBAN. With TRAC, you must include all of the child TRACs of the TRAC you are adding. With M3GM, you must also include the file that references the M3GM. With OBANs, you need to include the AKEV that links to them. There may be other file types that need their parents or children included.
Mods
Mod_Info.cfg
AEInstallVersion -> 2.0 NameOfMod -> Improved Weapons Creator -> Geyser, Loser, Iritscen, Gumby ModVersion -> 1.1 IncompatibleWith -> 11100,23050 DependsOn -> 45000 UnlockLevel -> 25 Readme -> Improves the appearance and mechanics of existing Oni weapons. \n \n Currently contains...
- Explanation of fields
Entries marked with an asterisk (*) are only used if the mod is not yet listed on the Mod Depot. Otherwise, the AEI will display the versions of those fields that are found on the Depot's node for that mod.
- AEInstallVersion
- What version of the Installer is needed to read this package. Here are the functional package-handling differences between 2.0 and 1.1 packages:
- The BSL -> Addon flag is now respected properly.
- DependsOn and IncompatibleWith flags added for mod interoperability.
- Tools can now be placed in packages and installed like mods (using the new "plain" subdirectory).
- Many .oni files can now be altered by XML patch instructions (using the new "patches" directory).
- Packages now support both platforms at once (using "common", "mac_only" and "win_only" sub-directories).
- NameOfMod
- The "public" name of the mod. It can be anything you like, but should be written in an easily understandable manner *.
- ModVersion
- The version of the mod *.
- Creator
- The name(s) that you want to get credit for the mod *.
- Readme
- The read-me text. You can make linebreaks by using " \n " *.
- IncompatibleWith
- Package numbers of mods this mod will not work with at the same time. Multiple entries separated by ",".
- DependsOn
- Package numbers of mods this mod depends on to function. Multiple entries separated by ",".
- HasBSL
- If set to "Yes", the Installer considers your mod a scenario and takes steps to exclude other BSL scenario mods from being installed for the same level. If set to "Addon", the Installer allows your mod to be installed to any level without restriction. Of course not all third-party BSL add-ons are guaranteed to be compatible with each other, but this is an inherent risk in third-party modding. Mods with conflicting BSL files for a level should be listed in the IncompatibleWith field. If this tag is left out, "Yes" is assumed by default if the mod contains a "bsl/" folder.
- UnlockLevel
- If this mod adds a new level this flag allows to unlock that level in persist.dat. Multiple level numbers can be given separated by ",". Note that an ONLD for the new level must be supplied by the mod, or else it won't be displayed in the Load Game dialog.
Folder structure
Compared to the folder structure of AEI 1.1 packages, AEI 2.0 packages have one additional level of folders to allow one mod package to separate files by platform.
12345ExampleMod(.zip) Mod_Info.cfg oni/ common/ level#_Final/ *.oni win_only/ level#_Final/ *.oni mac_only/ level#_Final/ *.oni patches/ common/ level#_Final/ *.oni-patch win_only/ level#_Final/ *.oni-patch mac_only/ level#_Final/ *.oni-patch bsl/ common/ tctf_ii/ *.bsl win_only/ tctf_ii/ *.bsl mac_only/ tctf_ii/ *.bsl
Folders without content can be left out, so a basic mod with only level 0 .oni files for Mac OS X only will look like this:
12345ExampleMod Mod_Info.cfg oni/ mac_only/ level0_Final/ myFile.oni
Tools
Mod_Info.cfg
AEInstallVersion -> 2.0 NameOfMod -> OniSplit Creator -> Neo ModVersion -> 0.9.82.0 Readme -> Management of Oni's .dat files ExeName -> Tools/OniSplit.exe ExeType -> DotNet WorkingDir -> Base IconName -> Tools/MyIcon.png
- Explanation of fields
Entries marked with an asterisk (*) are only used if the mod is not yet listed on the Oni Mod Depot, otherwise the AEI will display the version of those fields that is found on the mod's Depot node.
- AEInstallVersion
- What version of the Installer is needed to read this package. All tool packages must say "2.0", as earlier AE Installers did not support tool packages.
- NameOfMod
- The "public" name of the mod. It can be anything you like, but should be written in an easily understandable manner *.
- ModVersion
- The version of the mod *.
- Creator
- The name(s) that you want to get credit for the mod *.
- Readme
- The read-me text. You can make linebreaks by using " \n " *.
- ExeName
- Path to the executable file if it should be added to the Tools menu of the AEI. Probably mostly useful for GUI-based tools. Do not forget to add the path to the file in relation to the AE/ folder. (Optional tag)
- ExeType
- Type of the executable. Important if the executable has to be run by a specific interpreter like .Net. Can be either one of:
- OSBinary - Normal binary which can be executed by itself (assumed by default)
- WinExe - Normal Windows executable (.exe) - only supported for Windows only packages (assumed if ExeName ends in ".exe" and ExeType is not given as DotNet)
- DotNet - .Net binary, executed by MS.NET on Windows, Mono on Mac OS X and Linux
- Jar - Java .jar archive (assumed if ExeName ends in ".jar")
- WorkingDir
- Specify the working directory for the executable specified by ExeName. Can be either one of:
- Base - Working directory is the AE/ folder (assumed by default)
- Exe - Working directory is the folder where the executable is located
- GDF - Working directory is GameDataFolder/
- IconName
- Path to an icon for the AEI Tools menu. Must be in PNG format and between 16x16 and 32x32 in size. If not specified, no icon will be used.
Folder structure
00000OniSplit(.zip) Mod_Info.cfg plain/ common/ Tools/ OniSplit.exe win_only/ mac_only/
The folder plain/ is for non-mod files, whether executables, text files, etc. Files/folders within "plain/[platform]/" are relative to the base folder of the AE, so this example would put the file in "AE/Tools/OniSplit.exe" on both platforms.
Package format 1.1 (deprecated)
This is the format of package that was preferred by the Installer that came with the 2010-05 AE. Format 1.0 is not explicitly documented here, but the differences between 1.0 and 1.1 are summarized below; 1.0 was the format used for packages when the AE 2009-07 was released.
Mod_Info.cfg
AEInstallVersion -> 1.1 NameOfMod -> Improved Weapons ModVersion -> 1.1 Category -> AE: Weapons Creator -> Geyser/Loser/Iritscen/Gumby HasOnis -> Yes Readme -> Improves the appearance and mechanics of existing Oni weapons. \n \n Currently contains...
- AEInstallVersion
- What version of the Installer is needed to read this package (choices are 1.0 and 1.1). 1.0 is deprecated, but for the sake of thorough documentation, here are the functional package-handling differences between the versions:
- Now supports BSL mods. This means that the HasBSL flag now works. See step 7.
- No more division of level0_Final into level0_Character, level0_Textures, etc., and no more need for a double-path like level1_Final/level1_Final. See step 5.
- ModString is now deprecated in place of ModVersion.
- Supports floating-point version numbers, like "ModVersion -> 1.1".
- Supports platform-specific mods by use of Platform flag.
- NameOfMod
- The "public" name of the mod. It can be anything you like, but should be written in an easily understandable manner, since it is displayed for the user in the Installer.
- ModVersion
- The version of the mod; tells the Installer if you are using the most current version when updating.
- Creator
- The name(s) that you want to get credit for the mod, displayed to the user in the Installer.
- HasOnis
- Set this to "Yes" to tell the Installer that .oni files are present.
- HasBsl
- If set to "Yes", the Installer considers your mod a scenario and takes steps to exclude other BSL scenario mods from being installed for the same level. If set to "Addon", the Installer allows your mod to be installed to any level without restriction. Of course not all third-party BSL add-ons are guaranteed to be compatible with each other, but this is an inherent risk in third-party modding.
- Platform
- If set to "Windows", mod is not listed in the Installer window on the Macintosh. If set to "Macintosh", mod is ignored on Windows.
- Readme
- The read-me text displayed for the user in the Installer. You can make linebreaks by using " \n ".
Flags not documented here are currently ignored by the Installer.
You are done! Sample mod directory:
Folder structure
81000TCTF3
- bsl
- tctf_ii
- tctf_ii_cutscene.bsl
- tctf_ii
- Mod_Info.cfg
- oni
- level0_Final
- SUBTmessages.oni
- level18_Final
- BINACJBOCharacter.oni
- level0_Final
Package numbering
So, how do you pick a number for your mod? Here's the ranges which are recommended. The numbers help keep things organized, as well as determine the order in which the mods are installed, but your mod will probably work correctly even if you don't pick a number from the right range -- unless you pick a number below 10000, which has special meaning for the AE Installer.
0 - 7999 | Reserved for core AE mods |
8000 - 9999 | Reserved for tool packages |
10000 - 19999 | Weapons |
20000 - 29999 | Characters |
30000 - 39999 | Particles |
40000 - 49999 | Animations (non-combat) |
50000 - 59999 | Animations (combat) |
60000 - 69999 | Sounds, Music |
70000 - 79999 | UI (menu screens, HUD, etc.) |
80000 - 89999 | New levels (and new textures for existing levels) |
90000 - 99999 | Scenarios (BSL mods for other people's levels) |
Once you know which range to use, you should use the remaining digits to number your mod in a way that fits in with the other mod packages. For example, here's some hypothetical package numbers and what they tell you about the package:
41000 - a mod that tweaks animations
41100 - this mod might be related to mod 41000, or else you are just looking for another free number and 42000, 43000 ... 48000, 49000 are taken
41010 - probably someone's addition or improvement to mod 41000
41001 - must be an addition or improvement for mod 41000, or why else would they be numbered so closely?
Okay, so now you get the idea, but how do you know which numbers are free? Click here to see all used numbers on the Depot. You can also check the number by entering it into Vago's package creation wizard and clicking the Check button, and it will automatically check it for you.