HLLib - NemPosted: May 23rd, 2005 - 6:32:20 pm

HLLib is a package library for Half-Life that abstracts several package formats and provides a simple interface for all of them. HLLib is written in native C++ but exposes both a C and C++ interface which can be used in any C or C++ application (additional languages may also use the library with standard C imports). HLLib works natively in both Windows (x86 and x64) and Linux. BSP, GCF, NCF, PAK, VPK, WAD, XZP and uncompressed ZIP package formats are supported.

HLLib is an open source library licensed under the LGPL. It comes with the source code and binaries necessary to use it. An example application called HLExtract, which is licensed under the GPL, is also included. HLExtract is a command line utility written in C that can load all HLLib supported packages and extract multiple items from them while maintaining their directory structure. Also included is a C# HLExtract port called HLExtract.Net.

Download: GridMount:

A MacFUSE file system handler called GridMount is available for those looking to run HLLib on a Mac.

Java Wrapper:

A Java wrapper is available for those looking to use HLLib in Java. It can be found on SourceForge.

Revision History:

  • Modified VPF file support to handle the removal of a null terminator from the end of the directory.
  • Added support for new SGA file format (v6).
  • Added support for new SGA file format (v7).
  • Fixed support for VPK file format (v1).
  • Added support for new VPK file format (v2).
  • Added SGA file support.
  • Added ZIP deflate support.
  • Fixed crash when opening VBSP files with no pak file lump.
  • Fixed crash in CProcStream.
  • Fixed VPK signature check.
  • Workaround for crash in .Net wrapper.
  • Added support for GCF files larger than 4 GB.
  • Added support for x64.
  • Added Visual Studio 2010 solution.
  • Added Visual Studio 2008 solution..
  • Removed Visual Studio 2003 solution.
  • Added support for packages larger than 4 GB.
  • Added support for new VBSP file format.
  • Added support for new VPK file format.
  • Added VPK file validation.
  • Fixed crash when closing VPK files.
  • Added VPK file support.
  • Added VBSP .lmp support.
  • Fixed support for files over 2 GB.
  • Added Last Version Played attribute to NCF file.
  • Fixed change to directory entry folder terminator.
  • Added Last Version Played attribute to GCF file.
  • Improved GCF version check.
  • Fixed fragmentation header checksum after defragment.
  • Added different search string comparisons.
  • Added Visual Studio 2005 solution.
  • Improved package type tests.
  • Added generic write support to mapping interface.
  • Added no recurse option to FindFirst()/FindNext().
  • Improved package item attribute consistency.
  • Fixed GCC visibility support.
  • Fixed unnecessary GCF bounds check.
  • Fixed BSP unused lump check.
  • Added Linux support.
  • Fixed near infinite find next recursion.
  • Fixed bug in GCF file defragmentation progress.
  • Added NCF file support.
  • Added GCF file defragmentation.
  • Added fragmentation property to GCF files.
  • Added Dark Messiah VBSP support.
  • Fixed hlPackageCreateStream() bug.
  • Fixed CMapping::GetTotalMemoryUsed() calculation.
  • Fixed PAK file path parsing.
  • Improved error messages.
  • Improved file mapping performance.
  • Added memory tracking.
  • Improved view management.
  • Fixed memory mapping bug.
  • Fixed user data bug in proc reader.
  • Fixed WAD file GetImageData() bug.
  • Fixed default mapping stream view size.
  • Fixed a minor memory leak.
  • Rewrote entire library.
  • Open packages from anywhere (files, memory, abstract streams).
  • Get package and item attributes.
  • Stream package data.
  • Validate package data.
  • Added a C wrapper.
  • Improved and optimized package loading code.
  • Improved package detection.
  • Added XZP file support.
  • Added Source engine BSP support.
  • Added mipmap level option to CWADFile.
  • Improved WAD file support.
  • Improved detection of corrupt packages.
  • Extended CGCFFile.
  • Extended CFileMapping and CPrimitiveFileMapping to allow for volatile access.
  • Fixed CPackageUtility::Extract() bug caused by illegal characters.
  • Files of size 0 B are now treated as valid files.
  • Extended CPackage.
  • Extended CMappedPackage.
  • Improved error messages for system calls.
  • Fixed last error not being set in CMappedPackage::Open().
  • Rewrote mapping code to be more flexible.
  • Packages located on disk or in memory can now be loaded.
  • Optimized file mapping.
  • Fixed CPackage::Root bug.
  • Fixed CGCFFile::GetFileSizeOnDisk() bug.
  • Fixed CPackage memory leak.
  • Fixed CMappedPackage initialization bug.
  • Fixed CMappedPackage deinitialization bug.
  • Changed CDirectoryItem::Parent to a CDirectoryFolder.
  • Extended CWADFile.
  • Added CBSPFile which acts like CWADFile on a BSP's textures.
  • Extended CWADFile.
  • Changed GetFileSizeEx() to GetFileSize() (Not all versions of Windows supported the former).
  • Extended CPackage.
  • Extended CGCFFile.
  • Converted from bool to BOOL.
  • HLLib now used by GCFScape.
  • Added callback functionality to CPackageUtility::Extract().
  • Extended CGCFFile.
  • Minor bug fixes.
  • Original build.
