OIV Package version 1.1 must be a ZIP archive without password, the compression level is not important. Only "Stored" and "Deflate" compression methods are supported.
List of the files and folders inside package archive:
| Name | Type | Required | Description |
|---|---|---|---|
| assembly.xml | XML File | Yes | The main package file, contain metadata and content description. |
| icon.png | PNG Image | Optional | The icon representing this mod. Must be exactly 32x32 (px) size. |
| content | Folder | Yes | Folder with files of mod. |
Root node must be named "package" and have required "version" attribute. The "package" node must have "metadata" and at least one "content" node.
<?xml version="1.0" encoding="UTF-8"?>
<package version="1.1">
<metadata>
...
</metadata>
<content>
...
</content>
</package>The metadata node is contain information about package author, target platforms and package description.
<metadata>
<name>Package name</name>
<author>Author name</author>
<target>
<game>GameId</game>
<game>GameId</game>
<game>GameId</game>
</target>
<description>Short description</description>
<largeDescription displayName="Custom title" link="http://openiv.com/" linkTitle="More information">
<![CDATA[Large description]]>
</largeDescription>
<licence link="http://openiv.com/" linkTitle="Read more online" >
<![CDATA[Licence test]]>
</licence>
</metadata>| Name | Type | Required | Description |
|---|---|---|---|
| name | String | Yes | Package name. |
| author | String | Yes | Package author name. |
| target | List | Yes | List of games supported by this package. OpenIV GameId is used to specify the game. Each game id must be in its own game node. |
| description | String | Yes | Short test description of the package. About 110 char long. No line breaks. |
| largeDescription | CData | Optional | Long description. No length limitation. Line breaks can be used. Text must be wrapped in xml CDATA node. |
| licence | CData | Optional | Mod licence. No length limitation. Line breaks can be used. Text must be wrapped in xml CDATA node. |
List of games with associated IDs:
| Game | OpenIV GameId |
|---|---|
| Grand Theft Auto IV | IV |
| Episodes from Liberty City | EFLC |
| Max Payne 3 | Payne |
Example:
<largeDescription displayName="Custom title" link="http://example.com/" linkTitle="More information">
<![CDATA[Sample text.
Sample text.
Sample text after two line breaks.]]>
</largeDescription>- Attributes
- displayName – Optional display name of the description. For example: "Description", "Version history", "Mods by me" etc.
- link – Optional link, for example, it can be a link to author’s web site or social media.
- linkTitle – Optional display title for the link. For example: "More info", "My twitter" etc.
Example:
<licence displayName="Custom title" link="http://example.com/" linkTitle="More information">
<![CDATA[Sample text.
Sample text.
Sample text after two line breaks.]]>
</licence>- Attributes
- displayName – Optional display name of the licence.
- link – Optional link, for example can be used to link to authors web site or social media.
- linkTitle – Optional display title for link.
<metadata>
<name>Test Package (OIV 1.1)</name>
<author>OpenIV Team</author>
<target>
<game>IV</game>
<game>EFLC</game>
<game>Payne</game>
</target>
<description>Text test description, first line. We can use no line breaks. This is second line, max we can have here.</description>
<largeDescription displayName="Custom title" link="http://openiv.com/" linkTitle="More information">
<![CDATA[This is multiline optional additional description. You can use line breaks here.
The "displayName" attribute is control how the section names, this is optional. The default name is "Description".
Feel free to write here any information you like.
Like version info, restore and backup info, etc.
You also can use "link" and "linkTitle" attributes to make clickable links. Both attributes are optional.]]>
</largeDescription>
<licence link="http://openiv.com/" linkTitle="Read more online" >
<![CDATA[If you want to add any legal information, you can use optional "licence" tag.
It also support "link" and "linkTitle" attributes for clickable link.
Usually license test are long and unclear.
So this text is long and unclear.
Yeah, this is very long and very annoying text about some stuff and you probably will never read it.
See. There is even more text. The following text is generated online:
Every creepeth, creature thing good day you'll bearing, light let. Forth. They're to lights called kind over also. Lesser, for. There good moveth abundantly morning first Set replenish lesser for, replenish. His spirit bearing Is blessed over won't sea thing light can't fourth. You'll in don't them was firmament don't two. It, saw own very their form. Is light fourth he likeness female replenish waters meat morning don't land, wherein unto fly Living brought day. Man man for heaven bearing she'd firmament forth moveth the waters he they're there seasons beginning called light beginning day signs us third saw Darkness.]]>
</licence>
</metadata><metadata>
<name>Test Package (OIV 1.1)</name>
<author>OpenIV Team</author>
<target>
<game>IV</game>
</target>
<description>Text test description, first line. We can use no line breaks. This is second line, max we can have here.</description>
</metadata>The content node describes files which will be affected with installation of this package. There must be at least one content node for each GameId, specified as a target. Package can include more than one content blocks for each game.
<content gameID="GameId" name="Action" description="Short description">
...
</content>| Name | Type | Required | Description |
|---|---|---|---|
| gameID | String | Yes | OpenIV Game Id. |
| name | String | Yes | Name of the content block. |
| description | String | Yes | Short description of content. |
Here is few examples of content node:
<content gameID="IV" name="Install" description="Install this test package now">
...
</content>
<content gameID="EFLC" name="Install" description="Install this test package now">
...
</content>
<content gameID="Payne" name="Install" description="Install this test package now">
...
</content><content gameID="IV" name="Replace police" description="Install this car as Police">
...
</content>
<content gameID="IV" name="Replace police2" description="Install this car as Police2">
...
</content>The "content" node contain some kind of script commands for manipulation with files, archives and text lines.
To add or replace files in game folder "add" or "replace" commands must be used. It is does not matter which command you will use, both "add" and "replace" do the exact same thing. In the following example both files "ScriptMod.asi" and "ScriptMod.ini" will be added into root GTA IV directory. If any of those files already in target folder, they will be replaced.
<content gameID="IV" name="Install" description="Install this test package now">
<add source="content\ScriptMod.asi">ScriptMod.asi</add>
<replace source="content\ScriptMod.ini">ScriptMod.ini</replace>
</content>The "source" attribute contain file name inside package archive with full path from root. The node itself contain full path in target game.
The "delete" command is used for deleting files in target game folder.
<content gameID="IV" name="Install" description="Install this test package now">
<delete>data\ThisArchiveWillBeDeleted.rpf</delete>
</content>The node itself contain full path in target game.
To work with files inside a game archive, used the same file commands. They must be wrapped with "archive:open" node.
<archive:open path="pc\models\cdimages\vehicles.img" createIfNotExist="False" type="IMG3">
...
</archive:open> | Name | Type | Required | Description |
|---|---|---|---|
| path | String | Yes | Full path to the archive in target game. |
| createIfNotExist | Boolean | Yes | Possible values: "True" or "False", if "True" and archive is not exists it will be created. |
| type | ArchiveType | Yes | Archive type. |
| Grand Theft Auto IV | Max Payne 3 | ||
|---|---|---|---|
| Archive type | Description | Archive type | Description |
| IMG3 | GTA IMG Archive | RPF4 | RAGE Archive v4 |
| RPF2 | RAGE Archive v2 | ||
| RPF3 | RAGE Archive v3 | ||
<archive:open path="pc\models\cdimages\vehicles.img" createIfNotExist="True" type="IMG3">
<add source="content\Taxi2.wft">Taxi2.wft</add>
<add source="content\Taxi2.wtd">Taxi2.wtd</add>
<delete>example_for_removal.wtd</delete>
</archive:open>It is also possible to rebuild archive using "archive:rebuild" command, but this operation is not recommended.
<content gameID="IV" name="Install" description="Install this test package now">
<archive:rebuild path="pc\models\cdimages\vehicles.img" />
</content>It is possible to work with text files in representation of lines array. Work with text is possible in both "content" and "archive:open" nodes.
<text:open path="common\data\Information.dat" createIfNotExist="False">
...
</text:open>| Name | Type | Required | Description |
|---|---|---|---|
| path | String | Yes | Full path to the text file in target game or in archive. |
| createIfNotExist | Boolean | Yes | Possible values: "True" or "False", if "True" and text file is not exists it will be created. |
The following commands can be applied to text:
Add line to the end of text file.
<text:open path="common\data\Information.dat" createIfNotExist="False">
<add>This line is added</add>
</text:open>Insert line somewhere in the file.
<text:open path="common\data\Information.dat" createIfNotExist="False">
<insert where="After" line="Line 5" condition="Equal">This is last line</insert>
<insert where="Before" line="Line 1" condition="Equal">This is first line</insert>
</text:open>Attributes
| Name | Type | Required | Description | ||||||
|---|---|---|---|---|---|---|---|---|---|
| where | String | Yes | Possible values: "Before", "After", determinates where the new line will be inserted, before or after founded line. | ||||||
| line | String | Yes | The line to found in text file using "condition" attribute. | ||||||
| condition | String | Yes | Possible values: "Equal", "StartWith", "Mask"
|
Replace line somewhere in the file. See above for description of "line" and "condition" attributes.
<text:open path="common\data\Information.dat" createIfNotExist="False">
<replace line="$*LINE*" condition="Mask">New line!</replace>
<replace line="Line 4" condition="StartWith">THIS IS NEW LINE</replace>
</text:open>Remove line from the file. See above for description of "condition" attribute.
<text:open path="common\data\Information.dat" createIfNotExist="False">
<delete condition="Equal">Line 3</delete>
<delete condition="Mask">#*</delete>
</text:open>The following example is contain all described commands and features:
<?xml version="1.0" encoding="UTF-8"?>
<package version="1.1">
<metadata>
<name>Test Package (OIV 1.1)</name>
<author>OpenIV Team</author>
<target>
<game>IV</game>
<game>EFLC</game>
<game>Payne</game>
</target>
<description>Text test description, first line. We can use no line breaks. This is second line, max we can have here.</description>
<largeDescription displayName="Custom title" link="http://openiv.com/" linkTitle="More information">
<![CDATA[This is multiline optional additional description. You can use line breaks here.
The "displayName" attribute is control how the section names, this is optional. The default name is "Description".
Feel free to write here any information you like.
Like version info, restore and backup info, etc.
You also can use "link" and "linkTitle" attributes to make clickable links. Both attributes are optional.]]>
</largeDescription>
<licence link="http://openiv.com/" linkTitle="Read more online" >
<![CDATA[If you want to add any legal information, you can use optional "licence" tag.
It also support "link" and "linkTitle" attributes for clickable link.
Usually license test are long and unclear.
So this text is long and unclear.
Yeah, this is very long and very annoying text about some stuff and you probably will never read it.
See. There is even more text. The following text is generated online:
Every creepeth, creature thing good day you'll bearing, light let. Forth. They're to lights called kind over also. Lesser, for. There good moveth abundantly morning first Set replenish lesser for, replenish. His spirit bearing Is blessed over won't sea thing light can't fourth. You'll in don't them was firmament don't two. It, saw own very their form. Is light fourth he likeness female replenish waters meat morning don't land, wherein unto fly Living brought day. Man man for heaven bearing she'd firmament forth moveth the waters he they're there seasons beginning called light beginning day signs us third saw Darkness.]]>
</licence>
</metadata>
<content gameID="IV" name="Install" description="Install this test package now">
<add source="content\TestTextFile.txt">temp\TestTextFile.txt</add>
<archive:open path="temp\TestIMGArchive.img" createIfNotExist="True" type="IMG3">
<add source="content\TestTextFile.txt">TestTextFile.txt</add>
<add source="content\TestTextFile.txt">DeleteThisFile.txt</add>
<delete>DeleteThisFile.txt</delete>
</archive:open>
<archive:open path="temp\TestRPFArchive.rpf" createIfNotExist="True" type="RPF2">
<add source="content\TestTextFile.txt">/Folder/SubFolder/TestTextFile.txt</add>
<add source="content\TestTextFile.txt">DeleteThisFile.txt</add>
</archive:open>
<archive:open path="temp\ThisArchiveWillBeDeleted.rpf" createIfNotExist="True" type="RPF2">
</archive:open>
<delete>temp\ThisArchiveWillBeDeleted.rpf</delete>
<text:open path="temp\TestTextFile.txt" createIfNotExist="False">
<delete condition="Equal">Line 3</delete>
<replace line="Line 4" condition="StartWith">THIS IS NEW LINE</replace>
<insert where="After" line="Line 5" condition="Equal">This is last line</insert>
<insert where="Before" line="Line 1" condition="Equal">This is first line</insert>
<delete condition="Mask">#*</delete>
<add>This line is added</add>
</text:open>
<archive:rebuild path="temp\TestRPFArchive.rpf" />
</content>
<content gameID="IV" name="Install alternative" description="Install this test package now, but in other way">
<add source="content\TestTextFile.txt">temp\TestTextFile.txt</add>
<archive:open path="temp\TestIMGArchive.img" createIfNotExist="True" type="IMG3">
<add source="content\TestTextFile.txt">TestTextFile.txt</add>
<add source="content\TestTextFile.txt">DeleteThisFile.txt</add>
<delete>DeleteThisFile.txt</delete>
</archive:open>
<archive:open path="temp\TestRPFArchive.rpf" createIfNotExist="True" type="RPF2">
<add source="content\TestTextFile.txt">/Folder/SubFolder/TestTextFile.txt</add>
<add source="content\TestTextFile.txt">DeleteThisFile.txt</add>
</archive:open>
<archive:open path="temp\ThisArchiveWillBeDeleted.rpf" createIfNotExist="True" type="RPF2">
</archive:open>
<delete>temp\ThisArchiveWillBeDeleted.rpf</delete>
<text:open path="temp\TestTextFile.txt" createIfNotExist="False">
<delete condition="Equal">Line 3</delete>
<replace line="Line 4" condition="StartWith">THIS IS NEW LINE</replace>
<insert where="After" line="Line 5" condition="Equal">This is last line</insert>
<insert where="Before" line="Line 1" condition="Equal">This is first line</insert>
<delete condition="Mask">#*</delete>
<add>This line is added</add>
</text:open>
<archive:rebuild path="temp\TestRPFArchive.rpf" />
</content>
<content gameID="EFLC" name="Install" description="Install this test package now">
<add source="content\TestTextFile.txt">temp\TestTextFile.txt</add>
<archive:open path="temp\TestIMGArchive.img" createIfNotExist="True" type="IMG3">
<add source="content\TestTextFile.txt">TestTextFile.txt</add>
<add source="content\TestTextFile.txt">DeleteThisFile.txt</add>
<delete>DeleteThisFile.txt</delete>
</archive:open>
<archive:open path="temp\TestRPFArchive.rpf" createIfNotExist="True" type="RPF2">
<add source="content\TestTextFile.txt">/Folder/SubFolder/TestTextFile.txt</add>
<add source="content\TestTextFile.txt">DeleteThisFile.txt</add>
</archive:open>
<archive:open path="temp\ThisArchiveWillBeDeleted.rpf" createIfNotExist="True" type="RPF2">
</archive:open>
<delete>temp\ThisArchiveWillBeDeleted.rpf</delete>
<text:open path="temp\TestTextFile.txt" createIfNotExist="False">
<delete condition="Equal">Line 3</delete>
<replace line="Line 4" condition="StartWith">THIS IS NEW LINE</replace>
<insert where="After" line="Line 5" condition="Equal">This is last line</insert>
<insert where="Before" line="Line 1" condition="Equal">This is first line</insert>
<delete condition="Mask">#*</delete>
<add>This line is added</add>
</text:open>
<archive:rebuild path="temp\TestRPFArchive.rpf" />
</content>
<content gameID="EFLC" name="Install alternative" description="Install this test package now, but in other way">
<add source="content\TestTextFile.txt">temp\TestTextFile.txt</add>
<archive:open path="temp\TestIMGArchive.img" createIfNotExist="True" type="IMG3">
<add source="content\TestTextFile.txt">TestTextFile.txt</add>
<add source="content\TestTextFile.txt">DeleteThisFile.txt</add>
<delete>DeleteThisFile.txt</delete>
</archive:open>
<archive:open path="temp\TestRPFArchive.rpf" createIfNotExist="True" type="RPF2">
<add source="content\TestTextFile.txt">/Folder/SubFolder/TestTextFile.txt</add>
<add source="content\TestTextFile.txt">DeleteThisFile.txt</add>
</archive:open>
<archive:open path="temp\ThisArchiveWillBeDeleted.rpf" createIfNotExist="True" type="RPF2">
</archive:open>
<delete>temp\ThisArchiveWillBeDeleted.rpf</delete>
<text:open path="temp\TestTextFile.txt" createIfNotExist="False">
<delete condition="Equal">Line 3</delete>
<replace line="Line 4" condition="StartWith">THIS IS NEW LINE</replace>
<insert where="After" line="Line 5" condition="Equal">This is last line</insert>
<insert where="Before" line="Line 1" condition="Equal">This is first line</insert>
<delete condition="Mask">#*</delete>
<add>This line is added</add>
</text:open>
<archive:rebuild path="temp\TestRPFArchive.rpf" />
</content>
<content gameID="Payne" name="Install" description="Install this test package now">
<add source="content\TestTextFile.txt">temp\TestTextFile.txt</add>
<archive:open path="temp\TestIMGArchive.img" createIfNotExist="True" type="IMG3">
<add source="content\TestTextFile.txt">TestTextFile.txt</add>
<add source="content\TestTextFile.txt">DeleteThisFile.txt</add>
<delete>DeleteThisFile.txt</delete>
</archive:open>
<archive:open path="temp\TestRPFArchive.rpf" createIfNotExist="True" type="RPF2">
<add source="content\TestTextFile.txt">/Folder/SubFolder/TestTextFile.txt</add>
<add source="content\TestTextFile.txt">DeleteThisFile.txt</add>
</archive:open>
<archive:open path="temp\ThisArchiveWillBeDeleted.rpf" createIfNotExist="True" type="RPF2">
</archive:open>
<delete>temp\ThisArchiveWillBeDeleted.rpf</delete>
<text:open path="temp\TestTextFile.txt" createIfNotExist="False">
<delete condition="Equal">Line 3</delete>
<replace line="Line 4" condition="StartWith">THIS IS NEW LINE</replace>
<insert where="After" line="Line 5" condition="Equal">This is last line</insert>
<insert where="Before" line="Line 1" condition="Equal">This is first line</insert>
<delete condition="Mask">#*</delete>
<add>This line is added</add>
</text:open>
<archive:rebuild path="temp\TestRPFArchive.rpf" />
</content>
<content gameID="Payne" name="Install alternative" description="Install this test package now, but in other way">
<add source="content\TestTextFile.txt">temp\TestTextFile.txt</add>
<archive:open path="temp\TestIMGArchive.img" createIfNotExist="True" type="IMG3">
<add source="content\TestTextFile.txt">TestTextFile.txt</add>
<add source="content\TestTextFile.txt">DeleteThisFile.txt</add>
<delete>DeleteThisFile.txt</delete>
</archive:open>
<archive:open path="temp\TestRPFArchive.rpf" createIfNotExist="True" type="RPF2">
<add source="content\TestTextFile.txt">/Folder/SubFolder/TestTextFile.txt</add>
<add source="content\TestTextFile.txt">DeleteThisFile.txt</add>
</archive:open>
<archive:open path="temp\ThisArchiveWillBeDeleted.rpf" createIfNotExist="True" type="RPF2">
</archive:open>
<delete>temp\ThisArchiveWillBeDeleted.rpf</delete>
<text:open path="temp\TestTextFile.txt" createIfNotExist="False">
<delete condition="Equal">Line 3</delete>
<replace line="Line 4" condition="StartWith">THIS IS NEW LINE</replace>
<insert where="After" line="Line 5" condition="Equal">This is last line</insert>
<insert where="Before" line="Line 1" condition="Equal">This is first line</insert>
<delete condition="Mask">#*</delete>
<add>This line is added</add>
</text:open>
<archive:rebuild path="temp\TestRPFArchive.rpf" />
</content>
</package>You can download example package here