Creating Mods

What is 7th Heaven? | Getting Started | Using 7th Heaven | Creating Mods | FAQ/Troubleshooting
This section is to assist mod authors with supported tags and options that they can use in their mod.xml files for their mods. Mod.xml files specify how the mods should function, what files should be loaded, settings available for the mod, compatibility with other mods, and mod sort order. This section is not intended to teach you about the ins and outs of FF7's file/folder structure for modding, etc. You will have to research the Qhimm forums for that. It is intended to show the available functions of developing your mod to work best in 7th Heaven.

Contents:

Basic Mod.xml Features
Compatibility With Other Mods
Catalog Subscriptions

Basic Mod.xml Features

Mod Information: Your entire mod.xml code must be in the <ModInfo> tag, including the mod information, folders, settings, and compatibility. You can put comments in your mod.xml using standard XML formatting like .

ID: This is EXTREMELY IMPORTANT! You should specify a unique 32-character GUID that will identify your mod. This is so 7th Heaven and other mods know how to identify your mod for updates, sort order, compatibility, settings, etc. You can generate a new, random ID for your mod by opening the Catalog/Mod Creation Tool.
Name: Give your mod a name.
Author: The name of the author or authors of the mod.
Version: The version number of your mod in decimal type format x.xx.
ReleaseDate: The date your mod is/will be released in format YYYY-MM-DD.
Category: The category that your mod belogs to. Valid choices are Animations, Battle Models, Battle Textures, Field Models, Field Textures, Gameplay, Media, Minigames, Miscellaneous, Spell Textures, User Interface, World Models, World Textures. If you do not specify a category, 7th Heaven will categorize it as Unknown.
ReleaseNotes: These are notes for this specific release of your mod, such as "I added this new feature."
Link: The web address/URL for your mod, usually where users can find more information about your mod.
PreviewFile: The name of an image file that you want shown in the 7th Heaven UI in the Mod Info Panel.
Readme File: This isn't in the mod.xml file itself, but you can include a Readme.txt or a Readme.html file in the root of your mod folder and 7th Heaven will open it if the user clicks on the Readme link in the UI.

  
<?xml version="1.0"?>
<ModInfo>
  <ID>00000000-0000-0000-0000-000000000000</ID>
  <Name>My Awesome World Map Water Mod</Name>
  <Author>Some Person</Author>
  <Version>1.00</Version>
  <ReleaseDate>2019-12-25</ReleaseDate>
  <Category>World Textures</Category>
  <Description>Retextures for all water on the World Map.</Description>
  <ReleaseNotes>This is my first version!</ReleaseNotes>
  <Link>https://forums.qhimm.com/</Link>
  <PreviewFile>preview.gif</PreviewFile>
</ModInfo>

Mod Folders: Files needed for your mod should follow a folder structure. Each folder should be named so that you can easily identify them. You can manipulate which folders are active based on the mod settings you specify, or game conditions or other variables. 7th Heaven will check the mod paths in the order they're specified in its mod.xml file. The subfolders in your mod should follow the FF7 game folder structure. An example folder structure is below:

  
                    |- mymodfolder
                           |- mod.xml
                           |- menu_us.lgp
                                         |- cloud.tex
                                         |- earith.tex
                           |- sewer
                                         |- char.lgp
                                                 |- aaba.p
                           |- junon
                                         |- char.lgp
                                                 |- aaba.p
                           |- vgmstream
                                         |- fan2.ogg

To activate a subfolder in your mod based on a setting variable that you're using in 'Configure Mod', use <ModFolder Folder="NameOfSubFolder" ActiveWhen="MySetting = 1"/>. More on using the Configure Mod settings later.

  
<ModInfo>
  <ModFolder Folder="MyModFolder\ModSubFolder"  ActiveWhen="MySetting = 1" />
</ModInfo>

Conditional Folders: Conditional folders allow you to activate a folder of your mod when certain conditions are met, such as with runtime variables like a random number, counter, time, or game memory address. The below example is based on a mod with the folder structure as listed above in the 'Mod Folders' section.

  
<?xml version="1.0"?>
<ModInfo>
  <Conditional Folder="sewer">
    <RuntimeVar Var="Short:0xCC15D0:2" Values="0xD5,0x160" />
  </Conditional>
  <Conditional Folder="junon">
    <RuntimeVar Var="Short:0xDC08DC:2" Values="300..400" />
  </Conditional>
