GTA IV

The Complete Edition on Steam, including The Lost and Damned and The Ballad of Gay Tony. Changes go into the update folder, or into the game files with the originals kept, and can be undone.

Documentation · GTA IV

Setup

Choose the GTA IV folder in the setup dialog, or under File → Switch game… → Add a game…. The Steam folder Grand Theft Auto IV and the GTAIV folder inside it both work.

OpenRAGE finds the archive key in your own GTAIV.exe by a checksum and keeps it in gta4.keys in your config folder. That takes under a second; nothing else is needed. On the command line:

openrage --game "/path/to/Grand Theft Auto IV" keys
openrage ls pc/models/cdimages

At a glance

WhatFilesStatus
Archives.img (IMG3), .rpf (RPF2, RPF3)browse, extract and change
Textures.wtd, inside .wdrview, export DDS/PNG; replace, add and remove
Models.wdr, .wdd, .wftview, export glTF
Texts.gxtview and edit
Placement files and maps.wpl, map archivesview as text and in 3D, export glTF
Collisions.wbn, .wbd, in .wftview, export glTF
Animations.wadplay on peds
Cutscenes.cut with the .wad next to itplay with cast, camera and subtitles; view as text
Scripts.scoread the disassembly
Searcheverything above, .ide, .dat, .gxtnames, hashes and full text

Changes go into the update folder; see Editing.

The search box works as for GTA V: file names, hashes (a model's hash from a placement file finds its .wdr) and the full text of the game's .ide, .dat, .ipl, .csv and other text files and of its text tables (.gxt, with the language filter). GTA IV keeps much of this outside its archives, so loose files are indexed with their text too. The index is built in the background the first time you open the game (a few seconds) and updated when archives change.

openrage index
openrage search admiral                        # vehicles.img/admiral.wft, handling.dat, vehicles.ide, …
openrage search "Spieler ist unbesiegbar" --lang german

Archives

Most files are in .img archives, a few in .rpf archives (the audio archives are RPF3).

  • Archives open like folders: file details, a text preview for plain files, the resource type and memory sizes.
  • Extract… saves files, folders and whole archives. Files are saved as stored, like OpenIV does: resources as RSC5 files with their header.
  • RPF3 (audio) archives keep only a hash of each name. OpenRAGE names them from the game's own audio configuration (pc/audio/config and the episodes'), which names nearly all of them (general/music_ringtones, resident/amb_resident); the rest show their hash as eight hex digits. Paths work with either.

Checked: openrage verify reads all 303 archives of the game (46,889 resources, no errors).

Textures

Texture dictionaries (.wtd) open like GTA V's: preview, viewer and export as DDS or PNG. GTA IV stores DXT1/3/5 and uncompressed 32-bit textures.

In edit mode, textures can be replaced from a DDS file, added and removed, as in GTA V; the changed dictionary goes into the update folder (or the game files, see Editing) and can be undone. A replacement with the same format, size and mip count only swaps the pixel data. Anything else rebuilds the dictionary: its other data stays as it was, so fields OpenRAGE does not interpret are kept. Use DXT1, DXT3, DXT5 or 32-bit BGRA DDS files; textures that only exist in newer formats (BC7 and others) cannot go into GTA IV.

Textures inside models: many props and cutscene objects (.wdr) carry their own textures; vehicles and peds (.wft, .wdd) never do, theirs are in .wtd files. Selecting such a model shows a Textures (N) button that opens them as a list, edited like a dictionary. The model's other data stays untouched: a replacement with a new size or format adds its pixel data at the end, and every texture keeps its place, because the model's shaders point at it. A texture a shader uses cannot be removed (replace it instead); added textures are only used once a shader refers to them.

openrage textures pc/models/cdimages/vehicles.img/admiral.wtd --set admiral_badges=badges.dds   # replace
openrage textures pc/models/cdimages/vehicles.img/admiral.wtd --set my_decal=decal.dds --remove admiral_sign
openrage textures pc/anim/cutsprops.img/csak47.wdr --set cj_ak1=wood.dds        # a model's own textures
openrage verify --textures --rebuild           # rebuild every dictionary in memory and compare (writes nothing)

Checked: 6,400 dictionaries and 9,820 models with their own textures (136,125 textures), all decoded; every dictionary rebuilt and read back identically, every model rebuilt byte for byte.

Models

Drawables (.wdr), drawable dictionaries (.wdd) and fragments (.wft) open in the preview and the 3D viewer and export as glTF.

Vehicles and peds

  • Vehicles show their wheels on every wheel bone.
  • Peds (componentpeds.img) are put together from the first variant of each component on their skeleton; switch the others on under Parts.

Where textures come from

  1. the dictionary embedded in the model,
  2. the .wtd named after it,
  3. the dictionary the game's .ide files give the model, and its parent dictionaries,
  4. for vehicles, vehshare.wtd.

OpenRAGE indexes the .ide and .wtd files once per session (a second or two) and prefers an episode's own files for TLAD and TBoGT models.

Checked: 26,711 files, 46,658 drawables, 61 million triangles, no errors.

