͗j ddlZddlZddlZddlZddlmZddlmZddlmZddl m Z ddl m Z m Z mZmZmZmZmZddlmZe Gd d Zd ed eeeeffd ZededDZded efdZGddZy)N)fnmatch)md5)Path) dataclass)DictOptionalBinaryIOListTupleUnionAny)read_cstring_streamcreZdZUdZeed<eed<eed<eed<eed<dZeeed<e d e d dfd Z y) VPKDirectoryEntrya Metadata for a file entry within a VPK archive. Contains information needed to locate and extract the file data. Attributes: crc: CRC32 checksum of the file data. preload_bytes: Number of bytes stored inline in the directory. archive_index: Which archive file contains the data (0x7FFF = directory file). entry_offset: Byte offset within the archive file. entry_length: Size of the file data in bytes. preload_data: Inline data stored in the directory (if any). crc preload_bytes archive_index entry_offset entry_lengthN preload_datafilereturnc^tjd|jd}||d|d|d|d|d}|jdkDr |j|j|_tjd |jdd}|d k7rt d |d |S) N+>!?E ]]416q9   CJsCST U ) __name__ __module__ __qualname____doc__int__annotations__rrbytes classmethodr r,r-r+rrsU  H$(L(5/(X*=r-rfilepathrc|jddj}|jd}|dk\r|d|}||dzd}nd}|}|jd}|dkDr|d|}||dzd}n|}d}|||fS)zParse a file path into VPK components (extension, directory, filename). Also normalizes paths to lowercase as Source engine VPK files use lowercase filenames. \/rNr .)replacelowerrfind)r7 last_slash directory filename_extlast_dotfilename extensions r+_parse_vpk_pathrF<s c*002H$JQ[j)  Q 01   !!#&H!| * A0  i ))r-c#<K|]}d|cxkrdkrn|yw) ~Nr6).0bs r+ rLVsE*QR1^^q*s rc t|d}|jdt}|rC|sA|jdtt dd}t d|j |jdS)ztRead a null-terminated ASCII string, filtering non-printable bytes (paranoia for corrupt VPK directory entries).T)chunkedNrHz&[VPK] All chars filtered, bad_result: ascii)r translate_NON_PRINTABLEr4ranger&hexdecode)rrawresultbads r+_read_null_stringrZYse dD 1C ]]4 0F 6mmD%b#"78 6swwykBC == !!r-c LeZdZdZd/deeefdefdZdZ d0dZ de fdZ d e defd Z d Zd Zd e d e de deefdZ d1deedeedeefdZdedeefdZdedeefdZdedeeeeeffdZdedeeefdefdZ d2dedededefdZe d3deeefd eeefd!e defd"Zed#Zed4d$Z ed3d%Z!ed&Z"ed'Z#ed(Z$d5d)Z% d3d*eeefdeede dzfd+Z&dedeefd,Z'dedefd-Z(dedee)ee*ffd.Z+y)6VPKFilea5A parser for Valve Package (VPK) files. VPK files are Valve's archive format used in Source engine games to store game assets like textures, models, sounds, and scripts. Args: vpk_path: Path to the VPK file. Can be a single .vpk file or a _dir.vpk file for multi-file archives. Accepts str or Path objects. auto_parse: Whether to automatically parse the directory on initialization. Defaults to True for convenience. Example: >>> vpk = VPKFile("pak01_dir.vpk") # Auto-parses by default >>> files = vpk.list_files() >>> vpk.extract_file("materials/example.vmt", "output.vmt") >>> >>> # manual parsing if needed >>> vpk = VPKFile("pak01_dir.vpk", auto_parse=False) >>> vpk.parse_directory() vpk_path auto_parsect||_i|_|jd|_d|_i|_|js|j|r|jyy)NrF) strr]rA _setup_paths_header_and_tree_offset_parsed_open_archives _is_dir_vpk!_calculate_header_and_tree_offsetparse_directory)selfr]r^s r+__init__zVPKFile.__init__|s`H  MO '($ 35  2 2 4   " r-c*|jjdr-d|_|j|_|jdd|_yt t |jjd}|ddjr |ddk(r|dd}|d}t |jrd|_||_||_yd |_|j|_t t |jjd|_y) zJSet up paths for VPK file(s) - determines if single or multi-file archive._dir.vpkTNi_F) r]endswithre _dir_path _base_pathr`r with_suffixisdigitexists)rhpath_without_extpossible_dir_paths r+razVPKFile._setup_pathss == ! !* -#D !]]DN"mmCR0DO"4 #6#B#B2#FG $,,.3CB3G33N#3CR#8 #3"4H = %&--/#' !2"2#( !%"%d4==&9&E&Eb&I"Jr-rct|jd5}tjd}|j | t |}|sn t |}|sn{ t |}|snkt j|}||jvri|j|<||j|vri|j||<||j|||<y dddd|_ |S#1swYxYw)aMParse the VPK directory structure to enable file operations. Must be called before using file listing, extraction, or patching methods. Returns: Self for method chaining. Raises: IOError: If the VPK file cannot be read. ValueError: If the VPK format is invalid. rb<7ITN) openrqr#calcsizeseekrZrr,rArc)rhf tree_offsetrEpathrDr)s r+rgzVPKFile.parse_directorys$..$ '1 //%0K FF; -a0  ,Q/D#4Q#7'! 1 ; ;A >$DNN:8:DNN95t~~i'@@>@DNN95d;DIy1$7A  (6  9( 's CC**C3ct t|jd5}|jd}t|dk7rt dt|t j d|ddd}d|z|_|jcdddS#1swYyxYw#t$r}td |Yd}~yd}~wwxYw) z.Calculate offset for single-file VPK archives.ryz+Invalid VPK header: expected 28 bytes, got > !//"!M##6d;;r-c|jjD]}|j|jjy)z&Close all cached archive file handles.N)rdvaluescloseclear)rhr~s r+rz VPKFile.closes6$$++-A GGI. !!#r-c$|jyN)rrhs r+__del__zVPKFile.__del__s  r-offsetsizecj|j|} ||jvrt|d|j|<|j|}||js |jndz}|j ||j |S#ttf$r}td|d|Yd}~yd}~wwxYw)NryrzError reading from archive z: ) rrdr{rerbr}r%IOErrorOSErrorr&)rhrrr archive_pathr~adjusted_offsetrs r+_read_from_archivezVPKFile._read_from_archives--m<  4#6#6648t4L##L1##L1A$484D4D,,!O FF? #66$< !  / ~RsC D sA4BB2B--B2NrErc|jg}|r|gn|jj}|D]}||jvr|r|gn|j|j}|D]R}||j|vr|j||D])}|dk7r |d|d|n|d|} |j| +T|S)aList all files in the VPK archive. Args: extension: Filter files by extension (e.g., 'vtf', 'vmt'). Optional. path: Filter files by directory path. Optional. Returns: List of file paths within the archive. Example: >>> vpk.list_files(extension="vtf") # All texture files >>> vpk.list_files(path="materials/models") # Files in specific directory r;r:r<)_ensure_parsedrAkeysappend) rhrErfiles extensionsextpathsprD full_paths r+ list_fileszVPKFile.list_filess $-i[4>>3F3F3H C$..("TFs(;(@(@(BEDNN3// $s 3A 6H3481#Qxj#/H:QseATLL+ !7   r-patternc|j|j}|jdr"|Dcgc]}|j|s|c}S|Dcgc]}t ||s|c}Scc}wcc}w)aFind files matching a pattern. Args: pattern: Glob pattern to match against file paths. Examples: "materials/*.vmt", "models/player/*" Returns: List of matching file paths. Example: >>> vpk.find_files("materials/*.vmt") # All material files >>> vpk.find_files("models/player/*") # All player model files r:)rrrp startswithr)rhr all_filesr~s r+ find_fileszVPKFile.find_files sq OO%   C (By!ALL,AAyB B$<9a7(;9<<C>> full_path = vpk.find_file_path("example.vmt") >>> # Returns something like "materials/models/example.vmt" r<rNr;r:)rrsplitrrA)rhrDnamerrs r+find_file_pathzVPKFile.find_file_path4s   Q/ID# dnn $NN3'Dt~~c*400/3 $q +QQ(  sA33 A?>A?r7c.|j t|\}}}||jvr=||j|vr,||j||vr|||j|||fSy#ttf$r}t d|Yd}~yd}~wwxYw)zGGet raw directory entry for a file. Use get_file_info() for public API.zError getting file entry: N)rrFrAAttributeErrorKeyErrorr&)rhr7rErArDrs r+_get_file_entryzVPKFile._get_file_entryPs  4->> success = vpk.extract_file("materials/example.vmt", "output.vmt") >>> success = vpk.extract_file("materials/example.vmt", Path("output.vmt")) >>> if success: ... print("File extracted successfully") FwbrNTzError extracting file: ) rrrrrr{rrwriterr&) rhr7r entry_inforErAr) file_datar~rs r+ extract_filezVPKFile.extract_filefs ))(3 &0# 9e //##U%7%79K9KIk4(A&&*u/A/AGGE../ ")  )   +A3/ 0 s<3B9 B9AB-$B9-B62B96B99 CCCnew_data create_backupc |j|}|sy|\}}} t||jk7r(td|dt|d|jd|j |j }|rg|d}t |jsIt|d5} t|d5} | j| jd d d d d d t|d 5} | j|j| j|d d d y #1swYSxYw#1swYWxYw#1swYy xYw#t$r} td | Yd } ~ yd } ~ wwxYw) aReplace a file's contents within the VPK archive. Args: filepath: Path of the file within the VPK archive to replace. new_data: The new file contents as bytes. create_backup: Whether to create a backup of the original archive. Backup will have .backup extension. Returns: True if patching succeeded, False otherwise. Note: The new data must be exactly the same size as the original file. Example: >>> with open("my_material.vmt", "rb") as f: ... new_content = f.read() >>> success = vpk.patch_file("materials/example.vmt", new_content, create_backup=True) FzModified file z does not match original (z != z bytes)z.backupryrNzrb+TzError patching file: )rrrrrrrrur{rr%r}rrr&) rhr7rrrror)r backup_pathsrcdstr~rs r+ patch_filezVPKFile.patch_filesU,))(3  1e 8} 2 22 $XJ/H d5+=+=*>gG  11%2E2EFL!-g6 K(//1lD1S$#T; #((*-;1 lE*au))*!+;;11 +  )!- . sfBE# D.0 D"D.E,-D:E"D+ 'D..D73E:E?EE E'E""E' source_diroutput_base_path split_sizec$t|}t|} |jjddt|j }|j t js|t jz }t|}g}t j|D]E\} } } | D]:} t jj| | } | |d}|j| |f<G|s tdy|j|}|>> # Single file >>> VPKFile.create("my_mod", "my_mod.vpk") >>> VPKFile.create(Path("my_mod"), Path("my_mod.vpk")) >>> >>> # Multi-file with 100MB splits >>> VPKFile.create("my_mod", "my_mod", split_size=100*1024*1024) Tparentsexist_okNz"No files found in source directoryFrzError creating VPK: )rparentmkdirr`absoluterposseprwalkrjoinrr&_build_vpk_structure_create_single_vpk_create_multi_vpkr traceback print_exc)r'rrr source_pathbase_output_path source_str source_lenrrootdirs filenamesrD full_path_str rel_path_str vpk_structurerrs r+createzVPKFile.creates8:&  01%   # # ) )$ ) F[1134J&&rvv.bff$ ZJE)+)<%dI )H$&GGLLx$@M#0#=LLL-!>?!**= :;44U;M!/099&A((--. --m[II,,!#3Z  (, -    ! s%CE8AEE F#"F  Fci}|D]i\}}t|\}}}||vri||<|||vri|||<t|d5}|j}dddt||d||||<k|S#1swY%xYw)z6Build internal VPK directory structure from file list.ryN)contentrr)rFr{r%r) rr file_pathrrErrDr~rs r+rzVPKFile._build_vpk_structure s ', #I|(7 (E %ItX -+- i(=3313 i(.i&!&&('#G !8M) $T *8 4(- '&s A33A< c ld}d}tjddd||ddd}|j|||fS)z#Write VPK header structure to file.rrrzi4Urr0)r#packr)r~rembed_chunk_length tree_size_posembed_chunk_length_posrs r+_write_vpk_headerzVPKFile._write_vpk_header sH !# :q)-?B  444r-c$g}d}||n|}t|jD]}|j|jddzt||jD]}|j|jddzt|||jD]&}|j|jddz|rC|A||||} |jt j d| dd| d| d| dn||||} | d } t j| d z} |j|jd z|t| f|jt j d| dd dt| |t| z }|jt j d d)|jd|jd|jd|S)z+Write VPK directory tree structure to file.rrQrr archive_idxrrrrrr r!) sortedrrencoder#rzlibcrc32rtellr) r~rarchive_entriesentry_positionsarchive_offset structurerErrDr) file_inforrs r+_write_directory_treezVPKFile._write_directory_tree+s'4''..VVX\>3w<H Hc1faW VW&#g,6GGFKKf563!J6=<> GGENE2F r-cbt}|j||j|j|t}t}|jd|j|}|j||j|j |j|j |jdd|j |j |j |j |j |j y)z Write MD5 checksums to VPK file.rrN)rr}updater%digestr)r~ dir_startdir_sizetree_md5chunk_hashes_md5file_md5 header_datas r+_write_checksumszVPKFile._write_checksumsZs5 yx()55 q ffY'  $)*(//12 q!  !"  '')* !"r-c t|d5}tj|\}}|j}tj ||}|j}||z }|j} d} t |j D]f} t || j D]E} t || | j D]!} || | | d}|j|#Gh|j| z }|D]A\}}}|j||jtjd| | |z } Ctj||||j||jtjd||j||jtjd|dddy#1swYyxYw#t$r}td|Yd}~yd}~wwxYw) z!Create a single-file VPK archive.w+brrrNTz Error creating single-file VPK: F)r{r\rrrrrrr}r#rrrr&)rrr~rrrrdir_endr data_startcurrent_offsetrErrDrrposrlengthrs r+rzVPKFile._create_single_vpkns& k5)Q8?8Q8QRS8T5 5FFH ")"?"?="Q&&("Y.VVX "#!' (:(:(t&DX&N )'GGGG, )V!H">&'VVX %:"+:'CFF3KGGFKKn=>"f,N,; ((Ix@}% D(34-. D*<=>A*DE*D  4QC8 9 s5 G'GGG'G$ G'$G'' H0HHcr i}d}d}d}d} t|jD]}t||jD]} t||| jD]} ||| | } | d} | d} || z|kDr |dkDr|r|j|dz }d}d}||d|dd}t|d }d}t j | d z}||vri||<| ||vri||| <||| |d ||| | <|j | || z }|| z } |r|j |d }t|d 5}tj|\}}|j}tj|d||j}||z }tj||||j||j tjd|dddy#|r|jwwxYw#1swYyxYw#t$r}t!d|Yd}~yd}~wwxYw)z:Create a multi-file VPK archive with size-based splitting.rNrrrrorrrr)rrrrrkr rTzError creating multi-file VPK: F)rrrr{rrrr\rrrrr}r#rrr&)rrrrcurrent_archive_idx current_sizecurrent_archive_filecurrent_archive_posrErrDrrrrrdir_pathdir_frrorr rrs r+rzVPKFile._create_multi_vpksE  O"# L#' "# ) 1!' (:(:($>$@ 3q 8 3/0 7; 43;'7&8:Mc9RRV$W!-8N((..0++84Hh&%#*#<#|js|jyy)z,Ensure directory has been parsed before use.N)rcrgrs r+rzVPKFile._ensure_parseds||  "r- output_dirc \|jt|}|jddd}t}t |}g}|rt|j |}|j D]n} |j | D]Z} |j | | jD]5\} } | dk7r | d| d| n| d| } | |vs!|j| | | | f7\pnb|j D]S} |j | D]?} |j | | jD]\} } |j| | | | fAU|jdi} |D]K\} } } } | dk7rH|dz| z}||vr-t|jdd|j||dz| zdz| z}n|dz| zdz| z}|j| j}||vrt|d ||<||}| j|js |j ndz}|j#||j%| j&}t|d 5}| j(dkDr'| j*r|j-| j*|j-|d d d |d z }N |j3D]}|j5|S#1swY9xYw#t.$r}t1d |Yd }~d }~wwxYw#|j3D]}|j5wxYw)aExtract multiple files to a directory. Args: output_dir: Directory to extract files to (str or Path). pattern: Optional glob pattern to filter files (e.g., "materials/*.vmt"). If None, extracts all files. Returns: Number of files successfully extracted. Example: >>> count = vpk.extract_all("extracted_files") >>> count = vpk.extract_all(Path("extracted_files")) >>> print(f"Extracted {count} files") >>> >>> # extract only material files >>> count = vpk.extract_all("materials", "materials/*.vmt") Trrr;r:r<c>|dj|djfS)Nr)rr)xs r+z%VPKFile.extract_all..sQqT-?-?1ARAR,Sr-)keyryrNrzFailed to extract file: )rrrsetr`rrAitemsrsortaddrrr{rrerbr}r%rrrrrr&rr)rhrrr extracted created_dirsoutput_dir_strfiles_to_extractmatching_filesrErArDr)r7 open_archives parent_dirfull_output_pathr archive_filerrr~rs r+ extract_allzVPKFile.extract_allsa* :& $6 u [)  !9:N!^^ !% !:I+/>>)+DY+O+U+U+W% )C/ )k8*Ai[A$,:Qyk!:! $~5,33!*Ix G,X";,"^^ !% !:I+/>>)+DY+O+U+U+W%(//IxQV0WX,X";, "ST # %9I5 9h: C'%3c%9I%E %\9 ,224$2O(,,Z8+5+;h+F+Ly+X(+S08;cAIM)$(#9#9%:M:M#NL#=86:<6N l3#0#>L&+&8&8<@>> data = vpk.get_file_data("materials/example.vmt") >>> if data: ... content = data.decode('utf-8') # for text files NrzError reading file data: ) rrrrrr bytearrayrrextendr4rr&) rhr7rrErAr)rrXrs r+ get_file_datazVPKFile.get_file_dataDs ))(3 &0# 9e //##U%7%79K9KI[F""Q&5+=+= e001 MM) $=   -aS1 2 s3B< AB<< CCCcH|j|j|duS)aACheck if a file exists in the VPK archive. Args: filepath: Path of the file within the VPK archive. Returns: True if the file exists, False otherwise. Example: >>> if vpk.file_exists("materials/example.vmt"): ... print("File found!") N)rr)rhr7s r+ file_existszVPKFile.file_existsks& ##H-T99r-c|j|j|}|sy|\}}}|j|j|j|j |j ||dS)aGet comprehensive information about a file. Args: filepath: Path of the file within the VPK archive. Returns: Dictionary with file information or None if not found. Contains: 'size', 'crc', 'archive_index', 'offset', 'preload_bytes' Example: >>> info = vpk.get_file_info("materials/example.vmt") >>> if info: ... print(f"Size: {info['size']} bytes") ... print(f"CRC: 0x{info['crc']:08X}") N)rrrrrrErA)rrrrrrr)rhr7rrErAr)s r+ get_file_infozVPKFile.get_file_info{sm ))(3 &0# 9e&&99"00(("00""  r-)T)rr\)NN)Fr)rr)rN),r.r/r0r1r r`rboolrirargr2rfrrrrr4rr rrrr rrrrr5r staticmethodrrrrrrrr*r.r0rr r2r6r-r+r\r\fs* #sDy!1 #t #K,(T3"r:s !DDD$  (( (V*c*eCcM&:*4E%*EE "H " "s  s  r-