</ModInfo>

What this means, if you activate this mod:
1) cloud.tex and earith.tex always replace the files in menu_us.lgp
2) 7th Heaven will read a 2-byte value from a location in memory (0xCC15D0 - this is the 'FieldID' variable). If it becomes 0xD5 or 0x160 then the files in the 'sewer' folder will become active, and so aaba.p inside char.lgp will also be replaced.
3) 7th Heaven will also check memory location 0xDC08DC (this is the PPV variable). If it is in the range 300-400, then the 'junon' folder will become active and it will replace aaba.p inside char.lgp

If both conditions are true then the version of aaba.p from the 'sewer' folder is used, because it is listed first in the mod.xml file. If neither is true then the original version from the LGP file is used.
Note: Short:0xCC15D0:2 can be replaced with "FieldID" and Short:0xDC08DC:2 can be replaced with "PPV" as both of those memory locations are specified by default in the 7thHeaven.var file.

Config Options: Below is an example mod that has 2 options that you can configure for the mod. The first is a folder called 'HolidayOutfits' that contains models for the main characters that changes their clothing to holiday style outfits, say, a Barret Santa, Cait Sith Snowman, Tifa Elf, etc. This option is a 'bool' (on or off) <Type> toggle value. The second is an option that changes the in-game music to a set of tracks from different genres. This option is a 'List' <Type> which has 4 settings: Default, Dance, Pop, and Rock music which are selectable from a drop-down list. Depending on what settings the user has set, different options of your/this mod would apply to the game. The first option has 'PreviewFile' which will show a preview image (gif, jpg, or png) of the selected setting. The second option has 'PreviewAudio' which will display a 'Play' button where the user can hear a sample of the music (mp3 or ogg) that is selected. The default selection for the outfits is 0 or 'off', and the default value for the music selection is 3 or 'Rock'. All of the variable names you want to assign to these different config options are in the <ID> tag.

  
<?xml version="1.0"?>
<ModInfo>
  <ModFolder Folder="HolidayOutfits" ActiveWhen="outfits = 1" />
  <ModFolder Folder="MusicStyle\Dance\vgmstream" ActiveWhen="music = 1" />
  <ModFolder Folder="MusicStyle\Pop\vgmstream" ActiveWhen="music = 2" />
  <ModFolder Folder="MusicStyle\Rock\vgmstream" ActiveWhen="music = 3" />

  <ConfigOption>
    <Type>Bool</Type>
    <Default>0</Default>
    <ID>outfits</ID>
    <Name>Holiday Outfit Models</Name>
    <Description>This changes main characters outfits to Christmas style.</Description>
    <Option Value="0" Name="" PreviewFile="preview\hollyoff.jpg" />
    <Option Value="1" Name="" PreviewFile="preview\hollyon.jpg" />
  </ConfigOption>

  <ConfigOption>
    <Type>List</Type>
    <Default>3</Default>
    <ID>music</ID>
    <Name>Choose Music Style</Name>
    <Description>This lets you change the genre of music you hear in the game.</Description>
    <Option Value="0" Name="Default Game"/>
    <Option Value="1" Name="Dance" PreviewFile="preview\dance.ogg"/>
    <Option Value="2" Name="Pop" PreviewFile="preview\pop.ogg"/>
    <Option Value="3" Name="Rock" PreviewFile="preview\rock.ogg" />
  </ConfigOption>
</ModInfo>

