Perform the specified
actions on the given
archive. The actions are performed in order
(i.e. the first action specified on the command line is performed first.)
list files in the archive
extract all the files in the archive, saving them into the current directory. If a given file already exists, the newly extracted file will have .1 appended (or .2, .3, etc.)
filefrom the archive, saving it as
dest(or into the current directory if
destis not supplied)
sourceinto the archive, storing it as
sourceis not specified,
fileis read from the current directory. If
filealready exists in the archive, depending on the archive format either the operation will fail (see
--overwrite) or the file will be added with the same name as the existing file. (Those files with identical names will need to be referred to by their index number to avoid ambiguity.)
sourceinto the archive, storing it at the location currently used by
hereis moved out of the way to make room. If
sourceis not specified,
fileis read from the current directory.
heremust already exist in the archive and can be specified by name or index (see Notes below.) After the operation, the newly inserted file exists in the position previously occupied by
here, and the original file is moved one position down (i.e. it is now directly after the new
filewith the data from
filecan be specified as an index (see Notes below.) The filename inside the archive (if any) is unchanged.
change the name of
newname. This can be used to move files between folders with archives that support subdirectories.
filecan be specified as an index (see Notes below.) If
newnameis specified as an index, the file is moved to that position, pushing the rest of the files down by one.
filefrom the archive.
--insertthe file being added can have a type set, for those archives that store this value separately (often when no or incomplete filenames are used.) Valid values depend on the archive format, and viewing the archive with
--listwill show any existing file types. A set file type will remain in effect until changed. Set to a blank string ("") to return to the default file type.
--insertthe new file can have certain attributes set with this option. This option affects only
--insertoptions following it. Multiple attributes can be specified by using the option multiple times. Prefix the attribute with a minus sign to unset it again. Valid attributes are:
file slot is unused
file is hidden between two FAT entries
a compression algorithm has been applied to the file's content
an encryption algorithm has been applied to the file's content
Not all values are supported by a given archive format, and a warning will be shown if an unsupported value is used.
archives that can compress their files often store both the compressed and decompressed file sizes internally. Normally filters are enabled and these values are calculated automatically, but when
--unfilteredis in use, the uncompressed size is not known. This option will set the value to use as the uncompressed size for all subsequent changes. It can be specified multiple times, and would normally be used just prior to any
--overwrite. This option can only be used with
manually specify the archive type. The archive type is normally autodetected, but it needs to be specified for a few archives which lack signatures to identify them by. See
show a list of supported file formats, along with the code to pass to
do not filter files. When extracting files, if they are compressed or encrypted inside the archive, they will not be decompressed or decrypted, and the output file will contain the unmodified data directly from the archive. This allows use of an external utility to perform the decompression, such as gamecomp(1). When adding files to the archive, they will not be compressed/encrypted and must already be in the format the archive expects (i.e. they should be compressed by an external utility first.)
If the file is not encrypted or compressed inside the archive, this option has no effect. If this option is used,
--uncompressed-sizewill need to be specified if any changes are made to the archive.
open the archive as the given
--type, even if it doesn't look like it's in that format.
print more detail when listing files with
print output suitable for parsing by a script.
- gamearch duke3d.grp --list
display all the filenames inside the Duke Nukem 3D group file.
- gamearch duke3d.grp --extract-all
extract all the files inside duke3d.grp into the current directory.
- gamearch wacky.dat --type=dat-wacky --extract-all
extract the contents of
wacky.dat. Since the Wacky Wheels archive format lacks a signature, it can't be autodetected so the archive type must be specified with the
- gamearch duke3d.grp --extract=subway.voc
extract a sound effect into the current directory.
- gamearch duke3d.grp --add=newsong.mid
add a new music track into the group file.
- gamearch duke3d.grp --delete=newsong.mid
delete the file added in the last example.
- gamearch hocus.dat -x @1=first.bin
extract the first file in the archive and save it as
first.binin the current directory.
- gamearch duke3d.grp -f -a subway.voc=/tmp/truck.voc
/tmp/truck.vocinto the archive, saving it over the top of
- gamearch duke3d.grp -x @1.5=hidden.bin
extract the hidden data stored between the first and second files in the archive (only valid if
--listreports hidden data present)
- gamearch duke3d.grp -a @1.5=hidden.bin
add hidden data between the first and second files in the archive (not all archive formats support this)
- gamearch duke3d.grp -a music/newsong.mid
gamearch duke3d.grp -a newsong.mid=music/newsong.mid
the first command fails adding the file, because the .GRP format does not support subdirectories. The second command works as it is specifying a valid alternate name to store in the archive.
- gamearch disk.pod -a music/tame.mod
adds a file called
musicsubdirectory in the archive
disk.pod. The file being added (
tame.mod) must also reside in a folder called
musicin the current directory.
- gamearch disk.pod -a music/tame.mod=tame.mod
same as previous example, except the file being added is now read from the current directory instead
- gamearch duke3d.grp -r e1l1.map=@1
e1l1.mapto be the first file in the archive. The other files are shifted out of the way (so the original first file in the archive becomes the second file.) This is usually only necessary when a game places significance on the positions of files as well as their names (e.g. .wad)
- gamearch duke3d.grp -a data.bin -r data.bin=@5
data.binas the fifth file in the archive, moving the other files out of the way (but not overwriting any of them!)
- gamearch duke3d.grp -f -a @5=data.bin
overwrites the fifth file in the archive with
data.bin(renaming the fifth file to
data.binin the process, regardless of its previous name.)
- gamearch bash1.dat -a data1.bin --filetype image/bash-sprite -a data2.bin -a data3.bin
data1.binleaving its file type as the default, then appends
data3.bin, flagging them both as containing Monster Bash sprite data.
- gamearch bash1.dat -a data1.bin --attribute compressed -a data2.bin -a data3.bin --attribute hidden -a data4.bin --attribute -compressed -a data5.bin
data1.binis normal (no attributes),
data3.binare both compressed,
data4.binis both compressed and hidden, and
data5.binis just hidden.
When a filename refers to an item inside an archive, it can be specified
either by filename, or by index. When using an index, prepend an at-sign
@) before the number. Using an index is most useful
for archives which don't support filenames, or for accessing hidden data
between files in archives which support it.
Exit status is 0 on success, non-zero on failure (1 for bad parameters, 2 for critical errors such as being unable to open the the archive file, 3 for more information needed, 4 for non-critical errors such as being unable to insert one of many files, 5 for uncommon failures like running out of disk space.)
All the file formats supported by this utility are fully documented on the Game Modding Wiki.
Bugs and Questions
Report bugs at https://github.com/Malvineous/libgamearchive/issues
Ask questions about Camoto or modding in general at the RGB Classic Games modding forum
Copyright (c) 2010-2017 Adam Nielsen.
License GPLv3+: GNU GPL version 3 or later
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.