OpenIV Package format – Version 2.2

Summary

OIV Package version 2.2 must be a ZIP archive without password, the compression level is not important. Only "Stored" and "Deflate" compression methods are supported.

Files

List of the files and folders inside package archive:

Name	Type	Required	Description
assembly.xml	XML File	Yes	The main package file, contain metadata, appearance and content description.
icon.png	PNG Image	Optional	The icon representing this mod. Must be exactly 128x128 (px) size.
content	Folder	Yes	Folder with files of mod.

assembly.xml

Root node must be named "package" and must have three required sub nodes: "metadata", "colors", "content".

<?xml version="1.0" encoding="UTF-8"?>
<package version="2.2" id="{12345678-90AB-CDEF-1234-567890ABCDEF}" target="GameId">
    <metadata>
    ...
    </metadata>
    <colors>
    ...
    </colors>
    <content>
    ...
    </content>
</package>

Package attributes

Name	Type	Required	Description
version	Package Version	Yes	Value: "2.2", version of package format, always equal "2.2".
id	GUID	Yes	The unique identifier of the package. Must be unique for each package.
target	GameId	Yes	The target Game Id. May be one of the following values.

List of games with associated IDs:

Game	GameId
Grand Theft Auto V	Five
Grand Theft Auto IV	IV
Episodes from Liberty City	EFLC
Max Payne 3	Payne

The following online services can be used for generation unique GUID:

http://www.guidgen.com/
https://www.uuidgenerator.net/
https://www.guidgenerator.com/

Metadata

The metadata node is contain information about package author, version and package description.

<metadata>
	<name>Package Name</name>
	<version>
		<major>1</major>
		<minor>0</minor>
		<tag>EXAMPLE</tag>
	</version>
	<author>
		<displayName>Author Name</displayName>
		<actionLink>http://example.com/</actionLink>
		<web>http://example.com/</web>
		<facebook>Facebook</facebook>
		<twitter>Twitter</twitter>
		<youtube linkKind="channel">YouTube</youtube>
	</author>
	<description footerLink="http://example.com/" footerLinkTitle="Link title">
		<![CDATA[Description.]]>
	</description>
	<largeDescription displayName="Custom name" footerLink="http://example.com/" footerLinkTitle="Link title">
		<![CDATA[Additional description.]]>
	</largeDescription>
	<licence footerLink="http://example.com/" footerLinkTitle="Link title">
		<![CDATA[Licence text.]]>
	</licence>
</metadata>

Members

Name	Type	Required	Description
name	String	Yes	The name of the mod package.

Please consider the following recommendation:

Make sure your package name is not too long;
Do not add version into package name;
Do not add "OIV" prefix or postfix into package name. If you want to specify this information use version tag.

Name	Type	Required	Description
version	Node	Yes	The version of the mod package. The version is composed from two components, major and minor number.

Version node members

Name	Type	Required	Description
major	Integer	Yes	Major version number.
minor	Integer	Yes	Minor version number.
tag	String	Optional	Version tag, for example: "Alpha", "Beta", "Test" etc.

Name	Type	Required	Description
author	Node	Yes	This node contain information about mod package author.

Author node members