Treeview Style: New in 7th Heaven 2.0! In addition to the regular list style, you can now show your mod settings in a grouped Treeview style. You will trigger the Treeview style by placing at least 3 equal signs '===' at the beginning of the Name of the config option. The ===Name=== will become the header/group of the treeview. This was designed this way to maintain full backwards compatibility with older 7th Heaven versions. Note: You CANNOT switch back and forth between list items and the treeview! It is ALL or NOTHING. Once you trigger the TreeView style, all Config Options must then have a header--a Parent/Child relationship. See example below.

  
    <ConfigOption>
    <Type>List</Type>
    <Default>0</Default>
    <ID>CharacterThemesHeader</ID>
    <Name>===Character Themes===</Name>
    <Description>Character Themes - Expand arrows on the left for track selection options.</Description>
    <Option Value="0" Name=""/>
  </ConfigOption>

  <ConfigOption>
    <Type>List</Type>
    <Default>1</Default>
    <ID>oggearis</ID>
    <Name>Aerith's Theme</Name>
    <Description>Plays during scenes with Aeris and Sephiroth in the Forgotten City and during the subsequent battle with Jenova-LIFE.</Description>
    <Option Value="0" Name="No Change" PreviewFile="off.png"/>
    <Option Value="1" Name="Default Mix" PreviewFile="on.png" PreviewAudio="\vgmstream\earis.ogg"/>
  </ConfigOption>

  <ConfigOption>
    <Type>List</Type>
    <Default>1</Default>
    <ID>oggbarret</ID>
    <Name>Barret's Theme</Name>
    <Description>Plays as the background to Sector 7 and the 7th Heaven after Cloud agrees to attack the Sector 5 Reactor.</Description>
    <Option Value="0" Name="No Change" PreviewFile="off.png"/>
    <Option Value="1" Name="Default Mix" PreviewFile="on.png" PreviewAudio="\vgmstream\barret.ogg"/>
  </ConfigOption>

  <ConfigOption>
    <Type>List</Type>
    <Default>1</Default>
    <ID>oggsid2</ID>
    <Name>Cid's Theme</Name>
    <Description>Plays when meeting Cid and during prominent scenes featuring him.</Description>
    <Option Value="0" Name="No Change" PreviewFile="off.png"/>
    <Option Value="1" Name="Default Mix" PreviewFile="on.png" PreviewAudio="\vgmstream\sid2.ogg"/>
  </ConfigOption>

    <ConfigOption>
    <Type>List</Type>
    <Default>0</Default>
    <ID>NextGroupHeader</ID>
    <Name>===Next Header===</Name>
    <Description>This is the start of the next group of options.</Description>
    <Option Value="0" Name=""/>
  </ConfigOption>

Mod Operators: You can add operators that change the behavior of when a mod folder becomes active. Supported operators are 'And', 'Or', and 'Not'. See examples below.

  
<!--The folder would be active if BOTH MySetting AND MySetting2 do NOT equal 1-->
        <ModFolder Folder="MyModSubFolder" >
         <ActiveWhen>
            <Not>
             <And>
              <Option>MySetting = 1</Option>
              <Option>MySetting2 = 1</Option>
             </And>
            </Not>
         </ActiveWhen>
      </ModFolder>

  
<!--The folder would be active if EITHER MySetting OR MySetting2 equal 1-->
        <ModFolder Folder="MyModSubFolder" >
         <ActiveWhen>
             <Or>
              <Option>MySetting = 1</Option>
              <Option>MySetting2 = 1</Option>
             </Or>
         </ActiveWhen>
      </ModFolder>

Compatibility With Other Mods

Mod Dependency: If your mod is dependent on another mod to be activated or deactivated in order to work properly, you can specify that in your mod.xml file in the Compatibility section/tag. If your mod requires another mod to be activated in order for yours to work properly, use the 'Require' tag. If your mod is completely incompatible with another mod, you can use the 'Forbid' tag. There is an optional 'Versions' parameter if one or more specific versions of the mod must be activated/deactivated. Note that 'Versions' targets specific versions, it is not a minimum version requirement. Example, if you specify 'Versions="1.0,3.0", that means the mod is dependent on versions 1.0 or 3.0 specifically. Version 2.0 will NOT be considered a dependency. If no 'Versions' parameter is specified, then version numbers are ignored and the dependency applies to ANY version of the mod.

  
  <!--Your mod REQUIRES that any version of the modID specified is activated-->
  <Compatibility>
    <Require ModID="00000000-0000-0000-0000-000000000000">Name of Other Mod</Require>
  </Compatibility>

  
  <!--Your mod FORBIDS that any version of the modID specified is activated-->
  <Compatibility>
    <Forbid ModID="00000000-0000-0000-0000-000000000000">Name of Other Mod</Forbid>
  </Compatibility>

  
  <!--Your mod FORBIDS that versions 1.0 and 2.0 of the modID specified is activated (but 3.0 would work)-->
  <Compatibility>
    <Forbid ModID="00000000-0000-0000-0000-000000000000" Versions="1.0,2.0">Name of Other Mod</Forbid>
  </Compatibility>

