Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
1 contributor

Users who have contributed to this file

598 lines (525 sloc) 25.8 KB

OpenIV Package format – Version 2.1

Summary

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

Table of Contents

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.1" 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.1", version of package format, always equal "2.1".
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:

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.1 Test Package</name>
	<version>
		<major>2</major>
		<minor>1</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.1 Test Package</name>
	<version>
		<major>2</major>
		<minor>1</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:

ArchiveTypeDescription
Grand Theft Auto V
RPF7RAGE Archive v7
Grand Theft Auto IV
IMG3GTA IMG Archive
RPF2RAGE Archive v2
RPF3RAGE Archive v3
Max Payne 3
RPF4RAGE 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

NameTypeRequiredDescription
whereStringYesPossible values: "Before", "After", determinates where the new line will be inserted, before or after founded line.
lineStringYesThe line to found in text file using "condition" attribute.
conditionStringYesPossible values: "Equal", "StartWith", "Mask"
EqualThe line must be exact like in "line" attribute.
StartWithThe line must start with value from "line" attribute.
MaskIn 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 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="common\data\dlclist.xml">
	<add xpath="/SMandatoryPacksData/Paths">
		<item>dlcpacks:\spMyNewCar\</item>
	</add>
	<add xpath="/SMandatoryPacksData/Paths" append="First">
		<item>dlcpacks:\spMyNewCarOnTop\</item>
	</add>
</xml>

Attributes

NameTypeRequiredDescription
xpathXPATH SelectorYesThe XPATH path no node you want to select.
appendStringOptionalOptional attribute which allows to control where new node will be added. Possible values:
FirstNode will be added before first child in selected node.
LastNode will be added after last child in selected node.
If this attribute is not specified node will be added after last child.
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.

Examples

The following example is contain all described commands and features:

<?xml version="1.0" encoding="UTF-8"?>
<package version="2.1" id="{BDA5F91A-EC81-45ED-A101-480E9F5928D4}" target="Five">
	<metadata>
		<name>OIV 2.1 Test Package</name>
		<version>
			<major>2</major>
			<minor>1</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.0" id="{6D501E5D-DD68-42CB-ACA4-A920DFC905E3}" target="Five">
  <metadata>
    <name>Test Package (OIV 2.0)</name>
      <version>
        <major>1</major>
        <minor>0</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

You can’t perform that action at this time.