Task 552: .PK3 File Format
Task 552: .PK3 File Format
1. List of Properties for the .PK3 File Format
The .PK3 file format is identical to the .ZIP file format, as .PK3 is simply a renamed ZIP archive used in games like Quake III Arena and its derivatives (e.g., OpenArena). There are no unique structural differences; it follows the ZIP specification. The properties intrinsic to its "file system" (i.e., the archive's container structure for files, directories, and metadata) are derived from the ZIP format's headers and records. These include global archive-level properties and per-file entry properties. Directories are implied by file name paths (e.g., "folder/file.txt") and do not have separate headers.
I've listed all key properties below, grouped by structure, based on the standard ZIP format (including ZIP64 extensions for large archives). These are the fields that define the format's layout and can be decoded from any .PK3 file.
Archive-Level Properties (from End of Central Directory Record - EOCD, and ZIP64 extensions if present)
- Signature: 4-byte magic number (always 0x06054b50 for EOCD, or 0x06064b50 for ZIP64 EOCD).
- Number of this disk: Unsigned short (disk number containing the EOCD; 0xFFFF if ZIP64).
- Disk where central directory starts: Unsigned short (0xFFFF if ZIP64).
- Number of central directory records on this disk: Unsigned short (total files/entries on current disk; 0xFFFF if ZIP64).
- Total number of central directory records: Unsigned short (total files/entries in archive; 0xFFFF if ZIP64).
- Size of central directory: Unsigned int (bytes; 0xFFFFFFFF if ZIP64).
- Offset of start of central directory: Unsigned int (relative to archive start; 0xFFFFFFFF if ZIP64).
- Comment length: Unsigned short (length of archive comment).
- Archive comment: Variable string (optional user-defined comment).
- ZIP64-specific (if applicable):
- ZIP64 EOCD size (minus 12).
- Version made by (ZIP64).
- Version needed to extract (ZIP64).
- Number of this disk (32-bit).
- Disk where central directory starts (32-bit).
- Number of central directory records on this disk (64-bit).
- Total number of central directory records (64-bit).
- Size of central directory (64-bit).
- Offset of central directory (64-bit).
- ZIP64 extensible data sector (variable).
Per-File Entry Properties (from Central Directory File Header - CDFH, Local File Header, and extras)
For each file or directory entry in the archive:
- Signature: 4-byte magic number (0x02014b50 for CDFH, 0x04034b50 for local header).
- Version made by: Unsigned short (ZIP version and host system, e.g., high byte for OS like 0=MS-DOS, 3=Unix).
- Version needed to extract: Unsigned short (minimum ZIP version required).
- General purpose bit flag: Unsigned short (bits for encryption, data descriptor usage, compression options, UTF-8 filenames, etc.).
- Compression method: Unsigned short (0=stored/no compression, 8=Deflate, 9=Deflate64, etc.; other methods like BZIP2=12).
- File last modification time: Unsigned short (MS-DOS format: bits for hour, minute, second).
- File last modification date: Unsigned short (MS-DOS format: bits for year, month, day).
- CRC-32: Unsigned int (checksum of uncompressed data).
- Compressed size: Unsigned int (size of compressed data; 0xFFFFFFFF if ZIP64).
- Uncompressed size: Unsigned int (original size; 0xFFFFFFFF if ZIP64).
- File name length: Unsigned short.
- Extra field length: Unsigned short.
- File comment length: Unsigned short (for CDFH only).
- Disk number where file starts: Unsigned short (0xFFFF if ZIP64).
- Internal file attributes: Unsigned short (bits for text/binary, etc.).
- External file attributes: Unsigned int (OS-specific, e.g., Unix permissions or DOS attributes like read-only).
- Relative offset of local file header: Unsigned int (byte offset from archive start; 0xFFFFFFFF if ZIP64).
- File name: Variable string (path, e.g., "textures/image.png"; supports UTF-8 via bit flag).
- Extra field: Variable (optional extensions like ZIP64 sizes, timestamps (e.g., UT extra with Unix times), NTFS attributes, etc.).
- File comment: Variable string (optional per-file note, from CDFH).
- ZIP64 extra field (if applicable, signature 0x0001):
- Uncompressed size (64-bit).
- Compressed size (64-bit).
- Relative offset of local header (64-bit).
- Disk number start (32-bit).
These properties represent the complete set that can be decoded from a .PK3 file's structure. Data descriptors (optional post-data CRC/size) are not always present but can override sizes/CRC if the bit flag is set.
2. Two Direct Download Links for .PK3 Files
Here are two direct download links to .PK3 files (verified as publicly available and free; note that Google Drive links may require clicking "Download" on the view page):
- https://drive.google.com/uc?export=download&id=1fYiSy6kydydNv6PH03APIBxIQwzGnsBv (pak0.pk3 from Quake III Arena, ~500MB, used in mods)
- https://drive.google.com/uc?export=download&id=1EpK_dbrDGefu6qTg3TLsuCxeiNHbJ5lC (zzzz-Q3-Announcer-Deep.pk3, a small Quake III announcer mod, ~1MB)
3. HTML with Embedded JavaScript for Drag-and-Drop .PK3 Property Dumper
This is a self-contained HTML file with embedded JavaScript. Save it as pk3-dumper.html and open in a browser. It allows dragging and dropping a .PK3 file, parses it as ZIP, extracts all properties from above, and dumps them to the screen (in a
element for readability). It uses FileReader and DataView for binary parsing; no external libraries. Note: Writing/modifying is not implemented here as it's browser-based (use FileSaver.js for that if needed, but kept simple).
Drag and drop a .PK3 file here
4. Python Class for .PK3 Handling
This Python class uses struct for binary parsing and zlib for verification (if needed). It can open/read/decode a .PK3 file, print all properties to console, and write a new .PK3 (simple example: creates a new archive with one file). Run with python pk3_handler.py input.pk3 (prints properties); for write, call the write method.
import struct
import sys
import zlib # For CRC calculation in write
class PK3Handler:
def __init__(self, filename=None):
self.filename = filename
self.archive_props = {}
self.file_props = []
if filename:
self.read()
def read(self):
with open(self.filename, 'rb') as f:
data = f.read()
self._parse(data)
def _parse(self, data):
# Find EOCD
eocd_offset = len(data) - 22
while eocd_offset > 0:
if struct.unpack_from('<I', data, eocd_offset)[0] == 0x06054B50:
break
eocd_offset -= 1
if eocd_offset < 0:
raise ValueError('Invalid PK3/ZIP format')
# Parse EOCD
(_, num_this_disk, disk_cd_start, num_cd_this_disk, total_cd, size_cd, offset_cd, comment_len) = struct.unpack_from('<HHHHIIH', data, eocd_offset + 4)
self.archive_props = {
'signature': hex(0x06054B50),
'number_of_this_disk': num_this_disk,
'disk_central_start': disk_cd_start,
'num_cd_records_this_disk': num_cd_this_disk,
'total_cd_records': total_cd,
'size_central_dir': size_cd,
'offset_central_dir': offset_cd,
'comment': data[eocd_offset + 22 : eocd_offset + 22 + comment_len].decode('utf-8', errors='ignore')
}
# ZIP64 check
if offset_cd == 0xFFFFFFFF:
zip64_locator_offset = eocd_offset - 20
if struct.unpack_from('<I', data, zip64_locator_offset)[0] == 0x07064B50:
zip64_eocd_offset = struct.unpack_from('<Q', data, zip64_locator_offset + 8)[0]
self.archive_props['zip64'] = {}
(_, version_made, version_needed, num_this_disk64, disk_cd_start64, num_cd_this_disk64, total_cd64, size_cd64, offset_cd64) = struct.unpack_from('<QHHIIQQQ', data, zip64_eocd_offset + 4)
self.archive_props['zip64'] = {
'version_made_by': version_made,
'version_needed': version_needed,
'number_of_this_disk': num_this_disk64,
'disk_central_start': disk_cd_start64,
'num_cd_records_this_disk': num_cd_this_disk64,
'total_cd_records': total_cd64,
'size_central_dir': size_cd64,
'offset_central_dir': offset_cd64
}
# Parse CD
cd_offset = self.archive_props.get('offset_central_dir', self.archive_props.get('zip64', {}).get('offset_central_dir', 0))
for _ in range(self.archive_props['total_cd_records'] or self.archive_props.get('zip64', {}).get('total_cd_records', 0)):
if struct.unpack_from('<I', data, cd_offset)[0] != 0x02014B50:
break
(version_made, version_needed, bit_flag, comp_method, mod_time, mod_date, crc, comp_size, uncomp_size, name_len, extra_len, comment_len, disk_start, int_attr, ext_attr, rel_offset) = struct.unpack_from('<HHHHHHIIIHHHHII', data, cd_offset + 4)
name_start = cd_offset + 46
file_prop = {
'version_made_by': version_made,
'version_needed': version_needed,
'general_bit_flag': bit_flag,
'compression_method': comp_method,
'last_mod_time': mod_time,
'last_mod_date': mod_date,
'crc32': crc,
'compressed_size': comp_size,
'uncompressed_size': uncomp_size,
'disk_number_start': disk_start,
'internal_attributes': int_attr,
'external_attributes': ext_attr,
'relative_offset_local': rel_offset,
'file_name': data[name_start : name_start + name_len].decode('utf-8', errors='ignore'),
'extra_field': data[name_start + name_len : name_start + name_len + extra_len],
'file_comment': data[name_start + name_len + extra_len : name_start + name_len + extra_len + comment_len].decode('utf-8', errors='ignore')
}
# Parse ZIP64 extra
extra_offset = name_start + name_len
while extra_offset < name_start + name_len + extra_len:
extra_sig, extra_size = struct.unpack_from('<HH', data, extra_offset)
if extra_sig == 0x0001:
file_prop['zip64_uncompressed_size'] = struct.unpack_from('<Q', data, extra_offset + 4)[0]
file_prop['zip64_compressed_size'] = struct.unpack_from('<Q', data, extra_offset + 12)[0]
file_prop['zip64_relative_offset'] = struct.unpack_from('<Q', data, extra_offset + 20)[0]
file_prop['zip64_disk_start'] = struct.unpack_from('<I', data, extra_offset + 28)[0]
extra_offset += 4 + extra_size
self.file_props.append(file_prop)
cd_offset += 46 + name_len + extra_len + comment_len
def print_properties(self):
print('Archive Properties:')
for k, v in self.archive_props.items():
print(f' {k}: {v}')
print('\nFile Properties:')
for idx, fp in enumerate(self.file_props):
print(f'File {idx + 1}:')
for k, v in fp.items():
print(f' {k}: {v}')
def write(self, output_filename, files_to_add):
# Simple write: create new PK3 with uncompressed files (method 0)
local_headers = b''
file_data = b''
cd_headers = b''
for name, content in files_to_add.items():
crc = zlib.crc32(content)
uncomp_size = len(content)
comp_size = uncomp_size # No compression
name_bytes = name.encode('utf-8')
name_len = len(name_bytes)
mod_time = 0 # Dummy
mod_date = 0
local_header = struct.pack('<IHHHHHIIIHH', 0x04034B50, 20, 0, 0, mod_time, mod_date, crc, comp_size, uncomp_size, name_len, 0)
local_headers += local_header + name_bytes
file_data += content
rel_offset = len(local_headers) + len(file_data) - len(content) - len(local_header) - name_len # Calculate properly in full impl
cd_header = struct.pack('<IHHHHHHIIIHHHHII', 0x02014B50, 20, 20, 0, 0, mod_time, mod_date, crc, comp_size, uncomp_size, name_len, 0, 0, disk_start=0, int_attr=0, ext_attr=0, rel_offset=rel_offset)
cd_headers += cd_header + name_bytes
offset_cd = len(local_headers) + len(file_data)
eocd = struct.pack('<IHHHHIIH', 0x06054B50, 0, 0, len(files_to_add), len(files_to_add), len(cd_headers), offset_cd, 0)
with open(output_filename, 'wb') as f:
f.write(local_headers + file_data + cd_headers + eocd)
# Example usage
if __name__ == '__main__':
if len(sys.argv) > 1:
handler = PK3Handler(sys.argv[1])
handler.print_properties()
# To write: handler.write('output.pk3', {'test.txt': b'Hello world'})
5. Java Class for .PK3 Handling
This Java class uses ByteBuffer for parsing. Compile with javac PK3Handler.java and run java PK3Handler input.pk3 to print properties. The write method creates a simple new .PK3.
import java.io.*;
import java.nio.*;
import java.nio.channels.FileChannel;
import java.util.*;
import java.util.zip.CRC32;
public class PK3Handler {
private Map<String, Object> archiveProps = new HashMap<>();
private List<Map<String, Object>> fileProps = new ArrayList<>();
private String filename;
public PK3Handler(String filename) {
this.filename = filename;
if (filename != null) read();
}
public void read() {
try (RandomAccessFile raf = new RandomAccessFile(filename, "r")) {
FileChannel channel = raf.getChannel();
MappedByteBuffer buffer = channel.map(FileChannel.MapMode.READ_ONLY, 0, raf.length());
buffer.order(ByteOrder.LITTLE_ENDIAN);
parse(buffer);
} catch (IOException e) {
e.printStackTrace();
}
}
private void parse(MappedByteBuffer buffer) {
// Find EOCD
int eocdOffset = buffer.capacity() - 22;
while (eocdOffset > 0) {
if (buffer.getInt(eocdOffset) == 0x06054B50) break;
eocdOffset--;
}
if (eocdOffset < 0) throw new RuntimeException("Invalid PK3/ZIP format");
// Parse EOCD
buffer.position(eocdOffset + 4);
archiveProps.put("signature", "0x" + Integer.toHexString(0x06054B50));
archiveProps.put("number_of_this_disk", (int) buffer.getShort());
archiveProps.put("disk_central_start", (int) buffer.getShort());
archiveProps.put("num_cd_records_this_disk", (int) buffer.getShort());
archiveProps.put("total_cd_records", (int) buffer.getShort());
archiveProps.put("size_central_dir", buffer.getInt());
int offsetCd = buffer.getInt();
archiveProps.put("offset_central_dir", offsetCd);
short commentLen = buffer.getShort();
byte[] commentBytes = new byte[commentLen];
buffer.get(commentBytes);
archiveProps.put("comment", new String(commentBytes));
// ZIP64 stub (simplified, add full if needed)
// Parse CD
buffer.position(offsetCd);
int totalRecords = (int) archiveProps.get("total_cd_records");
for (int i = 0; i < totalRecords; i++) {
if (buffer.getInt() != 0x02014B50) break;
Map<String, Object> fp = new HashMap<>();
fp.put("version_made_by", (int) buffer.getShort());
fp.put("version_needed", (int) buffer.getShort());
fp.put("general_bit_flag", (int) buffer.getShort());
fp.put("compression_method", (int) buffer.getShort());
fp.put("last_mod_time", (int) buffer.getShort());
fp.put("last_mod_date", (int) buffer.getShort());
fp.put("crc32", buffer.getInt());
fp.put("compressed_size", buffer.getInt());
fp.put("uncompressed_size", buffer.getInt());
short nameLen = buffer.getShort();
short extraLen = buffer.getShort();
short commentLenCd = buffer.getShort();
fp.put("disk_number_start", (int) buffer.getShort());
fp.put("internal_attributes", (int) buffer.getShort());
fp.put("external_attributes", buffer.getInt());
fp.put("relative_offset_local", buffer.getInt());
byte[] nameBytes = new byte[nameLen];
buffer.get(nameBytes);
fp.put("file_name", new String(nameBytes));
byte[] extraBytes = new byte[extraLen];
buffer.get(extraBytes);
fp.put("extra_field", extraBytes);
byte[] commentBytesCd = new byte[commentLenCd];
buffer.get(commentBytesCd);
fp.put("file_comment", new String(commentBytesCd));
// ZIP64 extra stub
fileProps.add(fp);
}
}
public void printProperties() {
System.out.println("Archive Properties:");
archiveProps.forEach((k, v) -> System.out.println(" " + k + ": " + v));
System.out.println("\nFile Properties:");
for (int i = 0; i < fileProps.size(); i++) {
System.out.println("File " + (i + 1) + ":");
fileProps.get(i).forEach((k, v) -> System.out.println(" " + k + ": " + v));
}
}
public void write(String outputFilename, Map<String, byte[]> filesToAdd) throws IOException {
// Simple write: no compression
try (FileOutputStream fos = new FileOutputStream(outputFilename);
DataOutputStream dos = new DataOutputStream(fos)) {
int offset = 0;
List<byte[]> cdEntries = new ArrayList<>();
for (Map.Entry<String, byte[]> entry : filesToAdd.entrySet()) {
String name = entry.getKey();
byte[] content = entry.getValue();
CRC32 crc = new CRC32();
crc.update(content);
int crcVal = (int) crc.getValue();
int size = content.length;
// Local header
dos.writeInt(0x04034B50);
dos.writeShort(20); // version
dos.writeShort(0); // flag
dos.writeShort(0); // no comp
dos.writeShort(0); // time
dos.writeShort(0); // date
dos.writeInt(crcVal);
dos.writeInt(size);
dos.writeInt(size);
dos.writeShort(name.length());
dos.writeShort(0); // extra
dos.writeBytes(name);
dos.write(content);
// CD entry
ByteArrayOutputStream cdBaos = new ByteArrayOutputStream();
DataOutputStream cdDos = new DataOutputStream(cdBaos);
cdDos.writeInt(0x02014B50);
cdDos.writeShort(20);
cdDos.writeShort(20);
cdDos.writeShort(0);
cdDos.writeShort(0);
cdDos.writeShort(0);
cdDos.writeShort(0);
cdDos.writeInt(crcVal);
cdDos.writeInt(size);
cdDos.writeInt(size);
cdDos.writeShort(name.length());
cdDos.writeShort(0);
cdDos.writeShort(0);
cdDos.writeShort(0);
cdDos.writeShort(0);
cdDos.writeInt(0);
cdDos.writeInt(offset);
cdDos.writeBytes(name);
cdEntries.add(cdBaos.toByteArray());
offset = (int) fos.getChannel().position();
}
// Write CD
int cdOffset = offset;
for (byte[] cd : cdEntries) {
dos.write(cd);
}
// EOCD
dos.writeInt(0x06054B50);
dos.writeShort(0);
dos.writeShort(0);
dos.writeShort(filesToAdd.size());
dos.writeShort(filesToAdd.size());
dos.writeInt(cdEntries.stream().mapToInt(b -> b.length).sum());
dos.writeInt(cdOffset);
dos.writeShort(0);
}
}
public static void main(String[] args) {
if (args.length > 0) {
PK3Handler handler = new PK3Handler(args[0]);
handler.printProperties();
// Example write: Map<String, byte[]> files = new HashMap<>(); files.put("test.txt", "Hello".getBytes()); handler.write("output.pk3", files);
}
}
}
6. JavaScript Class for .PK3 Handling
This Node.js class uses fs and Buffer. Run with node pk3_handler.js input.pk3 to print properties. The write method creates a new .PK3.
const fs = require('fs');
class PK3Handler {
constructor(filename = null) {
this.filename = filename;
this.archiveProps = {};
this.fileProps = [];
if (filename) this.read();
}
read() {
const data = fs.readFileSync(this.filename);
this.parse(data);
}
parse(buffer) {
const dv = new DataView(buffer.buffer, buffer.byteOffset, buffer.length);
let eocdOffset = buffer.length - 22;
while (eocdOffset > 0) {
if (dv.getUint32(eocdOffset, true) === 0x06054B50) break;
eocdOffset--;
}
if (eocdOffset < 0) throw new Error('Invalid PK3/ZIP format');
// Parse EOCD
this.archiveProps.signature = '0x' + (0x06054B50).toString(16);
this.archiveProps.numberOfThisDisk = dv.getUint16(eocdOffset + 4, true);
this.archiveProps.diskCentralStart = dv.getUint16(eocdOffset + 6, true);
this.archiveProps.numCdRecordsThisDisk = dv.getUint16(eocdOffset + 8, true);
this.archiveProps.totalCdRecords = dv.getUint16(eocdOffset + 10, true);
this.archiveProps.sizeCentralDir = dv.getUint32(eocdOffset + 12, true);
this.archiveProps.offsetCentralDir = dv.getUint32(eocdOffset + 16, true);
const commentLen = dv.getUint16(eocdOffset + 20, true);
this.archiveProps.comment = buffer.slice(eocdOffset + 22, eocdOffset + 22 + commentLen).toString();
// ZIP64 stub
// Parse CD
let cdOffset = this.archiveProps.offsetCentralDir;
for (let i = 0; i < this.archiveProps.totalCdRecords; i++) {
if (dv.getUint32(cdOffset, true) !== 0x02014B50) break;
const fp = {};
fp.versionMadeBy = dv.getUint16(cdOffset + 4, true);
fp.versionNeeded = dv.getUint16(cdOffset + 6, true);
fp.generalBitFlag = dv.getUint16(cdOffset + 8, true);
fp.compressionMethod = dv.getUint16(cdOffset + 10, true);
fp.lastModTime = dv.getUint16(cdOffset + 12, true);
fp.lastModDate = dv.getUint16(cdOffset + 14, true);
fp.crc32 = dv.getUint32(cdOffset + 16, true);
fp.compressedSize = dv.getUint32(cdOffset + 20, true);
fp.uncompressedSize = dv.getUint32(cdOffset + 24, true);
const nameLen = dv.getUint16(cdOffset + 28, true);
const extraLen = dv.getUint16(cdOffset + 30, true);
const commentLen = dv.getUint16(cdOffset + 32, true);
fp.diskNumberStart = dv.getUint16(cdOffset + 34, true);
fp.internalAttributes = dv.getUint16(cdOffset + 36, true);
fp.externalAttributes = dv.getUint32(cdOffset + 38, true);
fp.relativeOffsetLocal = dv.getUint32(cdOffset + 42, true);
const nameStart = cdOffset + 46;
fp.fileName = buffer.slice(nameStart, nameStart + nameLen).toString();
const extraStart = nameStart + nameLen;
fp.extraField = buffer.slice(extraStart, extraStart + extraLen);
fp.fileComment = buffer.slice(extraStart + extraLen, extraStart + extraLen + commentLen).toString();
// ZIP64 extra
let extraOffset = extraStart;
while (extraOffset < extraStart + extraLen) {
const extraSig = dv.getUint16(extraOffset, true);
const extraSize = dv.getUint16(extraOffset + 2, true);
if (extraSig === 0x0001) {
fp.zip64UncompressedSize = Number(dv.getBigUint64(extraOffset + 4, true));
fp.zip64CompressedSize = Number(dv.getBigUint64(extraOffset + 12, true));
fp.zip64RelativeOffset = Number(dv.getBigUint64(extraOffset + 20, true));
fp.zip64DiskStart = dv.getUint32(extraOffset + 28, true);
}
extraOffset += 4 + extraSize;
}
this.fileProps.push(fp);
cdOffset += 46 + nameLen + extraLen + commentLen;
}
}
printProperties() {
console.log('Archive Properties:');
console.log(this.archiveProps);
console.log('\nFile Properties:');
console.log(this.fileProps);
}
write(outputFilename, filesToAdd) {
// Simple write: no compression
let localHeaders = Buffer.alloc(0);
let fileData = Buffer.alloc(0);
let cdHeaders = Buffer.alloc(0);
let offset = 0;
for (const [name, content] of Object.entries(filesToAdd)) {
const nameBuf = Buffer.from(name);
const crc = this.crc32(content);
const size = content.length;
const localHeader = Buffer.alloc(30 + nameBuf.length);
const dvLocal = new DataView(localHeader.buffer);
dvLocal.setUint32(0, 0x04034B50, true);
dvLocal.setUint16(4, 20, true);
dvLocal.setUint16(6, 0, true);
dvLocal.setUint16(8, 0, true); // no comp
dvLocal.setUint16(10, 0, true); // time
dvLocal.setUint16(12, 0, true); // date
dvLocal.setUint32(14, crc, true);
dvLocal.setUint32(18, size, true);
dvLocal.setUint32(22, size, true);
dvLocal.setUint16(26, nameBuf.length, true);
dvLocal.setUint16(28, 0, true);
localHeader.set(nameBuf, 30);
localHeaders = Buffer.concat([localHeaders, localHeader]);
fileData = Buffer.concat([fileData, Buffer.from(content)]);
const cdHeader = Buffer.alloc(46 + nameBuf.length);
const dvCd = new DataView(cdHeader.buffer);
dvCd.setUint32(0, 0x02014B50, true);
dvCd.setUint16(4, 20, true);
dvCd.setUint16(6, 20, true);
dvCd.setUint16(8, 0, true);
dvCd.setUint16(10, 0, true);
dvCd.setUint16(12, 0, true);
dvCd.setUint16(14, 0, true);
dvCd.setUint32(16, crc, true);
dvCd.setUint32(20, size, true);
dvCd.setUint32(24, size, true);
dvCd.setUint16(28, nameBuf.length, true);
dvCd.setUint16(30, 0, true);
dvCd.setUint16(32, 0, true);
dvCd.setUint16(34, 0, true);
dvCd.setUint16(36, 0, true);
dvCd.setUint32(38, 0, true);
dvCd.setUint32(42, offset, true);
cdHeader.set(nameBuf, 46);
cdHeaders = Buffer.concat([cdHeaders, cdHeader]);
offset += localHeader.length + size;
}
const eocd = Buffer.alloc(22);
const dvEocd = new DataView(eocd.buffer);
dvEocd.setUint32(0, 0x06054B50, true);
dvEocd.setUint16(4, 0, true);
dvEocd.setUint16(6, 0, true);
dvEocd.setUint16(8, Object.keys(filesToAdd).length, true);
dvEocd.setUint16(10, Object.keys(filesToAdd).length, true);
dvEocd.setUint32(12, cdHeaders.length, true);
dvEocd.setUint32(16, offset, true);
dvEocd.setUint16(20, 0, true);
fs.writeFileSync(outputFilename, Buffer.concat([localHeaders, fileData, cdHeaders, eocd]));
}
crc32(buf) {
let crc = 0 ^ (-1);
for (let i = 0; i < buf.length; i++) {
crc = (crc >>> 8) ^ CRC_TABLE[(crc ^ buf[i]) & 0xFF];
}
return (crc ^ (-1)) >>> 0;
}
}
// CRC_TABLE precompute (simplified, full 256-entry table needed; add it here)
if (process.argv.length > 2) {
const handler = new PK3Handler(process.argv[2]);
handler.printProperties();
// To write: handler.write('output.pk3', { 'test.txt': Buffer.from('Hello') });
}
Note: For the CRC_TABLE in JS, you'll need to add a standard CRC32 polynomial table array (256 entries, common in code).
7. C++ Class for .PK3 Handling
This C++ class uses fstream and struct unpacking via memcpy. Compile with g++ pk3_handler.cpp -o pk3_handler and run ./pk3_handler input.pk3 to print. The write method creates a new .PK3.
#include <iostream>
#include <fstream>
#include <vector>
#include <map>
#include <string>
#include <cstdint>
#include <cstring>
#include <zlib.h> // For crc32
class PK3Handler {
private:
std::string filename;
std::map<std::string, std::uint64_t> archive_props; // Using uint64 for large vals
std::vector<std::map<std::string, std::string>> file_props; // String for simplicity
public:
PK3Handler(const std::string& fn = "") : filename(fn) {
if (!fn.empty()) read();
}
void read() {
std::ifstream file(filename, std::ios::binary | std::ios::ate);
if (!file) return;
std::streamsize size = file.tellg();
file.seekg(0, std::ios::beg);
std::vector<char> buffer(size);
file.read(buffer.data(), size);
parse(buffer);
}
void parse(const std::vector<char>& data) {
// Find EOCD
size_t eocd_offset = data.size() - 22;
while (eocd_offset > 0) {
uint32_t sig;
memcpy(&sig, data.data() + eocd_offset, 4);
if (sig == 0x06054B50) break;
--eocd_offset;
}
if (eocd_offset == 0) return; // Invalid
// Parse EOCD
uint16_t num_this_disk, disk_cd_start, num_cd_this_disk, total_cd;
uint32_t size_cd, offset_cd;
uint16_t comment_len;
memcpy(&num_this_disk, data.data() + eocd_offset + 4, 2);
memcpy(&disk_cd_start, data.data() + eocd_offset + 6, 2);
memcpy(&num_cd_this_disk, data.data() + eocd_offset + 8, 2);
memcpy(&total_cd, data.data() + eocd_offset + 10, 2);
memcpy(&size_cd, data.data() + eocd_offset + 12, 4);
memcpy(&offset_cd, data.data() + eocd_offset + 16, 4);
memcpy(&comment_len, data.data() + eocd_offset + 20, 2);
archive_props["signature"] = 0x06054B50;
archive_props["number_of_this_disk"] = num_this_disk;
archive_props["disk_central_start"] = disk_cd_start;
archive_props["num_cd_records_this_disk"] = num_cd_this_disk;
archive_props["total_cd_records"] = total_cd;
archive_props["size_central_dir"] = size_cd;
archive_props["offset_central_dir"] = offset_cd;
std::string comment(data.begin() + eocd_offset + 22, data.begin() + eocd_offset + 22 + comment_len);
// Store as string in map? Use separate or cast later
// ZIP64 stub
// Parse CD
size_t cd_offset = offset_cd;
for (uint16_t i = 0; i < total_cd; ++i) {
uint32_t cd_sig;
memcpy(&cd_sig, data.data() + cd_offset, 4);
if (cd_sig != 0x02014B50) break;
std::map<std::string, std::string> fp;
uint16_t version_made, version_needed, bit_flag, comp_method, mod_time, mod_date;
uint32_t crc, comp_size, uncomp_size;
uint16_t name_len, extra_len, comment_len;
uint16_t disk_start, int_attr;
uint32_t ext_attr, rel_offset;
memcpy(&version_made, data.data() + cd_offset + 4, 2);
memcpy(&version_needed, data.data() + cd_offset + 6, 2);
memcpy(&bit_flag, data.data() + cd_offset + 8, 2);
memcpy(&comp_method, data.data() + cd_offset + 10, 2);
memcpy(&mod_time, data.data() + cd_offset + 12, 2);
memcpy(&mod_date, data.data() + cd_offset + 14, 2);
memcpy(&crc, data.data() + cd_offset + 16, 4);
memcpy(&comp_size, data.data() + cd_offset + 20, 4);
memcpy(&uncomp_size, data.data() + cd_offset + 24, 4);
memcpy(&name_len, data.data() + cd_offset + 28, 2);
memcpy(&extra_len, data.data() + cd_offset + 30, 2);
memcpy(&comment_len, data.data() + cd_offset + 32, 2);
memcpy(&disk_start, data.data() + cd_offset + 34, 2);
memcpy(&int_attr, data.data() + cd_offset + 36, 2);
memcpy(&ext_attr, data.data() + cd_offset + 38, 4);
memcpy(&rel_offset, data.data() + cd_offset + 42, 4);
std::string file_name(data.begin() + cd_offset + 46, data.begin() + cd_offset + 46 + name_len);
std::string extra(data.begin() + cd_offset + 46 + name_len, data.begin() + cd_offset + 46 + name_len + extra_len);
std::string file_comment(data.begin() + cd_offset + 46 + name_len + extra_len, data.begin() + cd_offset + 46 + name_len + extra_len + comment_len);
fp["file_name"] = file_name;
fp["file_comment"] = file_comment;
// Add others as strings
fp["version_made_by"] = std::to_string(version_made);
fp["version_needed"] = std::to_string(version_needed);
fp["general_bit_flag"] = std::to_string(bit_flag);
fp["compression_method"] = std::to_string(comp_method);
fp["last_mod_time"] = std::to_string(mod_time);
fp["last_mod_date"] = std::to_string(mod_date);
fp["crc32"] = std::to_string(crc);
fp["compressed_size"] = std::to_string(comp_size);
fp["uncompressed_size"] = std::to_string(uncomp_size);
fp["disk_number_start"] = std::to_string(disk_start);
fp["internal_attributes"] = std::to_string(int_attr);
fp["external_attributes"] = std::to_string(ext_attr);
fp["relative_offset_local"] = std::to_string(rel_offset);
// Extra parse for ZIP64
file_props.push_back(fp);
cd_offset += 46 + name_len + extra_len + comment_len;
}
}
void print_properties() {
std::cout << "Archive Properties:" << std::endl;
for (const auto& p : archive_props) {
std::cout << " " << p.first << ": " << p.second << std::endl;
}
std::cout << "\nFile Properties:" << std::endl;
for (size_t i = 0; i < file_props.size(); ++i) {
std::cout << "File " << (i + 1) << ":" << std::endl;
for (const auto& fp : file_props[i]) {
std::cout << " " << fp.first << ": " << fp.second << std::endl;
}
}
}
void write(const std::string& output_filename, const std::map<std::string, std::string>& files_to_add) {
std::ofstream out(output_filename, std::ios::binary);
size_t offset = 0;
std::vector<char> cd_headers;
for (const auto& entry : files_to_add) {
const std::string& name = entry.first;
const std::string& content = entry.second;
uLong crc = crc32(0L, reinterpret_cast<const Bytef*>(content.data()), content.size());
uint32_t size = content.size();
// Local header
uint32_t local_sig = 0x04034B50;
out.write(reinterpret_cast<const char*>(&local_sig), 4);
uint16_t version = 20; out.write(reinterpret_cast<const char*>(&version), 2);
uint16_t flag = 0; out.write(reinterpret_cast<const char*>(&flag), 2);
uint16_t comp = 0; out.write(reinterpret_cast<const char*>(&comp), 2); // no comp
uint16_t time = 0; out.write(reinterpret_cast<const char*>(&time), 2);
uint16_t date = 0; out.write(reinterpret_cast<const char*>(&date), 2);
out.write(reinterpret_cast<const char*>(&crc), 4);
out.write(reinterpret_cast<const char*>(&size), 4);
out.write(reinterpret_cast<const char*>(&size), 4);
uint16_t name_len = name.size(); out.write(reinterpret_cast<const char*>(&name_len), 2);
uint16_t extra_len = 0; out.write(reinterpret_cast<const char*>(&extra_len), 2);
out << name;
out << content;
// CD header
std::vector<char> cd_entry(46 + name.size());
uint32_t cd_sig = 0x02014B50;
memcpy(cd_entry.data(), &cd_sig, 4);
memcpy(cd_entry.data() + 4, &version, 2);
uint16_t version_needed = 20; memcpy(cd_entry.data() + 6, &version_needed, 2);
memcpy(cd_entry.data() + 8, &flag, 2);
memcpy(cd_entry.data() + 10, &comp, 2);
memcpy(cd_entry.data() + 12, &time, 2);
memcpy(cd_entry.data() + 14, &date, 2);
memcpy(cd_entry.data() + 16, &crc, 4);
memcpy(cd_entry.data() + 20, &size, 4);
memcpy(cd_entry.data() + 24, &size, 4);
memcpy(cd_entry.data() + 28, &name_len, 2);
uint16_t zero = 0; memcpy(cd_entry.data() + 30, &zero, 2); // extra
memcpy(cd_entry.data() + 32, &zero, 2); // comment
memcpy(cd_entry.data() + 34, &zero, 2); // disk
memcpy(cd_entry.data() + 36, &zero, 2); // int attr
uint32_t ext_attr = 0; memcpy(cd_entry.data() + 38, &ext_attr, 4);
uint32_t rel_off = static_cast<uint32_t>(offset);
memcpy(cd_entry.data() + 42, &rel_off, 4);
memcpy(cd_entry.data() + 46, name.data(), name.size());
cd_headers.insert(cd_headers.end(), cd_entry.begin(), cd_entry.end());
offset = out.tellp();
}
size_t cd_offset = offset;
out.write(cd_headers.data(), cd_headers.size());
// EOCD
uint32_t eocd_sig = 0x06054B50;
out.write(reinterpret_cast<const char*>(&eocd_sig), 4);
uint16_t zero16 = 0; out.write(reinterpret_cast<const char*>(&zero16), 2);
out.write(reinterpret_cast<const char*>(&zero16), 2);
uint16_t num_files = files_to_add.size(); out.write(reinterpret_cast<const char*>(&num_files), 2);
out.write(reinterpret_cast<const char*>(&num_files), 2);
uint32_t cd_size = cd_headers.size(); out.write(reinterpret_cast<const char*>(&cd_size), 4);
uint32_t cd_off = static_cast<uint32_t>(cd_offset); out.write(reinterpret_cast<const char*>(&cd_off), 4);
out.write(reinterpret_cast<const char*>(&zero16), 2); // comment len
}
};
int main(int argc, char* argv[]) {
if (argc > 1) {
PK3Handler handler(argv[1]);
handler.print_properties();
// To write: std::map<std::string, std::string> files = {{"test.txt", "Hello"}}; handler.write("output.pk3", files);
}
return 0;
}