Mod Compatibility Settings: You can specify that if your mod has certain settings enabled, that other settings must also be set (either in your own mod or other mods) in order for them to be compatible with each other. This example shows that if your mod has a setting turned on 'MySettingVariable', that another mod (Qhimm Catalog 3.0 Minigames) must have its 'Wonder Square - Tweaks' setting set to 0. Instead of using the 'Require' tag, you can also use 'Forbid'. So for example, if a setting has 4 options in a drop down list and all of them except the value of 0 works fine with your mod, you would specify <Forbid>0</Forbid>. That way, all options are selectable EXCEPT 0. The 'ModID' can specify your own mod's mod ID, or another (external of your mod) mod's ID. So, you could specify that if a specific setting in your own mod is selected, that another option be forced to a specific setting in your own mod as well.

  
<!--This specifies that if MySettingVariable has a value of 1 that-->
<!--the Qhimm Catalog 3.0 Minigames mod must have Wonder Square turned off.-->
<!--Otherwise the 2 mods would be incompatible.-->
<Compatibility>
	<Setting>
	  <MyID>MySettingVariable</MyID>
	  <MyValue>1</MyValue>
	  <ModID>fae201ee-9fa5-4163-ab56-2b478111449d</ModID>
	  <TheirID>Wonder Square - Tweaks</TheirID>
	  <Require>0</Require>
	</Setting>
</Compatibility>

Mod Load Order: You can specify in your mod.xml file that your mod requires being above (Before) or below (After) other mod IDs in order to work correctly using the <OrderConstraints> tag. 7th Heaven 2.0's Auto Sort feature will take this into account when auto-sorting the mods. First, mods will be sorted by category, then alphabetically by name, then by the settings specified in the mod load order in mod.xml (AFTER is processed FIRST and BEFORE is processed SECOND). You can specify one or many mods at a time.
Note: OrderConstraints do NOT go inside the Compatibility tag (despite being in this section of the Help).

  
<!--Specifies that your mod should be placed below (After) the modIDs specified-->
  <OrderConstraints>
	<After>00000000-0000-0000-0000-000000000000</After>
	<After>00000000-0000-0000-0000-000000000001</After>
	<After>00000000-0000-0000-0000-000000000002</After>
  </OrderConstraints>

  
<!--Specifies that your mod should be placed above (Before) the modIDs specified-->
  <OrderConstraints>
	<Before>00000000-0000-0000-0000-000000000000</Before>
	<Before>00000000-0000-0000-0000-000000000001</Before>
	<Before>00000000-0000-0000-0000-000000000002</Before>
  </OrderConstraints>

Catalog Subscriptions

You can create basic Catalog Subscriptions using the Catalog/Mod Creation Tool.

Link Formats: 7th Heaven supports links in the below formats. Links will begin with iros:// then the link type. The :// in http:// is replaced with a $ symbol in all links.

GDrive: Google Drive links are in the format of iros://GDrive/FileID . If you generate a shareable link in Google Drive, it will look something like https://drive.google.com/file/d/1mX0q6Yb4cgYNYkAmd8ocSfGu0c2QHT0B/view?usp=sharing . You would take the section 1mX0q6Yb4cgYNYkAmd8ocSfGu0c2QHT0B as the File ID so your link would become iros://GDrive/1mX0q6Yb4cgYNYkAmd8ocSfGu0c2QHT0B .

MEGA: MEGA links are in the format of iros://MegaSharedFolder/folderID,fileID,fileName . FolderID is the shared folder ID string. Then specify EITHER the fileID OR the fileName. It is recommended to just use fileName because finding out the FileID is difficult. You can also use the MEGA Link Generator tab in the Catalog/Mod Creation Tool.

URL: Regular URL links are in the format of iros://Url/http$www.mydomain.com/myfile.iro .

ExternalURL: External URL links are in the format of iros://ExternalUrl/http$www.mydomain.com/myfile.iro . External links tell 7th Heaven to open the link external of 7th Heaven, in a web browser. This is useful if you have ad-supported links that you must use in order to download your mods when direct download links are unavailable.

Downloading Mods: When 7th Heaven downloads a mod from a catalog subscription, it expects one of the following:

