OIV Package version 1.1 must be a ZIP archive without password, the compression level is not important.
List of files and folders inside package archive:
assembly.xml icon.png content
Type: XML File
Required: Yes
The main package file, contain metadata and content description.
Type: PNG Image
Required: Optional
The icon representing this mod. Must be exactly 32×32 (px) size.
Type: Folder
Required: 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>
Type: String line
Required: Yes
Package name.
Type: String line
Required: Yes
Package author name.
Type: List
Required: 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. List of games with associated ids:
Game | OpenIV GameId |
---|---|
Grand Theft Auto IV | IV |
Episodes from Liberty City | EFLC |
Max Payne 3 | Payne |
Type: String line
Required: Yes
Short test description of the package. About 110 char long. No line breaks.
Type: CData text
Required: Optional
Long description. No length limitation. Line breaks can be used. Text must be wrapped in xml CDATA node. Example:
<largeDescription displayName="Custom title" link="http://example.com/" linkTitle="More information"> <![CDATA[Sample text. Sample text. Sample text after two line breaks.]]> </largeDescription>
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.
Type: CData text
Required: Optional
Mod licence. No length limitation. Line breaks can be used. Text must be wrapped in xml CDATA node. Example:
<licence displayName="Custom title" link="http://example.com/" linkTitle="More information"> <![CDATA[Sample text. Sample text. Sample text after two line breaks.]]> </licence>
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 ling 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>
Type: String line
Required: Yes
OpenIV Game Id.
Type: String line
Required: Yes
Name of the content block.
Type: String line
Required: 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. In 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>
Type: String line
Required: Yes
Full path to the archive in target game.
Type: Boolean
Required: Yes
Value: “True” or “False”
If “True” and archive is not exists it will be created.
Type: Archive type
Required: Yes
Archive type.
The following values are possible:
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 represents of line array. Work with text is possible in both “content” and “archive:open” nodes.
<text:open path="common\data\Information.dat" createIfNotExist="False"> ... </text:open>
Type: String line
Required: Yes
Full path to the text file in target game or in archive.
Type: Boolean
Required: Yes
Value: “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>
Type: String line
Required: Yes
Possible values: “Before”, “After”
Determinates where the new line will be inserted, before or after founded line.
Type: String line
Required: Yes
The line to found in text file using “condition” attribute.
Type: String line
Required: Yes
Possible values: “Equal”, “StartWith”, “Mask”
Equal | The line must be exact like in “line” attribute. |
StartWith | The line must start with value from “line” attribute. |
Mask | In the “line” attribute, the mask for searching must be specified. |
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 ling 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.