OpenIV Package format – Version 1.1

Summary

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.

Files

List of files and folders inside package archive:

assembly.xml
icon.png
content

assembly.xml

Type: XML File
Required: Yes
The main package file, contain metadata and content description.

icon.png

Type: PNG Image
Required: Optional
The icon representing this mod. Must be exactly 32×32 (px) size.

content

Type: Folder
Required: Yes
Folder with files of mod.

assembly.xml

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>

Metadata

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>

Members

name

Type: String line
Required: Yes
Package name.

author

Type: String line
Required: Yes
Package author name.

target

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

description

Type: String line
Required: Yes
Short test description of the package. About 110 char long. No line breaks.

largeDescription

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>

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.

licence

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>

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.

Examples

1 – Full metadata

<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>

2 – Only required information

<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>

Content

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>

Attributes

gameID

Type: String line
Required: Yes
OpenIV Game Id.

name

Type: String line
Required: Yes
Name of the content block.

description

Type: String line
Required: Yes
Short description of content.

Examples

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>

Content Installation Script

The “content” node contain some kind of script commands for manipulation with files, archives and text lines.

File commands

Add or replace file

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.

Delete file

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.

Archive commands

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>

path

Type: String line
Required: Yes
Full path to the archive in target game.

createIfNotExist

Type: Boolean
Required: Yes
Value: “True” or “False”
If “True” and archive is not exists it will be created.

type

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>

Text commands

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>

path

Type: String line
Required: Yes
Full path to the text file in target game or in archive.

createIfNotExist

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

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

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

where

Type: String line
Required: Yes
Possible values: “Before”, “After”
Determinates where the new line will be inserted, before or after founded line.

line

Type: String line
Required: Yes
The line to found in text file using “condition” attribute.

condition

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

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>

delete

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>

Example

The following example is contain all described commands and features:

assembly.xml

<?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>

Package Example

You can download example package here.

OpenIV

User Tools

Site Tools

Sidebar

Table of Contents

OpenIV Package format – Version 1.1

Summary

Files

assembly.xml

icon.png

content

assembly.xml

Metadata

Members

name

author

target

description

largeDescription

Attributes

licence

Attributes

Examples

1 – Full metadata

2 – Only required information

Content

Attributes

gameID

name

description

Examples

Content Installation Script

File commands

Add or replace file

Delete file

Archive commands

path

createIfNotExist

type

Text commands

path

createIfNotExist

add

Insert

Attributes

where

line

condition

replace

delete

Example

Package Example

Page Tools