An .IRO file: Simple, it is installed directly.
A ZIP/RAR/7Z file w/ IRO: Containing a SINGLE .iro file. The file is extracted and installed. This is useful so that your IRO is compressed (externally) to save bandwidth/transfer time.
A ZIP/RAR/7Z file w/ Files: Containing many other files (PNGs, TEXs, .....). So like a mod folder just zipped up. For this:
- if 'ExtractSubFolder' is set, it extracts only files from inside that particular folder inside the zip.
- if 'ExtractInto' is set, it extracts the files into this particular subfolder inside the mod directory.

ExtractSubFolder is useful if your ZIP contains files that are not useful for the mod and you only need some of the files from the ZIP.

ExtractInto is useful if your ZIP doesn't have the right folder structure for 7th Heaven. Like if your avatar files are just inside the ZIP with no folder names, you need to extract them into a folder called "menu_us.lgp" for 7th Heaven to work.

Patching Mods: If you've released a large mod and want to update it with a small .irop patch file (can be created with the IRO Tools in 7th Heaven), you can add a <Patch> entry in the catalog so people who already have the mod can update using the small .irop patch file. See the example below. New in 7th Heaven 2.2, you can distribute .IROP files outside of catalogs and users can double-click them or use the Import Mod feature to apply patches. You must make sure your IROP's mod.xml contains the mod ID so 7H knows which mod to target. Users must apply each patch one after the other in the correct order, otherwise the final mod will not contain all the data that was included in each patch. If your patch contains ALL data/changes needed to upgrade the mod from any previous version, then you do not need to worry about this.

  
    <Mod>
      <ID>BFAE987C-C1E6-42E6-8139-FF809142D72E</ID>
      <Author>Iros</Author>
      <Link>http://forums.qhimm.com/</Link>
      <Name>Test music/patching</Name>
      <MetaVersion>2</MetaVersion>
      <Description>Testing music in a IRO archive</Description>
      <Tags>
        <string>Music</string>
      </Tags>
      <LatestVersion>
        <Link>iros://Url/http$www.myserver.com/Music1.iro</Link>
        <Version>1.2</Version>
        <ReleaseDate>2014-09-04</ReleaseDate>
        <CompatibleGameVersions>Original</CompatibleGameVersions>
        <PreviewImage></PreviewImage>
        <ReleaseNotes></ReleaseNotes>
      </LatestVersion>
      <Patch VerFrom="1.0" VerTo="1.1">iros://Url/http$www.myserver.com/Music_0_to_1.irop</Patch>
      <Patch VerFrom="1.1" VerTo="1.2">iros://Url/http$www.myserver.com/Music_1_to_2.irop</Patch>
    </Mod>

Backup Links for Patches: New in 7th Heaven 2.2: You can specify more than 1 link for 7H to attempt to download patches from.

  
    <Mod>
      <ID>BFAE987C-C1E6-42E6-8139-FF809142D72E</ID>
      <Author>Iros</Author>
      <Link>http://forums.qhimm.com/</Link>
      <Name>Test music/patching</Name>
      <MetaVersion>2</MetaVersion>
      <Description>Testing music in a IRO archive</Description>
      <Tags>
        <string>Music</string>
      </Tags>
      <LatestVersion>
        <Link>iros://Url/http$www.myserver.com/Music1.iro</Link>
        <Version>1.2</Version>
        <ReleaseDate>2014-09-04</ReleaseDate>
        <CompatibleGameVersions>Original</CompatibleGameVersions>
        <PreviewImage></PreviewImage>
        <ReleaseNotes></ReleaseNotes>
      </LatestVersion>
      <Patch VerFrom="1.0" VerTo="1.1">iros://Url/http$www.myserver.com/Music_0_to_1.irop</Patch>
      <Patch VerFrom="1.0" VerTo="1.1">iros://Url/http$www.backupserver.com/Music_0_to_1.irop</Patch>
      <Patch VerFrom="1.1" VerTo="1.2">iros://Url/http$www.myserver.com/Music_1_to_2.irop</Patch>
      <Patch VerFrom="1.1" VerTo="1.2">iros://Url/http$www.backupserver.com/Music_1_to_2.irop</Patch>

<!--The below example works to specify multiple versions at once:-->
<Patch VerFrom="1.0,1.1" VerTo="1.2" DownloadSize="0">iros://Url/http$www.myserver.com/Music_1x_1.2.irop</Patch>
    </Mod>

Top of page