Modified: Jan 22nd, 2017 - 6:09:30 pm[ 163653 Views ]

[ 1 2 3 ]

16. jwheareModified: Jun 13th, 2010 - 4:03:07 pm
I turned this into a homebrew package for Mac OS X


It only required a few minor tweaks to the Makefile and HLExtract source, mainly to replace the .so extensions with .dylib and fixing the limits.h include. Would be good if these changes could make it back to your package via some IFDEFS.

Cheers, hlextract is a great tool.

17. NemPosted: Jun 14th, 2010 - 1:42:26 am
Do you have a diff for your code changes? I'd be happy to integrate them in.

18. Crowley22gModified: Jun 14th, 2010 - 4:10:32 am
Great tools been using for years love

Wrote a script a while back to extract all the required files to build a Synergy Server :-)

This worked great until Valve did the updates for Apple Mac

Now Hlextract will not extract the NEW updated files some of which are maps :-(


Thats only a few from Half-life 2

Hope it's something simple. I'm sure there are other Synergy server admins saying OMG what have they done LOL

Thanks in advance


PS file will extract using GCFScape 1.8.0 (On Win 7 x64)
The server is Win2003 R2

19. Crowley22gPosted: Jun 20th, 2010 - 5:52:35 am
Done a bit more digging.

d1_eli_01.bsp is grey and will not extract on Server 2003 R2

d1_eli_01.bsp is fine and will extract OK on my Win 7 x64 PC

Also tried the HLExtract and the .net version on 2003 R2 and they get the same error message about the file not being complete

Hope you can help. If not I'll have to upload all the files from my Win 7 PC



20. neicoModified: Jul 25th, 2010 - 3:28:33 pm
could you consider to include the .pdb files for the HLLib.dll and the hlextract.exe in the next release? it would help people that don't build them and just use what comes with the download ;)

and to the thing about the new bsp files etc. I think I've come across the same problem, I guess the lib needs a little update for those... (using the Lib together with wxWidgets to write an GUI based extractor for just extracting content that doesn't come with hldsupdatetool but is required for mods like Synergy or Obsidian Conflict)

It also seems that CDirectoryFolder->FindFirst and FindNext don't work as they should when using only HL_FIND_FOLDER, it doesn't search all folders, only those inside that folder, it only works if I also add the flag HL_FIND_FILES

21. Crowley22gPosted: Jul 26th, 2010 - 5:41:07 pm
The files extracted on Win7 x64 when placed on the Synergy server still give a message "Server version differs". Whatever they did in the Mac update has broken some but not all files from being extracted correctly.

