Making a mod package: Difference between revisions

From OniGalore
Jump to navigation Jump to search
m (→‎Package numbering: modder must use five digits)
 
(22 intermediate revisions by the same user not shown)
Line 1: Line 1:
__TOC__
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.
 
The Anniversary Edition comes with a set of mods in the "package" format. This new framework also allows modders to make third-party mods that will install easily into the Edition. You can start your package by copying an existing AE package and modifying it to save time.


==Package format 2.0==
==Package format 2.0==
The [[AEI]] 2 prefers the new 2.0 package format, but will also read 1.1 packages.
The [[AEI]] 2 prefers the new 2.0 package format, but will also read 1.1 packages.


To create a new mod package from scratch, follow these [[seven]] easy steps:
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 (tool)|Vago's]] package wizard or follow these [[seven]] easy steps:


1. Open up your AE/install/packages/ folder.
1. Create a new folder with a name corresponding to your mod.
----
----
2. Create a new folder with a name corresponding to your mod. No spaces, please. The five digit number in front corresponds to where in the load order you want your mod to be. Please, leave some space between your mod and other AE mods. See the [[#Package numbering|numbering section below]] to know how to number 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 [[#Package numbering|numbering section below]] to know how to number your mod.
----
----
3. Create (or copy) a config file named "Mod_Info.cfg" inside your new folder (see section "Mod_Info.cfg" below).
3. Create a plain-text file named "Mod_Info.cfg" inside your new folder.  See section "Mod_Info.cfg" under the [[#Mods|Mods]] or [[#Tools|Tools]] section to learn what to put in the config file for that kind of package.
----
----
4. If you have .oni files, make a folder named "oni" inside your package folder. If you have .bsl files, make a folder named "bsl" inside the package folder. If you have XML patches (.oni-patch files), make a folder named "patches" inside the package folder.
4. If you have [[OniSplit|.oni]] files in your mod, you make a folder named "oni" inside your package folder. If you have [[BSL|.bsl]] files, make a folder named "bsl". If you have [[Making a patch mod|XML patches]] (.oni-patch files), make a folder named "patches". If you have other kinds of files, place them in a folder called "plain" and then a subfolder with the name of a folder under the AE/ directory for the files to be copied into (this is generally only done by tool packages, not mods). See section "Folder structure" under the [[#Mods|Mods]] or [[#Tools|Tools]] section for an illustration of the required hierarchy.
----
----
5. Make a folder called "common" inside the oni/, bsl/, or patches/ folders if your mod will work on both Windows and Mac OS X. 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.
5. Make a folder called "common" inside the oni/, bsl/, patches/ or plain/ folder for files which will work both in Windows and on 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 macOS (such as sounds).
----
----
6. If your mod modifies the global data in level0_Final, make a "level0_Final" folder inside "oni" or "patches". For every level that your mod uses, make a "levelX_Final" folder inside "oni" (level1_Final, level2_Final, etc...). 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/".
6. If your mod alters data which the AE globalizes into level0_Final, make a "level0_Final" folder inside oni/ or patches/. For every level that your mod uses, make a "levelX_Final" (e.g. "level1_Final") folder inside oni/ or patches/. However, a BSL mod uses the names of the IGMD subfolder(s) that 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" below to make sure you did it right!
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 preserves the executable bit when packaging a tool. The name of the ZIP file does not matter to the AEI; after it downloads and expands the .zip on the user's computer, it will title the expanded folder using the text you entered in the "Mod name" field when uploading the mod to the {{OMD}}.


'''Special note''': Be very careful when replacing (not adding) M3GM, TRAC and OBAN. With TRAC, you must include all of the children 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.
'''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===
===Mods===
==== Mod_Info.cfg ====
====Mod_Info.cfg====
  AEInstallVersion -> 2.0
  AEInstallVersion -> 2.0
  NameOfMod -> Improved Weapons
  NameOfMod -> Improved Weapons
Line 36: Line 34:


;Explanation of fields
;Explanation of fields
Entries marked with an asterisk ('''*''') are only used if the mod is not yet listed on the {{OMD}}. Otherwise, the AEI will display the versions of those fields that are found on the Depot's node for that mod.
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'''
; '''AEInstallVersion'''
: What version of the Installer is needed to read this package.
: 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.
*.oni files which can be exported to XML can now have individual elements altered using patch files or scripts, in order to allow multiple mods to affect the same resources.
*A single package can now support both platforms at once (using "common", "mac_only" and "win_only" sub-directories).


; '''NameOfMod'''
; '''NameOfMod'''
: The "public" name of the mod. It can be anything you like, but should be written in an easily understandable manner '''*'''.
: The "public" name of the mod. This should be more or less identical to whatever you entered in the "Mod name" field when uploading this mod to the Depot '''*'''.


; '''ModVersion'''
; '''ModVersion'''
Line 51: Line 54:


; '''Readme'''
; '''Readme'''
: The read-me text. You can make linebreaks by using " \n " '''*'''.
: The read-me text. You can make line breaks by using " \n " '''*'''.


; '''IncompatibleWith'''
; '''IncompatibleWith'''
: Package numbers of mods this mod will not work with at the same time. Multiple entries separated by ",".
: Package numbers of mods which this mod will not work with if they are installed at the same time. Multiple entries separated by ",".


; '''DependsOn'''
; '''DependsOn'''
: Package numbers of mods this mod depends on to function. Multiple entries separated by ",".
: Package numbers of mods that this mod requires in order to function. Multiple entries separated by ",".


; '''HasBSL'''
; '''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.
: If set to "Yes" (or if this field is not supplied at all but your mod contains a bsl/ folder), the Installer considers your mod a standalone scenario and excludes other mods with bsl/ folders from being installed to the same level. The major limitation with BSL mods is that you cannot mix two mods containing .bsl files with the same names and expect any kind of good result, which is why the AEI will normally prevent these mods from combining or overwriting each other. However if you set the ''HasBSL'' field to "Addon", your mod will be treated as an addition to existing level scripts (vanilla or mod-originated). You are then responsible for listing any conflicting mods (ones for which your mod cannot be an addon) in the ''IncompatibleWith'' field.


; '''UnlockLevel'''
; '''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 ",".
: If the mod adds a new level, this flag allows you to unlock that level in [[persist.dat]] so the player can access it on the Load Game screen. Multiple level numbers can be given separated by ",". Note that an [[ONLD]] for a new level must be supplied by the mod, or else it won't be displayed in the Load Game dialog.


==== Folder structure ====
====Folder structure====
Compared to the folder structure of AEI 1.1 packages, AEI 2.0 packages have one additional level of folders within the oni/ and bsl/ folders to allow one mod package to support both platforms. So if a mod contains sounds for Windows and Mac OS X, you put the OS-specific files within the appropriate folder, win_only/ or mac_only/. Furthermore, we now have the ability to add XML patches. Those have to go to the appropriate folder within patches/.
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. Note that, for mods, the "plain/" directory can only contain a GameDataFolder/ subfolder; mods are not allowed to place files outside this directory.


  12345ExampleMod(.zip)
  12345ExampleMod(.zip)
Line 90: Line 93:
             level''#''_Final/
             level''#''_Final/
                 *.oni-patch
                 *.oni-patch
    plain/
        common/
        win_only/
            GameDataFolder/
                intro.bik
        mac_only/
            GameDataFolder/
                intro.mov
     bsl/
     bsl/
         common/
         common/
Line 101: Line 112:
                 *.bsl
                 *.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:
Folders without content can be left out, so a basic mod that only modifies level 0 and only works on Macs will look like this:
  12345ExampleMod
  12345ExampleMod
     Mod_Info.cfg
     Mod_Info.cfg
Line 109: Line 120:
                 myFile.oni
                 myFile.oni


=== Tools ===
===Tools===
==== Mod_Info.cfg ====
====Mod_Info.cfg====
  AEInstallVersion -> 2.0
  AEInstallVersion -> 2.0
  NameOfMod -> OniSplit
  NameOfMod -> OniSplit
Line 125: Line 136:


; '''AEInstallVersion'''
; '''AEInstallVersion'''
: What version of the Installer is needed to read this package.
: 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'''
; '''NameOfMod'''
Line 140: Line 151:


; '''ExeName'''
; '''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)
: 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.


; '''ExeType'''
; '''ExeType'''
: Type of the executable. Important if the executable has to be run by a specific interpreter like .Net. Can be either one of:
: Type of the executable. Important if the executable has to be run by a specific interpreter like .NET. Allowed values are:
:: ''OSBinary'' - Normal binary which can be executed by itself (assumed by default)
:: ''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'')
:: ''WinExe'' - Normal Windows executable (.exe); only supported for Windows-only packages (the AEI assumes this is the type 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
:: ''DotNet'' - .NET binary, executed by the .NET Framework on Windows and by Mono in macOS and Linux
:: ''Jar'' - Java .jar archive (assumed if ''ExeName'' ends in ".jar")
:: ''Jar'' - Java .jar archive (assumed if ''ExeName'' ends in ".jar")


; '''WorkingDir'''
; '''WorkingDir'''
: Specify the working directory for the executable specified by ''ExeName''. Can be either one of:
: Specify the working directory for the executable specified by ''ExeName''. Allowed values are:
:: ''Base'' - Working directory is the AE/ folder (assumed by default)
:: ''Base'' - Working directory is the AE/ folder (assumed by default)
:: ''Exe'' - Working directory is the folder where the executable is located
:: ''Exe'' - Working directory is the folder where the executable is located
Line 156: Line 167:


; '''IconName'''
; '''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.
: Path to an icon for the [[AEI#Tools|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 ====


====Folder structure====
  00000OniSplit(.zip)
  00000OniSplit(.zip)
     Mod_Info.cfg
     Mod_Info.cfg
Line 169: Line 179:
         mac_only/
         mac_only/


The folder ''plain/'' is for files not related to mods. Files/folders within "plain/[platform]/" are relative to the base folder of the AE, so the example would put the file in "$VanillaOni/AE/Tools/OniSplit.exe" on both platforms.
The folder "plain/" is for files that are not game data or BSL, such as 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. Note that while "plain/" can be used for mod packages too, only files placed in a subfolder called GameDataFolder/ will actually be moved to that location, as mods are not allowed to install files outside that directory.
 
==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.


{{Divhide|Package format 1.1 (deprecated)}}
===Mod_Info.cfg===
===Mod_Info.cfg===
  AEInstallVersion -> 1.1
  AEInstallVersion -> 1.1
Line 182: Line 195:


:;'''AEInstallVersion'''
:;'''AEInstallVersion'''
:What version of the Installer is needed to read this package (choices are 1.0 and 1.1). 1.0 is [[wikipedia:deprecated|deprecated]], but for the sake of thorough documentation, here are the functional package-handling differences between the versions:
:What version of the Installer is needed to read this package (choices are 1.0 and 1.1). 1.0 is [[wikipedia:Deprecation#Software|deprecated]], but for the sake of thorough documentation, here are the functional package-handling differences between the versions:
::1.0 (Edition 2009-07): Initial release.
::*Now supports BSL mods. This means that the HasBSL flag now works. See step 7.
::1.1 (Edition 2010-05):
::*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.
:::*Now supports BSL mods. This means that the HasBSL flag now works. See step 7.
::*ModString is now deprecated in place of ModVersion.
:::*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.
::*Supports floating-point version numbers, like "ModVersion -> 1.1".
:::*ModString is now deprecated in place of ModVersion.
::*Supports platform-specific mods by use of Platform flag.
:::*Supports floating-point version numbers, like "ModVersion -> 1.1".
:::*Supports platform-specific mods by use of Platform flag.


:;'''NameOfMod'''
:;'''NameOfMod'''
Line 216: Line 227:
You are done!  Sample mod directory:
You are done!  Sample mod directory:


===Folder structure===
81000TCTF3
81000TCTF3
:bsl
:bsl
Line 229: Line 241:


==Package numbering==
==Package numbering==
So, how do you pick a number for your mod? Here's how you pick the first of the five digits (numbers with less than/more than five are reserved for the AE):
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.
 
{|border="0"
'''10000s - Weapons'''
|-
 
| style="text-align:right"|'''0 -'''
'''20000s - Characters'''
| style="text-align:right"|'''7999'''
 
|'''Reserved for [[Anniversary Edition/Core|core AE mods]]'''
'''30000s - Particles'''
|-
 
| style="text-align:right"|'''8000 -'''
'''40000s - Animations (non-combat)'''
| style="text-align:right"|'''9999'''
 
|'''Reserved for tool packages'''
'''50000s - Animations (combat)'''
|-
 
|'''10000 -'''
'''60000s - Sounds'''
|'''19999'''
 
|Weapons
'''70000s - UI (new menu screens, HUD, etc.)'''
|-
 
|'''20000 -'''
'''80000s - New levels (and new textures for existing levels)'''
|'''29999'''
 
|Characters, new textures for existing levels and characters
'''90000s - Scenarios (BSL mods for other people's levels)'''
|-
 
|'''30000 -'''
Once you know which digit to start with, 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:
|'''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
|-
|'''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
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 42-4900 are taken
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
Line 259: Line 298:
41001 - must be an addition or improvement for mod 41000, or why else would they be numbered so closely?
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 [http://mods.oni2.net/mods/Package?order=field_package_number&sort=asc here] to see all used numbers on the Depot. You can also check the number inserting it in [http://mods.oni2.net/node/247 Vago] (from v0.7) AEI2 package creation wizard and clicking the Check button, and it will automatically check it for you.
Okay, so now you get the idea, but how do you know which package numbers are free? Click [http://mods.oni2.net/mods/Package?order=field_package_number&sort=asc here] to see all used numbers on the Depot. You can also check the number by entering it into [[Vago (tool)|Vago's]] package creation wizard and clicking the Check button, and it will automatically check it for you. To see which level numbers (as in "levelX_Final") have been used already by new fan-made levels, see [[Creating a level#Fan-made levels|HERE]].


[[Category:Modding tutorials]]
[[Category:Modding tutorials]]

Latest revision as of 19:12, 10 November 2023

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" and then a subfolder with the name of a folder under the AE/ directory for the files to be copied into (this is generally only done by 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 which will work both in Windows and on 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 macOS (such as sounds).

6. If your mod alters data which the AE globalizes into level0_Final, make a "level0_Final" folder inside oni/ or patches/. For every level that your mod uses, make a "levelX_Final" (e.g. "level1_Final") folder inside oni/ or patches/. However, a BSL mod uses the names of the IGMD subfolder(s) that 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 preserves the executable bit when packaging a tool. The name of the ZIP file does not matter to the AEI; after it downloads and expands the .zip on the user's computer, it will title the expanded folder using the text you entered in the "Mod name" field when uploading the mod to the Oni Mod Depot.

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.
  • .oni files which can be exported to XML can now have individual elements altered using patch files or scripts, in order to allow multiple mods to affect the same resources.
  • A single package can now support both platforms at once (using "common", "mac_only" and "win_only" sub-directories).
NameOfMod
The "public" name of the mod. This should be more or less identical to whatever you entered in the "Mod name" field when uploading this mod to the Depot *.
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 line breaks by using " \n " *.
IncompatibleWith
Package numbers of mods which this mod will not work with if they are installed at the same time. Multiple entries separated by ",".
DependsOn
Package numbers of mods that this mod requires in order to function. Multiple entries separated by ",".
HasBSL
If set to "Yes" (or if this field is not supplied at all but your mod contains a bsl/ folder), the Installer considers your mod a standalone scenario and excludes other mods with bsl/ folders from being installed to the same level. The major limitation with BSL mods is that you cannot mix two mods containing .bsl files with the same names and expect any kind of good result, which is why the AEI will normally prevent these mods from combining or overwriting each other. However if you set the HasBSL field to "Addon", your mod will be treated as an addition to existing level scripts (vanilla or mod-originated). You are then responsible for listing any conflicting mods (ones for which your mod cannot be an addon) in the IncompatibleWith field.
UnlockLevel
If the mod adds a new level, this flag allows you to unlock that level in persist.dat so the player can access it on the Load Game screen. Multiple level numbers can be given separated by ",". Note that an ONLD for a 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. Note that, for mods, the "plain/" directory can only contain a GameDataFolder/ subfolder; mods are not allowed to place files outside this directory. 

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
    plain/
        common/
        win_only/
            GameDataFolder/
                intro.bik
        mac_only/
            GameDataFolder/
                intro.mov
    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 that only modifies level 0 and only works on Macs 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.
ExeType
Type of the executable. Important if the executable has to be run by a specific interpreter like .NET. Allowed values are:
OSBinary - Normal binary which can be executed by itself (assumed by default)
WinExe - Normal Windows executable (.exe); only supported for Windows-only packages (the AEI assumes this is the type if ExeName ends in ".exe" and ExeType is not given as DotNet)
DotNet - .NET binary, executed by the .NET Framework on Windows and by Mono in macOS and Linux
Jar - Java .jar archive (assumed if ExeName ends in ".jar")
WorkingDir
Specify the working directory for the executable specified by ExeName. Allowed values are:
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 files that are not game data or BSL, such as 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. Note that while "plain/" can be used for mod packages too, only files placed in a subfolder called GameDataFolder/ will actually be moved to that location, as mods are not allowed to install files outside that directory.

Package format 1.1 (deprecated)

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, new textures for existing levels and 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
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 package 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. To see which level numbers (as in "levelX_Final") have been used already by new fan-made levels, see HERE.

Retrieved from "https://wiki.oni2.net/w/index.php?title=Making_a_mod_package&oldid=41523"