Name	Type	Required	Description
displayName	String	Yes	Name of mod package author.
actionLink	Link	Optional	The action link, will be open when user click on author name. For example, can be used for author's email or web page with other author's mods. (Like profile page on http://gta5-mods.com/)
web	Link	Optional	Link to author's home page.
facebook	Facebook page name	Optional	Author's Facebook page.
twitter	Twitter account name	Optional	Author's twitter account.
youtube	YouTube account or channel name	Optional	Author's YouTube account.

For youtube node the "linkKind" attribute is required, generated link address is depends from this attribute, may be one of the following values:

linkKind	YouTube Link base address
user	https://www.youtube.com/user/
channel	https://www.youtube.com/c/

Name	Type	Required	Description
description	CData	Yes	The description of mod package. No length limitation. Line breaks can be used.

Description node attributes

Name	Type	Required	Description
footerLink	Link	Optional	Optional web link to additional information.
footerLinkTitle	String	Optional	Optional display title for the link.

Name	Type	Required	Description
largeDescription	CData	Optional	Optional additional description of mod package. No length limitation. Line breaks can be used. For example, can be used for "Version history" and other stuff.

Large description node attributes

Name	Type	Required	Description
displayName	String	Optional	Optional display name of the description. For example: "Description", "Version history", "Mods by me" etc.
footerLink	Link	Optional	Optional web link to additional information.
footerLinkTitle	String	Optional	Optional display title for the link.

Name	Type	Required	Description
licence	CData	Optional	Optional mod licence. No length limitation. Line breaks can be used.

Licence node attributes

Name	Type	Required	Description
footerLink	Link	Optional	Optional web link to additional information.
footerLinkTitle	String	Optional	Optional display title for the link.

Examples

1 – Full metadata

<metadata>
	<name>OIV 2.2 Test Package</name>
	<version>
		<major>2</major>
		<minor>2</minor>
		<tag>EXAMPLE</tag>
	</version>
	<author>
		<displayName>OpenIV Team</displayName>
		<actionLink>http://openiv.com/</actionLink>
		<web>http://openiv.com/</web>
		<facebook>OpenIV</facebook>
		<twitter>OpenIV</twitter>
		<youtube linkKind="channel">OpenIV</youtube>
	</author>
	<description footerLink="http://openiv.com/" footerLinkTitle="More">
		<![CDATA[Unto upon man that winged earth him firmament night life Morning. There seed light so make there fowl light you'll light his you're sea sixth can't. Morning was meat god can't appear let form set. Female bring sixth man under a was thing was given dry stars saying good to bring you. Very is. Every dominion. Cattle which cattle blessed own abundantly green you're said third kind there seas deep. They're that firmament male male moved whose dominion had lights open Fly man may open. He lesser itself sixth great us had tree forth bearing she'd face. Saw and forth.]]>
	</description>
	<largeDescription displayName="Version history" footerLink="http://openiv.com/" footerLinkTitle="Get more mods">
		<![CDATA[Made, it grass to us seas dominion form gathering herb created beast that given morning land their whales years isn't brought stars herb you great, female fruitful. Beginning. Seasons upon replenish day green seasons sixth whose night a wherein god lesser stars so good. Every you'll stars blessed open saw have seed them, can't fish Set. Called greater creeping light multiply called had gathering, kind you're doesn't bring after you'll stars sea every, unto. Likeness. Had said subdue. Him stars grass seas. You'll also night firmament. Appear rule light greater shall be. Third tree let living, creature were, creature don't.]]>
	</largeDescription>
	<licence footerLink="http://openiv.com/" footerLinkTitle="Online terms">
		<![CDATA[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.

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>OIV 2.2 Test Package</name>
	<version>
		<major>2</major>
		<minor>2</minor>
	</version>
	<author>
		<displayName>OpenIV Team</displayName>
	</author>
	<description>
		<![CDATA[Unto upon man that winged earth him firmament night life Morning. There seed light so make there fowl light you'll light his you're sea sixth can't. Morning was meat god can't appear let form set. Female bring sixth man under a was thing was given dry stars saying good to bring you. Very is. Every dominion. Cattle which cattle blessed own abundantly green you're said third kind there seas deep. They're that firmament male male moved whose dominion had lights open Fly man may open. He lesser itself sixth great us had tree forth bearing she'd face. Saw and forth.]]>
	</description>
</metadata>

colors

The colors node contain information with helps you to control appearance of Package Installer window.

<colors>
	<headerBackground useBlackTextColor="False">$FF23366A</headerBackground>
	<iconBackground>$FF3b5998</iconBackground>
</colors>

Colors node members

Name	Type	Required	Description
headerBackground	ARGB	Yes	The ARGB color of the header of the window. Each color value is hex.
useBlackTextColor	Boolean	Yes	Value: "True" or "False". If "True" the text in header area will be black. If "False" the text in header area will be white.
iconBackground	ARGB	Yes	The ARGB color of the icon aread in the header. Each color value is hex.

content

The content node describes files which will be affected with installation of this package. There must be only one content node.

<content>
	...
</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 the game folder use "add" command. If file is already in the target folder, it will be replaced.

<content>
  <add source="ScriptMod.asi">ScriptMod.asi</add>
  <add source="ScriptMod.ini">ScriptMod.ini</add>
</content>

The "source" attribute contain file name inside package content folder, the path is without "content". The node itself contain full path in the target game.

Delete file

The "delete" command is used for deleting files in the target game folder.

<content>
  <delete>data\ThisArchiveWillBeDeleted.rpf</delete>
</content>

The node itself contain full path in the target game.

Archive commands

To work with the files inside game archive, the same file commands are used. They must be wrapped with "archive" node. The archives can be included in other archives.

<archive path="x64a.rpf" createIfNotExist="False" type="RPF7">
  ...
</archive>

<archive path="x64e.rpf" createIfNotExist="False" type="RPF7">
  <archive path="levels\gta5\vehicles.rpf" createIfNotExist="False" type="RPF7">
    ...
  </archive> 
</archive>

Attributes

Name	Type	Required	Description
path	String	Yes	Full path to the archive in the target game.
createIfNotExist	Boolean	Yes	Value: "True" or "False", if "True" and archive is not exists it will be created.
type	ArchiveType	Yes	Archive type.

The following archive type are possible:

ArchiveType	Description
Grand Theft Auto V
RPF7	RAGE Archive v7
Grand Theft Auto IV
IMG3	GTA IMG Archive
RPF2	RAGE Archive v2
RPF3	RAGE Archive v3
Max Payne 3
RPF4	RAGE Archive v4

Example

<archive path="x64e.rpf" createIfNotExist="True" type="RPF7">
  <add source="ExampleTextFile.txt">ExampleTextFile.txt</add>
  <delete>RemoveThisFile.txt</delete>
  <archive path="levels\gta5\vehicles.rpf" createIfNotExist="True" type="RPF7">
    <add source="adder.yft">adder.yft</add>
    <add source="adder_hi.yft">adder_hi.yft</add>
    <add source="adder.ytd">adder.ytd</add>
  </archive>
</archive>

Archive defragmentation (rebuild)

Archive defragmenter consolidates files inside archive to reduce archive size on computer's hard disk. Usually, you no need to use defragmentation, but if by some reason you are sure you need it you can this command.

<defragmentation archive="x64a.rpf"/>

You can use defragmentation on embedded archives as well.

<archive path="update\x64\dlcpacks\patchday9ng\dlc.rpf" createIfNotExist="True" type="RPF7">
	<defragmentation archive="x64\levels\gta5\vehicles.rpf"/>
</archive>

Text commands

It is possible to work with text files in representation of lines array. Work with text is possible in both "content" and "archive" nodes. Do not use text commands for XML files. Use specific commands for XML editing.

<text path="common\data\Information.dat" createIfNotExist="False">
  ...
</text>

Attributes

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

Add line to the end of text file.

<text path="common\data\Information.dat" createIfNotExist="False">
  <add>This line is added</add>
</text>

Insert

Insert line somewhere in the file.

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

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"

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

delete

Remove line from the file. See above for description of "condition" attribute.

<text path="common\data\Information.dat" createIfNotExist="False">
  <delete condition="Equal">Line 3</delete>
  <delete condition="Mask">#*</delete>
</text>

XML commands

You can modify XML files using specific commands based on XPATH selector. Work with XML files is possible in both "content" and "archive" nodes.

<xml path="common\data\dlclist.xml">
  ...
</xml>

Attributes

Name	Type	Required	Description
path	String	Yes	Full path to the XML file in target game or in archive. The file must exist.

The following commands can be applied to XML:

add

Add new node into selected node.

<xml path="dlclist.xml">
	<add append="First" xpath="/SMandatoryPacksData/Paths">
		<Item>dlcpacks:\spFirstTestMod\</Item>
	</add>
	
	<add append="Last" xpath="/SMandatoryPacksData/Paths">
		<Item>dlcpacks:\spLastTestMod\</Item>
	</add>
	
	<add append="Before" xpath="/SMandatoryPacksData/Paths/Item[.='dlcpacks:/mpheist/']">
		<Item>dlcpacks:\spBeforeHeistTest\</Item>
	</add>
	
	<add append="After" xpath="/SMandatoryPacksData/Paths/Item[.='dlcpacks:/patchday21ng/']">
		<Item>dlcpacks:\spAfter21ngTest\</Item>
	</add>
</xml>

Attributes

Name

Type

Required

Description

append

String

Yes

Specifies how new node will be added. Possible values:

First	Node will be added before first child in selected node.
Last	Node will be added after last child in selected node.
Before	Node will be added before selected node.
After	Node will be added after selected node.

xpath

XPATH Selector

Yes

The XPATH path no node you want to select.

replace

Replace existing node with the new one.

<xml path="common\data\dlclist.xml">
	<replace xpath="/SMandatoryPacksData/Paths/Item[10]">
		<Item>platform:\dlcPacks\mpReplacedLine\</Item>
	</replace>
</xml>
<xml path="common\data\handling.meta">
	<replace xpath='/CHandlingDataMgr/HandlingData/Item[@type="CHandlingData"]/handlingName[.="BUFFALO"]/../fMass'>
		<fMass value="999999.000"/>
	</replace>
</xml>

Attributes

Name	Type	Required	Description
xpath	XPATH Selector	Yes	The XPATH path no node you want to replace.

remove

Remove existing node.

<xml path="common\data\dlclist.xml">
	<remove xpath="/SMandatoryPacksData/Paths/Item[15]" />
</xml>

Attributes

Name	Type	Required	Description
xpath	XPATH Selector	Yes	The XPATH path no node you want to remove.

PSO/META commands (GTA V)

You can modify GTA V PSO (*.ymt, *.ymf, etc) files using same commands as for XML files, but instead of xml use pso node. Work with PSO files is possible in both "content" and "archive" nodes. Not all PSO files editable by the OpenIV, you can find list of supported files for each OpenIV version here.

<pso path="x64\data\carcols.ymt">
  <!-- XML commands here -->
</pso>

<pso path="bt1_01.ymap">
  <!-- XML commands here -->
</pso>

<pso path="sunset_metadata_013_strm.ytyp">
  <!-- XML commands here -->
</pso>

Examples

The following example is contain all described commands and features:

<?xml version="1.0" encoding="UTF-8"?>
<package version="2.2" id="{BDA5F91A-EC81-45ED-A101-480E9F5928D4}" target="Five">
	<metadata>
		<name>OIV 2.2 Test Package</name>
		<version>
			<major>2</major>
			<minor>2</minor>
			<tag>EXAMPLE</tag>
		</version>
		<author>
			<displayName>OpenIV Team</displayName>
			<actionLink>http://openiv.com/</actionLink>
			<web>http://openiv.com/</web>
			<facebook>OpenIV</facebook>
			<twitter>OpenIV</twitter>
			<youtube linkKind="channel">OpenIV</youtube>
		</author>
		<description footerLink="http://openiv.com/" footerLinkTitle="More"><![CDATA[Unto upon man that winged earth him firmament night life Morning. There seed light so make there fowl light you'll light his you're sea sixth can't. Morning was meat god can't appear let form set. Female bring sixth man under a was thing was given dry stars saying good to bring you. Very is. Every dominion. Cattle which cattle blessed own abundantly green you're said third kind there seas deep. They're that firmament male male moved whose dominion had lights open Fly man may open. He lesser itself sixth great us had tree forth bearing she'd face. Saw and forth.]]></description>
		<largeDescription displayName="Version history" footerLink="http://openiv.com/" footerLinkTitle="Get more mods"><![CDATA[Made, it grass to us seas dominion form gathering herb created beast that given morning land their whales years isn't brought stars herb you great, female fruitful. Beginning. Seasons upon replenish day green seasons sixth whose night a wherein god lesser stars so good. Every you'll stars blessed open saw have seed them, can't fish Set. Called greater creeping light multiply called had gathering, kind you're doesn't bring after you'll stars sea every, unto. Likeness. Had said subdue. Him stars grass seas. You'll also night firmament. Appear rule light greater shall be. Third tree let living, creature were, creature don't.]]></largeDescription>
		<licence footerLink="http://openiv.com/" footerLinkTitle="Online terms"><![CDATA[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.
		
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>
	
	<colors>
		<headerBackground useBlackTextColor="False">$FF23366A</headerBackground>
		<iconBackground>$FF3b5998</iconBackground>
	</colors>
	
	<content>
		<archive path="x64_OIV.rpf" createIfNotExist="True" type="RPF7">
			<add source="dlclist.xml">dlclist.xml</add>
			<add source="dlclist.xml">dlclist_RSG.xml</add>
			<add source="TestTextFile.txt">TestTextFile.txt</add>
			<add source="TestTextFile.txt">Package\Installer\Test\TestTextFile.txt</add>
			
			<archive path="inner\x64a.rpf" createIfNotExist="True" type="RPF7">
				<add source="TestTextFile.txt">TestTextFile.txt</add>
				<add source="TestTextFile.txt">Package\Installer\Test\TestTextFile.txt</add>
			</archive>
			<defragmentation archive="inner\x64a.rpf"/>
			
			<text path="TestTextFile.txt" createIfNotExist="False">
				<add>This line is added</add>
				<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>
			</text>
			
			<xml path="dlclist.xml">
				<add xpath="/SMandatoryPacksData/Paths">
					<item>dlcpacks:\spLibertyV\</item>
				</add>
				<add xpath="/SMandatoryPacksData/Paths" append="First">
					<item>platform:\dlcPacks\xmTestLineOnTop\</item>
				</add>
				<replace xpath="/SMandatoryPacksData/Paths/Item[10]">
					<Item>platform:\dlcPacks\mpReplacedLine\</Item>
				</replace>
				<remove xpath="/SMandatoryPacksData/Paths/Item[15]" />
			</xml>
		</archive>
		<defragmentation archive="x64_OIV.rpf"/>
	</content>
</package>

The following example is showing how to add or replace file inside GTA V update.rpf:

<?xml version="1.0" encoding="UTF-8"?>
<package version="2.2" id="{6D501E5D-DD68-42CB-ACA4-A920DFC905E3}" target="Five">
  <metadata>
    <name>Test Package (OIV 2.2)</name>
      <version>
        <major>2</major>
        <minor>2</minor>
      </version>
      <author>
        <displayName>OpenIV Team</displayName>
      </author>
      <description>
        <![CDATA[Description text]]>
      </description>
  </metadata>

  <colors>
    <headerBackground useBlackTextColor="False">$FF23366A</headerBackground>
    <iconBackground>$FF3b5998</iconBackground>
  </colors>
	
  <content>
    <archive path="update\update.rpf" createIfNotExist="False" type="RPF7">
      <add source="water.xml">data\levels\gta5\water.xml</add>
    </archive>
  </content>
</package>

Package Example

You can download example package here

Files

2.2.md

Latest commit

History

2.2.md

File metadata and controls

OpenIV Package format – Version 2.2

Summary

Table of Contents

Files

assembly.xml

Package attributes

Metadata

Members

Version node members

Author node members

Description node attributes

Large description node attributes

Licence node attributes

Examples

colors

Colors node members

content

Content Installation Script

File commands

Add or replace file

Delete file

Archive commands

Attributes

Example

Archive defragmentation (rebuild)

Text commands

Attributes

add

Insert

replace

delete

XML commands

Attributes

add

replace

remove

PSO/META commands (GTA V)

Examples

Package Example