camoto/manpage/gamearch

From shikadi.net
Jump to: navigation, search

gamearch

Name

gamearch — manipulate file archives used internally by many games

Synopsis

gamearch [options...] archive [actions...]

Description

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

Actions

--list, -l

list files in the archive

--extract-all, -X

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

--extract=file[=dest], -x file[=dest]

extract file from the archive, saving it as dest (or into the current directory if dest is not supplied)

--add=file[=source], -a file[=source]

add source into the archive, storing it as file. If source is not specified, file is read from the current directory. If file already 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.)

--insert=file[=source]:here, -i file[=source]:here

insert source into the archive, storing it at the location currently used by here. here is moved out of the way to make room. If source is not specified, file is read from the current directory. here must 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 file.)

--overwrite=file[=source], -o file[=source]

replace file with the data from newfile. file can be specified as an index (see Notes below.) The filename inside the archive (if any) is unchanged.

--rename=file=newname, -r file=newname

change the name of file to newname. This can be used to move files between folders with archives that support subdirectories. file can be specified as an index (see Notes below.) If newname is specified as an index, the file is moved to that position, pushing the rest of the files down by one.

--delete=file, -d file

remove file from the archive.

--filetype=format, -y format

when using --add or --insert the 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 --list will 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.

--attribute=attr, -b attr

when using --add or --insert the new file can have certain attributes set with this option. This option affects only --add or --insert options 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:

empty

file slot is unused

hidden

file is hidden between two FAT entries

compressed

a compression algorithm has been applied to the file's content

encrypted

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.

--uncompressed-size=integer, -z integer

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 --unfiltered is 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 --add, --insert or --overwrite. This option can only be used with --unfiltered.

Options

--type=format, -t format

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

--list-types

show a list of supported file formats, along with the code to pass to --type.

--unfiltered, -u

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-size will need to be specified if any changes are made to the archive.

--force, -f

open the archive as the given --type, even if it doesn't look like it's in that format.

--verbose, -v

print more detail when listing files with --list.

--script, -s

print output suitable for parsing by a script.

Basic Examples

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

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.

Advanced Examples

gamearch hocus.dat -x @1=first.bin

extract the first file in the archive and save it as first.bin in the current directory.

gamearch duke3d.grp -f -a subway.voc=/tmp/truck.voc

add /tmp/truck.voc into the archive, saving it over the top of subway.voc

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 --list reports 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 tame.mod into the music subdirectory in the archive disk.pod. The file being added (tame.mod) must also reside in a folder called music in 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

moves e1l1.map to 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

inserts data.bin as 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.bin in the process, regardless of its previous name.)

gamearch bash1.dat -a data1.bin --filetype image/bash-sprite -a data2.bin -a data3.bin

appends data1.bin leaving its file type as the default, then appends data2.bin followed by 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

appends data1.bin through data5.bin as follows: data1.bin is normal (no attributes), data2.bin and data3.bin are both compressed, data4.bin is both compressed and hidden, and data5.bin is just hidden.

Notes

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 http://www.shikadi.net/camoto/bugs/

Ask questions about Camoto or modding in general at the RGB Classic Games modding forum

Copyright

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.