Texts, placement files and scripts

  • Texts (common/text/<language>.gxt, and the episodes' own) open in a read-only window: every table as a [NAME] section of 0xHASH = text lines, in GTA V's .oxt form.
  • Placement files (.wpl) show as IPL-style text: one line per object with position, rotation, model name, flags and LOD, then the other sections. In edit mode, Open in text editor (right-click; double-click opens the map) lets you move, add and remove objects; saving turns the text back into the .wpl (into the update folder, with undo). Numbers are written exactly (floats always with a point, 5.0), so an unchanged file saves byte for byte; model names become their hash, 0x… hashes work too, and mistakes are reported with their line. Objects name their LOD by its position in the list, so add new ones at the end.
  • Object definitions (.ide) and .ipl files are plain text: they open in the text editor and save the same way. New model names are picked up right after saving.
  • Scripts (.sco) show their facts and the strings they use; double-click opens the disassembly. Most are encrypted with the archive key, which OpenRAGE already has. Functions are named func_N and natives shown by hash: GTA IV keeps neither name. Every jump target gets a label.

Checked: 5,498 text tables (671,627 strings, converting back identically), 1,151 placement files (458,048 records, each file converting from text back to the same bytes), 941 scripts (14.5 million instructions; every jump, call and switch case lands on an instruction).

Maps

Double-click a placement file (.wpl) to see its objects in 3D, with the object list and glTF export.

  • A map archive (pc/data/maps/…/<area>.img) is mostly a set of streamed placement files. openrage map <archive> puts them together, for example a whole part of Algonquin with 2,483 objects.
  • Models come from the archive next to the placement file first, then from anywhere in the game.
  • Low-detail stand-ins (lod…, slod…) are left out unless a file holds nothing else.
  • Interiors (offices, shops, bars, the portacabins of the docks) are placed as one object whose contents the .ide files list (mlo sections): they show with everything inside.

Checked: 1,375 placed interiors expanded; of the 492,802 objects then placed, all but 59 have a model (their names are in no .ide file).

Collisions

.wbn (one bound, usually a piece of a map area) and .wbd (a dictionary of bounds) open like GTA V's collisions, coloured by material with the names from GTA IV's own materials.dat, and export as glTF.

Fragments (.wft: vehicles, peds, breakable props) carry their collision: switch on the hidden part Collision under Parts to see it over the model, for example a vehicle's body and wheels or a ped's ragdoll of capsules.

Checked: 2,907 files, 36,857 bounds, 26 million triangles, no errors.

Animations

Animation dictionaries (.wad, in pc/anim/anim.img, cutscenes in cuts.img) open like GTA V's clip dictionaries: one clip per animation, with the models to play it on. Every GTA IV ped shares one skeleton, and so do the cutscene characters (cs_* in cutsprops.img), whose faces have a fuller rig.

  • Translations, rotations, the mover and the cutscene camera (position, rotation, field of view) are read, also in animations longer than eight seconds, which the game stores in blocks of 240 frames. A few tracks of other values that move no bone (flags and weights for the game) are skipped.
  • Faces: facials@… (moods, gestures, pain, looks) and visemes@… (mouth shapes for speech) move the face bones like any other animation. The …_lo dictionaries fit the peds' face rig, the …_hi ones the cutscene characters': selecting one offers the fitting models.
  • The cutscene characters' skin shaders (gta_ped_skin…) keep other data in the texture's alpha channel; OpenRAGE draws them opaque (also in the glTF export), so their heads show.
  • Twist and roll helper bones follow the bone they rest on, keeping their own turn, so arms and wrists stay in one piece.
openrage clips <path to .wad>
openrage model <ped> --anim <wad>:<clip>[@seconds] --render pose.png
openrage model pc/anim/cutsprops.img/cs_andrei.wdd --anim "pc/anim/anim.img/facials@m_hi.wad:angry_c@0.6" --render angry.png

Checked: 1,772 dictionaries, 22,866 animations, every frame evaluated, no errors.

Cutscenes

A cutscene (.cut in pc/anim/cuts.img, and the episodes' own) is a text file; double-clicking it plays it in the scene window, the way GTA V cutscenes play. Its sections (b_1_0.wad, b_1_1.wad, …) run one after another:

  • The cast: the cutscene characters and props from cutsprops.img, other people from componentpeds.img, vehicles and map objects by name. The player is put together from playerped.rpf — Niko, Johnny or Luis, after the episode the cutscene belongs to. People play their body and facial clips; actors a section leaves out are hidden while it plays.
  • Outfits: people wear what the cutscene's [VARIATION] lines give them — which variant of each part (head, upper body, legs, hands, …) and its texture variant — and change them where the cutscene says (a time into the section, or into the cutscene when it is longer than the section).
  • Accessories ([PROPS]): hats, glasses, earrings and watches from the person's prop dictionary (pedprops.img), on the head or wrist they belong to.
  • Vehicle colours ([VEHICLE_DETAILS]) from carcols.dat: the paint materials take the cutscene's colours.
  • The map around it, interiors included, from the episode's placement files. Objects the cutscene replaces with its own copies ([REMOVE], a door that opens, a phone that is picked up) are left out. Sections that move to another place are put where they play.
  • The camera of each section, with its field of view, or a free camera (drag or scroll).
  • Lights: the key, fill and rim lights each section animates ([LIGHTS]): where they are, their colour, reach, intensity and cone, switched on and off as the cutscene does (Lights off in the window).
  • Sound from pc/audio/sfx/cutscenes.rpf (the episodes' EP1_SFX.rpf, EP2_SFX.rpf): the streams are decoded (IMA ADPCM, three channels — middle, left, right — mixed to stereo) and play with the scene, following pause and the time slider (Sound off in the window). A section that names no sound lets the one before run on, and so does a sound the game lacks.
  • Subtitles from the episode's american.gxt, each part of a cutscene put together from several with its own timing and text table.
  • Part cutscenes (y1_aap2, rb03p2, gt10_p1): when the game lacks their own sound or texts, they take those of the whole cutscene they are cut from, from where they start in it.

The text stays reachable through the context menu (Open in text editor).

openrage cutscene pc/anim/cuts.img/b_1.cut [--models] [--map 40]   # sections, cast, subtitles; outfits, map
openrage verify --cutscenes                    # every .cut: sections, clips, camera and models

Checked: 344 cutscenes (8.6 hours, 810 sections, 2,973 actors), every model found; every cutscene has sound but TBoGT/…/gt11_xa.cut, which also lacks its animation (gt11_xa_0.wad); every subtitle has its text; 237 of 238 accessories found (the glasses em_7.cut gives Elizabeta are in no prop dictionary); int_ae.cut names a clip its dictionary does not have. Particle effects ([EFFECTS]) come from the episode's effect lists (pc/data/effects/*.wpfl); all 852 the cutscenes name are found, but particles drawn as models (muzzle prongs, debris) are not shown.

Editing

GTA IV has no mods folder. With FusionFix installed, the game loads files from the update folder next to GTAIV.exe in place of the originals at the same path, so update/pc/models/cdimages/vehicles.img replaces pc/models/cdimages/vehicles.img. OpenRAGE writes every change there, as it uses the mods folder for GTA V; the game folder itself stays untouched. Without FusionFix the game ignores the update folder, and OpenRAGE says so when you make a change.

  • Archives (.img, .rpf): the first change copies the whole archive into the update folder; that copy is edited from then on. Import, replace, rename and remove entries as in GTA V; .rpf archives also have folders. Resources (.wtd, .wdr, .wft, …) keep their type and flags from their header. The table of an .rpf is written the way the game's own are (same order, encrypted again with the key from your GTAIV.exe); openrage verify --rebuild checks this against every .rpf of the game without writing anything.
  • Audio (.rpf, RPF3): these archives store only a hash of each name (joaat of the lower-case name); OpenRAGE shows the names the game's audio configuration gives. Replace an entry by importing a file under its name (or its hash, 061b65da); a new entry's name is hashed, and OpenRAGE remembers it (in update/.openrage/audio-names.txt) so it shows by name from then on.
  • Loose files (.dat, .ide, .gxt, …) are written to the update folder under the same path.
  • Texts: .gxt files open in the text editor and save into the update folder.
  • Changes and history: Changes lists every file and archive entry that differs from the game, History every change OpenRAGE made; all of them can be undone. The browser hides the update folder and shows its files in place of the originals.
openrage put admiral.wtd pc/models/cdimages/vehicles.img/       # import into a copy of the archive in update/
openrage mv pc/models/cdimages/vehicles.img/a.wft pc/models/cdimages/vehicles.img/b.wft
openrage rm pc/models/cdimages/vehicles.img/biff.wft
openrage put niko_feet.wdr pc/models/cdimages/playerped.rpf/feet_000_u.wdr   # .rpf archives work the same way
openrage put music_ringtones pc/audio/sfx/general.rpf/general/              # audio: by name (or by hash)
openrage put handling.dat common/data/                          # a loose file, written to update/common/data/
openrage mods --changes                                         # everything that differs from the game
openrage history
openrage undo

Writing into the game files

Without FusionFix, or if you prefer it, changes can go into the game's own files instead. Tick Write directly into the game files in the Unlock editing dialog, or run openrage write-target game; openrage write-target update switches back. The choice is remembered per game.

  • Before a game file is changed for the first time, OpenRAGE keeps its original in update/.openrage/originals/ (the game does not load anything from there). Make sure there is room for a copy of each archive you change.
  • Every change is still recorded in History and can be undone step by step. Changes lists them as "in the game".
  • History → Restore game files (or openrage originals --restore-all) puts every kept original back; the changes made to those files then leave the history.
  • If the update folder already holds a copy of a file, OpenRAGE refuses to change the game's own file: the game would load the copy, not your change. Change the copy, or remove it first.
openrage write-target game                                      # changes go into the game files from now on
openrage put admiral.wtd pc/models/cdimages/vehicles.img/       # edits pc/models/cdimages/vehicles.img itself
openrage originals                                              # files whose originals are kept
openrage originals --restore pc/models/cdimages/vehicles.img    # put one original back (or --restore-all)
openrage write-target update                                    # back to the update folder