Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
576 lines (473 sloc) 23.3 KB

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.

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

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

List of games with associated IDs:

Game OpenIV GameId
Grand Theft Auto IV IV
Episodes from Liberty City EFLC
Max Payne 3 Payne
largeDescription

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

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

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

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> 
Attributes
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.
Archive type
Grand Theft Auto IVMax Payne 3
Archive typeDescriptionArchive typeDescription
IMG3GTA IMG ArchiveRPF4RAGE Archive v4
RPF2RAGE Archive v2
RPF3RAGE Archive v3
Example
<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>
Defragmentation

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

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

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

Package Example

You can download example package here

You can’t perform that action at this time.