For the time being i've had to remove 15 maps from the mapcycle to prevent getting an empty server because no one can join.

Thanks in advance

22. Crowley22gPosted: Aug 7th, 2010 - 5:36:09 pm
Problem solved thanks to a reply on GCFScape

Missing file with the NEW updated maps etc... are now located in :

half-life 2 2007 base content.gcf

Now loaded on our server an working again :-)

23. ArimanPosted: May 2nd, 2011 - 5:34:18 am
Hi. I've encountered a small issues with HLLib.
In lpPackageTests array (which is used for hlGetPackageTypeFromMemory function) signature for VPK files defined as { 0x34, 0x12, 0x55, 0xaa }, but in Portal 2 pak01_dir.vpk has signature { 0x34, 0x12, 0xaa, 0x55 }.
And it can be opened with no problems. Is it an error in signature definition or both versions are valid?

24. NemPosted: May 2nd, 2011 - 10:39:52 pm
Good catch, the signature check should be against { 0x34, 0x12, 0xaa, 0x55 }.


25. ArimanPosted: May 3rd, 2011 - 4:03:12 am
Got it. Thanks.

26. NemPosted: May 11th, 2011 - 1:45:59 am
Version 2.4.1 has been released with a fixed signature check and a few other minor fixes.

27. King2500Posted: May 12th, 2011 - 6:40:00 pm
Hello Nem,

With Version 2.4.1 of HLLib I have the problem that I get a crash when mounting a AlienSwarm or Portal 2 BSP and calling GetRoot()

Same problem (similar error) applies to GCFScape in latest version.

28. neicoModified: Aug 5th, 2011 - 3:03:31 am
Just wanted to say that it would a good thing to add GetExtractable() to the Extract function since it's pretty obvious that the lib shouldn't try to extract if it's not extractable...

Also, could you provide a way to give out only the file / folder count that's been downloaded (and in fact is extractable), a simple GetFileCount( hlBool OnlyCompleted = false ) should be enough I guess~
else I really would need to add some extra looping just to archive that :S

I've also got an report from an tester that when I use Extract on an entire folder that it extracts files which show up in GCFScape as gray ( not downloaded ) too, but those are then 0 byte big, maybe this is related to the extract function not checking if it's extractable D:

I've also noticed that the Callbacks are only available in C Code, so I can't really use them to call Class Members (hlSetVoid would need an extra parameter to allow passing this for static functions at least~).
So making C Code features ( like the Callbacks ) usable with C++ Code would be cool :D

I would suggest making a class HLLib that has members like: RegisterCallback( hlOption Callback, hlCallback, hlVoid* EventHandler );
and the same for Unregister and stuff like that, you know what I mean~

29. kevincoxPosted: Jan 30th, 2013 - 3:21:19 am
Hi. I am trying to build these packages on linux (I'm actually trying to get them into the AUR (Arch User Repository) but I am running into problems building HLExtract.

HLLib appears to build and install fine using the Makefile but when I try to compile HLExtract using the following command I get the following error.

cc -o 'hlextract' -I "$headerdir" -L "$libdir" 'Main.c' -lhl
/data/Desktop/dassault-systemes-draftsight/pkg/usr/lib//libhl.so: undefined reference to `HLLib::CSGAFile::CSGAFile()'
collect2: error: ld returned 1 exit status

I might be doing something silly and would appreciate any help.

30. NemPosted: Jan 31st, 2013 - 6:01:30 am
Don't really maintain the Linux support, but it shouldn't be hard to get going again.

Add SGAFile.cpp to the makefile?

If you get it working send me your changes and I'll make sure they get in to the next release.

[ 1 2 3 ]

You must be logged in to post a comment.
New users can register here.
Nem's Tools v2.0 © 2006 Ryan Gregg.
Execution time: 0.031155s; Queries: 17.
dishes served.
Powered by The Wavelength.

Valid XHTML 1.0 Transitional Valid CSS