Unvanquished - User contributions [en-gb]

Tools/Crunch

2026-08-08T06:42:52Z

Illwieckz:

[[Category:Tools]]{{DISPLAYTITLE:Dæmon Crunch — Advanced DXTn Texture Compressor}}
[https://github.com/DaemonEngine/crunch Dæmon Crunch] is a maintained DXT texture compression library and command-line tool producing GPU-friendly formats such as CRN, DDS and KTX.

{{crunch}} is the recommended TGA-to-PNG converter. For converting TGA images prefer {{crunch}} over ImageMagick which is not reliable.

{{crunch}} is the most maintained and up-to-date Crunch available and the best choice for game developers.

==History==

The {{code|crunch}} tool was initially written by Binomial LLC then improved by Unity Technologies. The original Binomial Crunch is no longer maintained and lacks compatibility with newer Crunch formats. Although Unity contributed important improvements, the public Unity Crunch repository was never maintained as a proper long-term upstream project. Dæmon Crunch incorporated these improvements and has continued development with additional fixes, features, and maintenance.

Neither Binomial nor Unity have merged Unvanquished fixes and never demonstrated any serious interest in merging fixes provided by others, so the Unvanquished team not only maintained the Dæmon Crunch fork to host fixes, but also incorporated fixes from others developers. The Unvanquished team is actively maintaining Dæmon Crunch since 2014 (already more than a decade of maintenance and improvements!).

==Sources==

The Dæmon Crunch source repository is: [https://github.com/DaemonEngine/crunch github.com/DaemonEngine/crunch].

That repository provides the updated '''crunch''' tool, the '''crnlib''' library to provide full compression/decompression support to third-party applications, and the {{code|crn_decomp.h}} header-only library which is enough to transcode the Crunch CRN data for GPU upload and is perfect for lightweight integration in renderers. Some examples implementing various kinds of integrations are provided.

==Overview==

Some other details can be found in the [https://github.com/DaemonEngine/crunch/blob/master/README.md Crunch project README].

===Features===

The {{crunch}} provides many improvements over the original crunch:

* ✅️ Unity crunch format (runs many time faster and produces smaller files),
* ✅️ Unity crunch metadata (the header is compatible with Unity),
* ✅️ Improved image compatibility (1-bit PNG and horizontally-flipped TGA images are now supported),
* ✅️ Added features and command line options (top mip renormalization and more),
* ✅️ Network file system compatibility,
* ✅️ Optional header-only checksumming,
* ✅️ Multisystem and multiplatform,
* ✅️ Thoroughly tested and improved reproducibility,
* ✅️ CMake toolchain.

===Image formats===

* ✅️ CRN, DDS, KTX,
* ✅️ PNG, JPG, TGA, BMP.

Crunch produces compressed images optimized for performance and game rendering in various formats like DDS, KTX and CRN.

All those three formats are containers for DXT-compressed bitmaps. This DXT-compressed data can be uploaded directly to the GPU memory without decompression, and the GPU can process DXT-compressed data without decompression.

Crunch writes DXT-compressed data in a way an additional compression performs better on them, especially LZMA. For example, produced DDS images are expected to compress well if repackaged in an LZMA-based archive.

The CRN format does all of this in one go: it stores the DXT-compressed data into a custom LZMA container.

The game engine or any other application processing CRN files just have to unpack the LZMA container using provided functions and to upload the DXT-compressed data to the GPU.

The {{crunch}} sets the {{code|m_userdata0}} header field to {{code|1}} to make it compatible with Unity.

===Performance===

The {{crunch}} runs multiple times faster than the original Crunch by BinomialLLC, thanks to the work done by Unity that has been imported. Unity people claimed the tool runs 2.5 time faster, and we measured the tool running 4.3 time faster on the Unvanquished corpus. Unity people claimed the tool compresses about 10% better, we measured more than 11% on the Unvanquished corpus. This performance bump comes with a compatibility-breaking change introduced in the Unity branch.

The files produced by the Dæmon Crunch are then readable by both the Unity Crunch and the Dæmon Crunch but not by the original Binomial Crunch, while the files produced by the original Binomial Crunch are not readable by the Unity Crunch and the Dæmon Crunch. The Binomial Crunch isn't maintained anymore.

===Portability===

The {{crunch}} has very high cross-platform compatibility and is buildable with CMake.

The [https://github.com/DaemonEngine/crunch Dæmon Crunch source repository] is known to build with various compilers, and the Dæmon {{code|crunch}} tool is known to run on Linux, Windows, macOS and FreeBSD systems on various hardware architectures.

===Quality===

A continuous integration pipeline is configured to test the building of the tool and the library themselves and to run some tests. The code is frequently submitted to CodeQL static analysis.

===Adoption===

The {{crunch}} is known to be used by:

* The {{engine}},
* The {{Tools|Urcheon}} game data build tool,
* The {{Tools|NetRadiant}} level editor and the {{Tools|Q3map2}} map compiler and light mapper,
* The [https://github.com/XQF/xqf XQF] game server browser,
* The [https://unvanquished.net Unvanquished game],
* The [https://xonotic.org Xonotic game],
* The [https://overgrowth.wolfire.com Overgrowth game],
* Some games using the Unity game engine.

The {{crunch}} is known to be distributed by:

* The Debian operating system: {{url|tracker.debian.org/pkg/crunch-dxtc}}

==How to use Crunch==

{{QuickCrunchTutorial}}

Some other usage instructions can be found in the [https://github.com/DaemonEngine/crunch/blob/master/README.md#creating-compressed-textures-with-crunch README].

The {{code|-noNormalDetection}} and {{code|-rtopmip}} options are succinctly described below.

==Dæmon Crunch Enhancements==

Here are things you will not find in either Binomial Crunch, Unity Crunch or none of them:

===Unity Crunch format===

This repository merged improvements done by Unity Technologies, it produces
smaller files and produces them faster than original code by Binomial.
Unity also modified the format which makes it incompatible with earlier versions of the tool.

Quote from [https://unvanquished.net/unvanquished-area-51 unvanquished.net]:

<blockquote>
[https://blog.unity.com/technology/crunch-compression-of-etc-textures Unity guys said]
that their modified crunch tool “can compress up to 2.5
times faster, while providing about 10% better compression ratio”. So we
did a test on our own asset repository, re-crunching all the ressources
and textures packages. At the time we did the test the given corpus
produced 1797 .crn files.
The Unity’s crunch tool reduced compression time by 4.31 and reduced size
by 11.15%. They said “up to 2.5 time faster” but we’ve seen some random
textures being compressed 6 time faster and the average of the whole is
4.3 time faster, and yes the tool compresses more than 10% more.
</blockquote>

===Unity Crunch metadata===

Unlike the Unity {{code|crunch}} tool built from their public repository, this tool produces files loadable by the Unity engine. Since [https://github.com/DaemonEngine/crunch/blob/master/faf5127b8c69dfd1ae554f4f3bf8168048b48d9f February 11th 2023], this branch sets the CRN {{code|m_userdata0}} field to {{code|1}} to make CRN files loadable by the Unity engine which now prevents to load files with this value set to {{code|0}}.

Files with this value set to {{code|1}} are expected to use the new format. Files with this value set to {{code|0}} may or may not use the new format. When Unity updated the tool and modified the format in an incompatible way, no bit was modified to detect if a CRN file was using the old or the new format. Unity has not updated that field in their public repository of Crunch so files using new format with this value set to {{code|0}} may be found in the wild.

===Improved image compatibility===

Supported source file formats: CRN,DDS,KTX,TGA,BMP,PNG,JPG/JPEG,PSD. 
Supported output file formats: CRN,DDS,KTX,TGA,BMP,PNG,JPG/JPEG.

* 1-bit PNG files are supported.
* Flipped TGA files are supported.
* Progressive JPEG files are supported.

The {{code|stb_image}} library has been updated from version 1.18 to version 2.30, increasing the amount of image format variants that can be converted, like 1-bit PNG formats. Further improvements like horizontally-flipped TGA images were brought to {{code|stb_image}} to make it support more TGA variants.

Note: Some other specific file format variants may be unsupported.

See the docs for jpgd.h: {{url|code.google.com/p/jpeg-compressor}} 
See the docs for stb_image.h: {{url|github.com/nothings/stb}}

===Converted image reproducibility===

We take special care that, when using compilation options for IEEE 754 float processing (disabling fast math, preferring SSE over x87…), the bitstream of converted image files are the same whatever the compiler, the operating system, or the CPU architecture crunch is built for and running on. It helps making packaged game assets reproducible. The CI not only checks that crunch builds, but that it runs properly and that the same input converts to the same output.

When reproducibility isn't needed, fast math can be enabled with CMake with the {{code|1=-DUSE_FAST_MATH=ON}} CMake option.

It is recommended for those looking for generating reproducible CRN files to keep disabled the use of fast math. It is also recommended to disable x87 floats on i686 and to rely on SSE instead with the {{code|1=-mfpmath=sse -msse}} compiler flags.

===Added features and command line options===

In addition to the original {{code|crunch}} features and command line options this branch brings new features and options, including:

* {{code|-rtopmip}}: option to use with {{code|-renormalize}} to also renormalize on the top mip-level.
* {{code|-noNormalDetection}}: do not attempt to detect normal map to avoid selecting formats thought for normal maps when it's known an image is not a normal map. It may prevent the tool to use heavier and less-supported {{code|DXT5_AGBR}} format when {{code|DXT1}} is good enough.
* {{code|-h}} or {{code|--help}}: print the command line built-in help, listing all known options.

===Network file system compatibility===

The original {{code|crunch}} tool relied on non-standard I/O features not working on all file systems including network file systems like NFS or SSHFS. A standard implementation was added so the limitations are not there anymore and {{code|crunch}} can now process image files stored over the network and on any other file system.

===Optional header-only checksumming===

For applications distributing their files in containers already providing a checksum mechanism for the whole contained file, it's now possible to only validate the CRN header checksum instead of the whole file checksum to not checksum the whole file twice.

===Multisystem and multiplatform portability===

Unlike upstream branches from Binomial LLC and Unity Software Inc. this branch focuses on keeping the code buildable outside of Windows and Visual Studio, and adds a CMake build option alongside the legacy Makefile.

This {{code|crunch}} tool and the related {{code|crnlib}} library are known to build with and and run on:

* Compilers: GCC, MinGW, MSVC, Clang, Apple Clang, and more.
* Systems: Linux, Windows, macOS, FreeBSD.
* Architectures: amd64, arm64, i686, armhf.

===Thoroughly tested and improved reproducibility===

A continuous integration system tests the build of crunch for a dozen of configurations of different architecture, system or compiler. The output of such builds are also tested with most of those builds. It helped to improve and validate image support, to identify build options known to improve the reproducibility of the output, and is meant to catch regressions if they happen.

The Dæmon crunch code is frequently scanned with the the CodeQL static analyser.

===CMake build system===

CMake has now replaced the old Makefile. The supplied CMake configuration provides many useful build options. Toolchain files for MinGW cross-compilation are also supplied.

The native MSVC solution files were removed, it is expected that MSVC users generate them with CMake instead.

Tools/Crunch

2026-08-08T06:41:10Z

Illwieckz:

[[Category:Tools]]{{DISPLAYTITLE:Dæmon Crunch — Advanced DXTn Texture Compressor}}
[https://github.com/DaemonEngine/crunch Dæmon Crunch] is a maintained CRN texture compression library and command-line tool producing GPU-friendly formats such as CRN, DDS and KTX.

{{crunch}} is also the recommended TGA-to-PNG converter. When converting TGA images, prefer {{crunch}} over ImageMagick which is not reliable.

{{crunch}} is the most maintained and up-to-date Crunch available and the best choice for game developers.

==History==

The {{code|crunch}} tool was initially written by Binomial LLC then improved by Unity Technologies. The original Binomial Crunch is no longer maintained and lacks compatibility with newer Crunch formats. Although Unity contributed important improvements, the public Unity Crunch repository was never maintained as a proper long-term upstream project. Dæmon Crunch incorporated these improvements and has continued development with additional fixes, features, and maintenance.

Neither Binomial nor Unity have merged Unvanquished fixes and never demonstrated any serious interest in merging fixes provided by others, so the Unvanquished team not only maintained the Dæmon Crunch fork to host fixes, but also incorporated fixes from others developers. The Unvanquished team is actively maintaining Dæmon Crunch since 2014 (already more than a decade of maintenance and improvements!).

==Sources==

The Dæmon Crunch source repository is: [https://github.com/DaemonEngine/crunch github.com/DaemonEngine/crunch].

That repository provides the updated '''crunch''' tool, the '''crnlib''' library to provide full compression/decompression support to third-party applications, and the {{code|crn_decomp.h}} header-only library which is enough to transcode the Crunch CRN data for GPU upload and is perfect for lightweight integration in renderers. Some examples implementing various kinds of integrations are provided.

==Overview==

Some other details can be found in the [https://github.com/DaemonEngine/crunch/blob/master/README.md Crunch project README].

===Features===

The {{crunch}} provides many improvements over the original crunch:

* ✅️ Unity crunch format (runs many time faster and produces smaller files),
* ✅️ Unity crunch metadata (the header is compatible with Unity),
* ✅️ Improved image compatibility (1-bit PNG and horizontally-flipped TGA images are now supported),
* ✅️ Added features and command line options (top mip renormalization and more),
* ✅️ Network file system compatibility,
* ✅️ Optional header-only checksumming,
* ✅️ Multisystem and multiplatform,
* ✅️ Thoroughly tested and improved reproducibility,
* ✅️ CMake toolchain.

===Image formats===

* ✅️ CRN, DDS, KTX,
* ✅️ PNG, JPG, TGA, BMP.

Crunch produces compressed images optimized for performance and game rendering in various formats like DDS, KTX and CRN.

All those three formats are containers for DXT-compressed bitmaps. This DXT-compressed data can be uploaded directly to the GPU memory without decompression, and the GPU can process DXT-compressed data without decompression.

Crunch writes DXT-compressed data in a way an additional compression performs better on them, especially LZMA. For example, produced DDS images are expected to compress well if repackaged in an LZMA-based archive.

The CRN format does all of this in one go: it stores the DXT-compressed data into a custom LZMA container.

The game engine or any other application processing CRN files just have to unpack the LZMA container using provided functions and to upload the DXT-compressed data to the GPU.

The {{crunch}} sets the {{code|m_userdata0}} header field to {{code|1}} to make it compatible with Unity.

===Performance===

The {{crunch}} runs multiple times faster than the original Crunch by BinomialLLC, thanks to the work done by Unity that has been imported. Unity people claimed the tool runs 2.5 time faster, and we measured the tool running 4.3 time faster on the Unvanquished corpus. Unity people claimed the tool compresses about 10% better, we measured more than 11% on the Unvanquished corpus. This performance bump comes with a compatibility-breaking change introduced in the Unity branch.

The files produced by the Dæmon Crunch are then readable by both the Unity Crunch and the Dæmon Crunch but not by the original Binomial Crunch, while the files produced by the original Binomial Crunch are not readable by the Unity Crunch and the Dæmon Crunch. The Binomial Crunch isn't maintained anymore.

===Portability===

The {{crunch}} has very high cross-platform compatibility and is buildable with CMake.

The [https://github.com/DaemonEngine/crunch Dæmon Crunch source repository] is known to build with various compilers, and the Dæmon {{code|crunch}} tool is known to run on Linux, Windows, macOS and FreeBSD systems on various hardware architectures.

===Quality===

A continuous integration pipeline is configured to test the building of the tool and the library themselves and to run some tests. The code is frequently submitted to CodeQL static analysis.

===Adoption===

The {{crunch}} is known to be used by:

* The {{engine}},
* The {{Tools|Urcheon}} game data build tool,
* The {{Tools|NetRadiant}} level editor and the {{Tools|Q3map2}} map compiler and light mapper,
* The [https://github.com/XQF/xqf XQF] game server browser,
* The [https://unvanquished.net Unvanquished game],
* The [https://xonotic.org Xonotic game],
* The [https://overgrowth.wolfire.com Overgrowth game],
* Some games using the Unity game engine.

The {{crunch}} is known to be distributed by:

* The Debian operating system: {{url|tracker.debian.org/pkg/crunch-dxtc}}

==How to use Crunch==

{{QuickCrunchTutorial}}

Some other usage instructions can be found in the [https://github.com/DaemonEngine/crunch/blob/master/README.md#creating-compressed-textures-with-crunch README].

The {{code|-noNormalDetection}} and {{code|-rtopmip}} options are succinctly described below.

==Dæmon Crunch Enhancements==

Here are things you will not find in either Binomial Crunch, Unity Crunch or none of them:

===Unity Crunch format===

This repository merged improvements done by Unity Technologies, it produces
smaller files and produces them faster than original code by Binomial.
Unity also modified the format which makes it incompatible with earlier versions of the tool.

Quote from [https://unvanquished.net/unvanquished-area-51 unvanquished.net]:

<blockquote>
[https://blog.unity.com/technology/crunch-compression-of-etc-textures Unity guys said]
that their modified crunch tool “can compress up to 2.5
times faster, while providing about 10% better compression ratio”. So we
did a test on our own asset repository, re-crunching all the ressources
and textures packages. At the time we did the test the given corpus
produced 1797 .crn files.
The Unity’s crunch tool reduced compression time by 4.31 and reduced size
by 11.15%. They said “up to 2.5 time faster” but we’ve seen some random
textures being compressed 6 time faster and the average of the whole is
4.3 time faster, and yes the tool compresses more than 10% more.
</blockquote>

===Unity Crunch metadata===

Unlike the Unity {{code|crunch}} tool built from their public repository, this tool produces files loadable by the Unity engine. Since [https://github.com/DaemonEngine/crunch/blob/master/faf5127b8c69dfd1ae554f4f3bf8168048b48d9f February 11th 2023], this branch sets the CRN {{code|m_userdata0}} field to {{code|1}} to make CRN files loadable by the Unity engine which now prevents to load files with this value set to {{code|0}}.

Files with this value set to {{code|1}} are expected to use the new format. Files with this value set to {{code|0}} may or may not use the new format. When Unity updated the tool and modified the format in an incompatible way, no bit was modified to detect if a CRN file was using the old or the new format. Unity has not updated that field in their public repository of Crunch so files using new format with this value set to {{code|0}} may be found in the wild.

===Improved image compatibility===

Supported source file formats: CRN,DDS,KTX,TGA,BMP,PNG,JPG/JPEG,PSD. 
Supported output file formats: CRN,DDS,KTX,TGA,BMP,PNG,JPG/JPEG.

* 1-bit PNG files are supported.
* Flipped TGA files are supported.
* Progressive JPEG files are supported.

The {{code|stb_image}} library has been updated from version 1.18 to version 2.30, increasing the amount of image format variants that can be converted, like 1-bit PNG formats. Further improvements like horizontally-flipped TGA images were brought to {{code|stb_image}} to make it support more TGA variants.

Note: Some other specific file format variants may be unsupported.

See the docs for jpgd.h: {{url|code.google.com/p/jpeg-compressor}} 
See the docs for stb_image.h: {{url|github.com/nothings/stb}}

===Converted image reproducibility===

We take special care that, when using compilation options for IEEE 754 float processing (disabling fast math, preferring SSE over x87…), the bitstream of converted image files are the same whatever the compiler, the operating system, or the CPU architecture crunch is built for and running on. It helps making packaged game assets reproducible. The CI not only checks that crunch builds, but that it runs properly and that the same input converts to the same output.

When reproducibility isn't needed, fast math can be enabled with CMake with the {{code|1=-DUSE_FAST_MATH=ON}} CMake option.

It is recommended for those looking for generating reproducible CRN files to keep disabled the use of fast math. It is also recommended to disable x87 floats on i686 and to rely on SSE instead with the {{code|1=-mfpmath=sse -msse}} compiler flags.

===Added features and command line options===

In addition to the original {{code|crunch}} features and command line options this branch brings new features and options, including:

* {{code|-rtopmip}}: option to use with {{code|-renormalize}} to also renormalize on the top mip-level.
* {{code|-noNormalDetection}}: do not attempt to detect normal map to avoid selecting formats thought for normal maps when it's known an image is not a normal map. It may prevent the tool to use heavier and less-supported {{code|DXT5_AGBR}} format when {{code|DXT1}} is good enough.
* {{code|-h}} or {{code|--help}}: print the command line built-in help, listing all known options.

===Network file system compatibility===

The original {{code|crunch}} tool relied on non-standard I/O features not working on all file systems including network file systems like NFS or SSHFS. A standard implementation was added so the limitations are not there anymore and {{code|crunch}} can now process image files stored over the network and on any other file system.

===Optional header-only checksumming===

For applications distributing their files in containers already providing a checksum mechanism for the whole contained file, it's now possible to only validate the CRN header checksum instead of the whole file checksum to not checksum the whole file twice.

===Multisystem and multiplatform portability===

Unlike upstream branches from Binomial LLC and Unity Software Inc. this branch focuses on keeping the code buildable outside of Windows and Visual Studio, and adds a CMake build option alongside the legacy Makefile.

This {{code|crunch}} tool and the related {{code|crnlib}} library are known to build with and and run on:

* Compilers: GCC, MinGW, MSVC, Clang, Apple Clang, and more.
* Systems: Linux, Windows, macOS, FreeBSD.
* Architectures: amd64, arm64, i686, armhf.

===Thoroughly tested and improved reproducibility===

A continuous integration system tests the build of crunch for a dozen of configurations of different architecture, system or compiler. The output of such builds are also tested with most of those builds. It helped to improve and validate image support, to identify build options known to improve the reproducibility of the output, and is meant to catch regressions if they happen.

The Dæmon crunch code is frequently scanned with the the CodeQL static analyser.

===CMake build system===

CMake has now replaced the old Makefile. The supplied CMake configuration provides many useful build options. Toolchain files for MinGW cross-compilation are also supplied.

The native MSVC solution files were removed, it is expected that MSVC users generate them with CMake instead.

Tools/Crunch

2026-08-08T06:40:41Z

Illwieckz:

[[Category:Tools]]{{DISPLAYTITLE:Dæmon Crunch — Advanced DXTn Texture Compressor}}
[https://github.com/DaemonEngine/crunch Dæmon Crunch] is a maintained CRN texture compression library and command-line tool producing GPU-friendly formats such as CRN, DDS and KTX.

{{crunch}} is also the recommended TGA-to-PNG converter. When converting TGA images, prefer {{crunch}} over ImageMagick which is not reliable.

The {{crunch}} is the most maintained and up-to-date Crunch available and the best choice for game developers.

==History==

The {{code|crunch}} tool was initially written by Binomial LLC then improved by Unity Technologies. The original Binomial Crunch is no longer maintained and lacks compatibility with newer Crunch formats. Although Unity contributed important improvements, the public Unity Crunch repository was never maintained as a proper long-term upstream project. Dæmon Crunch incorporated these improvements and has continued development with additional fixes, features, and maintenance.

Neither Binomial nor Unity have merged Unvanquished fixes and never demonstrated any serious interest in merging fixes provided by others, so the Unvanquished team not only maintained the Dæmon Crunch fork to host fixes, but also incorporated fixes from others developers. The Unvanquished team is actively maintaining Dæmon Crunch since 2014 (already more than a decade of maintenance and improvements!).

==Sources==

The Dæmon Crunch source repository is: [https://github.com/DaemonEngine/crunch github.com/DaemonEngine/crunch].

That repository provides the updated '''crunch''' tool, the '''crnlib''' library to provide full compression/decompression support to third-party applications, and the {{code|crn_decomp.h}} header-only library which is enough to transcode the Crunch CRN data for GPU upload and is perfect for lightweight integration in renderers. Some examples implementing various kinds of integrations are provided.

==Overview==

Some other details can be found in the [https://github.com/DaemonEngine/crunch/blob/master/README.md Crunch project README].

===Features===

The {{crunch}} provides many improvements over the original crunch:

* ✅️ Unity crunch format (runs many time faster and produces smaller files),
* ✅️ Unity crunch metadata (the header is compatible with Unity),
* ✅️ Improved image compatibility (1-bit PNG and horizontally-flipped TGA images are now supported),
* ✅️ Added features and command line options (top mip renormalization and more),
* ✅️ Network file system compatibility,
* ✅️ Optional header-only checksumming,
* ✅️ Multisystem and multiplatform,
* ✅️ Thoroughly tested and improved reproducibility,
* ✅️ CMake toolchain.

===Image formats===

* ✅️ CRN, DDS, KTX,
* ✅️ PNG, JPG, TGA, BMP.

Crunch produces compressed images optimized for performance and game rendering in various formats like DDS, KTX and CRN.

All those three formats are containers for DXT-compressed bitmaps. This DXT-compressed data can be uploaded directly to the GPU memory without decompression, and the GPU can process DXT-compressed data without decompression.

Crunch writes DXT-compressed data in a way an additional compression performs better on them, especially LZMA. For example, produced DDS images are expected to compress well if repackaged in an LZMA-based archive.

The CRN format does all of this in one go: it stores the DXT-compressed data into a custom LZMA container.

The game engine or any other application processing CRN files just have to unpack the LZMA container using provided functions and to upload the DXT-compressed data to the GPU.

The {{crunch}} sets the {{code|m_userdata0}} header field to {{code|1}} to make it compatible with Unity.

===Performance===

The {{crunch}} runs multiple times faster than the original Crunch by BinomialLLC, thanks to the work done by Unity that has been imported. Unity people claimed the tool runs 2.5 time faster, and we measured the tool running 4.3 time faster on the Unvanquished corpus. Unity people claimed the tool compresses about 10% better, we measured more than 11% on the Unvanquished corpus. This performance bump comes with a compatibility-breaking change introduced in the Unity branch.

The files produced by the Dæmon Crunch are then readable by both the Unity Crunch and the Dæmon Crunch but not by the original Binomial Crunch, while the files produced by the original Binomial Crunch are not readable by the Unity Crunch and the Dæmon Crunch. The Binomial Crunch isn't maintained anymore.

===Portability===

The {{crunch}} has very high cross-platform compatibility and is buildable with CMake.

The [https://github.com/DaemonEngine/crunch Dæmon Crunch source repository] is known to build with various compilers, and the Dæmon {{code|crunch}} tool is known to run on Linux, Windows, macOS and FreeBSD systems on various hardware architectures.

===Quality===

A continuous integration pipeline is configured to test the building of the tool and the library themselves and to run some tests. The code is frequently submitted to CodeQL static analysis.

===Adoption===

The {{crunch}} is known to be used by:

* The {{engine}},
* The {{Tools|Urcheon}} game data build tool,
* The {{Tools|NetRadiant}} level editor and the {{Tools|Q3map2}} map compiler and light mapper,
* The [https://github.com/XQF/xqf XQF] game server browser,
* The [https://unvanquished.net Unvanquished game],
* The [https://xonotic.org Xonotic game],
* The [https://overgrowth.wolfire.com Overgrowth game],
* Some games using the Unity game engine.

The {{crunch}} is known to be distributed by:

* The Debian operating system: {{url|tracker.debian.org/pkg/crunch-dxtc}}

==How to use Crunch==

{{QuickCrunchTutorial}}

Some other usage instructions can be found in the [https://github.com/DaemonEngine/crunch/blob/master/README.md#creating-compressed-textures-with-crunch README].

The {{code|-noNormalDetection}} and {{code|-rtopmip}} options are succinctly described below.

==Dæmon Crunch Enhancements==

Here are things you will not find in either Binomial Crunch, Unity Crunch or none of them:

===Unity Crunch format===

This repository merged improvements done by Unity Technologies, it produces
smaller files and produces them faster than original code by Binomial.
Unity also modified the format which makes it incompatible with earlier versions of the tool.

Quote from [https://unvanquished.net/unvanquished-area-51 unvanquished.net]:

<blockquote>
[https://blog.unity.com/technology/crunch-compression-of-etc-textures Unity guys said]
that their modified crunch tool “can compress up to 2.5
times faster, while providing about 10% better compression ratio”. So we
did a test on our own asset repository, re-crunching all the ressources
and textures packages. At the time we did the test the given corpus
produced 1797 .crn files.
The Unity’s crunch tool reduced compression time by 4.31 and reduced size
by 11.15%. They said “up to 2.5 time faster” but we’ve seen some random
textures being compressed 6 time faster and the average of the whole is
4.3 time faster, and yes the tool compresses more than 10% more.
</blockquote>

===Unity Crunch metadata===

Unlike the Unity {{code|crunch}} tool built from their public repository, this tool produces files loadable by the Unity engine. Since [https://github.com/DaemonEngine/crunch/blob/master/faf5127b8c69dfd1ae554f4f3bf8168048b48d9f February 11th 2023], this branch sets the CRN {{code|m_userdata0}} field to {{code|1}} to make CRN files loadable by the Unity engine which now prevents to load files with this value set to {{code|0}}.

Files with this value set to {{code|1}} are expected to use the new format. Files with this value set to {{code|0}} may or may not use the new format. When Unity updated the tool and modified the format in an incompatible way, no bit was modified to detect if a CRN file was using the old or the new format. Unity has not updated that field in their public repository of Crunch so files using new format with this value set to {{code|0}} may be found in the wild.

===Improved image compatibility===

Supported source file formats: CRN,DDS,KTX,TGA,BMP,PNG,JPG/JPEG,PSD. 
Supported output file formats: CRN,DDS,KTX,TGA,BMP,PNG,JPG/JPEG.

* 1-bit PNG files are supported.
* Flipped TGA files are supported.
* Progressive JPEG files are supported.

The {{code|stb_image}} library has been updated from version 1.18 to version 2.30, increasing the amount of image format variants that can be converted, like 1-bit PNG formats. Further improvements like horizontally-flipped TGA images were brought to {{code|stb_image}} to make it support more TGA variants.

Note: Some other specific file format variants may be unsupported.

See the docs for jpgd.h: {{url|code.google.com/p/jpeg-compressor}} 
See the docs for stb_image.h: {{url|github.com/nothings/stb}}

===Converted image reproducibility===

We take special care that, when using compilation options for IEEE 754 float processing (disabling fast math, preferring SSE over x87…), the bitstream of converted image files are the same whatever the compiler, the operating system, or the CPU architecture crunch is built for and running on. It helps making packaged game assets reproducible. The CI not only checks that crunch builds, but that it runs properly and that the same input converts to the same output.

When reproducibility isn't needed, fast math can be enabled with CMake with the {{code|1=-DUSE_FAST_MATH=ON}} CMake option.

It is recommended for those looking for generating reproducible CRN files to keep disabled the use of fast math. It is also recommended to disable x87 floats on i686 and to rely on SSE instead with the {{code|1=-mfpmath=sse -msse}} compiler flags.

===Added features and command line options===

In addition to the original {{code|crunch}} features and command line options this branch brings new features and options, including:

* {{code|-rtopmip}}: option to use with {{code|-renormalize}} to also renormalize on the top mip-level.
* {{code|-noNormalDetection}}: do not attempt to detect normal map to avoid selecting formats thought for normal maps when it's known an image is not a normal map. It may prevent the tool to use heavier and less-supported {{code|DXT5_AGBR}} format when {{code|DXT1}} is good enough.
* {{code|-h}} or {{code|--help}}: print the command line built-in help, listing all known options.

===Network file system compatibility===

The original {{code|crunch}} tool relied on non-standard I/O features not working on all file systems including network file systems like NFS or SSHFS. A standard implementation was added so the limitations are not there anymore and {{code|crunch}} can now process image files stored over the network and on any other file system.

===Optional header-only checksumming===

For applications distributing their files in containers already providing a checksum mechanism for the whole contained file, it's now possible to only validate the CRN header checksum instead of the whole file checksum to not checksum the whole file twice.

===Multisystem and multiplatform portability===

Unlike upstream branches from Binomial LLC and Unity Software Inc. this branch focuses on keeping the code buildable outside of Windows and Visual Studio, and adds a CMake build option alongside the legacy Makefile.

This {{code|crunch}} tool and the related {{code|crnlib}} library are known to build with and and run on:

* Compilers: GCC, MinGW, MSVC, Clang, Apple Clang, and more.
* Systems: Linux, Windows, macOS, FreeBSD.
* Architectures: amd64, arm64, i686, armhf.

===Thoroughly tested and improved reproducibility===

A continuous integration system tests the build of crunch for a dozen of configurations of different architecture, system or compiler. The output of such builds are also tested with most of those builds. It helped to improve and validate image support, to identify build options known to improve the reproducibility of the output, and is meant to catch regressions if they happen.

The Dæmon crunch code is frequently scanned with the the CodeQL static analyser.

===CMake build system===

CMake has now replaced the old Makefile. The supplied CMake configuration provides many useful build options. Toolchain files for MinGW cross-compilation are also supplied.

The native MSVC solution files were removed, it is expected that MSVC users generate them with CMake instead.

Tools/Crunch

2026-08-08T06:40:08Z

Illwieckz:

[[Category:Tools]]{{DISPLAYTITLE:Dæmon Crunch — Advanced DXTn Texture Compressor}}
[https://github.com/DaemonEngine/crunch Dæmon Crunch] is a maintained CRN texture compression library and command-line tool producing GPU-friendly formats such as CRN, DDS and KTX.

{{crunch}} is also the recommended TGA-to-PNG converter. When converting TGA images, prefer {{crunch}} over ImageMagick which is not reliable.

The [https://github.com/DaemonEngine/crunch Dæmon Crunch] is the most maintained and up-to-date Crunch available and the best choice for game developers.

==History==

The {{code|crunch}} tool was initially written by Binomial LLC then improved by Unity Technologies. The original Binomial Crunch is no longer maintained and lacks compatibility with newer Crunch formats. Although Unity contributed important improvements, the public Unity Crunch repository was never maintained as a proper long-term upstream project. Dæmon Crunch incorporated these improvements and has continued development with additional fixes, features, and maintenance.

Neither Binomial nor Unity have merged Unvanquished fixes and never demonstrated any serious interest in merging fixes provided by others, so the Unvanquished team not only maintained the Dæmon Crunch fork to host fixes, but also incorporated fixes from others developers. The Unvanquished team is actively maintaining Dæmon Crunch since 2014 (already more than a decade of maintenance and improvements!).

==Sources==

The Dæmon Crunch source repository is: [https://github.com/DaemonEngine/crunch github.com/DaemonEngine/crunch].

That repository provides the updated '''crunch''' tool, the '''crnlib''' library to provide full compression/decompression support to third-party applications, and the {{code|crn_decomp.h}} header-only library which is enough to transcode the Crunch CRN data for GPU upload and is perfect for lightweight integration in renderers. Some examples implementing various kinds of integrations are provided.

==Overview==

Some other details can be found in the [https://github.com/DaemonEngine/crunch/blob/master/README.md Crunch project README].

===Features===

The {{crunch}} provides many improvements over the original crunch:

* ✅️ Unity crunch format (runs many time faster and produces smaller files),
* ✅️ Unity crunch metadata (the header is compatible with Unity),
* ✅️ Improved image compatibility (1-bit PNG and horizontally-flipped TGA images are now supported),
* ✅️ Added features and command line options (top mip renormalization and more),
* ✅️ Network file system compatibility,
* ✅️ Optional header-only checksumming,
* ✅️ Multisystem and multiplatform,
* ✅️ Thoroughly tested and improved reproducibility,
* ✅️ CMake toolchain.

===Image formats===

* ✅️ CRN, DDS, KTX,
* ✅️ PNG, JPG, TGA, BMP.

Crunch produces compressed images optimized for performance and game rendering in various formats like DDS, KTX and CRN.

All those three formats are containers for DXT-compressed bitmaps. This DXT-compressed data can be uploaded directly to the GPU memory without decompression, and the GPU can process DXT-compressed data without decompression.

Crunch writes DXT-compressed data in a way an additional compression performs better on them, especially LZMA. For example, produced DDS images are expected to compress well if repackaged in an LZMA-based archive.

The CRN format does all of this in one go: it stores the DXT-compressed data into a custom LZMA container.

The game engine or any other application processing CRN files just have to unpack the LZMA container using provided functions and to upload the DXT-compressed data to the GPU.

The {{crunch}} sets the {{code|m_userdata0}} header field to {{code|1}} to make it compatible with Unity.

===Performance===

The {{crunch}} runs multiple times faster than the original Crunch by BinomialLLC, thanks to the work done by Unity that has been imported. Unity people claimed the tool runs 2.5 time faster, and we measured the tool running 4.3 time faster on the Unvanquished corpus. Unity people claimed the tool compresses about 10% better, we measured more than 11% on the Unvanquished corpus. This performance bump comes with a compatibility-breaking change introduced in the Unity branch.

The files produced by the Dæmon Crunch are then readable by both the Unity Crunch and the Dæmon Crunch but not by the original Binomial Crunch, while the files produced by the original Binomial Crunch are not readable by the Unity Crunch and the Dæmon Crunch. The Binomial Crunch isn't maintained anymore.

===Portability===

The {{crunch}} has very high cross-platform compatibility and is buildable with CMake.

The [https://github.com/DaemonEngine/crunch Dæmon Crunch source repository] is known to build with various compilers, and the Dæmon {{code|crunch}} tool is known to run on Linux, Windows, macOS and FreeBSD systems on various hardware architectures.

===Quality===

A continuous integration pipeline is configured to test the building of the tool and the library themselves and to run some tests. The code is frequently submitted to CodeQL static analysis.

===Adoption===

The {{crunch}} is known to be used by:

* The {{engine}},
* The {{Tools|Urcheon}} game data build tool,
* The {{Tools|NetRadiant}} level editor and the {{Tools|Q3map2}} map compiler and light mapper,
* The [https://github.com/XQF/xqf XQF] game server browser,
* The [https://unvanquished.net Unvanquished game],
* The [https://xonotic.org Xonotic game],
* The [https://overgrowth.wolfire.com Overgrowth game],
* Some games using the Unity game engine.

The {{crunch}} is known to be distributed by:

* The Debian operating system: {{url|tracker.debian.org/pkg/crunch-dxtc}}

==How to use Crunch==

{{QuickCrunchTutorial}}

Some other usage instructions can be found in the [https://github.com/DaemonEngine/crunch/blob/master/README.md#creating-compressed-textures-with-crunch README].

The {{code|-noNormalDetection}} and {{code|-rtopmip}} options are succinctly described below.

==Dæmon Crunch Enhancements==

Here are things you will not find in either Binomial Crunch, Unity Crunch or none of them:

===Unity Crunch format===

This repository merged improvements done by Unity Technologies, it produces
smaller files and produces them faster than original code by Binomial.
Unity also modified the format which makes it incompatible with earlier versions of the tool.

Quote from [https://unvanquished.net/unvanquished-area-51 unvanquished.net]:

<blockquote>
[https://blog.unity.com/technology/crunch-compression-of-etc-textures Unity guys said]
that their modified crunch tool “can compress up to 2.5
times faster, while providing about 10% better compression ratio”. So we
did a test on our own asset repository, re-crunching all the ressources
and textures packages. At the time we did the test the given corpus
produced 1797 .crn files.
The Unity’s crunch tool reduced compression time by 4.31 and reduced size
by 11.15%. They said “up to 2.5 time faster” but we’ve seen some random
textures being compressed 6 time faster and the average of the whole is
4.3 time faster, and yes the tool compresses more than 10% more.
</blockquote>

===Unity Crunch metadata===

Unlike the Unity {{code|crunch}} tool built from their public repository, this tool produces files loadable by the Unity engine. Since [https://github.com/DaemonEngine/crunch/blob/master/faf5127b8c69dfd1ae554f4f3bf8168048b48d9f February 11th 2023], this branch sets the CRN {{code|m_userdata0}} field to {{code|1}} to make CRN files loadable by the Unity engine which now prevents to load files with this value set to {{code|0}}.

Files with this value set to {{code|1}} are expected to use the new format. Files with this value set to {{code|0}} may or may not use the new format. When Unity updated the tool and modified the format in an incompatible way, no bit was modified to detect if a CRN file was using the old or the new format. Unity has not updated that field in their public repository of Crunch so files using new format with this value set to {{code|0}} may be found in the wild.

===Improved image compatibility===

Supported source file formats: CRN,DDS,KTX,TGA,BMP,PNG,JPG/JPEG,PSD. 
Supported output file formats: CRN,DDS,KTX,TGA,BMP,PNG,JPG/JPEG.

* 1-bit PNG files are supported.
* Flipped TGA files are supported.
* Progressive JPEG files are supported.

The {{code|stb_image}} library has been updated from version 1.18 to version 2.30, increasing the amount of image format variants that can be converted, like 1-bit PNG formats. Further improvements like horizontally-flipped TGA images were brought to {{code|stb_image}} to make it support more TGA variants.

Note: Some other specific file format variants may be unsupported.

See the docs for jpgd.h: {{url|code.google.com/p/jpeg-compressor}} 
See the docs for stb_image.h: {{url|github.com/nothings/stb}}

===Converted image reproducibility===

We take special care that, when using compilation options for IEEE 754 float processing (disabling fast math, preferring SSE over x87…), the bitstream of converted image files are the same whatever the compiler, the operating system, or the CPU architecture crunch is built for and running on. It helps making packaged game assets reproducible. The CI not only checks that crunch builds, but that it runs properly and that the same input converts to the same output.

When reproducibility isn't needed, fast math can be enabled with CMake with the {{code|1=-DUSE_FAST_MATH=ON}} CMake option.

It is recommended for those looking for generating reproducible CRN files to keep disabled the use of fast math. It is also recommended to disable x87 floats on i686 and to rely on SSE instead with the {{code|1=-mfpmath=sse -msse}} compiler flags.

===Added features and command line options===

In addition to the original {{code|crunch}} features and command line options this branch brings new features and options, including:

* {{code|-rtopmip}}: option to use with {{code|-renormalize}} to also renormalize on the top mip-level.
* {{code|-noNormalDetection}}: do not attempt to detect normal map to avoid selecting formats thought for normal maps when it's known an image is not a normal map. It may prevent the tool to use heavier and less-supported {{code|DXT5_AGBR}} format when {{code|DXT1}} is good enough.
* {{code|-h}} or {{code|--help}}: print the command line built-in help, listing all known options.

===Network file system compatibility===

The original {{code|crunch}} tool relied on non-standard I/O features not working on all file systems including network file systems like NFS or SSHFS. A standard implementation was added so the limitations are not there anymore and {{code|crunch}} can now process image files stored over the network and on any other file system.

===Optional header-only checksumming===

For applications distributing their files in containers already providing a checksum mechanism for the whole contained file, it's now possible to only validate the CRN header checksum instead of the whole file checksum to not checksum the whole file twice.

===Multisystem and multiplatform portability===

Unlike upstream branches from Binomial LLC and Unity Software Inc. this branch focuses on keeping the code buildable outside of Windows and Visual Studio, and adds a CMake build option alongside the legacy Makefile.

This {{code|crunch}} tool and the related {{code|crnlib}} library are known to build with and and run on:

* Compilers: GCC, MinGW, MSVC, Clang, Apple Clang, and more.
* Systems: Linux, Windows, macOS, FreeBSD.
* Architectures: amd64, arm64, i686, armhf.

===Thoroughly tested and improved reproducibility===

A continuous integration system tests the build of crunch for a dozen of configurations of different architecture, system or compiler. The output of such builds are also tested with most of those builds. It helped to improve and validate image support, to identify build options known to improve the reproducibility of the output, and is meant to catch regressions if they happen.

The Dæmon crunch code is frequently scanned with the the CodeQL static analyser.

===CMake build system===

CMake has now replaced the old Makefile. The supplied CMake configuration provides many useful build options. Toolchain files for MinGW cross-compilation are also supplied.

The native MSVC solution files were removed, it is expected that MSVC users generate them with CMake instead.

Tools/Crunch

2026-08-08T06:39:36Z

Illwieckz:

[[Category:Tools]]{{DISPLAYTITLE:Dæmon Crunch — Advanced DXTn Texture Compressor}}
[https://github.com/DaemonEngine/crunch Dæmon Crunch] is a maintained CRN texture compression library and command-line tool producing GPU-friendly formats such as CRN, DDS and KTX.

Crunch is also the recommended TGA-to-PNG converter. When converting TGA images, prefer {{crunch}} over ImageMagick which is not reliable.

The [https://github.com/DaemonEngine/crunch Dæmon Crunch] is the most maintained and up-to-date Crunch available and the best choice for game developers.

==History==

The {{code|crunch}} tool was initially written by Binomial LLC then improved by Unity Technologies. The original Binomial Crunch is no longer maintained and lacks compatibility with newer Crunch formats. Although Unity contributed important improvements, the public Unity Crunch repository was never maintained as a proper long-term upstream project. Dæmon Crunch incorporated these improvements and has continued development with additional fixes, features, and maintenance.

Neither Binomial nor Unity have merged Unvanquished fixes and never demonstrated any serious interest in merging fixes provided by others, so the Unvanquished team not only maintained the Dæmon Crunch fork to host fixes, but also incorporated fixes from others developers. The Unvanquished team is actively maintaining Dæmon Crunch since 2014 (already more than a decade of maintenance and improvements!).

==Sources==

The Dæmon Crunch source repository is: [https://github.com/DaemonEngine/crunch github.com/DaemonEngine/crunch].

That repository provides the updated '''crunch''' tool, the '''crnlib''' library to provide full compression/decompression support to third-party applications, and the {{code|crn_decomp.h}} header-only library which is enough to transcode the Crunch CRN data for GPU upload and is perfect for lightweight integration in renderers. Some examples implementing various kinds of integrations are provided.

==Overview==

Some other details can be found in the [https://github.com/DaemonEngine/crunch/blob/master/README.md Crunch project README].

===Features===

The {{crunch}} provides many improvements over the original crunch:

* ✅️ Unity crunch format (runs many time faster and produces smaller files),
* ✅️ Unity crunch metadata (the header is compatible with Unity),
* ✅️ Improved image compatibility (1-bit PNG and horizontally-flipped TGA images are now supported),
* ✅️ Added features and command line options (top mip renormalization and more),
* ✅️ Network file system compatibility,
* ✅️ Optional header-only checksumming,
* ✅️ Multisystem and multiplatform,
* ✅️ Thoroughly tested and improved reproducibility,
* ✅️ CMake toolchain.

===Image formats===

* ✅️ CRN, DDS, KTX,
* ✅️ PNG, JPG, TGA, BMP.

Crunch produces compressed images optimized for performance and game rendering in various formats like DDS, KTX and CRN.

All those three formats are containers for DXT-compressed bitmaps. This DXT-compressed data can be uploaded directly to the GPU memory without decompression, and the GPU can process DXT-compressed data without decompression.

Crunch writes DXT-compressed data in a way an additional compression performs better on them, especially LZMA. For example, produced DDS images are expected to compress well if repackaged in an LZMA-based archive.

The CRN format does all of this in one go: it stores the DXT-compressed data into a custom LZMA container.

The game engine or any other application processing CRN files just have to unpack the LZMA container using provided functions and to upload the DXT-compressed data to the GPU.

The {{crunch}} sets the {{code|m_userdata0}} header field to {{code|1}} to make it compatible with Unity.

===Performance===

The {{crunch}} runs multiple times faster than the original Crunch by BinomialLLC, thanks to the work done by Unity that has been imported. Unity people claimed the tool runs 2.5 time faster, and we measured the tool running 4.3 time faster on the Unvanquished corpus. Unity people claimed the tool compresses about 10% better, we measured more than 11% on the Unvanquished corpus. This performance bump comes with a compatibility-breaking change introduced in the Unity branch.

The files produced by the Dæmon Crunch are then readable by both the Unity Crunch and the Dæmon Crunch but not by the original Binomial Crunch, while the files produced by the original Binomial Crunch are not readable by the Unity Crunch and the Dæmon Crunch. The Binomial Crunch isn't maintained anymore.

===Portability===

The {{crunch}} has very high cross-platform compatibility and is buildable with CMake.

The [https://github.com/DaemonEngine/crunch Dæmon Crunch source repository] is known to build with various compilers, and the Dæmon {{code|crunch}} tool is known to run on Linux, Windows, macOS and FreeBSD systems on various hardware architectures.

===Quality===

A continuous integration pipeline is configured to test the building of the tool and the library themselves and to run some tests. The code is frequently submitted to CodeQL static analysis.

===Adoption===

The {{crunch}} is known to be used by:

* The {{engine}},
* The {{Tools|Urcheon}} game data build tool,
* The {{Tools|NetRadiant}} level editor and the {{Tools|Q3map2}} map compiler and light mapper,
* The [https://github.com/XQF/xqf XQF] game server browser,
* The [https://unvanquished.net Unvanquished game],
* The [https://xonotic.org Xonotic game],
* The [https://overgrowth.wolfire.com Overgrowth game],
* Some games using the Unity game engine.

The {{crunch}} is known to be distributed by:

* The Debian operating system: {{url|tracker.debian.org/pkg/crunch-dxtc}}

==How to use Crunch==

{{QuickCrunchTutorial}}

Some other usage instructions can be found in the [https://github.com/DaemonEngine/crunch/blob/master/README.md#creating-compressed-textures-with-crunch README].

The {{code|-noNormalDetection}} and {{code|-rtopmip}} options are succinctly described below.

==Dæmon Crunch Enhancements==

Here are things you will not find in either Binomial Crunch, Unity Crunch or none of them:

===Unity Crunch format===

This repository merged improvements done by Unity Technologies, it produces
smaller files and produces them faster than original code by Binomial.
Unity also modified the format which makes it incompatible with earlier versions of the tool.

Quote from [https://unvanquished.net/unvanquished-area-51 unvanquished.net]:

<blockquote>
[https://blog.unity.com/technology/crunch-compression-of-etc-textures Unity guys said]
that their modified crunch tool “can compress up to 2.5
times faster, while providing about 10% better compression ratio”. So we
did a test on our own asset repository, re-crunching all the ressources
and textures packages. At the time we did the test the given corpus
produced 1797 .crn files.
The Unity’s crunch tool reduced compression time by 4.31 and reduced size
by 11.15%. They said “up to 2.5 time faster” but we’ve seen some random
textures being compressed 6 time faster and the average of the whole is
4.3 time faster, and yes the tool compresses more than 10% more.
</blockquote>

===Unity Crunch metadata===

Unlike the Unity {{code|crunch}} tool built from their public repository, this tool produces files loadable by the Unity engine. Since [https://github.com/DaemonEngine/crunch/blob/master/faf5127b8c69dfd1ae554f4f3bf8168048b48d9f February 11th 2023], this branch sets the CRN {{code|m_userdata0}} field to {{code|1}} to make CRN files loadable by the Unity engine which now prevents to load files with this value set to {{code|0}}.

Files with this value set to {{code|1}} are expected to use the new format. Files with this value set to {{code|0}} may or may not use the new format. When Unity updated the tool and modified the format in an incompatible way, no bit was modified to detect if a CRN file was using the old or the new format. Unity has not updated that field in their public repository of Crunch so files using new format with this value set to {{code|0}} may be found in the wild.

===Improved image compatibility===

Supported source file formats: CRN,DDS,KTX,TGA,BMP,PNG,JPG/JPEG,PSD. 
Supported output file formats: CRN,DDS,KTX,TGA,BMP,PNG,JPG/JPEG.

* 1-bit PNG files are supported.
* Flipped TGA files are supported.
* Progressive JPEG files are supported.

The {{code|stb_image}} library has been updated from version 1.18 to version 2.30, increasing the amount of image format variants that can be converted, like 1-bit PNG formats. Further improvements like horizontally-flipped TGA images were brought to {{code|stb_image}} to make it support more TGA variants.

Note: Some other specific file format variants may be unsupported.

See the docs for jpgd.h: {{url|code.google.com/p/jpeg-compressor}} 
See the docs for stb_image.h: {{url|github.com/nothings/stb}}

===Converted image reproducibility===

We take special care that, when using compilation options for IEEE 754 float processing (disabling fast math, preferring SSE over x87…), the bitstream of converted image files are the same whatever the compiler, the operating system, or the CPU architecture crunch is built for and running on. It helps making packaged game assets reproducible. The CI not only checks that crunch builds, but that it runs properly and that the same input converts to the same output.

When reproducibility isn't needed, fast math can be enabled with CMake with the {{code|1=-DUSE_FAST_MATH=ON}} CMake option.

It is recommended for those looking for generating reproducible CRN files to keep disabled the use of fast math. It is also recommended to disable x87 floats on i686 and to rely on SSE instead with the {{code|1=-mfpmath=sse -msse}} compiler flags.

===Added features and command line options===

In addition to the original {{code|crunch}} features and command line options this branch brings new features and options, including:

* {{code|-rtopmip}}: option to use with {{code|-renormalize}} to also renormalize on the top mip-level.
* {{code|-noNormalDetection}}: do not attempt to detect normal map to avoid selecting formats thought for normal maps when it's known an image is not a normal map. It may prevent the tool to use heavier and less-supported {{code|DXT5_AGBR}} format when {{code|DXT1}} is good enough.
* {{code|-h}} or {{code|--help}}: print the command line built-in help, listing all known options.

===Network file system compatibility===

The original {{code|crunch}} tool relied on non-standard I/O features not working on all file systems including network file systems like NFS or SSHFS. A standard implementation was added so the limitations are not there anymore and {{code|crunch}} can now process image files stored over the network and on any other file system.

===Optional header-only checksumming===

For applications distributing their files in containers already providing a checksum mechanism for the whole contained file, it's now possible to only validate the CRN header checksum instead of the whole file checksum to not checksum the whole file twice.

===Multisystem and multiplatform portability===

Unlike upstream branches from Binomial LLC and Unity Software Inc. this branch focuses on keeping the code buildable outside of Windows and Visual Studio, and adds a CMake build option alongside the legacy Makefile.

This {{code|crunch}} tool and the related {{code|crnlib}} library are known to build with and and run on:

* Compilers: GCC, MinGW, MSVC, Clang, Apple Clang, and more.
* Systems: Linux, Windows, macOS, FreeBSD.
* Architectures: amd64, arm64, i686, armhf.

===Thoroughly tested and improved reproducibility===

A continuous integration system tests the build of crunch for a dozen of configurations of different architecture, system or compiler. The output of such builds are also tested with most of those builds. It helped to improve and validate image support, to identify build options known to improve the reproducibility of the output, and is meant to catch regressions if they happen.

The Dæmon crunch code is frequently scanned with the the CodeQL static analyser.

===CMake build system===

CMake has now replaced the old Makefile. The supplied CMake configuration provides many useful build options. Toolchain files for MinGW cross-compilation are also supplied.

The native MSVC solution files were removed, it is expected that MSVC users generate them with CMake instead.

Tools/Crunch

2026-08-08T06:37:11Z

Illwieckz: /* Adoption */

[[Category:Tools]]{{DISPLAYTITLE:Dæmon Crunch — Advanced DXTn Texture Compressor}}
[https://github.com/DaemonEngine/crunch Dæmon Crunch] is a maintained CRN texture compression library and command-line tool producing GPU-friendly formats such as CRN, DDS and KTX.

Crunch is also the recommended TGA-to-PNG converter. When converting TGA images, prefer {{crunch}} over ImageMagick which is not reliable.

The [https://github.com/DaemonEngine/crunch Dæmon Crunch] is the most maintained and up-to-date Crunch available and the best choice for game developers.

==History==

The {{code|crunch}} tool was initially written by Binomial LLC then improved by Unity Technologies. The original Binomial Crunch is no longer maintained and lacks compatibility with newer Crunch formats. Although Unity contributed important improvements, the public Unity Crunch repository was never maintained as a proper long-term upstream project. Dæmon Crunch incorporated these improvements and has continued development with additional fixes, features, and maintenance.

Neither Binomial nor Unity have merged Unvanquished fixes and never demonstrated any serious interest in merging fixes provided by others, so the Unvanquished team not only maintained the Dæmon Crunch fork to host fixes, but also incorporated fixes from others developers. The Unvanquished team is actively maintaining Dæmon Crunch since 2014 (already more than a decade of maintenance and improvements!).

==Sources==

The Dæmon Crunch source repository is: [https://github.com/DaemonEngine/crunch github.com/DaemonEngine/crunch].

That repository provides the updated '''crunch''' tool, the '''crnlib''' library to provide full compression/decompression support to third-party applications, and the {{code|crn_decomp.h}} header-only library which is enough to transcode the Crunch CRN data for GPU upload and is perfect for lightweight integration in renderers. Some examples implementing various kinds of integrations are provided.

==Overview==

Some other details can be found in the [https://github.com/DaemonEngine/crunch/blob/master/README.md Crunch project README].

===Features===

The Dæmon Crunch provides many improvements over the original crunch:

* ✅️ Unity crunch format (runs many time faster and produces smaller files),
* ✅️ Unity crunch metadata (the header is compatible with Unity),
* ✅️ Improved image compatibility (1-bit PNG and horizontally-flipped TGA images are now supported),
* ✅️ Added features and command line options (top mip renormalization and more),
* ✅️ Network file system compatibility,
* ✅️ Optional header-only checksumming,
* ✅️ Multisystem and multiplatform,
* ✅️ Thoroughly tested and improved reproducibility,
* ✅️ CMake toolchain.

===Image formats===

* ✅️ CRN, DDS, KTX,
* ✅️ PNG, JPG, TGA, BMP.

Crunch can produce compressed images optimized for performance and game rendering in various formats like DDS, KTX and CRN.

All those three formats are containers for DXT-compressed bitmaps. This DXT-compressed data can be uploaded directly to the GPU memory without decompression, and the GPU can process DXT-compressed data without decompression.

Crunch writes DXT-compressed data in a way an additional compression performs better on them, especially LZMA. For example, produced DDS images are expected to compress well if repackaged in an LZMA-based archive.

The CRN format does all of this in one go: it stores the DXT-compressed data into a custom LZMA container.

The game engine or any other application processing CRN files just have to unpack the LZMA container using provided functions and to upload the DXT-compressed data to the GPU.

The Dæmon crunch sets the {{code|m_userdata0}} header field to {{code|1}} to make it compatible with Unity.

===Performance===

The Dæmon Crunch runs multiple times faster than the original Crunch by BinomialLLC, thanks to the work done by Unity that has been imported. Unity people claimed the tool runs 2.5 time faster, and we measured the tool running 4.3 time faster on the Unvanquished corpus. Unity people claimed the tool compresses about 10% better, we measured more than 11% on the Unvanquished corpus. This performance bump comes with a compatibility-breaking change introduced in the Unity branch.

The files produced by the Dæmon Crunch are then readable by both the Unity Crunch and the Dæmon Crunch but not by the original Binomial Crunch, while the files produced by the original Binomial Crunch are not readable by the Unity Crunch and the Dæmon Crunch. The Binomial Crunch isn't maintained anymore.

===Portability===

The Dæmon crunch has very high cross-platform compatibility and is buildable with CMake.

The [https://github.com/DaemonEngine/crunch Dæmon Crunch source repository] is known to build with various compilers, and the Dæmon {{code|crunch}} tool is known to run on Linux, Windows, macOS and FreeBSD systems on various hardware architectures.

===Quality===

A continuous integration pipeline is configured to test the building of the tool and the library themselves and to run some tests. The code is frequently submitted to CodeQL static analysis.

===Adoption===

The {{crunch}} is known to be used by:

* The {{engine}},
* The {{Tools|Urcheon}} game data build tool,
* The {{Tools|NetRadiant}} level editor and the {{Tools|Q3map2}} map compiler and light mapper,
* The [https://github.com/XQF/xqf XQF] game server browser,
* The [https://unvanquished.net Unvanquished game],
* The [https://xonotic.org Xonotic game],
* The [https://overgrowth.wolfire.com Overgrowth game],
* Some games using the Unity game engine.

The {{crunch}} is known to be distributed by:

* The Debian operating system: {{url|tracker.debian.org/pkg/crunch-dxtc}}

==How to use Crunch==

{{QuickCrunchTutorial}}

Some other usage instructions can be found in the [https://github.com/DaemonEngine/crunch/blob/master/README.md#creating-compressed-textures-with-crunch README].

The {{code|-noNormalDetection}} and {{code|-rtopmip}} options are succinctly described below.

==Dæmon Crunch Enhancements==

Here are things you will not find in either Binomial Crunch, Unity Crunch or none of them:

===Unity Crunch format===

This repository merged improvements done by Unity Technologies, it produces
smaller files and produces them faster than original code by Binomial.
Unity also modified the format which makes it incompatible with earlier versions of the tool.

Quote from [https://unvanquished.net/unvanquished-area-51 unvanquished.net]:

<blockquote>
[https://blog.unity.com/technology/crunch-compression-of-etc-textures Unity guys said]
that their modified crunch tool “can compress up to 2.5
times faster, while providing about 10% better compression ratio”. So we
did a test on our own asset repository, re-crunching all the ressources
and textures packages. At the time we did the test the given corpus
produced 1797 .crn files.
The Unity’s crunch tool reduced compression time by 4.31 and reduced size
by 11.15%. They said “up to 2.5 time faster” but we’ve seen some random
textures being compressed 6 time faster and the average of the whole is
4.3 time faster, and yes the tool compresses more than 10% more.
</blockquote>

===Unity Crunch metadata===

Unlike the Unity {{code|crunch}} tool built from their public repository, this tool produces files loadable by the Unity engine. Since [https://github.com/DaemonEngine/crunch/blob/master/faf5127b8c69dfd1ae554f4f3bf8168048b48d9f February 11th 2023], this branch sets the CRN {{code|m_userdata0}} field to {{code|1}} to make CRN files loadable by the Unity engine which now prevents to load files with this value set to {{code|0}}.

Files with this value set to {{code|1}} are expected to use the new format. Files with this value set to {{code|0}} may or may not use the new format. When Unity updated the tool and modified the format in an incompatible way, no bit was modified to detect if a CRN file was using the old or the new format. Unity has not updated that field in their public repository of Crunch so files using new format with this value set to {{code|0}} may be found in the wild.

===Improved image compatibility===

Supported source file formats: CRN,DDS,KTX,TGA,BMP,PNG,JPG/JPEG,PSD. 
Supported output file formats: CRN,DDS,KTX,TGA,BMP,PNG,JPG/JPEG.

* 1-bit PNG files are supported.
* Flipped TGA files are supported.
* Progressive JPEG files are supported.

The {{code|stb_image}} library has been updated from version 1.18 to version 2.30, increasing the amount of image format variants that can be converted, like 1-bit PNG formats. Further improvements like horizontally-flipped TGA images were brought to {{code|stb_image}} to make it support more TGA variants.

Note: Some other specific file format variants may be unsupported.

See the docs for jpgd.h: {{url|code.google.com/p/jpeg-compressor}} 
See the docs for stb_image.h: {{url|github.com/nothings/stb}}

===Converted image reproducibility===

We take special care that, when using compilation options for IEEE 754 float processing (disabling fast math, preferring SSE over x87…), the bitstream of converted image files are the same whatever the compiler, the operating system, or the CPU architecture crunch is built for and running on. It helps making packaged game assets reproducible. The CI not only checks that crunch builds, but that it runs properly and that the same input converts to the same output.

When reproducibility isn't needed, fast math can be enabled with CMake with the {{code|1=-DUSE_FAST_MATH=ON}} CMake option.

It is recommended for those looking for generating reproducible CRN files to keep disabled the use of fast math. It is also recommended to disable x87 floats on i686 and to rely on SSE instead with the {{code|1=-mfpmath=sse -msse}} compiler flags.

===Added features and command line options===

In addition to the original {{code|crunch}} features and command line options this branch brings new features and options, including:

* {{code|-rtopmip}}: option to use with {{code|-renormalize}} to also renormalize on the top mip-level.
* {{code|-noNormalDetection}}: do not attempt to detect normal map to avoid selecting formats thought for normal maps when it's known an image is not a normal map. It may prevent the tool to use heavier and less-supported {{code|DXT5_AGBR}} format when {{code|DXT1}} is good enough.
* {{code|-h}} or {{code|--help}}: print the command line built-in help, listing all known options.

===Network file system compatibility===

The original {{code|crunch}} tool relied on non-standard I/O features not working on all file systems including network file systems like NFS or SSHFS. A standard implementation was added so the limitations are not there anymore and {{code|crunch}} can now process image files stored over the network and on any other file system.

===Optional header-only checksumming===

For applications distributing their files in containers already providing a checksum mechanism for the whole contained file, it's now possible to only validate the CRN header checksum instead of the whole file checksum to not checksum the whole file twice.

===Multisystem and multiplatform portability===

Unlike upstream branches from Binomial LLC and Unity Software Inc. this branch focuses on keeping the code buildable outside of Windows and Visual Studio, and adds a CMake build option alongside the legacy Makefile.

This {{code|crunch}} tool and the related {{code|crnlib}} library are known to build with and and run on:

* Compilers: GCC, MinGW, MSVC, Clang, Apple Clang, and more.
* Systems: Linux, Windows, macOS, FreeBSD.
* Architectures: amd64, arm64, i686, armhf.

===Thoroughly tested and improved reproducibility===

A continuous integration system tests the build of crunch for a dozen of configurations of different architecture, system or compiler. The output of such builds are also tested with most of those builds. It helped to improve and validate image support, to identify build options known to improve the reproducibility of the output, and is meant to catch regressions if they happen.

The Dæmon crunch code is frequently scanned with the the CodeQL static analyser.

===CMake build system===

CMake has now replaced the old Makefile. The supplied CMake configuration provides many useful build options. Toolchain files for MinGW cross-compilation are also supplied.

The native MSVC solution files were removed, it is expected that MSVC users generate them with CMake instead.

Tools/Crunch

2026-08-08T06:20:54Z

Illwieckz: Debian provides dxtc

[[Category:Tools]]{{DISPLAYTITLE:Dæmon Crunch — Advanced DXTn Texture Compressor}}
[https://github.com/DaemonEngine/crunch Dæmon Crunch] is a maintained CRN texture compression library and command-line tool producing GPU-friendly formats such as CRN, DDS and KTX.

Crunch is also the recommended TGA-to-PNG converter. When converting TGA images, prefer {{crunch}} over ImageMagick which is not reliable.

The [https://github.com/DaemonEngine/crunch Dæmon Crunch] is the most maintained and up-to-date Crunch available and the best choice for game developers.

==History==

The {{code|crunch}} tool was initially written by Binomial LLC then improved by Unity Technologies. The original Binomial Crunch is no longer maintained and lacks compatibility with newer Crunch formats. Although Unity contributed important improvements, the public Unity Crunch repository was never maintained as a proper long-term upstream project. Dæmon Crunch incorporated these improvements and has continued development with additional fixes, features, and maintenance.

Neither Binomial nor Unity have merged Unvanquished fixes and never demonstrated any serious interest in merging fixes provided by others, so the Unvanquished team not only maintained the Dæmon Crunch fork to host fixes, but also incorporated fixes from others developers. The Unvanquished team is actively maintaining Dæmon Crunch since 2014 (already more than a decade of maintenance and improvements!).

==Sources==

The Dæmon Crunch source repository is: [https://github.com/DaemonEngine/crunch github.com/DaemonEngine/crunch].

That repository provides the updated '''crunch''' tool, the '''crnlib''' library to provide full compression/decompression support to third-party applications, and the {{code|crn_decomp.h}} header-only library which is enough to transcode the Crunch CRN data for GPU upload and is perfect for lightweight integration in renderers. Some examples implementing various kinds of integrations are provided.

==Overview==

Some other details can be found in the [https://github.com/DaemonEngine/crunch/blob/master/README.md Crunch project README].

===Features===

The Dæmon Crunch provides many improvements over the original crunch:

* ✅️ Unity crunch format (runs many time faster and produces smaller files),
* ✅️ Unity crunch metadata (the header is compatible with Unity),
* ✅️ Improved image compatibility (1-bit PNG and horizontally-flipped TGA images are now supported),
* ✅️ Added features and command line options (top mip renormalization and more),
* ✅️ Network file system compatibility,
* ✅️ Optional header-only checksumming,
* ✅️ Multisystem and multiplatform,
* ✅️ Thoroughly tested and improved reproducibility,
* ✅️ CMake toolchain.

===Image formats===

* ✅️ CRN, DDS, KTX,
* ✅️ PNG, JPG, TGA, BMP.

Crunch can produce compressed images optimized for performance and game rendering in various formats like DDS, KTX and CRN.

All those three formats are containers for DXT-compressed bitmaps. This DXT-compressed data can be uploaded directly to the GPU memory without decompression, and the GPU can process DXT-compressed data without decompression.

Crunch writes DXT-compressed data in a way an additional compression performs better on them, especially LZMA. For example, produced DDS images are expected to compress well if repackaged in an LZMA-based archive.

The CRN format does all of this in one go: it stores the DXT-compressed data into a custom LZMA container.

The game engine or any other application processing CRN files just have to unpack the LZMA container using provided functions and to upload the DXT-compressed data to the GPU.

The Dæmon crunch sets the {{code|m_userdata0}} header field to {{code|1}} to make it compatible with Unity.

===Performance===

The Dæmon Crunch runs multiple times faster than the original Crunch by BinomialLLC, thanks to the work done by Unity that has been imported. Unity people claimed the tool runs 2.5 time faster, and we measured the tool running 4.3 time faster on the Unvanquished corpus. Unity people claimed the tool compresses about 10% better, we measured more than 11% on the Unvanquished corpus. This performance bump comes with a compatibility-breaking change introduced in the Unity branch.

The files produced by the Dæmon Crunch are then readable by both the Unity Crunch and the Dæmon Crunch but not by the original Binomial Crunch, while the files produced by the original Binomial Crunch are not readable by the Unity Crunch and the Dæmon Crunch. The Binomial Crunch isn't maintained anymore.

===Portability===

The Dæmon crunch has very high cross-platform compatibility and is buildable with CMake.

The [https://github.com/DaemonEngine/crunch Dæmon Crunch source repository] is known to build with various compilers, and the Dæmon {{code|crunch}} tool is known to run on Linux, Windows, macOS and FreeBSD systems on various hardware architectures.

===Quality===

A continuous integration pipeline is configured to test the building of the tool and the library themselves and to run some tests. The code is frequently submitted to CodeQL static analysis.

===Adoption===

The Dæmon crunch is known to be used by:

* The {{engine}},
* The {{Tools|Urcheon}} game data build tool,
* The {{Tools|NetRadiant}} level editor and the {{Tools|Q3map2}} map compiler and light mapper,
* The [https://github.com/XQF/xqf XQF] game server browser,
* The [https://unvanquished.net Unvanquished game],
* The [https://xonotic.org Xonotic game],
* The [https://overgrowth.wolfire.com Overgrowth game],
* Some games using the Unity game engine.

The Dæmon crunch is known to be distributed by:

* The Debian operating system: {{url|tracker.debian.org/pkg/crunch-dxtc}}

==How to use Crunch==

{{QuickCrunchTutorial}}

Some other usage instructions can be found in the [https://github.com/DaemonEngine/crunch/blob/master/README.md#creating-compressed-textures-with-crunch README].

The {{code|-noNormalDetection}} and {{code|-rtopmip}} options are succinctly described below.

==Dæmon Crunch Enhancements==

Here are things you will not find in either Binomial Crunch, Unity Crunch or none of them:

===Unity Crunch format===

This repository merged improvements done by Unity Technologies, it produces
smaller files and produces them faster than original code by Binomial.
Unity also modified the format which makes it incompatible with earlier versions of the tool.

Quote from [https://unvanquished.net/unvanquished-area-51 unvanquished.net]:

<blockquote>
[https://blog.unity.com/technology/crunch-compression-of-etc-textures Unity guys said]
that their modified crunch tool “can compress up to 2.5
times faster, while providing about 10% better compression ratio”. So we
did a test on our own asset repository, re-crunching all the ressources
and textures packages. At the time we did the test the given corpus
produced 1797 .crn files.
The Unity’s crunch tool reduced compression time by 4.31 and reduced size
by 11.15%. They said “up to 2.5 time faster” but we’ve seen some random
textures being compressed 6 time faster and the average of the whole is
4.3 time faster, and yes the tool compresses more than 10% more.
</blockquote>

===Unity Crunch metadata===

Unlike the Unity {{code|crunch}} tool built from their public repository, this tool produces files loadable by the Unity engine. Since [https://github.com/DaemonEngine/crunch/blob/master/faf5127b8c69dfd1ae554f4f3bf8168048b48d9f February 11th 2023], this branch sets the CRN {{code|m_userdata0}} field to {{code|1}} to make CRN files loadable by the Unity engine which now prevents to load files with this value set to {{code|0}}.

Files with this value set to {{code|1}} are expected to use the new format. Files with this value set to {{code|0}} may or may not use the new format. When Unity updated the tool and modified the format in an incompatible way, no bit was modified to detect if a CRN file was using the old or the new format. Unity has not updated that field in their public repository of Crunch so files using new format with this value set to {{code|0}} may be found in the wild.

===Improved image compatibility===

Supported source file formats: CRN,DDS,KTX,TGA,BMP,PNG,JPG/JPEG,PSD. 
Supported output file formats: CRN,DDS,KTX,TGA,BMP,PNG,JPG/JPEG.

* 1-bit PNG files are supported.
* Flipped TGA files are supported.
* Progressive JPEG files are supported.

The {{code|stb_image}} library has been updated from version 1.18 to version 2.30, increasing the amount of image format variants that can be converted, like 1-bit PNG formats. Further improvements like horizontally-flipped TGA images were brought to {{code|stb_image}} to make it support more TGA variants.

Note: Some other specific file format variants may be unsupported.

See the docs for jpgd.h: {{url|code.google.com/p/jpeg-compressor}} 
See the docs for stb_image.h: {{url|github.com/nothings/stb}}

===Converted image reproducibility===

We take special care that, when using compilation options for IEEE 754 float processing (disabling fast math, preferring SSE over x87…), the bitstream of converted image files are the same whatever the compiler, the operating system, or the CPU architecture crunch is built for and running on. It helps making packaged game assets reproducible. The CI not only checks that crunch builds, but that it runs properly and that the same input converts to the same output.

When reproducibility isn't needed, fast math can be enabled with CMake with the {{code|1=-DUSE_FAST_MATH=ON}} CMake option.

It is recommended for those looking for generating reproducible CRN files to keep disabled the use of fast math. It is also recommended to disable x87 floats on i686 and to rely on SSE instead with the {{code|1=-mfpmath=sse -msse}} compiler flags.

===Added features and command line options===

In addition to the original {{code|crunch}} features and command line options this branch brings new features and options, including:

* {{code|-rtopmip}}: option to use with {{code|-renormalize}} to also renormalize on the top mip-level.
* {{code|-noNormalDetection}}: do not attempt to detect normal map to avoid selecting formats thought for normal maps when it's known an image is not a normal map. It may prevent the tool to use heavier and less-supported {{code|DXT5_AGBR}} format when {{code|DXT1}} is good enough.
* {{code|-h}} or {{code|--help}}: print the command line built-in help, listing all known options.

===Network file system compatibility===

The original {{code|crunch}} tool relied on non-standard I/O features not working on all file systems including network file systems like NFS or SSHFS. A standard implementation was added so the limitations are not there anymore and {{code|crunch}} can now process image files stored over the network and on any other file system.

===Optional header-only checksumming===

For applications distributing their files in containers already providing a checksum mechanism for the whole contained file, it's now possible to only validate the CRN header checksum instead of the whole file checksum to not checksum the whole file twice.

===Multisystem and multiplatform portability===

Unlike upstream branches from Binomial LLC and Unity Software Inc. this branch focuses on keeping the code buildable outside of Windows and Visual Studio, and adds a CMake build option alongside the legacy Makefile.

This {{code|crunch}} tool and the related {{code|crnlib}} library are known to build with and and run on:

* Compilers: GCC, MinGW, MSVC, Clang, Apple Clang, and more.
* Systems: Linux, Windows, macOS, FreeBSD.
* Architectures: amd64, arm64, i686, armhf.

===Thoroughly tested and improved reproducibility===

A continuous integration system tests the build of crunch for a dozen of configurations of different architecture, system or compiler. The output of such builds are also tested with most of those builds. It helped to improve and validate image support, to identify build options known to improve the reproducibility of the output, and is meant to catch regressions if they happen.

The Dæmon crunch code is frequently scanned with the the CodeQL static analyser.

===CMake build system===

CMake has now replaced the old Makefile. The supplied CMake configuration provides many useful build options. Toolchain files for MinGW cross-compilation are also supplied.

The native MSVC solution files were removed, it is expected that MSVC users generate them with CMake instead.

Tools/Saigo

2026-08-06T04:04:09Z

Illwieckz: /* Sources */

[[Category:Tools]][[Category:Native Client]]{{DISPLAYTITLE:Dæmon Saigo SDK — Modern Toolchain for Native Client}}
Saigo is a modern toolchain for compiling {{nacl}} applications.

{{Trivia|
In Japanese, ''Saigo'' (さいご / 最後) means “''the last''”, “''the end''”, “''the final''” or “''the conclusion''”. This refers to the end of an era, the final stage of an event, or the last item in a sequence…

Saigo is the name Google gave to its latest compiler suite for building Native Client applications. The {{saigo}} is based on it.}}

{{NativeClientGoogleDeprecation}}

==Status==

{{SaigoStatus}}

==Components==

The Saigo SDK consists of:

* C and C++ compilers based on LLVM clang;
* Utilities like a linker, based on GNU binutils;
* A debugger, based on GDB;
* A libc based on Newlib and a libc++ based on LLVM.
* Headers from the Native Client repositories.

The compiler supports latest C++ standards like C23 and C++23. Unlike PNaCl, Saigo compiles directly to {{code|.nexe}}.

Saigo may not support C++ exceptions as far as we know but supports {{code|setjmp/longjmp}}.

==Sources==

The project for rebuilding the Saigo Native Client SDK can be found there:

* {{url|github.com/DaemonEngine/saigo-nacl-sdk}}

This project include patches applied over compile, binutils and debugger repositories before building. This project builds clang, binutils and gdb from Google repositories, and fetches headers from the Dæmon Native Client Runtime repository:

* {{url|chromium.googlesource.com/native_client/nacl-llvm-project-v10}} (Saigo NaCl clang)
* {{url|chromium.googlesource.com/native_client/nacl-binutils}} (NaCl binutils)
* {{url|chromium.googlesource.com/native_client/nacl-gdb}} (NaCl Saigo GDB)
* {{url|github.com/DaemonEngine/native_client}} (NaCl headers)

==Platform support==

{{NativeClientPlatformSupport}}

==Breakpad support==

Code compiled with Saigo uses {{code|-2}} instead of {{code|-1}} as value for the CFA pseudo-register.

We patched {{Tools|Breakpad}} to also support Saigo binaries, see this [https://github.com/DaemonEngine/breakpad/pull/19 patch].

==Migration to Saigo==

Here is a GitHub issue about the ongoing efforts for migrating to Saigo:

* {{url|github.com/Unvanquished/Unvanquished/issues/3197}}

Native Client

2026-08-06T04:03:37Z

Illwieckz: /* Rebuild effort */

[[Category:Native Client]]{{DISPLAYTITLE:Native Client — Secure Native Code Sandbox Technology}}
{{nacl}} (also known as NaCl) is a sandboxing technology by Google. It was used by Chrome extensions and Chrome apps. The {{engine}} uses Native Client to securely and portably run downloadable compiled games. It replaced the Q3VM (Quake 3 Virtual Machine) in the engine.

The Native Client documentation can be found on [https://chrome.jscn.org/docs/native-client/welcome-to-native-client/ chrome.jscn.org/docs/native-client/welcome-to-native-client/].

The NaCl support consists of:

* {{naclruntime}} — a modern Native Client runtime to run NaCl executables;
* {{saigo}} — a modern toolchain for Native Client with compilers and a debugger to build NaCl executables;
* {{breakpad}} — an enhanced crash reporting library with support for NaCl executables built with Saigo.

==Status==

'''Native Client''' or '''NaCl''' is the current technology used for securely virtualising the game code in the {{engine}}.

Server-side game logic NaCl support was first shipped in Alpha 27, released in April 2014. See the [https://unvanquished.net/moving-the-server-side-gamelogic-to-pnacl/ blog article by Kangz] and [https://unvanquished.net/alpha-27-flying-in-your-direction/ the release note by DSalt].

Client-side game logic NaCl support was first shipped in Alpha 37, released on March 2, 2015. See the [https://unvanquished.net/alpha-37-anniversary-edition/ release note by Kangz].

This completed the transition by porting the client VM to NaCl and this replaced entirely the legacy Quake III Q3VM system.

NaCl upstream development has slowed down since the competing solution [[WebAssembly]] became the industry standard, so it is very unlikely support for new systems and architecture would be added. To overcome this problem, we would have to switch to WebAssembly (that unfortunately may only support using a slow interpreter for some platforms NaCl supports, like i686 or armhf), but more importantly may still lack support for exceptions or {{code|setjmp/longjmp}} and then not be complete enough for our needs yet.

{{NativeClientIsDying}}

==Comparison==

{|
|+ Game VM comparison
|-
! !! Quake 3 / Tremulous !! Dæmon / Unvanquished
|-
| Technology || Q3VM || NaCl
|-
| Language || Old C (<ins>NOT</ins> Quake C) || Modern C / C++
|-
| Compiler || LCC (proprietary) || Clang (open-source)
|-
| System portability || Yes || Yes
|-
| Architecture portability || Yes || No
|-
| Secure sandbox || No || Yes
|}

With the Quake 3 engine and the Q3VM, the game code was programmed in C (it should not be confused with the scripting language of Quake 1 named QuakeC). This C code was real C was meant to be compiled with the proprietary LCC compiler, which only supported an old C, and the developer couldn't really rely on off-the-shelf libraries. That C code was compiled by LCC into {{code|.qvm}} binaries.

With the {{engine}}, the game code can be programmed in C or C++. That C/C++ code is compiled with Clang-based open source compilers supporting modern-enough C++ versions that makes possible to reuse off-the-shelf C++ libraries that may even be shared between the engine and the game source code. The C/C+ code is compiled into {{code|.nexe}} binarie.

Unlike QVMs, NaCl gamelogic runs in a secure sandbox. Native Client lets you run mods downloaded from the internet without giving them free reign on your computer. QVM was equivalent to running a DLL with no protection.

==Platform support==

{{NativeClientPlatformSupport}}

==NaCl Runtime==

See the {{naclruntime}} page for details.

==Rebuild effort==

{{NativeClientGoogleDeprecation}}

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}} being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

The project for rebuilding the {{naclruntime}} can be found there:

* {{url|github.com/DaemonEngine/native_client}}

The official releases for Unvanquished are already using the {{naclruntime}} on Linux for the {{code|amd64}} architecture, other systems are still using the Google NaCl Runtime.

The project for rebuilding the {{saigo}} can be found there:

* {{url|github.com/DaemonEngine/saigo-nacl-sdk}}

It's already possible to build Unvanquished with a Saigo compiler rebuilt this way.

==Compilers==

===Google PNaCl SDK===

PNaCl Clang is the current NaCl compiler we use to build the nexe game binaries. It is based on an old Clang 3.6 and does not support C++ above C++14. To overcome some of the related limitations we may switch to Saigo.

The PNaCl compilation workflow is to build a single {{code|.pexe}} then to translate them to per-architecture {{code|.nexe}} (amd64, i686, armhf) using a specific translator tool.

The PNaCl SDK consists on Python-based wrappers around Clang internals. It was initially using now-obsolete and hard-to-find Python2 but we ported it to Python3 to extend its lifespan.

The provided PNaCl SDK runs on Linux, Windows and macOS systems, on amd64 architectures.

While the {{code|.pexe}} compiler itself runs on FreeBSD with the Linuxulator, the translator does not, meaning it's not possible to build {{code|.nexe}} binaries on FreeBSD using Google PNaCl.

PNaCl supports C++ exception. There exist newer PNaCl SDKs (from chromium canary releases) that do not support exceptions and may not provide more what we already have with latest stable PNaCl.

===Dæmon Saigo SDK===

Saigo is a new NaCl compiler based on latest Clang and supporting latest C++ standards. It compiles directly to {{code|.nexe}}.

{{SaigoStatus}}

See {{saigo}} for details.

Saigo may not support C++ exceptions as far as we know but supports {{code|setjmp/longjmp}}.

Unlike PNaCl, Saigo wasn't released by Google, meaning a switch from PNaCl to Saigo required a convenient way to provide it to contributors. Google provided some nightly Linux amd64 Saigo toolchain snapshots that aren't easy to get without some Google scripts. The Saigo compiler itself isn't hard to build (same as Clang itself), the binutils are a bit more tricky but not that hard (10 years-old configure build). What is tricky to rebuild is the libc that requires some very old NaCl GCC. Fortunately there exists libc and libc++ snapshots provided by Google that can be reused with a self-built toolchain.

The Saigo compiler and NaCl binutils can be rebuilt to run natively on many platforms (Like Clang and GNU binutils), but they will always target the usual platforms as the NaCl loader is still the same: a more recent NaCl runtime is also buildable but doesn't bring any new platform support.

Moving to Saigo is considered as a migration step that can be achievable before migrating to [[WebAssembly]], as it allows us to migrate to a new C++ standard and update libraries we use without waiting for the migration to WebAssembly.

Some redesign of our CMake configuration for Saigo may help later when migrating to WebAssembly as it makes it more generic for different VM toolchains.

Here is a GitHub issue about the ongoing efforts for migrating to Saigo:

* {{url|github.com/Unvanquished/Unvanquished/issues/3197}}

==Interactive Debugging==

Most of the time it is easiest to debug with a native DLL. But if you have a problem that cannot be reproduced outside of NaCl, you may be forced to resort to the following tutorial.

These steps for attaching the NaCl debugger<ref>https://web.archive.org/web/20250909075554/https://www.chromium.org/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/getting-started-with-debug-stub/</ref> have been tested on Windows with a PNaCl toolchain. They should also work on binaries built with Saigo, using the old GDB from the PNaCl SDK or the GDB provided with the {{saigo}}. On Linux or Mac you may experience more difficulties due to the lack of support for old binaries (meaning nacl-gdb). illwieckz reports that on amd64 Linux in 2025, using the old GDB which is a 32-bit binary, debugging an amd64 nexe does not work (despite the documentation's claims of debugger platform independence), but debugging an i686 nexe does.

# Build the NaCl gamelogic with debugging symbols (build type Debug or RelWithDebInfo).
# Launch Daemon configured for NaCl debugging. For example, <code>./daemonded -set vm.sgame.type 1 -set vm.sgame.debug 1 +map chasm</code> When the relevant gamelogic starts, the engine should pause and emit the message <code>Waiting for GDB connection on localhost:4014</code>.
# Start NaCl GDB, e.g. <code>daemon\external_deps\windows-amd64-mingw_10\nacl-gdb.exe</code> This works better out of a command prompt rather than an MSYS window.
# Use the "file" command to tell the debugger where the binary with symbols is. For example, <code>file sgame-amd64.nexe</code>
# OPTIONAL, probably a waste of time: load the IRT (Integrated Runtime) symbols: <code>nacl-irt irt_core-amd64.nexe</code>
# Connect to the NaCl program with the command <code>target remote :4014</code>
# You should see a message like <code>0x000000000ffc00a0 in ?? ()</code> (or <code>0x000000000ffc00a0 in __pnacl_start ()</code> if you did step 5). This means the program is paused at the beginning.
# Set some breakpoints, e.g. <code>b G_RunFrame</code>. Alternatively, just wait for the debugger to break when the game crashes.
# Start the program by continuing (<code>c</code>).

==Postmortem Debugging==

See {{breakpad}}.

WebAssembly

2026-08-06T01:58:40Z

Illwieckz:

'''WebAssembly''' or '''Wasm''' is the best candidate for a future technology used for securely virtualising the game code in the {{engine}}.

It may replace {{nacl}} in the {{engine}} in the future.

Some work has been started some years ago but for now that effort is stalled.

{{NativeClientIsDying}}

WebAssembly

2026-08-06T01:58:28Z

Illwieckz:

'''WebAssembly''' or '''Wasm''' is the best candidate for a future technology used for securely virtualising the game code in the {{engine}}.

It may replace [[Native Client]] in the {{engine}} in the future.

Some work has been started some years ago but for now that effort is stalled.

{{NativeClientIsDying}}

Template:NativeClientIsDying

2026-08-06T01:57:57Z

Illwieckz:

{{note|header=Native Client is (not yet) dying|Thanks to the [[Native Client#Rebuild effort|Native Client Rebuild effort]] for both the {{naclruntime}} and the {{saigo}}, and the fact the Saigo compiler has been maintained by Google up to 2025, bringing Clang 21 and C++23, the NaCl technology may be relevant for another decade and this allows the Unvanquished team to focus resources on other things.

But {{nacl}} will die one day and we are slowly preparing the future. [[WebAssembly]] is the best candidate for a NaCl successor.

It's possible that the actual NaCl death will not come from Google but from Apple as they progressively deprecate the Rosetta 2 translation layer. When that will prevent to run the amd64 loader on Apple Silicon, then Native Client will be dead for macOS and would not be a viable multi-platform sandboxing solution anymore.}}

Tools/Saigo

2026-08-06T01:57:19Z

Illwieckz: /* Status */

[[Category:Tools]][[Category:Native Client]]{{DISPLAYTITLE:Dæmon Saigo SDK — Modern Toolchain for Native Client}}
Saigo is a modern toolchain for compiling {{nacl}} applications.

{{Trivia|
In Japanese, ''Saigo'' (さいご / 最後) means “''the last''”, “''the end''”, “''the final''” or “''the conclusion''”. This refers to the end of an era, the final stage of an event, or the last item in a sequence…

Saigo is the name Google gave to its latest compiler suite for building Native Client applications. The {{saigo}} is based on it.}}

{{NativeClientGoogleDeprecation}}

==Status==

{{SaigoStatus}}

==Components==

The Saigo SDK consists of:

* C and C++ compilers based on LLVM clang;
* Utilities like a linker, based on GNU binutils;
* A debugger, based on GDB;
* A libc based on Newlib and a libc++ based on LLVM.
* Headers from the Native Client repositories.

The compiler supports latest C++ standards like C23 and C++23. Unlike PNaCl, Saigo compiles directly to {{code|.nexe}}.

Saigo may not support C++ exceptions as far as we know but supports {{code|setjmp/longjmp}}.

==Sources==

The project for rebuilding the Saigo Native Client SDK can be found there:

* {{url|github.com/DaemonEngine/saigo-release-scripts}}

This project include patches applied over compile, binutils and debugger repositories before building. This project builds clang, binutils and gdb from Google repositories, and fetches headers from the Dæmon Native Client Runtime repository:

* {{url|chromium.googlesource.com/native_client/nacl-llvm-project-v10}} (Saigo NaCl clang)
* {{url|chromium.googlesource.com/native_client/nacl-binutils}} (NaCl binutils)
* {{url|chromium.googlesource.com/native_client/nacl-gdb}} (NaCl Saigo GDB)
* {{url|github.com/DaemonEngine/native_client}} (NaCl headers)

==Platform support==

{{NativeClientPlatformSupport}}

==Breakpad support==

Code compiled with Saigo uses {{code|-2}} instead of {{code|-1}} as value for the CFA pseudo-register.

We patched {{Tools|Breakpad}} to also support Saigo binaries, see this [https://github.com/DaemonEngine/breakpad/pull/19 patch].

==Migration to Saigo==

Here is a GitHub issue about the ongoing efforts for migrating to Saigo:

* {{url|github.com/Unvanquished/Unvanquished/issues/3197}}

Native Client

2026-08-06T01:56:59Z

Illwieckz: /* Dæmon Saigo SDK */

[[Category:Native Client]]{{DISPLAYTITLE:Native Client — Secure Native Code Sandbox Technology}}
{{nacl}} (also known as NaCl) is a sandboxing technology by Google. It was used by Chrome extensions and Chrome apps. The {{engine}} uses Native Client to securely and portably run downloadable compiled games. It replaced the Q3VM (Quake 3 Virtual Machine) in the engine.

The Native Client documentation can be found on [https://chrome.jscn.org/docs/native-client/welcome-to-native-client/ chrome.jscn.org/docs/native-client/welcome-to-native-client/].

The NaCl support consists of:

* {{naclruntime}} — a modern Native Client runtime to run NaCl executables;
* {{saigo}} — a modern toolchain for Native Client with compilers and a debugger to build NaCl executables;
* {{breakpad}} — an enhanced crash reporting library with support for NaCl executables built with Saigo.

==Status==

'''Native Client''' or '''NaCl''' is the current technology used for securely virtualising the game code in the {{engine}}.

Server-side game logic NaCl support was first shipped in Alpha 27, released in April 2014. See the [https://unvanquished.net/moving-the-server-side-gamelogic-to-pnacl/ blog article by Kangz] and [https://unvanquished.net/alpha-27-flying-in-your-direction/ the release note by DSalt].

Client-side game logic NaCl support was first shipped in Alpha 37, released on March 2, 2015. See the [https://unvanquished.net/alpha-37-anniversary-edition/ release note by Kangz].

This completed the transition by porting the client VM to NaCl and this replaced entirely the legacy Quake III Q3VM system.

NaCl upstream development has slowed down since the competing solution [[WebAssembly]] became the industry standard, so it is very unlikely support for new systems and architecture would be added. To overcome this problem, we would have to switch to WebAssembly (that unfortunately may only support using a slow interpreter for some platforms NaCl supports, like i686 or armhf), but more importantly may still lack support for exceptions or {{code|setjmp/longjmp}} and then not be complete enough for our needs yet.

{{NativeClientIsDying}}

==Comparison==

{|
|+ Game VM comparison
|-
! !! Quake 3 / Tremulous !! Dæmon / Unvanquished
|-
| Technology || Q3VM || NaCl
|-
| Language || Old C (<ins>NOT</ins> Quake C) || Modern C / C++
|-
| Compiler || LCC (proprietary) || Clang (open-source)
|-
| System portability || Yes || Yes
|-
| Architecture portability || Yes || No
|-
| Secure sandbox || No || Yes
|}

With the Quake 3 engine and the Q3VM, the game code was programmed in C (it should not be confused with the scripting language of Quake 1 named QuakeC). This C code was real C was meant to be compiled with the proprietary LCC compiler, which only supported an old C, and the developer couldn't really rely on off-the-shelf libraries. That C code was compiled by LCC into {{code|.qvm}} binaries.

With the {{engine}}, the game code can be programmed in C or C++. That C/C++ code is compiled with Clang-based open source compilers supporting modern-enough C++ versions that makes possible to reuse off-the-shelf C++ libraries that may even be shared between the engine and the game source code. The C/C+ code is compiled into {{code|.nexe}} binarie.

Unlike QVMs, NaCl gamelogic runs in a secure sandbox. Native Client lets you run mods downloaded from the internet without giving them free reign on your computer. QVM was equivalent to running a DLL with no protection.

==Platform support==

{{NativeClientPlatformSupport}}

==NaCl Runtime==

See the {{naclruntime}} page for details.

==Rebuild effort==

{{NativeClientGoogleDeprecation}}

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}} being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

The project for rebuilding the {{naclruntime}} can be found there:

* {{url|github.com/DaemonEngine/native_client}}

The official releases for Unvanquished are already using the {{naclruntime}} on Linux for the {{code|amd64}} architecture, other systems are still using the Google NaCl Runtime.

The project for rebuilding the {{saigo}} can be found there:

* {{url|github.com/DaemonEngine/saigo-release-scripts}}

It's already possible to build Unvanquished with a Saigo compiler rebuilt this way.

==Compilers==

===Google PNaCl SDK===

PNaCl Clang is the current NaCl compiler we use to build the nexe game binaries. It is based on an old Clang 3.6 and does not support C++ above C++14. To overcome some of the related limitations we may switch to Saigo.

The PNaCl compilation workflow is to build a single {{code|.pexe}} then to translate them to per-architecture {{code|.nexe}} (amd64, i686, armhf) using a specific translator tool.

The PNaCl SDK consists on Python-based wrappers around Clang internals. It was initially using now-obsolete and hard-to-find Python2 but we ported it to Python3 to extend its lifespan.

The provided PNaCl SDK runs on Linux, Windows and macOS systems, on amd64 architectures.

While the {{code|.pexe}} compiler itself runs on FreeBSD with the Linuxulator, the translator does not, meaning it's not possible to build {{code|.nexe}} binaries on FreeBSD using Google PNaCl.

PNaCl supports C++ exception. There exist newer PNaCl SDKs (from chromium canary releases) that do not support exceptions and may not provide more what we already have with latest stable PNaCl.

===Dæmon Saigo SDK===

Saigo is a new NaCl compiler based on latest Clang and supporting latest C++ standards. It compiles directly to {{code|.nexe}}.

{{SaigoStatus}}

See {{saigo}} for details.

Saigo may not support C++ exceptions as far as we know but supports {{code|setjmp/longjmp}}.

Unlike PNaCl, Saigo wasn't released by Google, meaning a switch from PNaCl to Saigo required a convenient way to provide it to contributors. Google provided some nightly Linux amd64 Saigo toolchain snapshots that aren't easy to get without some Google scripts. The Saigo compiler itself isn't hard to build (same as Clang itself), the binutils are a bit more tricky but not that hard (10 years-old configure build). What is tricky to rebuild is the libc that requires some very old NaCl GCC. Fortunately there exists libc and libc++ snapshots provided by Google that can be reused with a self-built toolchain.

The Saigo compiler and NaCl binutils can be rebuilt to run natively on many platforms (Like Clang and GNU binutils), but they will always target the usual platforms as the NaCl loader is still the same: a more recent NaCl runtime is also buildable but doesn't bring any new platform support.

Moving to Saigo is considered as a migration step that can be achievable before migrating to [[WebAssembly]], as it allows us to migrate to a new C++ standard and update libraries we use without waiting for the migration to WebAssembly.

Some redesign of our CMake configuration for Saigo may help later when migrating to WebAssembly as it makes it more generic for different VM toolchains.

Here is a GitHub issue about the ongoing efforts for migrating to Saigo:

* {{url|github.com/Unvanquished/Unvanquished/issues/3197}}

==Interactive Debugging==

Most of the time it is easiest to debug with a native DLL. But if you have a problem that cannot be reproduced outside of NaCl, you may be forced to resort to the following tutorial.

These steps for attaching the NaCl debugger<ref>https://web.archive.org/web/20250909075554/https://www.chromium.org/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/getting-started-with-debug-stub/</ref> have been tested on Windows with a PNaCl toolchain. They should also work on binaries built with Saigo, using the old GDB from the PNaCl SDK or the GDB provided with the {{saigo}}. On Linux or Mac you may experience more difficulties due to the lack of support for old binaries (meaning nacl-gdb). illwieckz reports that on amd64 Linux in 2025, using the old GDB which is a 32-bit binary, debugging an amd64 nexe does not work (despite the documentation's claims of debugger platform independence), but debugging an i686 nexe does.

# Build the NaCl gamelogic with debugging symbols (build type Debug or RelWithDebInfo).
# Launch Daemon configured for NaCl debugging. For example, <code>./daemonded -set vm.sgame.type 1 -set vm.sgame.debug 1 +map chasm</code> When the relevant gamelogic starts, the engine should pause and emit the message <code>Waiting for GDB connection on localhost:4014</code>.
# Start NaCl GDB, e.g. <code>daemon\external_deps\windows-amd64-mingw_10\nacl-gdb.exe</code> This works better out of a command prompt rather than an MSYS window.
# Use the "file" command to tell the debugger where the binary with symbols is. For example, <code>file sgame-amd64.nexe</code>
# OPTIONAL, probably a waste of time: load the IRT (Integrated Runtime) symbols: <code>nacl-irt irt_core-amd64.nexe</code>
# Connect to the NaCl program with the command <code>target remote :4014</code>
# You should see a message like <code>0x000000000ffc00a0 in ?? ()</code> (or <code>0x000000000ffc00a0 in __pnacl_start ()</code> if you did step 5). This means the program is paused at the beginning.
# Set some breakpoints, e.g. <code>b G_RunFrame</code>. Alternatively, just wait for the debugger to break when the game crashes.
# Start the program by continuing (<code>c</code>).

==Postmortem Debugging==

See {{breakpad}}.

Template:SaigoStatus

2026-08-06T01:56:47Z

Illwieckz: Created page with "The Unvanquished team publishes frequent releases of the {{saigo}} with ready-to-use prebuilt packages for a large number of platforms: * {{url|github.com/DaemonEngine/saigo-..."

The Unvanquished team publishes frequent releases of the {{saigo}} with ready-to-use prebuilt packages for a large number of platforms:

* {{url|github.com/DaemonEngine/saigo-nacl-sdk/releases}}

The Unvanquished game code is already buildable with Saigo. Saigo is meant to replace PNaCl for Unvanquished release builds.

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}}) being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

Tools/Saigo

2026-08-06T01:55:21Z

Illwieckz:

[[Category:Tools]][[Category:Native Client]]{{DISPLAYTITLE:Dæmon Saigo SDK — Modern Toolchain for Native Client}}
Saigo is a modern toolchain for compiling {{nacl}} applications.

{{Trivia|
In Japanese, ''Saigo'' (さいご / 最後) means “''the last''”, “''the end''”, “''the final''” or “''the conclusion''”. This refers to the end of an era, the final stage of an event, or the last item in a sequence…

Saigo is the name Google gave to its latest compiler suite for building Native Client applications. The {{saigo}} is based on it.}}

{{NativeClientGoogleDeprecation}}

==Status==

The Unvanquished team publish frequent releases of the {{saigo}} with ready-to-use prebuilt packages for a large number of platforms:

* {{url|github.com/DaemonEngine/saigo-nacl-sdk/releases}}

The Unvanquished game code is already buildable with Saigo. Saigo is meant to replace PNaCl for Unvanquished release builds.

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}}) being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

==Components==

The Saigo SDK consists of:

* C and C++ compilers based on LLVM clang;
* Utilities like a linker, based on GNU binutils;
* A debugger, based on GDB;
* A libc based on Newlib and a libc++ based on LLVM.
* Headers from the Native Client repositories.

The compiler supports latest C++ standards like C23 and C++23. Unlike PNaCl, Saigo compiles directly to {{code|.nexe}}.

Saigo may not support C++ exceptions as far as we know but supports {{code|setjmp/longjmp}}.

==Sources==

The project for rebuilding the Saigo Native Client SDK can be found there:

* {{url|github.com/DaemonEngine/saigo-release-scripts}}

This project include patches applied over compile, binutils and debugger repositories before building. This project builds clang, binutils and gdb from Google repositories, and fetches headers from the Dæmon Native Client Runtime repository:

* {{url|chromium.googlesource.com/native_client/nacl-llvm-project-v10}} (Saigo NaCl clang)
* {{url|chromium.googlesource.com/native_client/nacl-binutils}} (NaCl binutils)
* {{url|chromium.googlesource.com/native_client/nacl-gdb}} (NaCl Saigo GDB)
* {{url|github.com/DaemonEngine/native_client}} (NaCl headers)

==Platform support==

{{NativeClientPlatformSupport}}

==Breakpad support==

Code compiled with Saigo uses {{code|-2}} instead of {{code|-1}} as value for the CFA pseudo-register.

We patched {{Tools|Breakpad}} to also support Saigo binaries, see this [https://github.com/DaemonEngine/breakpad/pull/19 patch].

==Migration to Saigo==

Here is a GitHub issue about the ongoing efforts for migrating to Saigo:

* {{url|github.com/Unvanquished/Unvanquished/issues/3197}}

Template:NativeClientIsDying

2026-08-06T01:53:27Z

Illwieckz:

{{note|header=Native Client is (not yet) dying|Thanks to the [[Native Client#Rebuild effort|Native Client Rebuild effort]] for both the {{naclruntime}} and the {{saigo}}, and the fact the Saigo compiler has been maintained by Google up to 2025, bringing Clang 21 and C++23, the NaCl technology may be relevant for another decade and this allows the Unvanquished team to focus resources on other things.

But [[Native Client]] will die one day and we are slowly preparing the future. [[WebAssembly]] is the best candidate for a NaCl successor.

It's possible that the actual NaCl death will not come from Google but from Apple as they progressively deprecate the Rosetta 2 translation layer. When that will prevent to run the amd64 loader on Apple Silicon, then Native Client will be dead for macOS and would not be a viable multi-platform sandboxing solution anymore.}}

Template:NativeClientIsDying

2026-08-06T01:52:29Z

Illwieckz:

{{note|header=Native Client is (not yet) dying|Thanks to the [[Native Client#Rebuild effort|Native Client Rebuild effort]] for both the {{naclruntime}} and the {{saigo}}, and the fact the Saigo compiler has been maintained by Google up to 2025, bringing Clang 21 and C++23, the NaCl technology may be relevant for another decade and this allows the Unvanquished team to focus resources on other things.

But [[Native Client]] will die one day and we are slowly preparing the future. [[WebAssembly]] is the best candidate for a Native Client successor.

It's possible that the actual NaCl death will not come from Google but from Apple as they progressively deprecate the Rosetta 2 translation layer. When that will prevent to run the amd64 loader on Apple Silicon, then Native Client will be dead for macOS and would not be a viable multi-platform sandboxing solution anymore.}}

Template:NativeClientIsDying

2026-08-06T01:51:44Z

Illwieckz:

{{note|header=Native Client is (not yet) dying|Thanks to the [[Native Client#Rebuild effort|Native Client Rebuild effort]] for both the NaCl loader and the Saigo NaCl compiler, and the fact the Saigo compiler has been maintained by Google up to 2025, bringing Clang 21 and C++23, the NaCl technology may be relevant for another decade and this allows the Unvanquished team to focus resources on other things.

But [[Native Client]] will die one day and we are slowly preparing the future. [[WebAssembly]] is the best candidate for a Native Client successor.

It's possible that the actual NaCl death will not come from Google but from Apple as they progressively deprecate the Rosetta 2 translation layer. When that will prevent to run the amd64 loader on Apple Silicon, then Native Client will be dead for macOS and would not be a viable multi-platform sandboxing solution anymore.}}

Template:NativeClientIsDying

2026-08-06T01:49:32Z

Illwieckz:

{{note|header=Native Client is (not yet) dying|Thanks to the [[Native Client#Rebuild effort|Native Client Rebuild effort]] for both the NaCl loader and the Saigo NaCl compiler, and the fact the Saigo compiler has been maintained by Google up to 2025, bringing Clang 21 and C++23, the NaCl technology may be relevant for another decade and this allows the Unvanquished team to focus resources on other things.

But [[Native Client]] will die one day, and we are slowly preparing the future, and [[WebAssembly]] is the best candidate for a Native Client successor.

It's possible that the actual NaCl death will not come from Google but from Apple when they will deprecate the Rosetta 2 translation layer. If that prevents to run the amd64 loader on Apple Silicon, then Native Client will be dead for macOS and would not be a viable multi-platform sandboxing solution anymore.}}

Native Client

2026-08-06T01:48:53Z

Illwieckz:

[[Category:Native Client]]{{DISPLAYTITLE:Native Client — Secure Native Code Sandbox Technology}}
{{nacl}} (also known as NaCl) is a sandboxing technology by Google. It was used by Chrome extensions and Chrome apps. The {{engine}} uses Native Client to securely and portably run downloadable compiled games. It replaced the Q3VM (Quake 3 Virtual Machine) in the engine.

The Native Client documentation can be found on [https://chrome.jscn.org/docs/native-client/welcome-to-native-client/ chrome.jscn.org/docs/native-client/welcome-to-native-client/].

The NaCl support consists of:

* {{naclruntime}} — a modern Native Client runtime to run NaCl executables;
* {{saigo}} — a modern toolchain for Native Client with compilers and a debugger to build NaCl executables;
* {{breakpad}} — an enhanced crash reporting library with support for NaCl executables built with Saigo.

==Status==

'''Native Client''' or '''NaCl''' is the current technology used for securely virtualising the game code in the {{engine}}.

Server-side game logic NaCl support was first shipped in Alpha 27, released in April 2014. See the [https://unvanquished.net/moving-the-server-side-gamelogic-to-pnacl/ blog article by Kangz] and [https://unvanquished.net/alpha-27-flying-in-your-direction/ the release note by DSalt].

Client-side game logic NaCl support was first shipped in Alpha 37, released on March 2, 2015. See the [https://unvanquished.net/alpha-37-anniversary-edition/ release note by Kangz].

This completed the transition by porting the client VM to NaCl and this replaced entirely the legacy Quake III Q3VM system.

NaCl upstream development has slowed down since the competing solution [[WebAssembly]] became the industry standard, so it is very unlikely support for new systems and architecture would be added. To overcome this problem, we would have to switch to WebAssembly (that unfortunately may only support using a slow interpreter for some platforms NaCl supports, like i686 or armhf), but more importantly may still lack support for exceptions or {{code|setjmp/longjmp}} and then not be complete enough for our needs yet.

{{NativeClientIsDying}}

==Comparison==

{|
|+ Game VM comparison
|-
! !! Quake 3 / Tremulous !! Dæmon / Unvanquished
|-
| Technology || Q3VM || NaCl
|-
| Language || Old C (<ins>NOT</ins> Quake C) || Modern C / C++
|-
| Compiler || LCC (proprietary) || Clang (open-source)
|-
| System portability || Yes || Yes
|-
| Architecture portability || Yes || No
|-
| Secure sandbox || No || Yes
|}

With the Quake 3 engine and the Q3VM, the game code was programmed in C (it should not be confused with the scripting language of Quake 1 named QuakeC). This C code was real C was meant to be compiled with the proprietary LCC compiler, which only supported an old C, and the developer couldn't really rely on off-the-shelf libraries. That C code was compiled by LCC into {{code|.qvm}} binaries.

With the {{engine}}, the game code can be programmed in C or C++. That C/C++ code is compiled with Clang-based open source compilers supporting modern-enough C++ versions that makes possible to reuse off-the-shelf C++ libraries that may even be shared between the engine and the game source code. The C/C+ code is compiled into {{code|.nexe}} binarie.

Unlike QVMs, NaCl gamelogic runs in a secure sandbox. Native Client lets you run mods downloaded from the internet without giving them free reign on your computer. QVM was equivalent to running a DLL with no protection.

==Platform support==

{{NativeClientPlatformSupport}}

==NaCl Runtime==

See the {{naclruntime}} page for details.

==Rebuild effort==

{{NativeClientGoogleDeprecation}}

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}} being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

The project for rebuilding the {{naclruntime}} can be found there:

* {{url|github.com/DaemonEngine/native_client}}

The official releases for Unvanquished are already using the {{naclruntime}} on Linux for the {{code|amd64}} architecture, other systems are still using the Google NaCl Runtime.

The project for rebuilding the {{saigo}} can be found there:

* {{url|github.com/DaemonEngine/saigo-release-scripts}}

It's already possible to build Unvanquished with a Saigo compiler rebuilt this way.

==Compilers==

===Google PNaCl SDK===

PNaCl Clang is the current NaCl compiler we use to build the nexe game binaries. It is based on an old Clang 3.6 and does not support C++ above C++14. To overcome some of the related limitations we may switch to Saigo.

The PNaCl compilation workflow is to build a single {{code|.pexe}} then to translate them to per-architecture {{code|.nexe}} (amd64, i686, armhf) using a specific translator tool.

The PNaCl SDK consists on Python-based wrappers around Clang internals. It was initially using now-obsolete and hard-to-find Python2 but we ported it to Python3 to extend its lifespan.

The provided PNaCl SDK runs on Linux, Windows and macOS systems, on amd64 architectures.

While the {{code|.pexe}} compiler itself runs on FreeBSD with the Linuxulator, the translator does not, meaning it's not possible to build {{code|.nexe}} binaries on FreeBSD using Google PNaCl.

PNaCl supports C++ exception. There exist newer PNaCl SDKs (from chromium canary releases) that do not support exceptions and may not provide more what we already have with latest stable PNaCl.

===Dæmon Saigo SDK===

Saigo is a new NaCl compiler based on latest Clang and supporting latest C++ standards. It compiles directly to {{code|.nexe}}.

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}}) being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

The Unvanquished game code is already buildable with Saigo. Saigo is meant to replace PNaCl for Unvanquished release builds.

See {{saigo}} for details.

Saigo may not support C++ exceptions as far as we know but supports {{code|setjmp/longjmp}}.

Unlike PNaCl, Saigo wasn't released by Google, meaning a switch from PNaCl to Saigo required a convenient way to provide it to contributors. Google provided some nightly Linux amd64 Saigo toolchain snapshots that aren't easy to get without some Google scripts. The Saigo compiler itself isn't hard to build (same as Clang itself), the binutils are a bit more tricky but not that hard (10 years-old configure build). What is tricky to rebuild is the libc that requires some very old NaCl GCC. Fortunately there exists libc and libc++ snapshots provided by Google that can be reused with a self-built toolchain.

The Saigo compiler and NaCl binutils can be rebuilt to run natively on many platforms (Like Clang and GNU binutils), but they will always target the usual platforms as the NaCl loader is still the same: a more recent NaCl runtime is also buildable but doesn't bring any new platform support.

Moving to Saigo is considered as a migration step that can be achievable before migrating to [[WebAssembly]], as it allows us to migrate to a new C++ standard and update libraries we use without waiting for the migration to WebAssembly.

Some redesign of our CMake configuration for Saigo may help later when migrating to WebAssembly as it makes it more generic for different VM toolchains.

Here is a GitHub issue about the ongoing efforts for migrating to Saigo:

* {{url|github.com/Unvanquished/Unvanquished/issues/3197}}

==Interactive Debugging==

Most of the time it is easiest to debug with a native DLL. But if you have a problem that cannot be reproduced outside of NaCl, you may be forced to resort to the following tutorial.

These steps for attaching the NaCl debugger<ref>https://web.archive.org/web/20250909075554/https://www.chromium.org/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/getting-started-with-debug-stub/</ref> have been tested on Windows with a PNaCl toolchain. They should also work on binaries built with Saigo, using the old GDB from the PNaCl SDK or the GDB provided with the {{saigo}}. On Linux or Mac you may experience more difficulties due to the lack of support for old binaries (meaning nacl-gdb). illwieckz reports that on amd64 Linux in 2025, using the old GDB which is a 32-bit binary, debugging an amd64 nexe does not work (despite the documentation's claims of debugger platform independence), but debugging an i686 nexe does.

# Build the NaCl gamelogic with debugging symbols (build type Debug or RelWithDebInfo).
# Launch Daemon configured for NaCl debugging. For example, <code>./daemonded -set vm.sgame.type 1 -set vm.sgame.debug 1 +map chasm</code> When the relevant gamelogic starts, the engine should pause and emit the message <code>Waiting for GDB connection on localhost:4014</code>.
# Start NaCl GDB, e.g. <code>daemon\external_deps\windows-amd64-mingw_10\nacl-gdb.exe</code> This works better out of a command prompt rather than an MSYS window.
# Use the "file" command to tell the debugger where the binary with symbols is. For example, <code>file sgame-amd64.nexe</code>
# OPTIONAL, probably a waste of time: load the IRT (Integrated Runtime) symbols: <code>nacl-irt irt_core-amd64.nexe</code>
# Connect to the NaCl program with the command <code>target remote :4014</code>
# You should see a message like <code>0x000000000ffc00a0 in ?? ()</code> (or <code>0x000000000ffc00a0 in __pnacl_start ()</code> if you did step 5). This means the program is paused at the beginning.
# Set some breakpoints, e.g. <code>b G_RunFrame</code>. Alternatively, just wait for the debugger to break when the game crashes.
# Start the program by continuing (<code>c</code>).

==Postmortem Debugging==

See {{breakpad}}.

Native Client

2026-08-06T01:46:21Z

Illwieckz:

[[Category:Native Client]]{{DISPLAYTITLE:Native Client — Secure Native Code Sandbox Technology}}
Native Client (also known as NaCl) is a sandboxing technology by Google. It was used by Chrome extensions and Chrome apps. The {{engine}} uses Native Client to securely and portably run downloadable compiled games. It replaced the Q3VM (Quake 3 Virtual Machine) in the engine.

The Native Client documentation can be found on [https://chrome.jscn.org/docs/native-client/welcome-to-native-client/ chrome.jscn.org/docs/native-client/welcome-to-native-client/].

The NaCl support consists of:

* {{naclruntime}} — a modern Native Client runtime to run NaCl executables;
* {{saigo}} — a modern toolchain for Native Client with compilers and a debugger to build NaCl executables;
* {{breakpad}} — an enhanced crash reporting library with support for NaCl executables built with Saigo.

==Status==

'''Native Client''' or '''NaCl''' is the current technology used for securely virtualising the game code in the {{engine}}.

Server-side game logic NaCl support was first shipped in Alpha 27, released in April 2014. See the [https://unvanquished.net/moving-the-server-side-gamelogic-to-pnacl/ blog article by Kangz] and [https://unvanquished.net/alpha-27-flying-in-your-direction/ the release note by DSalt].

Client-side game logic NaCl support was first shipped in Alpha 37, released on March 2, 2015. See the [https://unvanquished.net/alpha-37-anniversary-edition/ release note by Kangz].

This completed the transition by porting the client VM to NaCl and this replaced entirely the legacy Quake III Q3VM system.

NaCl upstream development has slowed down since the competing solution [[WebAssembly]] became the industry standard, so it is very unlikely support for new systems and architecture would be added. To overcome this problem, we would have to switch to WebAssembly (that unfortunately may only support using a slow interpreter for some platforms NaCl supports, like i686 or armhf), but more importantly may still lack support for exceptions or {{code|setjmp/longjmp}} and then not be complete enough for our needs yet.

{{NativeClientIsDying}}

==Comparison==

{|
|+ Game VM comparison
|-
! !! Quake 3 / Tremulous !! Dæmon / Unvanquished
|-
| Technology || Q3VM || NaCl
|-
| Language || Old C (<ins>NOT</ins> Quake C) || Modern C / C++
|-
| Compiler || LCC (proprietary) || Clang (open-source)
|-
| System portability || Yes || Yes
|-
| Architecture portability || Yes || No
|-
| Secure sandbox || No || Yes
|}

With the Quake 3 engine and the Q3VM, the game code was programmed in C (it should not be confused with the scripting language of Quake 1 named QuakeC). This C code was real C was meant to be compiled with the proprietary LCC compiler, which only supported an old C, and the developer couldn't really rely on off-the-shelf libraries. That C code was compiled by LCC into {{code|.qvm}} binaries.

With the {{engine}}, the game code can be programmed in C or C++. That C/C++ code is compiled with Clang-based open source compilers supporting modern-enough C++ versions that makes possible to reuse off-the-shelf C++ libraries that may even be shared between the engine and the game source code. The C/C+ code is compiled into {{code|.nexe}} binarie.

Unlike QVMs, NaCl gamelogic runs in a secure sandbox. Native Client lets you run mods downloaded from the internet without giving them free reign on your computer. QVM was equivalent to running a DLL with no protection.

==Platform support==

{{NativeClientPlatformSupport}}

==NaCl Runtime==

See the {{naclruntime}} page for details.

==Rebuild effort==

{{NativeClientGoogleDeprecation}}

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}} being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

The project for rebuilding the {{naclruntime}} can be found there:

* {{url|github.com/DaemonEngine/native_client}}

The official releases for Unvanquished are already using the {{naclruntime}} on Linux for the {{code|amd64}} architecture, other systems are still using the Google NaCl Runtime.

The project for rebuilding the {{saigo}} can be found there:

* {{url|github.com/DaemonEngine/saigo-release-scripts}}

It's already possible to build Unvanquished with a Saigo compiler rebuilt this way.

==Compilers==

===Google PNaCl SDK===

PNaCl Clang is the current NaCl compiler we use to build the nexe game binaries. It is based on an old Clang 3.6 and does not support C++ above C++14. To overcome some of the related limitations we may switch to Saigo.

The PNaCl compilation workflow is to build a single {{code|.pexe}} then to translate them to per-architecture {{code|.nexe}} (amd64, i686, armhf) using a specific translator tool.

The PNaCl SDK consists on Python-based wrappers around Clang internals. It was initially using now-obsolete and hard-to-find Python2 but we ported it to Python3 to extend its lifespan.

The provided PNaCl SDK runs on Linux, Windows and macOS systems, on amd64 architectures.

While the {{code|.pexe}} compiler itself runs on FreeBSD with the Linuxulator, the translator does not, meaning it's not possible to build {{code|.nexe}} binaries on FreeBSD using Google PNaCl.

PNaCl supports C++ exception. There exist newer PNaCl SDKs (from chromium canary releases) that do not support exceptions and may not provide more what we already have with latest stable PNaCl.

===Dæmon Saigo SDK===

Saigo is a new NaCl compiler based on latest Clang and supporting latest C++ standards. It compiles directly to {{code|.nexe}}.

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}}) being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

The Unvanquished game code is already buildable with Saigo. Saigo is meant to replace PNaCl for Unvanquished release builds.

See {{saigo}} for details.

Saigo may not support C++ exceptions as far as we know but supports {{code|setjmp/longjmp}}.

Unlike PNaCl, Saigo wasn't released by Google, meaning a switch from PNaCl to Saigo required a convenient way to provide it to contributors. Google provided some nightly Linux amd64 Saigo toolchain snapshots that aren't easy to get without some Google scripts. The Saigo compiler itself isn't hard to build (same as Clang itself), the binutils are a bit more tricky but not that hard (10 years-old configure build). What is tricky to rebuild is the libc that requires some very old NaCl GCC. Fortunately there exists libc and libc++ snapshots provided by Google that can be reused with a self-built toolchain.

The Saigo compiler and NaCl binutils can be rebuilt to run natively on many platforms (Like Clang and GNU binutils), but they will always target the usual platforms as the NaCl loader is still the same: a more recent NaCl runtime is also buildable but doesn't bring any new platform support.

Moving to Saigo is considered as a migration step that can be achievable before migrating to [[WebAssembly]], as it allows us to migrate to a new C++ standard and update libraries we use without waiting for the migration to WebAssembly.

Some redesign of our CMake configuration for Saigo may help later when migrating to WebAssembly as it makes it more generic for different VM toolchains.

Here is a GitHub issue about the ongoing efforts for migrating to Saigo:

* {{url|github.com/Unvanquished/Unvanquished/issues/3197}}

==Interactive Debugging==

Most of the time it is easiest to debug with a native DLL. But if you have a problem that cannot be reproduced outside of NaCl, you may be forced to resort to the following tutorial.

These steps for attaching the NaCl debugger<ref>https://web.archive.org/web/20250909075554/https://www.chromium.org/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/getting-started-with-debug-stub/</ref> have been tested on Windows with a PNaCl toolchain. They should also work on binaries built with Saigo, using the old GDB from the PNaCl SDK or the GDB provided with the {{saigo}}. On Linux or Mac you may experience more difficulties due to the lack of support for old binaries (meaning nacl-gdb). illwieckz reports that on amd64 Linux in 2025, using the old GDB which is a 32-bit binary, debugging an amd64 nexe does not work (despite the documentation's claims of debugger platform independence), but debugging an i686 nexe does.

# Build the NaCl gamelogic with debugging symbols (build type Debug or RelWithDebInfo).
# Launch Daemon configured for NaCl debugging. For example, <code>./daemonded -set vm.sgame.type 1 -set vm.sgame.debug 1 +map chasm</code> When the relevant gamelogic starts, the engine should pause and emit the message <code>Waiting for GDB connection on localhost:4014</code>.
# Start NaCl GDB, e.g. <code>daemon\external_deps\windows-amd64-mingw_10\nacl-gdb.exe</code> This works better out of a command prompt rather than an MSYS window.
# Use the "file" command to tell the debugger where the binary with symbols is. For example, <code>file sgame-amd64.nexe</code>
# OPTIONAL, probably a waste of time: load the IRT (Integrated Runtime) symbols: <code>nacl-irt irt_core-amd64.nexe</code>
# Connect to the NaCl program with the command <code>target remote :4014</code>
# You should see a message like <code>0x000000000ffc00a0 in ?? ()</code> (or <code>0x000000000ffc00a0 in __pnacl_start ()</code> if you did step 5). This means the program is paused at the beginning.
# Set some breakpoints, e.g. <code>b G_RunFrame</code>. Alternatively, just wait for the debugger to break when the game crashes.
# Start the program by continuing (<code>c</code>).

==Postmortem Debugging==

See {{breakpad}}.

Native Client

2026-08-06T01:45:25Z

Illwieckz:

[[Category:Native Client]]{{DISPLAYTITLE:Native Client — Secure Native Code Sandbox Technology}}
Native Client (also known as NaCl) is a sandboxing technology by Google. It was used by Chrome extensions and Chrome apps. The {{engine}} uses Native Client to securely and portably run downloadable compiled games. It replaced the Q3VM (Quake 3 Virtual Machine) in the engine.

The Native Client documentation can be found on [https://chrome.jscn.org/docs/native-client/welcome-to-native-client/ chrome.jscn.org/docs/native-client/welcome-to-native-client/].

The NaCl support consists of:

* {{naclruntime}} — a modern Native Client runtime to run NaCl executables;
* {{saigo}} — a modern toolchain for Native Client with compilers and a debugger to build NaCl executables;
* {{breakpad}} — an enhanced breakpad crash reporting library with support for NaCl executables built with Saigo.

==Status==

'''Native Client''' or '''NaCl''' is the current technology used for securely virtualising the game code in the {{engine}}.

Server-side game logic NaCl support was first shipped in Alpha 27, released in April 2014. See the [https://unvanquished.net/moving-the-server-side-gamelogic-to-pnacl/ blog article by Kangz] and [https://unvanquished.net/alpha-27-flying-in-your-direction/ the release note by DSalt].

Client-side game logic NaCl support was first shipped in Alpha 37, released on March 2, 2015. See the [https://unvanquished.net/alpha-37-anniversary-edition/ release note by Kangz].

This completed the transition by porting the client VM to NaCl and this replaced entirely the legacy Quake III Q3VM system.

NaCl upstream development has slowed down since the competing solution [[WebAssembly]] became the industry standard, so it is very unlikely support for new systems and architecture would be added. To overcome this problem, we would have to switch to WebAssembly (that unfortunately may only support using a slow interpreter for some platforms NaCl supports, like i686 or armhf), but more importantly may still lack support for exceptions or {{code|setjmp/longjmp}} and then not be complete enough for our needs yet.

{{NativeClientIsDying}}

==Comparison==

{|
|+ Game VM comparison
|-
! !! Quake 3 / Tremulous !! Dæmon / Unvanquished
|-
| Technology || Q3VM || NaCl
|-
| Language || Old C (<ins>NOT</ins> Quake C) || Modern C / C++
|-
| Compiler || LCC (proprietary) || Clang (open-source)
|-
| System portability || Yes || Yes
|-
| Architecture portability || Yes || No
|-
| Secure sandbox || No || Yes
|}

With the Quake 3 engine and the Q3VM, the game code was programmed in C (it should not be confused with the scripting language of Quake 1 named QuakeC). This C code was real C was meant to be compiled with the proprietary LCC compiler, which only supported an old C, and the developer couldn't really rely on off-the-shelf libraries. That C code was compiled by LCC into {{code|.qvm}} binaries.

With the {{engine}}, the game code can be programmed in C or C++. That C/C++ code is compiled with Clang-based open source compilers supporting modern-enough C++ versions that makes possible to reuse off-the-shelf C++ libraries that may even be shared between the engine and the game source code. The C/C+ code is compiled into {{code|.nexe}} binarie.

Unlike QVMs, NaCl gamelogic runs in a secure sandbox. Native Client lets you run mods downloaded from the internet without giving them free reign on your computer. QVM was equivalent to running a DLL with no protection.

==Platform support==

{{NativeClientPlatformSupport}}

==NaCl Runtime==

See the {{naclruntime}} page for details.

==Rebuild effort==

{{NativeClientGoogleDeprecation}}

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}} being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

The project for rebuilding the {{naclruntime}} can be found there:

* {{url|github.com/DaemonEngine/native_client}}

The official releases for Unvanquished are already using the {{naclruntime}} on Linux for the {{code|amd64}} architecture, other systems are still using the Google NaCl Runtime.

The project for rebuilding the {{saigo}} can be found there:

* {{url|github.com/DaemonEngine/saigo-release-scripts}}

It's already possible to build Unvanquished with a Saigo compiler rebuilt this way.

==Compilers==

===Google PNaCl SDK===

PNaCl Clang is the current NaCl compiler we use to build the nexe game binaries. It is based on an old Clang 3.6 and does not support C++ above C++14. To overcome some of the related limitations we may switch to Saigo.

The PNaCl compilation workflow is to build a single {{code|.pexe}} then to translate them to per-architecture {{code|.nexe}} (amd64, i686, armhf) using a specific translator tool.

The PNaCl SDK consists on Python-based wrappers around Clang internals. It was initially using now-obsolete and hard-to-find Python2 but we ported it to Python3 to extend its lifespan.

The provided PNaCl SDK runs on Linux, Windows and macOS systems, on amd64 architectures.

While the {{code|.pexe}} compiler itself runs on FreeBSD with the Linuxulator, the translator does not, meaning it's not possible to build {{code|.nexe}} binaries on FreeBSD using Google PNaCl.

PNaCl supports C++ exception. There exist newer PNaCl SDKs (from chromium canary releases) that do not support exceptions and may not provide more what we already have with latest stable PNaCl.

===Dæmon Saigo SDK===

Saigo is a new NaCl compiler based on latest Clang and supporting latest C++ standards. It compiles directly to {{code|.nexe}}.

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}}) being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

The Unvanquished game code is already buildable with Saigo. Saigo is meant to replace PNaCl for Unvanquished release builds.

See {{saigo}} for details.

Saigo may not support C++ exceptions as far as we know but supports {{code|setjmp/longjmp}}.

Unlike PNaCl, Saigo wasn't released by Google, meaning a switch from PNaCl to Saigo required a convenient way to provide it to contributors. Google provided some nightly Linux amd64 Saigo toolchain snapshots that aren't easy to get without some Google scripts. The Saigo compiler itself isn't hard to build (same as Clang itself), the binutils are a bit more tricky but not that hard (10 years-old configure build). What is tricky to rebuild is the libc that requires some very old NaCl GCC. Fortunately there exists libc and libc++ snapshots provided by Google that can be reused with a self-built toolchain.

The Saigo compiler and NaCl binutils can be rebuilt to run natively on many platforms (Like Clang and GNU binutils), but they will always target the usual platforms as the NaCl loader is still the same: a more recent NaCl runtime is also buildable but doesn't bring any new platform support.

Moving to Saigo is considered as a migration step that can be achievable before migrating to [[WebAssembly]], as it allows us to migrate to a new C++ standard and update libraries we use without waiting for the migration to WebAssembly.

Some redesign of our CMake configuration for Saigo may help later when migrating to WebAssembly as it makes it more generic for different VM toolchains.

Here is a GitHub issue about the ongoing efforts for migrating to Saigo:

* {{url|github.com/Unvanquished/Unvanquished/issues/3197}}

==Interactive Debugging==

Most of the time it is easiest to debug with a native DLL. But if you have a problem that cannot be reproduced outside of NaCl, you may be forced to resort to the following tutorial.

These steps for attaching the NaCl debugger<ref>https://web.archive.org/web/20250909075554/https://www.chromium.org/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/getting-started-with-debug-stub/</ref> have been tested on Windows with a PNaCl toolchain. They should also work on binaries built with Saigo, using the old GDB from the PNaCl SDK or the GDB provided with the {{saigo}}. On Linux or Mac you may experience more difficulties due to the lack of support for old binaries (meaning nacl-gdb). illwieckz reports that on amd64 Linux in 2025, using the old GDB which is a 32-bit binary, debugging an amd64 nexe does not work (despite the documentation's claims of debugger platform independence), but debugging an i686 nexe does.

# Build the NaCl gamelogic with debugging symbols (build type Debug or RelWithDebInfo).
# Launch Daemon configured for NaCl debugging. For example, <code>./daemonded -set vm.sgame.type 1 -set vm.sgame.debug 1 +map chasm</code> When the relevant gamelogic starts, the engine should pause and emit the message <code>Waiting for GDB connection on localhost:4014</code>.
# Start NaCl GDB, e.g. <code>daemon\external_deps\windows-amd64-mingw_10\nacl-gdb.exe</code> This works better out of a command prompt rather than an MSYS window.
# Use the "file" command to tell the debugger where the binary with symbols is. For example, <code>file sgame-amd64.nexe</code>
# OPTIONAL, probably a waste of time: load the IRT (Integrated Runtime) symbols: <code>nacl-irt irt_core-amd64.nexe</code>
# Connect to the NaCl program with the command <code>target remote :4014</code>
# You should see a message like <code>0x000000000ffc00a0 in ?? ()</code> (or <code>0x000000000ffc00a0 in __pnacl_start ()</code> if you did step 5). This means the program is paused at the beginning.
# Set some breakpoints, e.g. <code>b G_RunFrame</code>. Alternatively, just wait for the debugger to break when the game crashes.
# Start the program by continuing (<code>c</code>).

==Postmortem Debugging==

See {{breakpad}}.

Native Client

2026-08-06T01:42:03Z

Illwieckz: /* Dæmon Saigo SDK */

[[Category:Native Client]]{{DISPLAYTITLE:Native Client — Secure Native Code Sandbox Technology}}
Native Client (also known as NaCl) is a sandboxing technology by Google. It was used by Chrome extensions and Chrome apps. The {{engine}} uses Native Client to securely and portably run downloadable compiled games. It replaced the Q3VM (Quake 3 Virtual Machine) in the engine.

The Native Client documentation can be found on [https://chrome.jscn.org/docs/native-client/welcome-to-native-client/ chrome.jscn.org/docs/native-client/welcome-to-native-client/].

The NaCl support consists of:

* {{naclruntime}} — a modern Native Client runtime;
* {{saigo}} — a modern toolchain for Native Client with compilers and a debugger;
* {{breakpad}} — an enhanced breakpad crash reporting library.

==Status==

'''Native Client''' or '''NaCl''' is the current technology used for securely virtualising the game code in the {{engine}}.

Server-side game logic NaCl support was first shipped in Alpha 27, released in April 2014. See the [https://unvanquished.net/moving-the-server-side-gamelogic-to-pnacl/ blog article by Kangz] and [https://unvanquished.net/alpha-27-flying-in-your-direction/ the release note by DSalt].

Client-side game logic NaCl support was first shipped in Alpha 37, released on March 2, 2015. See the [https://unvanquished.net/alpha-37-anniversary-edition/ release note by Kangz].

This completed the transition by porting the client VM to NaCl and this replaced entirely the legacy Quake III Q3VM system.

NaCl upstream development has slowed down since the competing solution [[WebAssembly]] became the industry standard, so it is very unlikely support for new systems and architecture would be added. To overcome this problem, we would have to switch to WebAssembly (that unfortunately may only support using a slow interpreter for some platforms NaCl supports, like i686 or armhf), but more importantly may still lack support for exceptions or {{code|setjmp/longjmp}} and then not be complete enough for our needs yet.

{{NativeClientIsDying}}

==Comparison==

{|
|+ Game VM comparison
|-
! !! Quake 3 / Tremulous !! Dæmon / Unvanquished
|-
| Technology || Q3VM || NaCl
|-
| Language || Old C (<ins>NOT</ins> Quake C) || Modern C / C++
|-
| Compiler || LCC (proprietary) || Clang (open-source)
|-
| System portability || Yes || Yes
|-
| Architecture portability || Yes || No
|-
| Secure sandbox || No || Yes
|}

With the Quake 3 engine and the Q3VM, the game code was programmed in C (it should not be confused with the scripting language of Quake 1 named QuakeC). This C code was real C was meant to be compiled with the proprietary LCC compiler, which only supported an old C, and the developer couldn't really rely on off-the-shelf libraries. That C code was compiled by LCC into {{code|.qvm}} binaries.

With the {{engine}}, the game code can be programmed in C or C++. That C/C++ code is compiled with Clang-based open source compilers supporting modern-enough C++ versions that makes possible to reuse off-the-shelf C++ libraries that may even be shared between the engine and the game source code. The C/C+ code is compiled into {{code|.nexe}} binarie.

Unlike QVMs, NaCl gamelogic runs in a secure sandbox. Native Client lets you run mods downloaded from the internet without giving them free reign on your computer. QVM was equivalent to running a DLL with no protection.

==Platform support==

{{NativeClientPlatformSupport}}

==NaCl Runtime==

See the {{naclruntime}} page for details.

==Rebuild effort==

{{NativeClientGoogleDeprecation}}

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}} being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

The project for rebuilding the {{naclruntime}} can be found there:

* {{url|github.com/DaemonEngine/native_client}}

The official releases for Unvanquished are already using the {{naclruntime}} on Linux for the {{code|amd64}} architecture, other systems are still using the Google NaCl Runtime.

The project for rebuilding the {{saigo}} can be found there:

* {{url|github.com/DaemonEngine/saigo-release-scripts}}

It's already possible to build Unvanquished with a Saigo compiler rebuilt this way.

==Compilers==

===Google PNaCl SDK===

PNaCl Clang is the current NaCl compiler we use to build the nexe game binaries. It is based on an old Clang 3.6 and does not support C++ above C++14. To overcome some of the related limitations we may switch to Saigo.

The PNaCl compilation workflow is to build a single {{code|.pexe}} then to translate them to per-architecture {{code|.nexe}} (amd64, i686, armhf) using a specific translator tool.

The PNaCl SDK consists on Python-based wrappers around Clang internals. It was initially using now-obsolete and hard-to-find Python2 but we ported it to Python3 to extend its lifespan.

The provided PNaCl SDK runs on Linux, Windows and macOS systems, on amd64 architectures.

While the {{code|.pexe}} compiler itself runs on FreeBSD with the Linuxulator, the translator does not, meaning it's not possible to build {{code|.nexe}} binaries on FreeBSD using Google PNaCl.

PNaCl supports C++ exception. There exist newer PNaCl SDKs (from chromium canary releases) that do not support exceptions and may not provide more what we already have with latest stable PNaCl.

===Dæmon Saigo SDK===

Saigo is a new NaCl compiler based on latest Clang and supporting latest C++ standards. It compiles directly to {{code|.nexe}}.

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}}) being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

The Unvanquished game code is already buildable with Saigo. Saigo is meant to replace PNaCl for Unvanquished release builds.

See {{saigo}} for details.

Saigo may not support C++ exceptions as far as we know but supports {{code|setjmp/longjmp}}.

Unlike PNaCl, Saigo wasn't released by Google, meaning a switch from PNaCl to Saigo required a convenient way to provide it to contributors. Google provided some nightly Linux amd64 Saigo toolchain snapshots that aren't easy to get without some Google scripts. The Saigo compiler itself isn't hard to build (same as Clang itself), the binutils are a bit more tricky but not that hard (10 years-old configure build). What is tricky to rebuild is the libc that requires some very old NaCl GCC. Fortunately there exists libc and libc++ snapshots provided by Google that can be reused with a self-built toolchain.

The Saigo compiler and NaCl binutils can be rebuilt to run natively on many platforms (Like Clang and GNU binutils), but they will always target the usual platforms as the NaCl loader is still the same: a more recent NaCl runtime is also buildable but doesn't bring any new platform support.

Moving to Saigo is considered as a migration step that can be achievable before migrating to [[WebAssembly]], as it allows us to migrate to a new C++ standard and update libraries we use without waiting for the migration to WebAssembly.

Some redesign of our CMake configuration for Saigo may help later when migrating to WebAssembly as it makes it more generic for different VM toolchains.

Here is a GitHub issue about the ongoing efforts for migrating to Saigo:

* {{url|github.com/Unvanquished/Unvanquished/issues/3197}}

==Interactive Debugging==

Most of the time it is easiest to debug with a native DLL. But if you have a problem that cannot be reproduced outside of NaCl, you may be forced to resort to the following tutorial.

These steps for attaching the NaCl debugger<ref>https://web.archive.org/web/20250909075554/https://www.chromium.org/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/getting-started-with-debug-stub/</ref> have been tested on Windows with a PNaCl toolchain. They should also work on binaries built with Saigo, using the old GDB from the PNaCl SDK or the GDB provided with the {{saigo}}. On Linux or Mac you may experience more difficulties due to the lack of support for old binaries (meaning nacl-gdb). illwieckz reports that on amd64 Linux in 2025, using the old GDB which is a 32-bit binary, debugging an amd64 nexe does not work (despite the documentation's claims of debugger platform independence), but debugging an i686 nexe does.

# Build the NaCl gamelogic with debugging symbols (build type Debug or RelWithDebInfo).
# Launch Daemon configured for NaCl debugging. For example, <code>./daemonded -set vm.sgame.type 1 -set vm.sgame.debug 1 +map chasm</code> When the relevant gamelogic starts, the engine should pause and emit the message <code>Waiting for GDB connection on localhost:4014</code>.
# Start NaCl GDB, e.g. <code>daemon\external_deps\windows-amd64-mingw_10\nacl-gdb.exe</code> This works better out of a command prompt rather than an MSYS window.
# Use the "file" command to tell the debugger where the binary with symbols is. For example, <code>file sgame-amd64.nexe</code>
# OPTIONAL, probably a waste of time: load the IRT (Integrated Runtime) symbols: <code>nacl-irt irt_core-amd64.nexe</code>
# Connect to the NaCl program with the command <code>target remote :4014</code>
# You should see a message like <code>0x000000000ffc00a0 in ?? ()</code> (or <code>0x000000000ffc00a0 in __pnacl_start ()</code> if you did step 5). This means the program is paused at the beginning.
# Set some breakpoints, e.g. <code>b G_RunFrame</code>. Alternatively, just wait for the debugger to break when the game crashes.
# Start the program by continuing (<code>c</code>).

==Postmortem Debugging==

See {{breakpad}}.

Tools/Saigo

2026-08-06T01:40:27Z

Illwieckz:

[[Category:Tools]][[Category:Native Client]]{{DISPLAYTITLE:Dæmon Saigo SDK — Modern Toolchain for Native Client}}
Saigo is a modern toolchain for compiling {{nacl}} applications.

{{Trivia|
In Japanese, ''Saigo'' (さいご / 最後) means “''the last''”, “''the end''”, “''the final''” or “''the conclusion''”. This refers to the end of an era, the final stage of an event, or the last item in a sequence…}}

{{NativeClientGoogleDeprecation}}

==Status==

The Unvanquished team publish frequent releases of the {{saigo}} with ready-to-use prebuilt packages for a large number of platforms:

* {{url|github.com/DaemonEngine/saigo-nacl-sdk/releases}}

The Unvanquished game code is already buildable with Saigo. Saigo is meant to replace PNaCl for Unvanquished release builds.

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}}) being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

==Components==

The Saigo SDK consists of:

* C and C++ compilers based on LLVM clang;
* Utilities like a linker, based on GNU binutils;
* A debugger, based on GDB;
* A libc based on Newlib and a libc++ based on LLVM.
* Headers from the Native Client repositories.

The compiler supports latest C++ standards like C23 and C++23. Unlike PNaCl, Saigo compiles directly to {{code|.nexe}}.

Saigo may not support C++ exceptions as far as we know but supports {{code|setjmp/longjmp}}.

==Sources==

The project for rebuilding the Saigo Native Client SDK can be found there:

* {{url|github.com/DaemonEngine/saigo-release-scripts}}

This project include patches applied over compile, binutils and debugger repositories before building. This project builds clang, binutils and gdb from Google repositories, and fetches headers from the Dæmon Native Client Runtime repository:

* {{url|chromium.googlesource.com/native_client/nacl-llvm-project-v10}} (Saigo NaCl clang)
* {{url|chromium.googlesource.com/native_client/nacl-binutils}} (NaCl binutils)
* {{url|chromium.googlesource.com/native_client/nacl-gdb}} (NaCl Saigo GDB)
* {{url|github.com/DaemonEngine/native_client}} (NaCl headers)

==Platform support==

{{NativeClientPlatformSupport}}

==Breakpad support==

Code compiled with Saigo uses {{code|-2}} instead of {{code|-1}} as value for the CFA pseudo-register.

We patched {{Tools|Breakpad}} to also support Saigo binaries, see this [https://github.com/DaemonEngine/breakpad/pull/19 patch].

==Migration to Saigo==

Here is a GitHub issue about the ongoing efforts for migrating to Saigo:

* {{url|github.com/Unvanquished/Unvanquished/issues/3197}}

Native Client

2026-08-05T08:40:46Z

Illwieckz: /* Google PNaCl SDK */

[[Category:Native Client]]{{DISPLAYTITLE:Native Client — Secure Native Code Sandbox Technology}}
Native Client (also known as NaCl) is a sandboxing technology by Google. It was used by Chrome extensions and Chrome apps. The {{engine}} uses Native Client to securely and portably run downloadable compiled games. It replaced the Q3VM (Quake 3 Virtual Machine) in the engine.

The Native Client documentation can be found on [https://chrome.jscn.org/docs/native-client/welcome-to-native-client/ chrome.jscn.org/docs/native-client/welcome-to-native-client/].

The NaCl support consists of:

* {{naclruntime}} — a modern Native Client runtime;
* {{saigo}} — a modern toolchain for Native Client with compilers and a debugger;
* {{breakpad}} — an enhanced breakpad crash reporting library.

==Status==

'''Native Client''' or '''NaCl''' is the current technology used for securely virtualising the game code in the {{engine}}.

Server-side game logic NaCl support was first shipped in Alpha 27, released in April 2014. See the [https://unvanquished.net/moving-the-server-side-gamelogic-to-pnacl/ blog article by Kangz] and [https://unvanquished.net/alpha-27-flying-in-your-direction/ the release note by DSalt].

Client-side game logic NaCl support was first shipped in Alpha 37, released on March 2, 2015. See the [https://unvanquished.net/alpha-37-anniversary-edition/ release note by Kangz].

This completed the transition by porting the client VM to NaCl and this replaced entirely the legacy Quake III Q3VM system.

NaCl upstream development has slowed down since the competing solution [[WebAssembly]] became the industry standard, so it is very unlikely support for new systems and architecture would be added. To overcome this problem, we would have to switch to WebAssembly (that unfortunately may only support using a slow interpreter for some platforms NaCl supports, like i686 or armhf), but more importantly may still lack support for exceptions or {{code|setjmp/longjmp}} and then not be complete enough for our needs yet.

{{NativeClientIsDying}}

==Comparison==

{|
|+ Game VM comparison
|-
! !! Quake 3 / Tremulous !! Dæmon / Unvanquished
|-
| Technology || Q3VM || NaCl
|-
| Language || Old C (<ins>NOT</ins> Quake C) || Modern C / C++
|-
| Compiler || LCC (proprietary) || Clang (open-source)
|-
| System portability || Yes || Yes
|-
| Architecture portability || Yes || No
|-
| Secure sandbox || No || Yes
|}

With the Quake 3 engine and the Q3VM, the game code was programmed in C (it should not be confused with the scripting language of Quake 1 named QuakeC). This C code was real C was meant to be compiled with the proprietary LCC compiler, which only supported an old C, and the developer couldn't really rely on off-the-shelf libraries. That C code was compiled by LCC into {{code|.qvm}} binaries.

With the {{engine}}, the game code can be programmed in C or C++. That C/C++ code is compiled with Clang-based open source compilers supporting modern-enough C++ versions that makes possible to reuse off-the-shelf C++ libraries that may even be shared between the engine and the game source code. The C/C+ code is compiled into {{code|.nexe}} binarie.

Unlike QVMs, NaCl gamelogic runs in a secure sandbox. Native Client lets you run mods downloaded from the internet without giving them free reign on your computer. QVM was equivalent to running a DLL with no protection.

==Platform support==

{{NativeClientPlatformSupport}}

==NaCl Runtime==

See the {{naclruntime}} page for details.

==Rebuild effort==

{{NativeClientGoogleDeprecation}}

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}} being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

The project for rebuilding the {{naclruntime}} can be found there:

* {{url|github.com/DaemonEngine/native_client}}

The official releases for Unvanquished are already using the {{naclruntime}} on Linux for the {{code|amd64}} architecture, other systems are still using the Google NaCl Runtime.

The project for rebuilding the {{saigo}} can be found there:

* {{url|github.com/DaemonEngine/saigo-release-scripts}}

It's already possible to build Unvanquished with a Saigo compiler rebuilt this way.

==Compilers==

===Google PNaCl SDK===

PNaCl Clang is the current NaCl compiler we use to build the nexe game binaries. It is based on an old Clang 3.6 and does not support C++ above C++14. To overcome some of the related limitations we may switch to Saigo.

The PNaCl compilation workflow is to build a single {{code|.pexe}} then to translate them to per-architecture {{code|.nexe}} (amd64, i686, armhf) using a specific translator tool.

The PNaCl SDK consists on Python-based wrappers around Clang internals. It was initially using now-obsolete and hard-to-find Python2 but we ported it to Python3 to extend its lifespan.

The provided PNaCl SDK runs on Linux, Windows and macOS systems, on amd64 architectures.

While the {{code|.pexe}} compiler itself runs on FreeBSD with the Linuxulator, the translator does not, meaning it's not possible to build {{code|.nexe}} binaries on FreeBSD using Google PNaCl.

PNaCl supports C++ exception. There exist newer PNaCl SDKs (from chromium canary releases) that do not support exceptions and may not provide more what we already have with latest stable PNaCl.

===Dæmon Saigo SDK===

Saigo is a new NaCl compiler based on latest Clang and supporting latest C++ standards. It compiles directly to {{code|.nexe}}.

See {{saigo}} for details.

The Unvanquished game code is now buildable with Saigo.

Saigo may not support C++ exceptions as far as we know but supports {{code|setjmp/longjmp}}.

Unlike PNaCl, Saigo wasn't released by Google, meaning a switch from PNaCl to Saigo required a convenient way to provide it to contributors. Google provided some nightly Linux amd64 Saigo toolchain snapshots that aren't easy to get without some Google scripts. The Saigo compiler itself isn't hard to build (same as Clang itself), the binutils are a bit more tricky but not that hard (10 years-old configure build). What is tricky to rebuild is the libc that requires some very old NaCl GCC. Fortunately there exists libc and libc++ snapshots provided by Google that can be reused with a self-built toolchain.

The Saigo compiler and NaCl binutils can be rebuilt to run natively on many platforms (Like Clang and GNU binutils), but they will always target the usual platforms as the NaCl loader is still the same: a more recent NaCl runtime is also buildable but doesn't bring any new platform support.

Moving to Saigo is considered as a migration step that can be achievable before migrating to [[WebAssembly]], as it allows us to migrate to a new C++ standard and update libraries we use without waiting for the migration to WebAssembly.

Some redesign of our CMake configuration for Saigo may help later when migrating to WebAssembly as it makes it more generic for different VM toolchains.

Here is a GitHub issue about the ongoing efforts for migrating to Saigo:

* {{url|github.com/Unvanquished/Unvanquished/issues/3197}}

==Interactive Debugging==

Most of the time it is easiest to debug with a native DLL. But if you have a problem that cannot be reproduced outside of NaCl, you may be forced to resort to the following tutorial.

These steps for attaching the NaCl debugger<ref>https://web.archive.org/web/20250909075554/https://www.chromium.org/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/getting-started-with-debug-stub/</ref> have been tested on Windows with a PNaCl toolchain. They should also work on binaries built with Saigo, using the old GDB from the PNaCl SDK or the GDB provided with the {{saigo}}. On Linux or Mac you may experience more difficulties due to the lack of support for old binaries (meaning nacl-gdb). illwieckz reports that on amd64 Linux in 2025, using the old GDB which is a 32-bit binary, debugging an amd64 nexe does not work (despite the documentation's claims of debugger platform independence), but debugging an i686 nexe does.

# Build the NaCl gamelogic with debugging symbols (build type Debug or RelWithDebInfo).
# Launch Daemon configured for NaCl debugging. For example, <code>./daemonded -set vm.sgame.type 1 -set vm.sgame.debug 1 +map chasm</code> When the relevant gamelogic starts, the engine should pause and emit the message <code>Waiting for GDB connection on localhost:4014</code>.
# Start NaCl GDB, e.g. <code>daemon\external_deps\windows-amd64-mingw_10\nacl-gdb.exe</code> This works better out of a command prompt rather than an MSYS window.
# Use the "file" command to tell the debugger where the binary with symbols is. For example, <code>file sgame-amd64.nexe</code>
# OPTIONAL, probably a waste of time: load the IRT (Integrated Runtime) symbols: <code>nacl-irt irt_core-amd64.nexe</code>
# Connect to the NaCl program with the command <code>target remote :4014</code>
# You should see a message like <code>0x000000000ffc00a0 in ?? ()</code> (or <code>0x000000000ffc00a0 in __pnacl_start ()</code> if you did step 5). This means the program is paused at the beginning.
# Set some breakpoints, e.g. <code>b G_RunFrame</code>. Alternatively, just wait for the debugger to break when the game crashes.
# Start the program by continuing (<code>c</code>).

==Postmortem Debugging==

See {{breakpad}}.

Tools/Crunch

2026-08-05T05:58:15Z

Illwieckz:

[[Category:Tools]]{{DISPLAYTITLE:Dæmon Crunch — Advanced DXTn Texture Compressor}}
[https://github.com/DaemonEngine/crunch Dæmon Crunch] is a maintained CRN texture compression library and command-line tool producing GPU-friendly formats such as CRN, DDS and KTX.

Crunch is also the recommended TGA-to-PNG converter. When converting TGA images, prefer {{crunch}} over ImageMagick which is not reliable.

The [https://github.com/DaemonEngine/crunch Dæmon Crunch] is the most maintained and up-to-date Crunch available and the best choice for game developers.

==History==

The {{code|crunch}} tool was initially written by Binomial LLC then improved by Unity Technologies. The original Binomial Crunch is no longer maintained and lacks compatibility with newer Crunch formats. Although Unity contributed important improvements, the public Unity Crunch repository was never maintained as a proper long-term upstream project. Dæmon Crunch incorporated these improvements and has continued development with additional fixes, features, and maintenance.

Neither Binomial nor Unity have merged Unvanquished fixes and never demonstrated any serious interest in merging fixes provided by others, so the Unvanquished team not only maintained the Dæmon Crunch fork to host fixes, but also incorporated fixes from others developers. The Unvanquished team is actively maintaining Dæmon Crunch since 2014 (already more than a decade of maintenance and improvements!).

==Sources==

The Dæmon Crunch source repository is: [https://github.com/DaemonEngine/crunch github.com/DaemonEngine/crunch].

That repository provides the updated '''crunch''' tool, the '''crnlib''' library to provide full compression/decompression support to third-party applications, and the {{code|crn_decomp.h}} header-only library which is enough to transcode the Crunch CRN data for GPU upload and is perfect for lightweight integration in renderers. Some examples implementing various kinds of integrations are provided.

==Overview==

Some other details can be found in the [https://github.com/DaemonEngine/crunch/blob/master/README.md Crunch project README].

===Features===

The Dæmon Crunch provides many improvements over the original crunch:

* ✅️ Unity crunch format (runs many time faster and produces smaller files),
* ✅️ Unity crunch metadata (the header is compatible with Unity),
* ✅️ Improved image compatibility (1-bit PNG and horizontally-flipped TGA images are now supported),
* ✅️ Added features and command line options (top mip renormalization and more),
* ✅️ Network file system compatibility,
* ✅️ Optional header-only checksumming,
* ✅️ Multisystem and multiplatform,
* ✅️ Thoroughly tested and improved reproducibility,
* ✅️ CMake toolchain.

===Image formats===

* ✅️ CRN, DDS, KTX,
* ✅️ PNG, JPG, TGA, BMP.

Crunch can produce compressed images optimized for performance and game rendering in various formats like DDS, KTX and CRN.

All those three formats are containers for DXT-compressed bitmaps. This DXT-compressed data can be uploaded directly to the GPU memory without decompression, and the GPU can process DXT-compressed data without decompression.

Crunch writes DXT-compressed data in a way an additional compression performs better on them, especially LZMA. For example, produced DDS images are expected to compress well if repackaged in an LZMA-based archive.

The CRN format does all of this in one go: it stores the DXT-compressed data into a custom LZMA container.

The game engine or any other application processing CRN files just have to unpack the LZMA container using provided functions and to upload the DXT-compressed data to the GPU.

The Dæmon crunch sets the {{code|m_userdata0}} header field to {{code|1}} to make it compatible with Unity.

===Performance===

The Dæmon Crunch runs multiple times faster than the original Crunch by BinomialLLC, thanks to the work done by Unity that has been imported. Unity people claimed the tool runs 2.5 time faster, and we measured the tool running 4.3 time faster on the Unvanquished corpus. Unity people claimed the tool compresses about 10% better, we measured more than 11% on the Unvanquished corpus. This performance bump comes with a compatibility-breaking change introduced in the Unity branch.

The files produced by the Dæmon Crunch are then readable by both the Unity Crunch and the Dæmon Crunch but not by the original Binomial Crunch, while the files produced by the original Binomial Crunch are not readable by the Unity Crunch and the Dæmon Crunch. The Binomial Crunch isn't maintained anymore.

===Portability===

The Dæmon crunch has very high cross-platform compatibility and is buildable with CMake.

The [https://github.com/DaemonEngine/crunch Dæmon Crunch source repository] is known to build with various compilers, and the Dæmon {{code|crunch}} tool is known to run on Linux, Windows, macOS and FreeBSD systems on various hardware architectures.

===Quality===

A continuous integration pipeline is configured to test the building of the tool and the library themselves and to run some tests. The code is frequently submitted to CodeQL static analysis.

===Adoption===

The Dæmon crunch is known to be used by:

* The {{engine}},
* The {{Tools|Urcheon}} game data build tool,
* The {{Tools|NetRadiant}} level editor and the {{Tools|Q3map2}} map compiler and light mapper,
* The [https://github.com/XQF/xqf XQF] game server browser,
* The [https://unvanquished.net Unvanquished game],
* The [https://xonotic.org Xonotic game],
* The [https://overgrowth.wolfire.com Overgrowth game],
* Some games using the Unity game engine.

==How to use Crunch==

{{QuickCrunchTutorial}}

Some other usage instructions can be found in the [https://github.com/DaemonEngine/crunch/blob/master/README.md#creating-compressed-textures-with-crunch README].

The {{code|-noNormalDetection}} and {{code|-rtopmip}} options are succinctly described below.

==Dæmon Crunch Enhancements==

Here are things you will not find in either Binomial Crunch, Unity Crunch or none of them:

===Unity Crunch format===

This repository merged improvements done by Unity Technologies, it produces
smaller files and produces them faster than original code by Binomial.
Unity also modified the format which makes it incompatible with earlier versions of the tool.

Quote from [https://unvanquished.net/unvanquished-area-51 unvanquished.net]:

<blockquote>
[https://blog.unity.com/technology/crunch-compression-of-etc-textures Unity guys said]
that their modified crunch tool “can compress up to 2.5
times faster, while providing about 10% better compression ratio”. So we
did a test on our own asset repository, re-crunching all the ressources
and textures packages. At the time we did the test the given corpus
produced 1797 .crn files.
The Unity’s crunch tool reduced compression time by 4.31 and reduced size
by 11.15%. They said “up to 2.5 time faster” but we’ve seen some random
textures being compressed 6 time faster and the average of the whole is
4.3 time faster, and yes the tool compresses more than 10% more.
</blockquote>

===Unity Crunch metadata===

Unlike the Unity {{code|crunch}} tool built from their public repository, this tool produces files loadable by the Unity engine. Since [https://github.com/DaemonEngine/crunch/blob/master/faf5127b8c69dfd1ae554f4f3bf8168048b48d9f February 11th 2023], this branch sets the CRN {{code|m_userdata0}} field to {{code|1}} to make CRN files loadable by the Unity engine which now prevents to load files with this value set to {{code|0}}.

Files with this value set to {{code|1}} are expected to use the new format. Files with this value set to {{code|0}} may or may not use the new format. When Unity updated the tool and modified the format in an incompatible way, no bit was modified to detect if a CRN file was using the old or the new format. Unity has not updated that field in their public repository of Crunch so files using new format with this value set to {{code|0}} may be found in the wild.

===Improved image compatibility===

Supported source file formats: CRN,DDS,KTX,TGA,BMP,PNG,JPG/JPEG,PSD. 
Supported output file formats: CRN,DDS,KTX,TGA,BMP,PNG,JPG/JPEG.

* 1-bit PNG files are supported.
* Flipped TGA files are supported.
* Progressive JPEG files are supported.

The {{code|stb_image}} library has been updated from version 1.18 to version 2.30, increasing the amount of image format variants that can be converted, like 1-bit PNG formats. Further improvements like horizontally-flipped TGA images were brought to {{code|stb_image}} to make it support more TGA variants.

Note: Some other specific file format variants may be unsupported.

See the docs for jpgd.h: {{url|code.google.com/p/jpeg-compressor}} 
See the docs for stb_image.h: {{url|github.com/nothings/stb}}

===Converted image reproducibility===

We take special care that, when using compilation options for IEEE 754 float processing (disabling fast math, preferring SSE over x87…), the bitstream of converted image files are the same whatever the compiler, the operating system, or the CPU architecture crunch is built for and running on. It helps making packaged game assets reproducible. The CI not only checks that crunch builds, but that it runs properly and that the same input converts to the same output.

When reproducibility isn't needed, fast math can be enabled with CMake with the {{code|1=-DUSE_FAST_MATH=ON}} CMake option.

It is recommended for those looking for generating reproducible CRN files to keep disabled the use of fast math. It is also recommended to disable x87 floats on i686 and to rely on SSE instead with the {{code|1=-mfpmath=sse -msse}} compiler flags.

===Added features and command line options===

In addition to the original {{code|crunch}} features and command line options this branch brings new features and options, including:

* {{code|-rtopmip}}: option to use with {{code|-renormalize}} to also renormalize on the top mip-level.
* {{code|-noNormalDetection}}: do not attempt to detect normal map to avoid selecting formats thought for normal maps when it's known an image is not a normal map. It may prevent the tool to use heavier and less-supported {{code|DXT5_AGBR}} format when {{code|DXT1}} is good enough.
* {{code|-h}} or {{code|--help}}: print the command line built-in help, listing all known options.

===Network file system compatibility===

The original {{code|crunch}} tool relied on non-standard I/O features not working on all file systems including network file systems like NFS or SSHFS. A standard implementation was added so the limitations are not there anymore and {{code|crunch}} can now process image files stored over the network and on any other file system.

===Optional header-only checksumming===

For applications distributing their files in containers already providing a checksum mechanism for the whole contained file, it's now possible to only validate the CRN header checksum instead of the whole file checksum to not checksum the whole file twice.

===Multisystem and multiplatform portability===

Unlike upstream branches from Binomial LLC and Unity Software Inc. this branch focuses on keeping the code buildable outside of Windows and Visual Studio, and adds a CMake build option alongside the legacy Makefile.

This {{code|crunch}} tool and the related {{code|crnlib}} library are known to build with and and run on:

* Compilers: GCC, MinGW, MSVC, Clang, Apple Clang, and more.
* Systems: Linux, Windows, macOS, FreeBSD.
* Architectures: amd64, arm64, i686, armhf.

===Thoroughly tested and improved reproducibility===

A continuous integration system tests the build of crunch for a dozen of configurations of different architecture, system or compiler. The output of such builds are also tested with most of those builds. It helped to improve and validate image support, to identify build options known to improve the reproducibility of the output, and is meant to catch regressions if they happen.

The Dæmon crunch code is frequently scanned with the the CodeQL static analyser.

===CMake build system===

CMake has now replaced the old Makefile. The supplied CMake configuration provides many useful build options. Toolchain files for MinGW cross-compilation are also supplied.

The native MSVC solution files were removed, it is expected that MSVC users generate them with CMake instead.

Tools/Crunch

2026-08-05T05:57:49Z

Illwieckz:

[[Category:Tools]]{{DISPLAYTITLE:Dæmon Crunch — Advanced DXTn Texture Compressor}}
[https://github.com/DaemonEngine/crunch Dæmon Crunch] is a maintained CRN texture compression library and command-line tool producing GPU-friendly formats such as CRN, DDS and KTX.

Crunch is also the recommended TGA-to-PNG converter (when converting TGA images, prefer {{crunch}} over ImageMagick which is not reliable.

The [https://github.com/DaemonEngine/crunch Dæmon Crunch] is the most maintained and up-to-date Crunch available and the best choice for game developers.

==History==

The {{code|crunch}} tool was initially written by Binomial LLC then improved by Unity Technologies. The original Binomial Crunch is no longer maintained and lacks compatibility with newer Crunch formats. Although Unity contributed important improvements, the public Unity Crunch repository was never maintained as a proper long-term upstream project. Dæmon Crunch incorporated these improvements and has continued development with additional fixes, features, and maintenance.

Neither Binomial nor Unity have merged Unvanquished fixes and never demonstrated any serious interest in merging fixes provided by others, so the Unvanquished team not only maintained the Dæmon Crunch fork to host fixes, but also incorporated fixes from others developers. The Unvanquished team is actively maintaining Dæmon Crunch since 2014 (already more than a decade of maintenance and improvements!).

==Sources==

The Dæmon Crunch source repository is: [https://github.com/DaemonEngine/crunch github.com/DaemonEngine/crunch].

That repository provides the updated '''crunch''' tool, the '''crnlib''' library to provide full compression/decompression support to third-party applications, and the {{code|crn_decomp.h}} header-only library which is enough to transcode the Crunch CRN data for GPU upload and is perfect for lightweight integration in renderers. Some examples implementing various kinds of integrations are provided.

==Overview==

Some other details can be found in the [https://github.com/DaemonEngine/crunch/blob/master/README.md Crunch project README].

===Features===

The Dæmon Crunch provides many improvements over the original crunch:

* ✅️ Unity crunch format (runs many time faster and produces smaller files),
* ✅️ Unity crunch metadata (the header is compatible with Unity),
* ✅️ Improved image compatibility (1-bit PNG and horizontally-flipped TGA images are now supported),
* ✅️ Added features and command line options (top mip renormalization and more),
* ✅️ Network file system compatibility,
* ✅️ Optional header-only checksumming,
* ✅️ Multisystem and multiplatform,
* ✅️ Thoroughly tested and improved reproducibility,
* ✅️ CMake toolchain.

===Image formats===

* ✅️ CRN, DDS, KTX,
* ✅️ PNG, JPG, TGA, BMP.

Crunch can produce compressed images optimized for performance and game rendering in various formats like DDS, KTX and CRN.

All those three formats are containers for DXT-compressed bitmaps. This DXT-compressed data can be uploaded directly to the GPU memory without decompression, and the GPU can process DXT-compressed data without decompression.

Crunch writes DXT-compressed data in a way an additional compression performs better on them, especially LZMA. For example, produced DDS images are expected to compress well if repackaged in an LZMA-based archive.

The CRN format does all of this in one go: it stores the DXT-compressed data into a custom LZMA container.

The game engine or any other application processing CRN files just have to unpack the LZMA container using provided functions and to upload the DXT-compressed data to the GPU.

The Dæmon crunch sets the {{code|m_userdata0}} header field to {{code|1}} to make it compatible with Unity.

===Performance===

The Dæmon Crunch runs multiple times faster than the original Crunch by BinomialLLC, thanks to the work done by Unity that has been imported. Unity people claimed the tool runs 2.5 time faster, and we measured the tool running 4.3 time faster on the Unvanquished corpus. Unity people claimed the tool compresses about 10% better, we measured more than 11% on the Unvanquished corpus. This performance bump comes with a compatibility-breaking change introduced in the Unity branch.

The files produced by the Dæmon Crunch are then readable by both the Unity Crunch and the Dæmon Crunch but not by the original Binomial Crunch, while the files produced by the original Binomial Crunch are not readable by the Unity Crunch and the Dæmon Crunch. The Binomial Crunch isn't maintained anymore.

===Portability===

The Dæmon crunch has very high cross-platform compatibility and is buildable with CMake.

The [https://github.com/DaemonEngine/crunch Dæmon Crunch source repository] is known to build with various compilers, and the Dæmon {{code|crunch}} tool is known to run on Linux, Windows, macOS and FreeBSD systems on various hardware architectures.

===Quality===

A continuous integration pipeline is configured to test the building of the tool and the library themselves and to run some tests. The code is frequently submitted to CodeQL static analysis.

===Adoption===

The Dæmon crunch is known to be used by:

* The {{engine}},
* The {{Tools|Urcheon}} game data build tool,
* The {{Tools|NetRadiant}} level editor and the {{Tools|Q3map2}} map compiler and light mapper,
* The [https://github.com/XQF/xqf XQF] game server browser,
* The [https://unvanquished.net Unvanquished game],
* The [https://xonotic.org Xonotic game],
* The [https://overgrowth.wolfire.com Overgrowth game],
* Some games using the Unity game engine.

==How to use Crunch==

{{QuickCrunchTutorial}}

Some other usage instructions can be found in the [https://github.com/DaemonEngine/crunch/blob/master/README.md#creating-compressed-textures-with-crunch README].

The {{code|-noNormalDetection}} and {{code|-rtopmip}} options are succinctly described below.

==Dæmon Crunch Enhancements==

Here are things you will not find in either Binomial Crunch, Unity Crunch or none of them:

===Unity Crunch format===

This repository merged improvements done by Unity Technologies, it produces
smaller files and produces them faster than original code by Binomial.
Unity also modified the format which makes it incompatible with earlier versions of the tool.

Quote from [https://unvanquished.net/unvanquished-area-51 unvanquished.net]:

<blockquote>
[https://blog.unity.com/technology/crunch-compression-of-etc-textures Unity guys said]
that their modified crunch tool “can compress up to 2.5
times faster, while providing about 10% better compression ratio”. So we
did a test on our own asset repository, re-crunching all the ressources
and textures packages. At the time we did the test the given corpus
produced 1797 .crn files.
The Unity’s crunch tool reduced compression time by 4.31 and reduced size
by 11.15%. They said “up to 2.5 time faster” but we’ve seen some random
textures being compressed 6 time faster and the average of the whole is
4.3 time faster, and yes the tool compresses more than 10% more.
</blockquote>

===Unity Crunch metadata===

Unlike the Unity {{code|crunch}} tool built from their public repository, this tool produces files loadable by the Unity engine. Since [https://github.com/DaemonEngine/crunch/blob/master/faf5127b8c69dfd1ae554f4f3bf8168048b48d9f February 11th 2023], this branch sets the CRN {{code|m_userdata0}} field to {{code|1}} to make CRN files loadable by the Unity engine which now prevents to load files with this value set to {{code|0}}.

Files with this value set to {{code|1}} are expected to use the new format. Files with this value set to {{code|0}} may or may not use the new format. When Unity updated the tool and modified the format in an incompatible way, no bit was modified to detect if a CRN file was using the old or the new format. Unity has not updated that field in their public repository of Crunch so files using new format with this value set to {{code|0}} may be found in the wild.

===Improved image compatibility===

Supported source file formats: CRN,DDS,KTX,TGA,BMP,PNG,JPG/JPEG,PSD. 
Supported output file formats: CRN,DDS,KTX,TGA,BMP,PNG,JPG/JPEG.

* 1-bit PNG files are supported.
* Flipped TGA files are supported.
* Progressive JPEG files are supported.

The {{code|stb_image}} library has been updated from version 1.18 to version 2.30, increasing the amount of image format variants that can be converted, like 1-bit PNG formats. Further improvements like horizontally-flipped TGA images were brought to {{code|stb_image}} to make it support more TGA variants.

Note: Some other specific file format variants may be unsupported.

See the docs for jpgd.h: {{url|code.google.com/p/jpeg-compressor}} 
See the docs for stb_image.h: {{url|github.com/nothings/stb}}

===Converted image reproducibility===

We take special care that, when using compilation options for IEEE 754 float processing (disabling fast math, preferring SSE over x87…), the bitstream of converted image files are the same whatever the compiler, the operating system, or the CPU architecture crunch is built for and running on. It helps making packaged game assets reproducible. The CI not only checks that crunch builds, but that it runs properly and that the same input converts to the same output.

When reproducibility isn't needed, fast math can be enabled with CMake with the {{code|1=-DUSE_FAST_MATH=ON}} CMake option.

It is recommended for those looking for generating reproducible CRN files to keep disabled the use of fast math. It is also recommended to disable x87 floats on i686 and to rely on SSE instead with the {{code|1=-mfpmath=sse -msse}} compiler flags.

===Added features and command line options===

In addition to the original {{code|crunch}} features and command line options this branch brings new features and options, including:

* {{code|-rtopmip}}: option to use with {{code|-renormalize}} to also renormalize on the top mip-level.
* {{code|-noNormalDetection}}: do not attempt to detect normal map to avoid selecting formats thought for normal maps when it's known an image is not a normal map. It may prevent the tool to use heavier and less-supported {{code|DXT5_AGBR}} format when {{code|DXT1}} is good enough.
* {{code|-h}} or {{code|--help}}: print the command line built-in help, listing all known options.

===Network file system compatibility===

The original {{code|crunch}} tool relied on non-standard I/O features not working on all file systems including network file systems like NFS or SSHFS. A standard implementation was added so the limitations are not there anymore and {{code|crunch}} can now process image files stored over the network and on any other file system.

===Optional header-only checksumming===

For applications distributing their files in containers already providing a checksum mechanism for the whole contained file, it's now possible to only validate the CRN header checksum instead of the whole file checksum to not checksum the whole file twice.

===Multisystem and multiplatform portability===

Unlike upstream branches from Binomial LLC and Unity Software Inc. this branch focuses on keeping the code buildable outside of Windows and Visual Studio, and adds a CMake build option alongside the legacy Makefile.

This {{code|crunch}} tool and the related {{code|crnlib}} library are known to build with and and run on:

* Compilers: GCC, MinGW, MSVC, Clang, Apple Clang, and more.
* Systems: Linux, Windows, macOS, FreeBSD.
* Architectures: amd64, arm64, i686, armhf.

===Thoroughly tested and improved reproducibility===

A continuous integration system tests the build of crunch for a dozen of configurations of different architecture, system or compiler. The output of such builds are also tested with most of those builds. It helped to improve and validate image support, to identify build options known to improve the reproducibility of the output, and is meant to catch regressions if they happen.

The Dæmon crunch code is frequently scanned with the the CodeQL static analyser.

===CMake build system===

CMake has now replaced the old Makefile. The supplied CMake configuration provides many useful build options. Toolchain files for MinGW cross-compilation are also supplied.

The native MSVC solution files were removed, it is expected that MSVC users generate them with CMake instead.

Tools/Saigo

2026-08-05T05:55:20Z

Illwieckz:

[[Category:Tools]][[Category:Native Client]]{{DISPLAYTITLE:Dæmon Saigo SDK — Modern Toolchain for Native Client}}
Saigo is a modern toolchain for compiling {{nacl}} applications.

{{Trivia|
In Japanese, ''Saigo'' (さいご / 最後) means “''the last''”, “''the end''”, “''the final''” or “''the conclusion''”. This refers to the end of an era, the final stage of an event, or the last item in a sequence…}}

{{NativeClientGoogleDeprecation}}

==Status==

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}} being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

The Unvanquished game code is already buildable with Saigo. Saigo is meant to replace PNaCl for Unvanquished release builds.

==Components==

The Saigo SDK consists of:

* C and C++ compilers based on LLVM clang;
* Utilities like a linker, based on GNU binutils;
* A debugger, based on GDB;
* A libc based on Newlib and a libc++ based on LLVM.
* Headers from the Native Client repositories.

The compiler supports latest C++ standards like C23 and C++23. Unlike PNaCl, Saigo compiles directly to {{code|.nexe}}.

Saigo may not support C++ exceptions as far as we know but supports {{code|setjmp/longjmp}}.

==Sources==

The project for rebuilding the Saigo Native Client SDK can be found there:

* {{url|github.com/DaemonEngine/saigo-release-scripts}}

This project include patches applied over compile, binutils and debugger repositories before building. This project builds clang, binutils and gdb from Google repositories, and fetches headers from the Dæmon Native Client Runtime repository:

* {{url|chromium.googlesource.com/native_client/nacl-llvm-project-v10}} (Saigo NaCl clang)
* {{url|chromium.googlesource.com/native_client/nacl-binutils}} (NaCl binutils)
* {{url|chromium.googlesource.com/native_client/nacl-gdb}} (NaCl Saigo GDB)
* {{url|github.com/DaemonEngine/native_client}} (NaCl headers)

==Platform support==

{{NativeClientPlatformSupport}}

==Breakpad support==

Code compiled with Saigo uses {{code|-2}} instead of {{code|-1}} as value for the CFA pseudo-register.

We patched {{Tools|Breakpad}} to also support Saigo binaries, see this [https://github.com/DaemonEngine/breakpad/pull/19 patch].

==Migration to Saigo==

Here is a GitHub issue about the ongoing efforts for migrating to Saigo:

* {{url|github.com/Unvanquished/Unvanquished/issues/3197}}

Main Page

2026-08-05T04:50:20Z

Illwieckz:

{{DISPLAYTITLE:Unvanquished Wiki}}
* If you need help about the game or the wiki, jump on [https://unvanquished.net/chat/ IRC or Matrix or Discord] (see [[Chat#Rules|rules]]) or the {{forums}}.
* If you are facing a bug in the game, report it on [https://github.com/Unvanquished/Unvanquished/issues GitHub].
* Build the wiki! Contribute guides, information, corrections and improvements.

<div class="mainPageNewBox">

<h2> [[Install and play]] </h2>
* [[Install and play#Getting the game|Getting the game]]
* [[Install and play#Running and configuration|Game configuration]]
* [[Bug reporting]]
* [[Install and play#Getting in contact|Getting in contact]]
* [[Linux packages|Alternative Linux packages]]
* [[Server/Running|Running a server]]
* [[GPU compatibility matrix]]

</div>

<div class="mainPageNewBox">

<h2> [[Lore]] </h2>
* [[Humans]], [[Aliens]], [[:Category:Buildables|Buildables]], [[:Category:Weapons|Weapons]]…
* [[Gameplay|Gameplay guides]]
* [[Lore#Stories|Unvanquished stories]]
* [[Maps]] and [[Mods]]

</div>

<div class="mainPageNewBox">

<h2> [[Projects|Projects and Tools]] </h2>

* [[Unvanquished|Unvanquished game]]
* [[Daemon|Dæmon engine]]
* [[Native Client|Native Client sandbox]]
* [[Infrastructure|Unvanquished infrastructure]]
* [[Tools|Unvanquished tools]]
* [[Projects#Unvanquished on the web|Unvanquished on the web]]
* [[Wiki project resources]]

</div>

<div class="mainPageNewBox">

<h2> [[Coding]] </h2>
* [[Getting the source]]
* [[Compiling the source]]
* [[Contributing|Contributing guide]]
* [[Coding convention]]
* [[Dealing with submodules]]
* [[Continuous integration]]
* Reference materials

</div>

<div class="mainPageNewBox">

<h2> [[Making and modding]] </h2>
* [[Mapping]], [[Modeling]], [[Texturing]]…
* [[Music and sounds]]
* [[Tutorials]], [[Formats]]
* [[Translation]]
* Gameplay modification

</div>

<div class="mainPageNewBox">

<h2> [[Install and play#Getting in contact|Getting in contact]] </h2>

* [[Chat]]
* [//forums.unvanquished.net Forums]
* [[Web#Unvanquished on social hubs|Social hubs]]

</div>

<div style="clear: both;"></div>

<div style="text-align: center;">{{NUMBEROFEDITS}} edits to {{NUMBEROFPAGES}} pages with {{NUMBEROFFILES}} uploaded files</div>

<div style="height: 150px; width: 100%; overflow:hidden; align:centre;">

[[File:Dir inpackage.png|x150px]][[File:Egg concept.png|x150px]] [[File:Om concept.png|x150px]] [[File:Librocket test custom menuscreen.png|x150px]] [[File:NetRadiant texture browser common.png|x150px]] [[File:Colourgrade_2.png|x150px]] [[File:Parpax upper.png|x150px]] [[File:Niveus brushesSelected.jpeg|x150px]] [[File:Mgturret render 300x240.png|x150px]] [[File:Barricade.png|x150px]]

</div>

__NOTOC__

Tools

2026-08-05T04:47:47Z

Illwieckz: /* Debugging tools */

[[Category:Tools]]{{DISPLAYTITLE:Unvanquished tools}}
Unvanquished provides or recommend a number of tools to assist developers and artists in creating content or in doing some game-related operations. All required editors and tools are expected to be free software.

If you notice a specific task can't be done with free software, [https://github.com/Unvanquished/unvanquished-infrastructure/issues please report the issue there].

==Version control system==

{{InfoGit}}

==Subset lists==

* {{Tools|Level editors}} compares level editors;
* {{Tools|Mapping}} tools, including level editors, map compilers and other things;
* {{Tools|Modeling}} tools;
* {{Tools|IQM}} tools to edit or convert IQM model formats;
* {{Tools|Image}} tools;
* {{Tools|Audio}} tools;

==Common editors==

===Specific editors we have created, or we maintain, or we may contribute to===

See {{Tools|DaemonMediaAuthoringKit}} for an easy way to build all of them on Linux.

* {{Tools|NetRadiant}} is a graphical level editor, maintained by [https://xonotic.org Xonotic] and Unvanquished from id Software, Xonotic, and Unvanquished code;
* {{Tools|Chameleon}} is a graphical application to assist mappers in replacing textures in game levels, created for Unvanquished.

===Other generic editors===

Unvanquished does not provide any way to install them, it is recommended to get them from their respective projects.

* {{Tools|Blender}} is a 3D modeler used for modeling and animating Unvanquished models, by Blender Foundation;
* {{Tools|GIMP}} is a graphical editor used to edit Unvanquished textures and other images, by GIMP Development Team;
* {{Tools|Inkscape}} is a vector-based image editor to editor Unvanquished scalable images, by Inkscape authors;
* {{Tools|Audacity}} is an audio editor, by Audacity Team.

==Common creation tools==

===Specific tools we have created, or we maintain, or we may contribute to===

See {{Tools|DaemonMediaAuthoringKit}} for an easy way to build all of them on Linux.

* {{Tools|Sloth}} is a command-line tool to generate shader files from directories of texture maps, created for Unvanquished;
* {{Tools|Q3map2}} is a command-line tool to compile game levels, maintained by [https://xonotic.org Xonotic] and Unvanquished from id Software, Xonotic, and Unvanquished code;
* {{crunch}} is a command-line tool to compress images optimized for GPUs, Crunch is also the recommended TGA to PNG converter (prefer Dæmon Crunch over ImageMagick which is not reliable), maintained by Unvanquished, based on BinomialLLC, Unity Technologies and Unvanquished code;
* {{Tools|Iqmtool}} is a command-line tool to compile IQM models, maintained by [https://fte.triptohell.info FTE QuakeWorld], based on Lee Salzman ([http://sauerbraten.org Sauerbraten]) and FTE QuakeWorld code;
* {{Tools|Urcheon}} is a command-line tool to build and package asset repositories, created for Unvanquished;
* {{Tools|Esquirel}} is a command-line tool (part of Urcheon) to parse and edit MAP and BSP files, created for Unvanquished.

===Other generic tools===

See {{Tools|DaemonMediaAuthoringKit}} for an easy way to build all of them on Linux, but it is very likely you'll find upstream packages for your system.

* [https://developers.google.com/speed/webp/docs/cwebp cwebp] is a WebP image converter, by Google;
* [https://opus-codec.org/ opusenc] is an Opus audio converter, by IETF, Xiph.Org and Skype;
* [https://xiph.org/vorbis/ oggenc] is a Vorbis audio converter, by Xiph.Org;
* [https://xiph.org/flac/ flac] is a FLAC audio converter, by Xiph.Org.

==Game runtime==

* {{naclruntime}} is a modern sandbox for running {{nacl}} applications, maintained by Unvanquished, based on Google code.

==Compilers==

* {{saigo}} is a modern toolchain for compiling {{nacl}} applications, maintained by Unvanquished, based on LLVM, GNU and Google code.

==Debugging tools==

* {{breakpad}} is a crash-reporting system for generating and analyzing crash dumps for the {{engine}} and {{nacl}} game modules, maintained by Unvanquished, based on Google and Jon Turney code.
* The {{saigo}} also provides the {{code|nacl-gdb}} debugger.

==Development frameworks==

* {{Tools|Yokai}} is a CMake framework for C/C++ projects providing advanced cross-compilation support and features like embedded file C++ generation, created for Unvanquished;

==Obsolete tools==

* {{Tools|DaemonMap}} was a navmesh generator, maintained by Unvanquished from id Software code and Unvanquished code, starting with Unvanquished 0.54.0 the navmesh generator is built in the game itself so there is no need anymore to use an external tool.

==Stalled editors==

* {{Tools|Archipelago}} was a project for a web-based utility to rearrange UV islands in a model either to minimize texture sheet usage or to make room for new geometry.

Tools

2026-08-05T04:46:28Z

Illwieckz: /* Debugging tools */

[[Category:Tools]]{{DISPLAYTITLE:Unvanquished tools}}
Unvanquished provides or recommend a number of tools to assist developers and artists in creating content or in doing some game-related operations. All required editors and tools are expected to be free software.

If you notice a specific task can't be done with free software, [https://github.com/Unvanquished/unvanquished-infrastructure/issues please report the issue there].

==Version control system==

{{InfoGit}}

==Subset lists==

* {{Tools|Level editors}} compares level editors;
* {{Tools|Mapping}} tools, including level editors, map compilers and other things;
* {{Tools|Modeling}} tools;
* {{Tools|IQM}} tools to edit or convert IQM model formats;
* {{Tools|Image}} tools;
* {{Tools|Audio}} tools;

==Common editors==

===Specific editors we have created, or we maintain, or we may contribute to===

See {{Tools|DaemonMediaAuthoringKit}} for an easy way to build all of them on Linux.

* {{Tools|NetRadiant}} is a graphical level editor, maintained by [https://xonotic.org Xonotic] and Unvanquished from id Software, Xonotic, and Unvanquished code;
* {{Tools|Chameleon}} is a graphical application to assist mappers in replacing textures in game levels, created for Unvanquished.

===Other generic editors===

Unvanquished does not provide any way to install them, it is recommended to get them from their respective projects.

* {{Tools|Blender}} is a 3D modeler used for modeling and animating Unvanquished models, by Blender Foundation;
* {{Tools|GIMP}} is a graphical editor used to edit Unvanquished textures and other images, by GIMP Development Team;
* {{Tools|Inkscape}} is a vector-based image editor to editor Unvanquished scalable images, by Inkscape authors;
* {{Tools|Audacity}} is an audio editor, by Audacity Team.

==Common creation tools==

===Specific tools we have created, or we maintain, or we may contribute to===

See {{Tools|DaemonMediaAuthoringKit}} for an easy way to build all of them on Linux.

* {{Tools|Sloth}} is a command-line tool to generate shader files from directories of texture maps, created for Unvanquished;
* {{Tools|Q3map2}} is a command-line tool to compile game levels, maintained by [https://xonotic.org Xonotic] and Unvanquished from id Software, Xonotic, and Unvanquished code;
* {{crunch}} is a command-line tool to compress images optimized for GPUs, Crunch is also the recommended TGA to PNG converter (prefer Dæmon Crunch over ImageMagick which is not reliable), maintained by Unvanquished, based on BinomialLLC, Unity Technologies and Unvanquished code;
* {{Tools|Iqmtool}} is a command-line tool to compile IQM models, maintained by [https://fte.triptohell.info FTE QuakeWorld], based on Lee Salzman ([http://sauerbraten.org Sauerbraten]) and FTE QuakeWorld code;
* {{Tools|Urcheon}} is a command-line tool to build and package asset repositories, created for Unvanquished;
* {{Tools|Esquirel}} is a command-line tool (part of Urcheon) to parse and edit MAP and BSP files, created for Unvanquished.

===Other generic tools===

See {{Tools|DaemonMediaAuthoringKit}} for an easy way to build all of them on Linux, but it is very likely you'll find upstream packages for your system.

* [https://developers.google.com/speed/webp/docs/cwebp cwebp] is a WebP image converter, by Google;
* [https://opus-codec.org/ opusenc] is an Opus audio converter, by IETF, Xiph.Org and Skype;
* [https://xiph.org/vorbis/ oggenc] is a Vorbis audio converter, by Xiph.Org;
* [https://xiph.org/flac/ flac] is a FLAC audio converter, by Xiph.Org.

==Game runtime==

* {{naclruntime}} is a modern sandbox for running {{nacl}} applications, maintained by Unvanquished, based on Google code.

==Compilers==

* {{saigo}} is a modern toolchain for compiling {{nacl}} applications, maintained by Unvanquished, based on LLVM, GNU and Google code.

==Debugging tools==

* {{breakpad}} is a crash-reporting system used for generating and analyzing crash dumps for the {{engine}} and {{nacl}} gamelogic modules, maintained by Unvanquished, based on Google and Jon Turney code.
* The {{saigo}} also provides the {{code|nacl-gdb}} debugger.

==Development frameworks==

* {{Tools|Yokai}} is a CMake framework for C/C++ projects providing advanced cross-compilation support and features like embedded file C++ generation, created for Unvanquished;

==Obsolete tools==

* {{Tools|DaemonMap}} was a navmesh generator, maintained by Unvanquished from id Software code and Unvanquished code, starting with Unvanquished 0.54.0 the navmesh generator is built in the game itself so there is no need anymore to use an external tool.

==Stalled editors==

* {{Tools|Archipelago}} was a project for a web-based utility to rearrange UV islands in a model either to minimize texture sheet usage or to make room for new geometry.

Tools

2026-08-05T04:46:11Z

Illwieckz: /* Common creation tools */

[[Category:Tools]]{{DISPLAYTITLE:Unvanquished tools}}
Unvanquished provides or recommend a number of tools to assist developers and artists in creating content or in doing some game-related operations. All required editors and tools are expected to be free software.

If you notice a specific task can't be done with free software, [https://github.com/Unvanquished/unvanquished-infrastructure/issues please report the issue there].

==Version control system==

{{InfoGit}}

==Subset lists==

* {{Tools|Level editors}} compares level editors;
* {{Tools|Mapping}} tools, including level editors, map compilers and other things;
* {{Tools|Modeling}} tools;
* {{Tools|IQM}} tools to edit or convert IQM model formats;
* {{Tools|Image}} tools;
* {{Tools|Audio}} tools;

==Common editors==

===Specific editors we have created, or we maintain, or we may contribute to===

See {{Tools|DaemonMediaAuthoringKit}} for an easy way to build all of them on Linux.

* {{Tools|NetRadiant}} is a graphical level editor, maintained by [https://xonotic.org Xonotic] and Unvanquished from id Software, Xonotic, and Unvanquished code;
* {{Tools|Chameleon}} is a graphical application to assist mappers in replacing textures in game levels, created for Unvanquished.

===Other generic editors===

Unvanquished does not provide any way to install them, it is recommended to get them from their respective projects.

* {{Tools|Blender}} is a 3D modeler used for modeling and animating Unvanquished models, by Blender Foundation;
* {{Tools|GIMP}} is a graphical editor used to edit Unvanquished textures and other images, by GIMP Development Team;
* {{Tools|Inkscape}} is a vector-based image editor to editor Unvanquished scalable images, by Inkscape authors;
* {{Tools|Audacity}} is an audio editor, by Audacity Team.

==Common creation tools==

===Specific tools we have created, or we maintain, or we may contribute to===

See {{Tools|DaemonMediaAuthoringKit}} for an easy way to build all of them on Linux.

* {{Tools|Sloth}} is a command-line tool to generate shader files from directories of texture maps, created for Unvanquished;
* {{Tools|Q3map2}} is a command-line tool to compile game levels, maintained by [https://xonotic.org Xonotic] and Unvanquished from id Software, Xonotic, and Unvanquished code;
* {{crunch}} is a command-line tool to compress images optimized for GPUs, Crunch is also the recommended TGA to PNG converter (prefer Dæmon Crunch over ImageMagick which is not reliable), maintained by Unvanquished, based on BinomialLLC, Unity Technologies and Unvanquished code;
* {{Tools|Iqmtool}} is a command-line tool to compile IQM models, maintained by [https://fte.triptohell.info FTE QuakeWorld], based on Lee Salzman ([http://sauerbraten.org Sauerbraten]) and FTE QuakeWorld code;
* {{Tools|Urcheon}} is a command-line tool to build and package asset repositories, created for Unvanquished;
* {{Tools|Esquirel}} is a command-line tool (part of Urcheon) to parse and edit MAP and BSP files, created for Unvanquished.

===Other generic tools===

See {{Tools|DaemonMediaAuthoringKit}} for an easy way to build all of them on Linux, but it is very likely you'll find upstream packages for your system.

* [https://developers.google.com/speed/webp/docs/cwebp cwebp] is a WebP image converter, by Google;
* [https://opus-codec.org/ opusenc] is an Opus audio converter, by IETF, Xiph.Org and Skype;
* [https://xiph.org/vorbis/ oggenc] is a Vorbis audio converter, by Xiph.Org;
* [https://xiph.org/flac/ flac] is a FLAC audio converter, by Xiph.Org.

==Game runtime==

* {{naclruntime}} is a modern sandbox for running {{nacl}} applications, maintained by Unvanquished, based on Google code.

==Compilers==

* {{saigo}} is a modern toolchain for compiling {{nacl}} applications, maintained by Unvanquished, based on LLVM, GNU and Google code.

==Debugging tools==

* {{breakpad}} is a crash-reporting system used for generating and analyzing crash dumps for the {{engine}} and [[Native Client|NaCl]] gamelogic modules, maintained by Unvanquished, based on Google and Jon Turney code.
* The {{saigo}} also provides the {{code|nacl-gdb}} debugger.

==Development frameworks==

* {{Tools|Yokai}} is a CMake framework for C/C++ projects providing advanced cross-compilation support and features like embedded file C++ generation, created for Unvanquished;

==Obsolete tools==

* {{Tools|DaemonMap}} was a navmesh generator, maintained by Unvanquished from id Software code and Unvanquished code, starting with Unvanquished 0.54.0 the navmesh generator is built in the game itself so there is no need anymore to use an external tool.

==Stalled editors==

* {{Tools|Archipelago}} was a project for a web-based utility to rearrange UV islands in a model either to minimize texture sheet usage or to make room for new geometry.

Tools

2026-08-05T04:45:34Z

Illwieckz: /* Specific editors we have created, or we maintain, or we may contribute to */

[[Category:Tools]]{{DISPLAYTITLE:Unvanquished tools}}
Unvanquished provides or recommend a number of tools to assist developers and artists in creating content or in doing some game-related operations. All required editors and tools are expected to be free software.

If you notice a specific task can't be done with free software, [https://github.com/Unvanquished/unvanquished-infrastructure/issues please report the issue there].

==Version control system==

{{InfoGit}}

==Subset lists==

* {{Tools|Level editors}} compares level editors;
* {{Tools|Mapping}} tools, including level editors, map compilers and other things;
* {{Tools|Modeling}} tools;
* {{Tools|IQM}} tools to edit or convert IQM model formats;
* {{Tools|Image}} tools;
* {{Tools|Audio}} tools;

==Common editors==

===Specific editors we have created, or we maintain, or we may contribute to===

See {{Tools|DaemonMediaAuthoringKit}} for an easy way to build all of them on Linux.

* {{Tools|NetRadiant}} is a graphical level editor, maintained by [https://xonotic.org Xonotic] and Unvanquished from id Software, Xonotic, and Unvanquished code;
* {{Tools|Chameleon}} is a graphical application to assist mappers in replacing textures in game levels, created for Unvanquished.

===Other generic editors===

Unvanquished does not provide any way to install them, it is recommended to get them from their respective projects.

* {{Tools|Blender}} is a 3D modeler used for modeling and animating Unvanquished models, by Blender Foundation;
* {{Tools|GIMP}} is a graphical editor used to edit Unvanquished textures and other images, by GIMP Development Team;
* {{Tools|Inkscape}} is a vector-based image editor to editor Unvanquished scalable images, by Inkscape authors;
* {{Tools|Audacity}} is an audio editor, by Audacity Team.

==Common creation tools==

===Specific tools we have created, or we maintain, or we may contribute to===

See {{Tools|DaemonMediaAuthoringKit}} for an easy way to build all of them on Linux.

* {{Tools|Sloth}} is a command-line tool to generate shader files from directories of texture maps, created for Unvanquished;
* {{Tools|Q3map2}} is a command-line tool to compile game levels, maintained by [https://xonotic.org Xonotic] from id Software, Xonotic, and Unvanquished code;
* {{crunch}} is a command-line tool to compress images optimized for GPUs, Crunch is also the recommended TGA to PNG converter (prefer Dæmon Crunch over ImageMagick which is not reliable), maintained by Unvanquished, based on BinomialLLC, Unity Technologies and Unvanquished code;
* {{Tools|Iqmtool}} is a command-line tool to compile IQM models, maintained by [https://fte.triptohell.info FTE QuakeWorld], based on Lee Salzman ([http://sauerbraten.org Sauerbraten]) and FTE QuakeWorld code;
* {{Tools|Urcheon}} is a command-line tool to build and package asset repositories, created for Unvanquished;
* {{Tools|Esquirel}} is a command-line tool (part of Urcheon) to parse and edit MAP and BSP files, created for Unvanquished.

===Other generic tools===

See {{Tools|DaemonMediaAuthoringKit}} for an easy way to build all of them on Linux, but it is very likely you'll find upstream packages for your system.

* [https://developers.google.com/speed/webp/docs/cwebp cwebp] is a WebP image converter, by Google;
* [https://opus-codec.org/ opusenc] is an Opus audio converter, by IETF, Xiph.Org and Skype;
* [https://xiph.org/vorbis/ oggenc] is a Vorbis audio converter, by Xiph.Org;
* [https://xiph.org/flac/ flac] is a FLAC audio converter, by Xiph.Org.

==Game runtime==

* {{naclruntime}} is a modern sandbox for running {{nacl}} applications, maintained by Unvanquished, based on Google code.

==Compilers==

* {{saigo}} is a modern toolchain for compiling {{nacl}} applications, maintained by Unvanquished, based on LLVM, GNU and Google code.

==Debugging tools==

* {{breakpad}} is a crash-reporting system used for generating and analyzing crash dumps for the {{engine}} and [[Native Client|NaCl]] gamelogic modules, maintained by Unvanquished, based on Google and Jon Turney code.
* The {{saigo}} also provides the {{code|nacl-gdb}} debugger.

==Development frameworks==

* {{Tools|Yokai}} is a CMake framework for C/C++ projects providing advanced cross-compilation support and features like embedded file C++ generation, created for Unvanquished;

==Obsolete tools==

* {{Tools|DaemonMap}} was a navmesh generator, maintained by Unvanquished from id Software code and Unvanquished code, starting with Unvanquished 0.54.0 the navmesh generator is built in the game itself so there is no need anymore to use an external tool.

==Stalled editors==

* {{Tools|Archipelago}} was a project for a web-based utility to rearrange UV islands in a model either to minimize texture sheet usage or to make room for new geometry.

Template:Crunch

2026-08-05T04:43:39Z

Illwieckz:

'''{{#ifeq: {{{link|}}}|no|Dæmon Crunch|[[Tools/Crunch|Dæmon Crunch]]}}'''

Tools

2026-08-05T04:42:42Z

Illwieckz: /* Common creation tools */

[[Category:Tools]]{{DISPLAYTITLE:Unvanquished tools}}
Unvanquished provides or recommend a number of tools to assist developers and artists in creating content or in doing some game-related operations. All required editors and tools are expected to be free software.

If you notice a specific task can't be done with free software, [https://github.com/Unvanquished/unvanquished-infrastructure/issues please report the issue there].

==Version control system==

{{InfoGit}}

==Subset lists==

* {{Tools|Level editors}} compares level editors;
* {{Tools|Mapping}} tools, including level editors, map compilers and other things;
* {{Tools|Modeling}} tools;
* {{Tools|IQM}} tools to edit or convert IQM model formats;
* {{Tools|Image}} tools;
* {{Tools|Audio}} tools;

==Common editors==

===Specific editors we have created, or we maintain, or we may contribute to===

See {{Tools|DaemonMediaAuthoringKit}} for an easy way to build all of them on Linux.

* {{Tools|NetRadiant}} is a graphical level editor, maintained by [https://xonotic.org Xonotic] from id Software, Xonotic, and Unvanquished code;
* {{Tools|Chameleon}} is a graphical application to assist mappers in replacing textures in game levels, created for Unvanquished.

===Other generic editors===

Unvanquished does not provide any way to install them, it is recommended to get them from their respective projects.

* {{Tools|Blender}} is a 3D modeler used for modeling and animating Unvanquished models, by Blender Foundation;
* {{Tools|GIMP}} is a graphical editor used to edit Unvanquished textures and other images, by GIMP Development Team;
* {{Tools|Inkscape}} is a vector-based image editor to editor Unvanquished scalable images, by Inkscape authors;
* {{Tools|Audacity}} is an audio editor, by Audacity Team.

==Common creation tools==

===Specific tools we have created, or we maintain, or we may contribute to===

See {{Tools|DaemonMediaAuthoringKit}} for an easy way to build all of them on Linux.

* {{Tools|Sloth}} is a command-line tool to generate shader files from directories of texture maps, created for Unvanquished;
* {{Tools|Q3map2}} is a command-line tool to compile game levels, maintained by [https://xonotic.org Xonotic] from id Software, Xonotic, and Unvanquished code;
* {{crunch}} is a command-line tool to compress images optimized for GPUs, Crunch is also the recommended TGA to PNG converter (prefer Dæmon Crunch over ImageMagick which is not reliable), maintained by Unvanquished, based on BinomialLLC, Unity Technologies and Unvanquished code;
* {{Tools|Iqmtool}} is a command-line tool to compile IQM models, maintained by [https://fte.triptohell.info FTE QuakeWorld], based on Lee Salzman ([http://sauerbraten.org Sauerbraten]) and FTE QuakeWorld code;
* {{Tools|Urcheon}} is a command-line tool to build and package asset repositories, created for Unvanquished;
* {{Tools|Esquirel}} is a command-line tool (part of Urcheon) to parse and edit MAP and BSP files, created for Unvanquished.

===Other generic tools===

See {{Tools|DaemonMediaAuthoringKit}} for an easy way to build all of them on Linux, but it is very likely you'll find upstream packages for your system.

* [https://developers.google.com/speed/webp/docs/cwebp cwebp] is a WebP image converter, by Google;
* [https://opus-codec.org/ opusenc] is an Opus audio converter, by IETF, Xiph.Org and Skype;
* [https://xiph.org/vorbis/ oggenc] is a Vorbis audio converter, by Xiph.Org;
* [https://xiph.org/flac/ flac] is a FLAC audio converter, by Xiph.Org.

==Game runtime==

* {{naclruntime}} is a modern sandbox for running {{nacl}} applications, maintained by Unvanquished, based on Google code.

==Compilers==

* {{saigo}} is a modern toolchain for compiling {{nacl}} applications, maintained by Unvanquished, based on LLVM, GNU and Google code.

==Debugging tools==

* {{breakpad}} is a crash-reporting system used for generating and analyzing crash dumps for the {{engine}} and [[Native Client|NaCl]] gamelogic modules, maintained by Unvanquished, based on Google and Jon Turney code.
* The {{saigo}} also provides the {{code|nacl-gdb}} debugger.

==Development frameworks==

* {{Tools|Yokai}} is a CMake framework for C/C++ projects providing advanced cross-compilation support and features like embedded file C++ generation, created for Unvanquished;

==Obsolete tools==

* {{Tools|DaemonMap}} was a navmesh generator, maintained by Unvanquished from id Software code and Unvanquished code, starting with Unvanquished 0.54.0 the navmesh generator is built in the game itself so there is no need anymore to use an external tool.

==Stalled editors==

* {{Tools|Archipelago}} was a project for a web-based utility to rearrange UV islands in a model either to minimize texture sheet usage or to make room for new geometry.

Tools

2026-08-05T04:41:23Z

Illwieckz:

[[Category:Tools]]{{DISPLAYTITLE:Unvanquished tools}}
Unvanquished provides or recommend a number of tools to assist developers and artists in creating content or in doing some game-related operations. All required editors and tools are expected to be free software.

If you notice a specific task can't be done with free software, [https://github.com/Unvanquished/unvanquished-infrastructure/issues please report the issue there].

==Version control system==

{{InfoGit}}

==Subset lists==

* {{Tools|Level editors}} compares level editors;
* {{Tools|Mapping}} tools, including level editors, map compilers and other things;
* {{Tools|Modeling}} tools;
* {{Tools|IQM}} tools to edit or convert IQM model formats;
* {{Tools|Image}} tools;
* {{Tools|Audio}} tools;

==Common editors==

===Specific editors we have created, or we maintain, or we may contribute to===

See {{Tools|DaemonMediaAuthoringKit}} for an easy way to build all of them on Linux.

* {{Tools|NetRadiant}} is a graphical level editor, maintained by [https://xonotic.org Xonotic] from id Software, Xonotic, and Unvanquished code;
* {{Tools|Chameleon}} is a graphical application to assist mappers in replacing textures in game levels, created for Unvanquished.

===Other generic editors===

Unvanquished does not provide any way to install them, it is recommended to get them from their respective projects.

* {{Tools|Blender}} is a 3D modeler used for modeling and animating Unvanquished models, by Blender Foundation;
* {{Tools|GIMP}} is a graphical editor used to edit Unvanquished textures and other images, by GIMP Development Team;
* {{Tools|Inkscape}} is a vector-based image editor to editor Unvanquished scalable images, by Inkscape authors;
* {{Tools|Audacity}} is an audio editor, by Audacity Team.

==Common creation tools==

===Specific tools we have created, or we maintain, or we may contribute to===

See {{Tools|DaemonMediaAuthoringKit}} for an easy way to build all of them on Linux.

* {{Tools|Sloth}} is a command-line tool to generate shader files from directories of texture maps, created for Unvanquished;
* {{Tools|Q3map2}} is a command-line tool to compile game levels, maintained by [https://xonotic.org Xonotic] from id Software, Xonotic, and Unvanquished code;
* {{Crunch}} is a command-line tool to compress images optimized for GPUs, Crunch is also the recommended TGA to PNG converter (prefer Dæmon Crunch over ImageMagick which is not reliable), maintained by Unvanquished, based on BinomialLLC, Unity Technologies and Unvanquished code;
* {{Tools|Iqmtool}} is a command-line tool to compile IQM models, maintained by [https://fte.triptohell.info FTE QuakeWorld], based on Lee Salzman ([http://sauerbraten.org Sauerbraten]) and FTE QuakeWorld code;
* {{Tools|Urcheon}} is a command-line tool to build and package asset repositories, created for Unvanquished;
* {{Tools|Esquirel}} is a command-line tool (part of Urcheon) to parse and edit MAP and BSP files, created for Unvanquished.

===Other generic tools===

See {{Tools|DaemonMediaAuthoringKit}} for an easy way to build all of them on Linux, but it is very likely you'll find upstream packages for your system.

* [https://developers.google.com/speed/webp/docs/cwebp cwebp] is a WebP image converter, by Google;
* [https://opus-codec.org/ opusenc] is an Opus audio converter, by IETF, Xiph.Org and Skype;
* [https://xiph.org/vorbis/ oggenc] is a Vorbis audio converter, by Xiph.Org;
* [https://xiph.org/flac/ flac] is a FLAC audio converter, by Xiph.Org.

==Game runtime==

* {{naclruntime}} is a modern sandbox for running {{nacl}} applications, maintained by Unvanquished, based on Google code.

==Compilers==

* {{saigo}} is a modern toolchain for compiling {{nacl}} applications, maintained by Unvanquished, based on LLVM, GNU and Google code.

==Debugging tools==

* {{breakpad}} is a crash-reporting system used for generating and analyzing crash dumps for the {{engine}} and [[Native Client|NaCl]] gamelogic modules, maintained by Unvanquished, based on Google and Jon Turney code.
* The {{saigo}} also provides the {{code|nacl-gdb}} debugger.

==Development frameworks==

* {{Tools|Yokai}} is a CMake framework for C/C++ projects providing advanced cross-compilation support and features like embedded file C++ generation, created for Unvanquished;

==Obsolete tools==

* {{Tools|DaemonMap}} was a navmesh generator, maintained by Unvanquished from id Software code and Unvanquished code, starting with Unvanquished 0.54.0 the navmesh generator is built in the game itself so there is no need anymore to use an external tool.

==Stalled editors==

* {{Tools|Archipelago}} was a project for a web-based utility to rearrange UV islands in a model either to minimize texture sheet usage or to make room for new geometry.

Tools/Breakpad

2026-08-05T04:38:48Z

Illwieckz:

[[Category:Tools]][[Category:Native Client]]{{DISPLAYTITLE:Dæmon Breakpad — Enhanced Breakpad Crash Reporting Library}}
Breakpad is a set of client and server components which implement a crash-reporting system, originally developed by Google.

Dæmon Breakpad is an enhanced version of Google Breakpad providing wider platform compatibility and additional executable and symbol formats while incorporating upstream changes.

The {{game}} uses Breakpad for generating and analyzing crash dumps from both the {{engine}} and {{nacl}} gamelogic modules.

A crash dump is a file that is generated when the program crashes, which can be analyzed by developers to find out why the crash occurred. Breakpad is currently available in Daemon for the Windows (if built with MinGW) and Linux engine code, and the NaCl gamelogic on any platform.

{{Note|content=Breakpad cannot be used for native executable gamelogic modules. But (assuming a Linux server) you may use traditional core dumps instead. OR, you can use the <code>vm.cgame.type</code> or <code>vm.sgame.type</code> cvars to start up gdbserver.
{{TODO|inline=true|Explain how to use this.}}}}

==Sources==

The Breakpad source repository is: {{url|github.com/DaemonEngine/breakpad}}

Dæmon's Breakpad fork is based on {{url|github.com/jon-turney/google-breakpad}}. Jon Turney's version adds MinGW support. It is in turn a fork of Chromium's Breakpad {{url|chromium.googlesource.com/breakpad/breakpad}}. Improvements from Google upstream are merged from time to time. We also implement our own improvements, like {{nacl}} compatibility and extended cross-platform support.

== Dæmon Breakpad enhancements ==

=== MinGW and DWARF5 compatibility ===

The Dæmon Breakpad adds MinGW support to Google Breakpad, based on Jon Turney's patches, with merged Google upstream adding support for DWARF5 debugging information format. It retains the support for systems already supported by the Google Breakpad upstream.

===Saigo-built nexe compatibility===

The Dæmon Breakpad adds support for {{nacl}} {{code|.nexe}} binaries built with the {{saigo}}. The {{code|linux/dump_syms}} tool can extract symbols from those nexe. Don't mind the “linux” directory, it's an ELF tool.

===Multiplatform ELF symbolizer===

The {{code|linux/dumps_syms}} tool can build for and run on Linux, macOS, FreeBSD and Windows (when built with MinGW). It can then symbolize ELF binaries on all those platforms, including Linux binaries, FreeBSD binaries, and NaCl binaries.

==Cross symbolizer compatibility==

{|
|-
! ↓ Host \ Binary →
! NaCl ELF !! Linux ELF !! FreeBSD ELF !! macOS Mach-O !! Windows PE+DWARF (MinGW)
|-
! Linux
| ✅️ || ✅️ || ✅️ || ✅️ || ✅️
|-
! FreeBSD
| ✅️ || ✅️ || ✅️ || ||
|-
! macOS
| ✅️ || ✅️ || ✅️ || ||
|-
! Windows (MinGW)
| ✅️ || ✅️ || ✅️ || ||
|}

==Engine build configuration==

The {{code|USE_BREAKPAD}} CMake option controls whether Breakpad support is built into the engine. It is disabled by default because Breakpad is primarily useful for publicly distributed release binaries, not people who build and run the code themselves. Note that NaCl crash dump support is always built in, regardless of options.

For an engine built with Breakpad support, the <code>common.breakpad.enabled</code> cvar turns it on or off.

The cvar can only be set via the command line, like <code>./daemon -set common.breakpad.enabled 0</code>.

==For users: reporting a crash==

The crash dumps are stored in the homepath under the <code>crashdump/</code> directory. Sort by date to find the most recent one and make sure it matches the date/time when the crash occurred. Send the .dmp file to someone on the Unvanquished development team.

==For developers: how to trace a crash==

=== 1. Getting the tools ===

The Breakpad repository for the {{engine}} is at {{url|github.com/DaemonEngine/breakpad}}. If you have already checked out {{code|Daemon}}, then it is located in the <code>libs/breakpad/</code> submodule there. cd into this repo.

=== 2. Get symbols ===

==== 2a. Symbols for an official Unvanquished release ====

If you are debugging an official release binary, you don't need to (and can't) generate symbols yourself -- the Unvanquished release script handles this. In the Unvanquished unizip/torrent (or updater installation directory), symbol files are found in the <code>symbols_${VERSION}.zip</code> archive. Simply extract the zip somewhere.

==== 2b. Generating your own symbols ====

To produce symbols, you need a binary with debug info. For MinGW, the binary additionally needs to have been built with the {{code|-Wl,--build-id}} flag so that it has a nonzero build ID.

The first step is to build the dump_syms and/or dump_syms_dwarf executable using Make. Then you can use the <code>symbolize.py</code> script in the root of Daemon's Breakpad repository to produce the symbols and store them in a symbol directory. Or if you want to know how to do it yourself, you can read the following paragraph which describes what the script does:

You need to run the dump_syms tool (located at <code>src/tools/linux/dump_syms/dump_syms</code> for Linux or NaCl targets or <code>src/tools/windows/dump_syms_dwarf/dump_syms</code> for MinGW targets) on the binary(ies) where the crash occurred. Usage: <code>dump_syms <binary></code>. The output must be stored in a specific directory format. Pick a directory to be the symbol directory (<code>symbols</code> in the following examples). The output must be stored at <code>symbols/$FILENAME/$BUILD_ID/$FILENAME.sym</code> . For example, <code>symbols/cgame-native-dll.dll/1A74E057938E0BF10930C4F54740B2E21/cgame-native-dll.dll.sym</code>. The build ID can be seen in the first few lines of dump_syms output in a line beginning with <code>MODULE</code>.

=== 3. Stack walk ===
Running the stack walk tool (located at <code>src/processor/minidump_stackwalk</code>) will give the human-readable stack trace.

Usage: <code>minidump_stackwalk <dump file> <symbol directory></code>.

Tools/Breakpad

2026-08-05T04:36:58Z

Illwieckz:

[[Category:Tools]][[Category:Native Client]]{{DISPLAYTITLE:Dæmon Breakpad — Enhanced Breakpad Crash Reporting Library}}
Breakpad is a set of client and server components which implement a crash-reporting system, originally developed by Google.

Dæmon Breakpad is an enhanced version of Google Breakpad providing wider platform compatibility and additional executable and symbol formats while incorporating upstream changes.

The {{game}} uses Breakpad for generating and analyzing crash dumps from both the {{engine}} and {{nacl}} gamelogic modules.

A crash dump is a file that is generated when the program crashes, which can be analyzed by developers to find out why the crash occurred. Breakpad is currently available in Daemon for the Windows (if built with MinGW) and Linux engine code, and the NaCl gamelogic on any platform.

{{Note|content=Breakpad cannot be used for native executable gamelogic modules. But (assuming a Linux server) you may use traditional core dumps instead. OR, you can use the <code>vm.cgame.type</code> or <code>vm.sgame.type</code> cvars to start up gdbserver.
{{TODO|inline=true|Explain how to use this.}}}}

==Sources==

The Breakpad source repository is: {{url|github.com/DaemonEngine/breakpad}}

Dæmon's Breakpad fork is based on {{url|github.com/jon-turney/google-breakpad}}. Jon Turney's version adds MinGW support. It is in turn a fork of Chromium's Breakpad {{url|chromium.googlesource.com/breakpad/breakpad}}. Improvements from Google upstream are merged from time to time. We also implement our own improvements, like [[Native Client]] compatibility and extended cross-platform support.

== Dæmon Breakpad enhancements ==

=== MinGW and DWARF5 compatibility ===

The Dæmon Breakpad adds MinGW support to Google Breakpad, based on Jon Turney's patches, with merged Google upstream adding support for DWARF5 debugging information format. It retains the support for systems already supported by the Google Breakpad upstream.

===Saigo-built nexe compatibility===

The Dæmon Breakpad adds support for [[Native Client]] {{code|.nexe}} binaries built with the {{saigo}}. The {{code|linux/dump_syms}} tool can extract symbols from those nexe. Don't mind the “linux” directory, it's an ELF tool.

===Multiplatform ELF symbolizer===

The {{code|linux/dumps_syms}} tool can build for and run on Linux, macOS, FreeBSD and Windows (when built with MinGW). It can then symbolize ELF binaries on all those platforms, including Linux binaries, FreeBSD binaries, and NaCl binaries.

==Cross symbolizer compatibility==

{|
|-
! ↓ Host \ Binary →
! NaCl ELF !! Linux ELF !! FreeBSD ELF !! macOS Mach-O !! Windows PE+DWARF (MinGW)
|-
! Linux
| ✅️ || ✅️ || ✅️ || ✅️ || ✅️
|-
! FreeBSD
| ✅️ || ✅️ || ✅️ || ||
|-
! macOS
| ✅️ || ✅️ || ✅️ || ||
|-
! Windows (MinGW)
| ✅️ || ✅️ || ✅️ || ||
|}

==Engine build configuration==

The {{code|USE_BREAKPAD}} CMake option controls whether Breakpad support is built into the engine. It is disabled by default because Breakpad is primarily useful for publicly distributed release binaries, not people who build and run the code themselves. Note that NaCl crash dump support is always built in, regardless of options.

For an engine built with Breakpad support, the <code>common.breakpad.enabled</code> cvar turns it on or off.

The cvar can only be set via the command line, like <code>./daemon -set common.breakpad.enabled 0</code>.

==For users: reporting a crash==

The crash dumps are stored in the homepath under the <code>crashdump/</code> directory. Sort by date to find the most recent one and make sure it matches the date/time when the crash occurred. Send the .dmp file to someone on the Unvanquished development team.

==For developers: how to trace a crash==

=== 1. Getting the tools ===

The Breakpad repository for the {{engine}} is at {{url|github.com/DaemonEngine/breakpad}}. If you have already checked out {{code|Daemon}}, then it is located in the <code>libs/breakpad/</code> submodule there. cd into this repo.

=== 2. Get symbols ===

==== 2a. Symbols for an official Unvanquished release ====

If you are debugging an official release binary, you don't need to (and can't) generate symbols yourself -- the Unvanquished release script handles this. In the Unvanquished unizip/torrent (or updater installation directory), symbol files are found in the <code>symbols_${VERSION}.zip</code> archive. Simply extract the zip somewhere.

==== 2b. Generating your own symbols ====

To produce symbols, you need a binary with debug info. For MinGW, the binary additionally needs to have been built with the {{code|-Wl,--build-id}} flag so that it has a nonzero build ID.

The first step is to build the dump_syms and/or dump_syms_dwarf executable using Make. Then you can use the <code>symbolize.py</code> script in the root of Daemon's Breakpad repository to produce the symbols and store them in a symbol directory. Or if you want to know how to do it yourself, you can read the following paragraph which describes what the script does:

You need to run the dump_syms tool (located at <code>src/tools/linux/dump_syms/dump_syms</code> for Linux or NaCl targets or <code>src/tools/windows/dump_syms_dwarf/dump_syms</code> for MinGW targets) on the binary(ies) where the crash occurred. Usage: <code>dump_syms <binary></code>. The output must be stored in a specific directory format. Pick a directory to be the symbol directory (<code>symbols</code> in the following examples). The output must be stored at <code>symbols/$FILENAME/$BUILD_ID/$FILENAME.sym</code> . For example, <code>symbols/cgame-native-dll.dll/1A74E057938E0BF10930C4F54740B2E21/cgame-native-dll.dll.sym</code>. The build ID can be seen in the first few lines of dump_syms output in a line beginning with <code>MODULE</code>.

=== 3. Stack walk ===
Running the stack walk tool (located at <code>src/processor/minidump_stackwalk</code>) will give the human-readable stack trace.

Usage: <code>minidump_stackwalk <dump file> <symbol directory></code>.

Native Client

2026-08-05T04:35:32Z

Illwieckz: /* Postmortem Debugging */

[[Category:Native Client]]{{DISPLAYTITLE:Native Client — Secure Native Code Sandbox Technology}}
Native Client (also known as NaCl) is a sandboxing technology by Google. It was used by Chrome extensions and Chrome apps. The {{engine}} uses Native Client to securely and portably run downloadable compiled games. It replaced the Q3VM (Quake 3 Virtual Machine) in the engine.

The Native Client documentation can be found on [https://chrome.jscn.org/docs/native-client/welcome-to-native-client/ chrome.jscn.org/docs/native-client/welcome-to-native-client/].

The NaCl support consists of:

* {{naclruntime}} — a modern Native Client runtime;
* {{saigo}} — a modern toolchain for Native Client with compilers and a debugger;
* {{breakpad}} — an enhanced breakpad crash reporting library.

==Status==

'''Native Client''' or '''NaCl''' is the current technology used for securely virtualising the game code in the {{engine}}.

Server-side game logic NaCl support was first shipped in Alpha 27, released in April 2014. See the [https://unvanquished.net/moving-the-server-side-gamelogic-to-pnacl/ blog article by Kangz] and [https://unvanquished.net/alpha-27-flying-in-your-direction/ the release note by DSalt].

Client-side game logic NaCl support was first shipped in Alpha 37, released on March 2, 2015. See the [https://unvanquished.net/alpha-37-anniversary-edition/ release note by Kangz].

This completed the transition by porting the client VM to NaCl and this replaced entirely the legacy Quake III Q3VM system.

NaCl upstream development has slowed down since the competing solution [[WebAssembly]] became the industry standard, so it is very unlikely support for new systems and architecture would be added. To overcome this problem, we would have to switch to WebAssembly (that unfortunately may only support using a slow interpreter for some platforms NaCl supports, like i686 or armhf), but more importantly may still lack support for exceptions or {{code|setjmp/longjmp}} and then not be complete enough for our needs yet.

{{NativeClientIsDying}}

==Comparison==

{|
|+ Game VM comparison
|-
! !! Quake 3 / Tremulous !! Dæmon / Unvanquished
|-
| Technology || Q3VM || NaCl
|-
| Language || Old C (<ins>NOT</ins> Quake C) || Modern C / C++
|-
| Compiler || LCC (proprietary) || Clang (open-source)
|-
| System portability || Yes || Yes
|-
| Architecture portability || Yes || No
|-
| Secure sandbox || No || Yes
|}

With the Quake 3 engine and the Q3VM, the game code was programmed in C (it should not be confused with the scripting language of Quake 1 named QuakeC). This C code was real C was meant to be compiled with the proprietary LCC compiler, which only supported an old C, and the developer couldn't really rely on off-the-shelf libraries. That C code was compiled by LCC into {{code|.qvm}} binaries.

With the {{engine}}, the game code can be programmed in C or C++. That C/C++ code is compiled with Clang-based open source compilers supporting modern-enough C++ versions that makes possible to reuse off-the-shelf C++ libraries that may even be shared between the engine and the game source code. The C/C+ code is compiled into {{code|.nexe}} binarie.

Unlike QVMs, NaCl gamelogic runs in a secure sandbox. Native Client lets you run mods downloaded from the internet without giving them free reign on your computer. QVM was equivalent to running a DLL with no protection.

==Platform support==

{{NativeClientPlatformSupport}}

==NaCl Runtime==

See the {{naclruntime}} page for details.

==Rebuild effort==

{{NativeClientGoogleDeprecation}}

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}} being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

The project for rebuilding the {{naclruntime}} can be found there:

* {{url|github.com/DaemonEngine/native_client}}

The official releases for Unvanquished are already using the {{naclruntime}} on Linux for the {{code|amd64}} architecture, other systems are still using the Google NaCl Runtime.

The project for rebuilding the {{saigo}} can be found there:

* {{url|github.com/DaemonEngine/saigo-release-scripts}}

It's already possible to build Unvanquished with a Saigo compiler rebuilt this way.

==Compilers==

===Google PNaCl SDK===

PNaCl Clang is the current NaCl compiler we use to build the nexe game binaries. It is based on an old Clang 3.6 and does not support C++ above C++14. To overcome some of the related limitations we may switch to Saigo.

The PNaCl compilation workflow is to build a single {{code|.pexe}} then to translate them to per-architecture {{code|.nexe}} (amd64, i686, armhf) using a specific translator tool.

The PNaCl SDK consists on Python-based wrappers around Clang internals. It was initially using now-obsolete and hard-to-find Python2 but we ported it to Python3 to extend its lifespan.

The provided PNaCl SDK runs on Linux, Windows and macOS systems, on amd64 architectures.

While the {{code|.pexe}} compiler itself runs on FreeBSD with the Linuxulator, the translator does not, meaning it's not possible to build {{code|.nexe}} binaries on FreeBSD.

PNaCl supports C++ exception. There exist newer PNaCl SDKs (from chromium canary releases) that do not support exceptions and may not provide more what we already have with latest stable PNaCl.

===Dæmon Saigo SDK===

Saigo is a new NaCl compiler based on latest Clang and supporting latest C++ standards. It compiles directly to {{code|.nexe}}.

See {{saigo}} for details.

The Unvanquished game code is now buildable with Saigo.

Saigo may not support C++ exceptions as far as we know but supports {{code|setjmp/longjmp}}.

Unlike PNaCl, Saigo wasn't released by Google, meaning a switch from PNaCl to Saigo required a convenient way to provide it to contributors. Google provided some nightly Linux amd64 Saigo toolchain snapshots that aren't easy to get without some Google scripts. The Saigo compiler itself isn't hard to build (same as Clang itself), the binutils are a bit more tricky but not that hard (10 years-old configure build). What is tricky to rebuild is the libc that requires some very old NaCl GCC. Fortunately there exists libc and libc++ snapshots provided by Google that can be reused with a self-built toolchain.

The Saigo compiler and NaCl binutils can be rebuilt to run natively on many platforms (Like Clang and GNU binutils), but they will always target the usual platforms as the NaCl loader is still the same: a more recent NaCl runtime is also buildable but doesn't bring any new platform support.

Moving to Saigo is considered as a migration step that can be achievable before migrating to [[WebAssembly]], as it allows us to migrate to a new C++ standard and update libraries we use without waiting for the migration to WebAssembly.

Some redesign of our CMake configuration for Saigo may help later when migrating to WebAssembly as it makes it more generic for different VM toolchains.

Here is a GitHub issue about the ongoing efforts for migrating to Saigo:

* {{url|github.com/Unvanquished/Unvanquished/issues/3197}}

==Interactive Debugging==

Most of the time it is easiest to debug with a native DLL. But if you have a problem that cannot be reproduced outside of NaCl, you may be forced to resort to the following tutorial.

These steps for attaching the NaCl debugger<ref>https://web.archive.org/web/20250909075554/https://www.chromium.org/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/getting-started-with-debug-stub/</ref> have been tested on Windows with a PNaCl toolchain. They should also work on binaries built with Saigo, using the old GDB from the PNaCl SDK or the GDB provided with the {{saigo}}. On Linux or Mac you may experience more difficulties due to the lack of support for old binaries (meaning nacl-gdb). illwieckz reports that on amd64 Linux in 2025, using the old GDB which is a 32-bit binary, debugging an amd64 nexe does not work (despite the documentation's claims of debugger platform independence), but debugging an i686 nexe does.

# Build the NaCl gamelogic with debugging symbols (build type Debug or RelWithDebInfo).
# Launch Daemon configured for NaCl debugging. For example, <code>./daemonded -set vm.sgame.type 1 -set vm.sgame.debug 1 +map chasm</code> When the relevant gamelogic starts, the engine should pause and emit the message <code>Waiting for GDB connection on localhost:4014</code>.
# Start NaCl GDB, e.g. <code>daemon\external_deps\windows-amd64-mingw_10\nacl-gdb.exe</code> This works better out of a command prompt rather than an MSYS window.
# Use the "file" command to tell the debugger where the binary with symbols is. For example, <code>file sgame-amd64.nexe</code>
# OPTIONAL, probably a waste of time: load the IRT (Integrated Runtime) symbols: <code>nacl-irt irt_core-amd64.nexe</code>
# Connect to the NaCl program with the command <code>target remote :4014</code>
# You should see a message like <code>0x000000000ffc00a0 in ?? ()</code> (or <code>0x000000000ffc00a0 in __pnacl_start ()</code> if you did step 5). This means the program is paused at the beginning.
# Set some breakpoints, e.g. <code>b G_RunFrame</code>. Alternatively, just wait for the debugger to break when the game crashes.
# Start the program by continuing (<code>c</code>).

==Postmortem Debugging==

See {{breakpad}}.

Native Client

2026-08-05T04:34:59Z

Illwieckz: /* Interactive Debugging */

[[Category:Native Client]]{{DISPLAYTITLE:Native Client — Secure Native Code Sandbox Technology}}
Native Client (also known as NaCl) is a sandboxing technology by Google. It was used by Chrome extensions and Chrome apps. The {{engine}} uses Native Client to securely and portably run downloadable compiled games. It replaced the Q3VM (Quake 3 Virtual Machine) in the engine.

The Native Client documentation can be found on [https://chrome.jscn.org/docs/native-client/welcome-to-native-client/ chrome.jscn.org/docs/native-client/welcome-to-native-client/].

The NaCl support consists of:

* {{naclruntime}} — a modern Native Client runtime;
* {{saigo}} — a modern toolchain for Native Client with compilers and a debugger;
* {{breakpad}} — an enhanced breakpad crash reporting library.

==Status==

'''Native Client''' or '''NaCl''' is the current technology used for securely virtualising the game code in the {{engine}}.

Server-side game logic NaCl support was first shipped in Alpha 27, released in April 2014. See the [https://unvanquished.net/moving-the-server-side-gamelogic-to-pnacl/ blog article by Kangz] and [https://unvanquished.net/alpha-27-flying-in-your-direction/ the release note by DSalt].

Client-side game logic NaCl support was first shipped in Alpha 37, released on March 2, 2015. See the [https://unvanquished.net/alpha-37-anniversary-edition/ release note by Kangz].

This completed the transition by porting the client VM to NaCl and this replaced entirely the legacy Quake III Q3VM system.

NaCl upstream development has slowed down since the competing solution [[WebAssembly]] became the industry standard, so it is very unlikely support for new systems and architecture would be added. To overcome this problem, we would have to switch to WebAssembly (that unfortunately may only support using a slow interpreter for some platforms NaCl supports, like i686 or armhf), but more importantly may still lack support for exceptions or {{code|setjmp/longjmp}} and then not be complete enough for our needs yet.

{{NativeClientIsDying}}

==Comparison==

{|
|+ Game VM comparison
|-
! !! Quake 3 / Tremulous !! Dæmon / Unvanquished
|-
| Technology || Q3VM || NaCl
|-
| Language || Old C (<ins>NOT</ins> Quake C) || Modern C / C++
|-
| Compiler || LCC (proprietary) || Clang (open-source)
|-
| System portability || Yes || Yes
|-
| Architecture portability || Yes || No
|-
| Secure sandbox || No || Yes
|}

With the Quake 3 engine and the Q3VM, the game code was programmed in C (it should not be confused with the scripting language of Quake 1 named QuakeC). This C code was real C was meant to be compiled with the proprietary LCC compiler, which only supported an old C, and the developer couldn't really rely on off-the-shelf libraries. That C code was compiled by LCC into {{code|.qvm}} binaries.

With the {{engine}}, the game code can be programmed in C or C++. That C/C++ code is compiled with Clang-based open source compilers supporting modern-enough C++ versions that makes possible to reuse off-the-shelf C++ libraries that may even be shared between the engine and the game source code. The C/C+ code is compiled into {{code|.nexe}} binarie.

Unlike QVMs, NaCl gamelogic runs in a secure sandbox. Native Client lets you run mods downloaded from the internet without giving them free reign on your computer. QVM was equivalent to running a DLL with no protection.

==Platform support==

{{NativeClientPlatformSupport}}

==NaCl Runtime==

See the {{naclruntime}} page for details.

==Rebuild effort==

{{NativeClientGoogleDeprecation}}

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}} being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

The project for rebuilding the {{naclruntime}} can be found there:

* {{url|github.com/DaemonEngine/native_client}}

The official releases for Unvanquished are already using the {{naclruntime}} on Linux for the {{code|amd64}} architecture, other systems are still using the Google NaCl Runtime.

The project for rebuilding the {{saigo}} can be found there:

* {{url|github.com/DaemonEngine/saigo-release-scripts}}

It's already possible to build Unvanquished with a Saigo compiler rebuilt this way.

==Compilers==

===Google PNaCl SDK===

PNaCl Clang is the current NaCl compiler we use to build the nexe game binaries. It is based on an old Clang 3.6 and does not support C++ above C++14. To overcome some of the related limitations we may switch to Saigo.

The PNaCl compilation workflow is to build a single {{code|.pexe}} then to translate them to per-architecture {{code|.nexe}} (amd64, i686, armhf) using a specific translator tool.

The PNaCl SDK consists on Python-based wrappers around Clang internals. It was initially using now-obsolete and hard-to-find Python2 but we ported it to Python3 to extend its lifespan.

The provided PNaCl SDK runs on Linux, Windows and macOS systems, on amd64 architectures.

While the {{code|.pexe}} compiler itself runs on FreeBSD with the Linuxulator, the translator does not, meaning it's not possible to build {{code|.nexe}} binaries on FreeBSD.

PNaCl supports C++ exception. There exist newer PNaCl SDKs (from chromium canary releases) that do not support exceptions and may not provide more what we already have with latest stable PNaCl.

===Dæmon Saigo SDK===

Saigo is a new NaCl compiler based on latest Clang and supporting latest C++ standards. It compiles directly to {{code|.nexe}}.

See {{saigo}} for details.

The Unvanquished game code is now buildable with Saigo.

Saigo may not support C++ exceptions as far as we know but supports {{code|setjmp/longjmp}}.

Unlike PNaCl, Saigo wasn't released by Google, meaning a switch from PNaCl to Saigo required a convenient way to provide it to contributors. Google provided some nightly Linux amd64 Saigo toolchain snapshots that aren't easy to get without some Google scripts. The Saigo compiler itself isn't hard to build (same as Clang itself), the binutils are a bit more tricky but not that hard (10 years-old configure build). What is tricky to rebuild is the libc that requires some very old NaCl GCC. Fortunately there exists libc and libc++ snapshots provided by Google that can be reused with a self-built toolchain.

The Saigo compiler and NaCl binutils can be rebuilt to run natively on many platforms (Like Clang and GNU binutils), but they will always target the usual platforms as the NaCl loader is still the same: a more recent NaCl runtime is also buildable but doesn't bring any new platform support.

Moving to Saigo is considered as a migration step that can be achievable before migrating to [[WebAssembly]], as it allows us to migrate to a new C++ standard and update libraries we use without waiting for the migration to WebAssembly.

Some redesign of our CMake configuration for Saigo may help later when migrating to WebAssembly as it makes it more generic for different VM toolchains.

Here is a GitHub issue about the ongoing efforts for migrating to Saigo:

* {{url|github.com/Unvanquished/Unvanquished/issues/3197}}

==Interactive Debugging==

Most of the time it is easiest to debug with a native DLL. But if you have a problem that cannot be reproduced outside of NaCl, you may be forced to resort to the following tutorial.

These steps for attaching the NaCl debugger<ref>https://web.archive.org/web/20250909075554/https://www.chromium.org/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/getting-started-with-debug-stub/</ref> have been tested on Windows with a PNaCl toolchain. They should also work on binaries built with Saigo, using the old GDB from the PNaCl SDK or the GDB provided with the {{saigo}}. On Linux or Mac you may experience more difficulties due to the lack of support for old binaries (meaning nacl-gdb). illwieckz reports that on amd64 Linux in 2025, using the old GDB which is a 32-bit binary, debugging an amd64 nexe does not work (despite the documentation's claims of debugger platform independence), but debugging an i686 nexe does.

# Build the NaCl gamelogic with debugging symbols (build type Debug or RelWithDebInfo).
# Launch Daemon configured for NaCl debugging. For example, <code>./daemonded -set vm.sgame.type 1 -set vm.sgame.debug 1 +map chasm</code> When the relevant gamelogic starts, the engine should pause and emit the message <code>Waiting for GDB connection on localhost:4014</code>.
# Start NaCl GDB, e.g. <code>daemon\external_deps\windows-amd64-mingw_10\nacl-gdb.exe</code> This works better out of a command prompt rather than an MSYS window.
# Use the "file" command to tell the debugger where the binary with symbols is. For example, <code>file sgame-amd64.nexe</code>
# OPTIONAL, probably a waste of time: load the IRT (Integrated Runtime) symbols: <code>nacl-irt irt_core-amd64.nexe</code>
# Connect to the NaCl program with the command <code>target remote :4014</code>
# You should see a message like <code>0x000000000ffc00a0 in ?? ()</code> (or <code>0x000000000ffc00a0 in __pnacl_start ()</code> if you did step 5). This means the program is paused at the beginning.
# Set some breakpoints, e.g. <code>b G_RunFrame</code>. Alternatively, just wait for the debugger to break when the game crashes.
# Start the program by continuing (<code>c</code>).

==Postmortem Debugging==

See {{Tools|Breakpad}}.

Category:Native Client

2026-08-05T04:32:45Z

Illwieckz: Created page with "Pages related to {{nacl}}."

Pages related to {{nacl}}.

Tools/Saigo

2026-08-05T04:32:23Z

Illwieckz:

[[Category:Tools]][[Category:Native Client]]{{DISPLAYTITLE:Dæmon Saigo SDK — Modern toolchain for Native Client}}
Saigo is a modern toolchain for compiling {{nacl}} applications.

{{Trivia|
In Japanese, ''Saigo'' (さいご / 最後) means “''the last''”, “''the end''”, “''the final''” or “''the conclusion''”. This refers to the end of an era, the final stage of an event, or the last item in a sequence…}}

{{NativeClientGoogleDeprecation}}

==Status==

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}} being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

The Unvanquished game code is already buildable with Saigo. Saigo is meant to replace PNaCl for Unvanquished release builds.

==Components==

The Saigo SDK consists of:

* C and C++ compilers based on LLVM clang;
* Utilities like a linker, based on GNU binutils;
* A debugger, based on GDB;
* A libc based on Newlib and a libc++ based on LLVM.
* Headers from the Native Client repositories.

The compiler supports latest C++ standards like C23 and C++23. Unlike PNaCl, Saigo compiles directly to {{code|.nexe}}.

Saigo may not support C++ exceptions as far as we know but supports {{code|setjmp/longjmp}}.

==Sources==

The project for rebuilding the Saigo Native Client SDK can be found there:

* {{url|github.com/DaemonEngine/saigo-release-scripts}}

This project include patches applied over compile, binutils and debugger repositories before building. This project builds clang, binutils and gdb from Google repositories, and fetches headers from the Dæmon Native Client Runtime repository:

* {{url|chromium.googlesource.com/native_client/nacl-llvm-project-v10}} (Saigo NaCl clang)
* {{url|chromium.googlesource.com/native_client/nacl-binutils}} (NaCl binutils)
* {{url|chromium.googlesource.com/native_client/nacl-gdb}} (NaCl Saigo GDB)
* {{url|github.com/DaemonEngine/native_client}} (NaCl headers)

==Platform support==

{{NativeClientPlatformSupport}}

==Breakpad support==

Code compiled with Saigo uses {{code|-2}} instead of {{code|-1}} as value for the CFA pseudo-register.

We patched {{Tools|Breakpad}} to also support Saigo binaries, see this [https://github.com/DaemonEngine/breakpad/pull/19 patch].

==Migration to Saigo==

Here is a GitHub issue about the ongoing efforts for migrating to Saigo:

* {{url|github.com/Unvanquished/Unvanquished/issues/3197}}

Tools/Breakpad

2026-08-05T04:32:03Z

Illwieckz:

[[Category:Tools]][[Category:Native Client]]{{DISPLAYTITLE:Dæmon Breakpad — Enhanced Breakpad Crash Reporting Library}}
Breakpad is a set of client and server components which implement a crash-reporting system, originally developed by Google.

Dæmon Breakpad is an enhanced version of Google Breakpad providing wider platform compatibility and additional executable and symbol formats while incorporating upstream changes.

The {{game}} uses Breakpad for generating and analyzing crash dumps from both the {{engine}} and [[Native Client|NaCl]] gamelogic modules.

A crash dump is a file that is generated when the program crashes, which can be analyzed by developers to find out why the crash occurred. Breakpad is currently available in Daemon for the Windows (if built with MinGW) and Linux engine code, and the NaCl gamelogic on any platform.

{{Note|content=Breakpad cannot be used for native executable gamelogic modules. But (assuming a Linux server) you may use traditional core dumps instead. OR, you can use the <code>vm.cgame.type</code> or <code>vm.sgame.type</code> cvars to start up gdbserver.
{{TODO|inline=true|Explain how to use this.}}}}

==Sources==

The Breakpad source repository is: {{url|github.com/DaemonEngine/breakpad}}

Dæmon's Breakpad fork is based on {{url|github.com/jon-turney/google-breakpad}}. Jon Turney's version adds MinGW support. It is in turn a fork of Chromium's Breakpad {{url|chromium.googlesource.com/breakpad/breakpad}}. Improvements from Google upstream are merged from time to time. We also implement our own improvements, like [[Native Client]] compatibility and extended cross-platform support.

== Dæmon Breakpad enhancements ==

=== MinGW and DWARF5 compatibility ===

The Dæmon Breakpad adds MinGW support to Google Breakpad, based on Jon Turney's patches, with merged Google upstream adding support for DWARF5 debugging information format. It retains the support for systems already supported by the Google Breakpad upstream.

===Saigo-built nexe compatibility===

The Dæmon Breakpad adds support for [[Native Client]] {{code|.nexe}} binaries built with the {{saigo}}. The {{code|linux/dump_syms}} tool can extract symbols from those nexe. Don't mind the “linux” directory, it's an ELF tool.

===Multiplatform ELF symbolizer===

The {{code|linux/dumps_syms}} tool can build for and run on Linux, macOS, FreeBSD and Windows (when built with MinGW). It can then symbolize ELF binaries on all those platforms, including Linux binaries, FreeBSD binaries, and NaCl binaries.

==Cross symbolizer compatibility==

{|
|-
! ↓ Host \ Binary →
! NaCl ELF !! Linux ELF !! FreeBSD ELF !! macOS Mach-O !! Windows PE+DWARF (MinGW)
|-
! Linux
| ✅️ || ✅️ || ✅️ || ✅️ || ✅️
|-
! FreeBSD
| ✅️ || ✅️ || ✅️ || ||
|-
! macOS
| ✅️ || ✅️ || ✅️ || ||
|-
! Windows (MinGW)
| ✅️ || ✅️ || ✅️ || ||
|}

==Engine build configuration==

The {{code|USE_BREAKPAD}} CMake option controls whether Breakpad support is built into the engine. It is disabled by default because Breakpad is primarily useful for publicly distributed release binaries, not people who build and run the code themselves. Note that NaCl crash dump support is always built in, regardless of options.

For an engine built with Breakpad support, the <code>common.breakpad.enabled</code> cvar turns it on or off.

The cvar can only be set via the command line, like <code>./daemon -set common.breakpad.enabled 0</code>.

==For users: reporting a crash==

The crash dumps are stored in the homepath under the <code>crashdump/</code> directory. Sort by date to find the most recent one and make sure it matches the date/time when the crash occurred. Send the .dmp file to someone on the Unvanquished development team.

==For developers: how to trace a crash==

=== 1. Getting the tools ===

The Breakpad repository for the {{engine}} is at {{url|github.com/DaemonEngine/breakpad}}. If you have already checked out {{code|Daemon}}, then it is located in the <code>libs/breakpad/</code> submodule there. cd into this repo.

=== 2. Get symbols ===

==== 2a. Symbols for an official Unvanquished release ====

If you are debugging an official release binary, you don't need to (and can't) generate symbols yourself -- the Unvanquished release script handles this. In the Unvanquished unizip/torrent (or updater installation directory), symbol files are found in the <code>symbols_${VERSION}.zip</code> archive. Simply extract the zip somewhere.

==== 2b. Generating your own symbols ====

To produce symbols, you need a binary with debug info. For MinGW, the binary additionally needs to have been built with the {{code|-Wl,--build-id}} flag so that it has a nonzero build ID.

The first step is to build the dump_syms and/or dump_syms_dwarf executable using Make. Then you can use the <code>symbolize.py</code> script in the root of Daemon's Breakpad repository to produce the symbols and store them in a symbol directory. Or if you want to know how to do it yourself, you can read the following paragraph which describes what the script does:

You need to run the dump_syms tool (located at <code>src/tools/linux/dump_syms/dump_syms</code> for Linux or NaCl targets or <code>src/tools/windows/dump_syms_dwarf/dump_syms</code> for MinGW targets) on the binary(ies) where the crash occurred. Usage: <code>dump_syms <binary></code>. The output must be stored in a specific directory format. Pick a directory to be the symbol directory (<code>symbols</code> in the following examples). The output must be stored at <code>symbols/$FILENAME/$BUILD_ID/$FILENAME.sym</code> . For example, <code>symbols/cgame-native-dll.dll/1A74E057938E0BF10930C4F54740B2E21/cgame-native-dll.dll.sym</code>. The build ID can be seen in the first few lines of dump_syms output in a line beginning with <code>MODULE</code>.

=== 3. Stack walk ===
Running the stack walk tool (located at <code>src/processor/minidump_stackwalk</code>) will give the human-readable stack trace.

Usage: <code>minidump_stackwalk <dump file> <symbol directory></code>.

Native Client

2026-08-05T04:31:50Z

Illwieckz:

[[Category:Native Client]]{{DISPLAYTITLE:Native Client — Secure Native Code Sandbox Technology}}
Native Client (also known as NaCl) is a sandboxing technology by Google. It was used by Chrome extensions and Chrome apps. The {{engine}} uses Native Client to securely and portably run downloadable compiled games. It replaced the Q3VM (Quake 3 Virtual Machine) in the engine.

The Native Client documentation can be found on [https://chrome.jscn.org/docs/native-client/welcome-to-native-client/ chrome.jscn.org/docs/native-client/welcome-to-native-client/].

The NaCl support consists of:

* {{naclruntime}} — a modern Native Client runtime;
* {{saigo}} — a modern toolchain for Native Client with compilers and a debugger;
* {{breakpad}} — an enhanced breakpad crash reporting library.

==Status==

'''Native Client''' or '''NaCl''' is the current technology used for securely virtualising the game code in the {{engine}}.

Server-side game logic NaCl support was first shipped in Alpha 27, released in April 2014. See the [https://unvanquished.net/moving-the-server-side-gamelogic-to-pnacl/ blog article by Kangz] and [https://unvanquished.net/alpha-27-flying-in-your-direction/ the release note by DSalt].

Client-side game logic NaCl support was first shipped in Alpha 37, released on March 2, 2015. See the [https://unvanquished.net/alpha-37-anniversary-edition/ release note by Kangz].

This completed the transition by porting the client VM to NaCl and this replaced entirely the legacy Quake III Q3VM system.

NaCl upstream development has slowed down since the competing solution [[WebAssembly]] became the industry standard, so it is very unlikely support for new systems and architecture would be added. To overcome this problem, we would have to switch to WebAssembly (that unfortunately may only support using a slow interpreter for some platforms NaCl supports, like i686 or armhf), but more importantly may still lack support for exceptions or {{code|setjmp/longjmp}} and then not be complete enough for our needs yet.

{{NativeClientIsDying}}

==Comparison==

{|
|+ Game VM comparison
|-
! !! Quake 3 / Tremulous !! Dæmon / Unvanquished
|-
| Technology || Q3VM || NaCl
|-
| Language || Old C (<ins>NOT</ins> Quake C) || Modern C / C++
|-
| Compiler || LCC (proprietary) || Clang (open-source)
|-
| System portability || Yes || Yes
|-
| Architecture portability || Yes || No
|-
| Secure sandbox || No || Yes
|}

With the Quake 3 engine and the Q3VM, the game code was programmed in C (it should not be confused with the scripting language of Quake 1 named QuakeC). This C code was real C was meant to be compiled with the proprietary LCC compiler, which only supported an old C, and the developer couldn't really rely on off-the-shelf libraries. That C code was compiled by LCC into {{code|.qvm}} binaries.

With the {{engine}}, the game code can be programmed in C or C++. That C/C++ code is compiled with Clang-based open source compilers supporting modern-enough C++ versions that makes possible to reuse off-the-shelf C++ libraries that may even be shared between the engine and the game source code. The C/C+ code is compiled into {{code|.nexe}} binarie.

Unlike QVMs, NaCl gamelogic runs in a secure sandbox. Native Client lets you run mods downloaded from the internet without giving them free reign on your computer. QVM was equivalent to running a DLL with no protection.

==Platform support==

{{NativeClientPlatformSupport}}

==NaCl Runtime==

See the {{naclruntime}} page for details.

==Rebuild effort==

{{NativeClientGoogleDeprecation}}

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}} being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

The project for rebuilding the {{naclruntime}} can be found there:

* {{url|github.com/DaemonEngine/native_client}}

The official releases for Unvanquished are already using the {{naclruntime}} on Linux for the {{code|amd64}} architecture, other systems are still using the Google NaCl Runtime.

The project for rebuilding the {{saigo}} can be found there:

* {{url|github.com/DaemonEngine/saigo-release-scripts}}

It's already possible to build Unvanquished with a Saigo compiler rebuilt this way.

==Compilers==

===Google PNaCl SDK===

PNaCl Clang is the current NaCl compiler we use to build the nexe game binaries. It is based on an old Clang 3.6 and does not support C++ above C++14. To overcome some of the related limitations we may switch to Saigo.

The PNaCl compilation workflow is to build a single {{code|.pexe}} then to translate them to per-architecture {{code|.nexe}} (amd64, i686, armhf) using a specific translator tool.

The PNaCl SDK consists on Python-based wrappers around Clang internals. It was initially using now-obsolete and hard-to-find Python2 but we ported it to Python3 to extend its lifespan.

The provided PNaCl SDK runs on Linux, Windows and macOS systems, on amd64 architectures.

While the {{code|.pexe}} compiler itself runs on FreeBSD with the Linuxulator, the translator does not, meaning it's not possible to build {{code|.nexe}} binaries on FreeBSD.

PNaCl supports C++ exception. There exist newer PNaCl SDKs (from chromium canary releases) that do not support exceptions and may not provide more what we already have with latest stable PNaCl.

===Dæmon Saigo SDK===

Saigo is a new NaCl compiler based on latest Clang and supporting latest C++ standards. It compiles directly to {{code|.nexe}}.

See {{saigo}} for details.

The Unvanquished game code is now buildable with Saigo.

Saigo may not support C++ exceptions as far as we know but supports {{code|setjmp/longjmp}}.

Unlike PNaCl, Saigo wasn't released by Google, meaning a switch from PNaCl to Saigo required a convenient way to provide it to contributors. Google provided some nightly Linux amd64 Saigo toolchain snapshots that aren't easy to get without some Google scripts. The Saigo compiler itself isn't hard to build (same as Clang itself), the binutils are a bit more tricky but not that hard (10 years-old configure build). What is tricky to rebuild is the libc that requires some very old NaCl GCC. Fortunately there exists libc and libc++ snapshots provided by Google that can be reused with a self-built toolchain.

The Saigo compiler and NaCl binutils can be rebuilt to run natively on many platforms (Like Clang and GNU binutils), but they will always target the usual platforms as the NaCl loader is still the same: a more recent NaCl runtime is also buildable but doesn't bring any new platform support.

Moving to Saigo is considered as a migration step that can be achievable before migrating to [[WebAssembly]], as it allows us to migrate to a new C++ standard and update libraries we use without waiting for the migration to WebAssembly.

Some redesign of our CMake configuration for Saigo may help later when migrating to WebAssembly as it makes it more generic for different VM toolchains.

Here is a GitHub issue about the ongoing efforts for migrating to Saigo:

* {{url|github.com/Unvanquished/Unvanquished/issues/3197}}

==Interactive Debugging==

Most of the time it is easiest to debug with a native DLL. But if you have a problem that cannot be reproduced outside of NaCl, you may be forced to resort to the following tutorial.

These steps for attaching the NaCl debugger<ref>https://web.archive.org/web/20250909075554/https://www.chromium.org/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/getting-started-with-debug-stub/</ref> have been tested on Windows with a PNaCl toolchain. They should also work on binaries built with Saigo, using the old PNaCl GDB. On Linux or Mac you may experience more difficulties due to the lack of support for old binaries (meaning nacl-gdb). illwieckz reports that on amd64 Linux in 2025, using the old GDB which is a 32-bit binary, debugging an amd64 nexe does not work (despite the documentation's claims of debugger platform independence), but debugging an i686 nexe does.

# Build the NaCl gamelogic with debugging symbols (build type Debug or RelWithDebInfo).
# Launch Daemon configured for NaCl debugging. For example, <code>./daemonded -set vm.sgame.type 1 -set vm.sgame.debug 1 +map chasm</code> When the relevant gamelogic starts, the engine should pause and emit the message <code>Waiting for GDB connection on localhost:4014</code>.
# Start NaCl GDB, e.g. <code>daemon\external_deps\windows-amd64-mingw_10\nacl-gdb.exe</code> This works better out of a command prompt rather than an MSYS window.
# Use the "file" command to tell the debugger where the binary with symbols is. For example, <code>file sgame-amd64.nexe</code>
# OPTIONAL, probably a waste of time: load the IRT (Integrated Runtime) symbols: <code>nacl-irt irt_core-amd64.nexe</code>
# Connect to the NaCl program with the command <code>target remote :4014</code>
# You should see a message like <code>0x000000000ffc00a0 in ?? ()</code> (or <code>0x000000000ffc00a0 in __pnacl_start ()</code> if you did step 5). This means the program is paused at the beginning.
# Set some breakpoints, e.g. <code>b G_RunFrame</code>. Alternatively, just wait for the debugger to break when the game crashes.
# Start the program by continuing (<code>c</code>).

==Postmortem Debugging==

See {{Tools|Breakpad}}.

Tools/NaCl Runtime

2026-08-05T04:31:42Z

Illwieckz:

[[Category:Tools]][[Category:Native Client]]{{DISPLAYTITLE:Dæmon NaCl Runtime — Modern Native Client Runtime}}
The {{naclruntime}} provides the loader to run {{nacl}} applications built with the {{saigo}}.

{{NativeClientGoogleDeprecation}}

==Status==

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}} being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

The official releases for Unvanquished are already using the {{naclruntime}} on Linux for the {{code|amd64}} architecture, other systems are still using the Google NaCl Runtime.

==Sources==

The project for rebuilding the {{naclruntime}} can be found there:

* {{url|github.com/DaemonEngine/native_client}}

==Platform support==

{{NativeClientPlatformSupport}}

It has been verified that Linux on {{code|arm64}}, {{code|ppc64el}} and {{code|riscv64}} can run the {{code|amd64}} loader on [https://box86.org Box64], though on {{code|riscv64}} it is very slow. The '''Box64''' translation layer can also run on {{code|loong64}} but this has not been tested yet. The {{engine}} received patches to run Box64, but the user has to build the engine themselves and provides Box64. This is work-in-progress. Box64 integration is still work in progress (at some point we may ship Box64 with engines that can use it).

The NaCl loader (the virtual machine running the virtualised code) is available for three systems: Linux, Windows and macOS. The supported architectures differs per system:

* Linux: amd64, i686, armhf;
* Windows: amd64, i686;
* macOS: amd64.

It is possible to run native engines with other platforms when there is a compatibility layer to run the NaCl loader:

* Linux, arm64: running the armhf NaCl loader through built-in Linux Multiarch compatibility;
* macOS, arm64: running the amd64 NaCl loader through Rosetta2 compatibility;
* FreeBSD, amd64: running the Linux NaCl loader through built-in Linuxulator compatibility.

We provide the Multiarch libraries for running the armhf game on Linux arm64, no system modification is required on that part.

The Linux armhf NaCl loader requires a 4k PageSize kernel, this may require a system modification:

* {{url|github.com/Unvanquished/Unvanquished/issues/3286}}

There is work in progress to remove this restriction.

The Linux i686 and armhf NaCl loaders may run on FreeBSD using Linuxulator but it is not tested.

NaCl also supportrf 32-bit MIPS on Linux but this architecture is not supported by the {{engine}} and the {{game}} project, and is not supported by the {{saigo}}.

Native Client

2026-08-05T04:31:05Z

Illwieckz:

{{DISPLAYTITLE:Native Client — Secure Native Code Sandbox Technology}}
Native Client (also known as NaCl) is a sandboxing technology by Google. It was used by Chrome extensions and Chrome apps. The {{engine}} uses Native Client to securely and portably run downloadable compiled games. It replaced the Q3VM (Quake 3 Virtual Machine) in the engine.

The Native Client documentation can be found on [https://chrome.jscn.org/docs/native-client/welcome-to-native-client/ chrome.jscn.org/docs/native-client/welcome-to-native-client/].

The NaCl support consists of:

* {{naclruntime}} — a modern Native Client runtime;
* {{saigo}} — a modern toolchain for Native Client with compilers and a debugger;
* {{breakpad}} — an enhanced breakpad crash reporting library.

==Status==

'''Native Client''' or '''NaCl''' is the current technology used for securely virtualising the game code in the {{engine}}.

Server-side game logic NaCl support was first shipped in Alpha 27, released in April 2014. See the [https://unvanquished.net/moving-the-server-side-gamelogic-to-pnacl/ blog article by Kangz] and [https://unvanquished.net/alpha-27-flying-in-your-direction/ the release note by DSalt].

Client-side game logic NaCl support was first shipped in Alpha 37, released on March 2, 2015. See the [https://unvanquished.net/alpha-37-anniversary-edition/ release note by Kangz].

This completed the transition by porting the client VM to NaCl and this replaced entirely the legacy Quake III Q3VM system.

NaCl upstream development has slowed down since the competing solution [[WebAssembly]] became the industry standard, so it is very unlikely support for new systems and architecture would be added. To overcome this problem, we would have to switch to WebAssembly (that unfortunately may only support using a slow interpreter for some platforms NaCl supports, like i686 or armhf), but more importantly may still lack support for exceptions or {{code|setjmp/longjmp}} and then not be complete enough for our needs yet.

{{NativeClientIsDying}}

==Comparison==

{|
|+ Game VM comparison
|-
! !! Quake 3 / Tremulous !! Dæmon / Unvanquished
|-
| Technology || Q3VM || NaCl
|-
| Language || Old C (<ins>NOT</ins> Quake C) || Modern C / C++
|-
| Compiler || LCC (proprietary) || Clang (open-source)
|-
| System portability || Yes || Yes
|-
| Architecture portability || Yes || No
|-
| Secure sandbox || No || Yes
|}

With the Quake 3 engine and the Q3VM, the game code was programmed in C (it should not be confused with the scripting language of Quake 1 named QuakeC). This C code was real C was meant to be compiled with the proprietary LCC compiler, which only supported an old C, and the developer couldn't really rely on off-the-shelf libraries. That C code was compiled by LCC into {{code|.qvm}} binaries.

With the {{engine}}, the game code can be programmed in C or C++. That C/C++ code is compiled with Clang-based open source compilers supporting modern-enough C++ versions that makes possible to reuse off-the-shelf C++ libraries that may even be shared between the engine and the game source code. The C/C+ code is compiled into {{code|.nexe}} binarie.

Unlike QVMs, NaCl gamelogic runs in a secure sandbox. Native Client lets you run mods downloaded from the internet without giving them free reign on your computer. QVM was equivalent to running a DLL with no protection.

==Platform support==

{{NativeClientPlatformSupport}}

==NaCl Runtime==

See the {{naclruntime}} page for details.

==Rebuild effort==

{{NativeClientGoogleDeprecation}}

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}} being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

The project for rebuilding the {{naclruntime}} can be found there:

* {{url|github.com/DaemonEngine/native_client}}

The official releases for Unvanquished are already using the {{naclruntime}} on Linux for the {{code|amd64}} architecture, other systems are still using the Google NaCl Runtime.

The project for rebuilding the {{saigo}} can be found there:

* {{url|github.com/DaemonEngine/saigo-release-scripts}}

It's already possible to build Unvanquished with a Saigo compiler rebuilt this way.

==Compilers==

===Google PNaCl SDK===

PNaCl Clang is the current NaCl compiler we use to build the nexe game binaries. It is based on an old Clang 3.6 and does not support C++ above C++14. To overcome some of the related limitations we may switch to Saigo.

The PNaCl compilation workflow is to build a single {{code|.pexe}} then to translate them to per-architecture {{code|.nexe}} (amd64, i686, armhf) using a specific translator tool.

The PNaCl SDK consists on Python-based wrappers around Clang internals. It was initially using now-obsolete and hard-to-find Python2 but we ported it to Python3 to extend its lifespan.

The provided PNaCl SDK runs on Linux, Windows and macOS systems, on amd64 architectures.

While the {{code|.pexe}} compiler itself runs on FreeBSD with the Linuxulator, the translator does not, meaning it's not possible to build {{code|.nexe}} binaries on FreeBSD.

PNaCl supports C++ exception. There exist newer PNaCl SDKs (from chromium canary releases) that do not support exceptions and may not provide more what we already have with latest stable PNaCl.

===Dæmon Saigo SDK===

Saigo is a new NaCl compiler based on latest Clang and supporting latest C++ standards. It compiles directly to {{code|.nexe}}.

See {{saigo}} for details.

The Unvanquished game code is now buildable with Saigo.

Saigo may not support C++ exceptions as far as we know but supports {{code|setjmp/longjmp}}.

Unlike PNaCl, Saigo wasn't released by Google, meaning a switch from PNaCl to Saigo required a convenient way to provide it to contributors. Google provided some nightly Linux amd64 Saigo toolchain snapshots that aren't easy to get without some Google scripts. The Saigo compiler itself isn't hard to build (same as Clang itself), the binutils are a bit more tricky but not that hard (10 years-old configure build). What is tricky to rebuild is the libc that requires some very old NaCl GCC. Fortunately there exists libc and libc++ snapshots provided by Google that can be reused with a self-built toolchain.

The Saigo compiler and NaCl binutils can be rebuilt to run natively on many platforms (Like Clang and GNU binutils), but they will always target the usual platforms as the NaCl loader is still the same: a more recent NaCl runtime is also buildable but doesn't bring any new platform support.

Moving to Saigo is considered as a migration step that can be achievable before migrating to [[WebAssembly]], as it allows us to migrate to a new C++ standard and update libraries we use without waiting for the migration to WebAssembly.

Some redesign of our CMake configuration for Saigo may help later when migrating to WebAssembly as it makes it more generic for different VM toolchains.

Here is a GitHub issue about the ongoing efforts for migrating to Saigo:

* {{url|github.com/Unvanquished/Unvanquished/issues/3197}}

==Interactive Debugging==

Most of the time it is easiest to debug with a native DLL. But if you have a problem that cannot be reproduced outside of NaCl, you may be forced to resort to the following tutorial.

These steps for attaching the NaCl debugger<ref>https://web.archive.org/web/20250909075554/https://www.chromium.org/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/getting-started-with-debug-stub/</ref> have been tested on Windows with a PNaCl toolchain. They should also work on binaries built with Saigo, using the old PNaCl GDB. On Linux or Mac you may experience more difficulties due to the lack of support for old binaries (meaning nacl-gdb). illwieckz reports that on amd64 Linux in 2025, using the old GDB which is a 32-bit binary, debugging an amd64 nexe does not work (despite the documentation's claims of debugger platform independence), but debugging an i686 nexe does.

# Build the NaCl gamelogic with debugging symbols (build type Debug or RelWithDebInfo).
# Launch Daemon configured for NaCl debugging. For example, <code>./daemonded -set vm.sgame.type 1 -set vm.sgame.debug 1 +map chasm</code> When the relevant gamelogic starts, the engine should pause and emit the message <code>Waiting for GDB connection on localhost:4014</code>.
# Start NaCl GDB, e.g. <code>daemon\external_deps\windows-amd64-mingw_10\nacl-gdb.exe</code> This works better out of a command prompt rather than an MSYS window.
# Use the "file" command to tell the debugger where the binary with symbols is. For example, <code>file sgame-amd64.nexe</code>
# OPTIONAL, probably a waste of time: load the IRT (Integrated Runtime) symbols: <code>nacl-irt irt_core-amd64.nexe</code>
# Connect to the NaCl program with the command <code>target remote :4014</code>
# You should see a message like <code>0x000000000ffc00a0 in ?? ()</code> (or <code>0x000000000ffc00a0 in __pnacl_start ()</code> if you did step 5). This means the program is paused at the beginning.
# Set some breakpoints, e.g. <code>b G_RunFrame</code>. Alternatively, just wait for the debugger to break when the game crashes.
# Start the program by continuing (<code>c</code>).

==Postmortem Debugging==

See {{Tools|Breakpad}}.

Tools/NaCl Runtime

2026-08-05T04:29:27Z

Illwieckz:

[[Category:Tools]]{{DISPLAYTITLE:Dæmon NaCl Runtime — Modern Native Client Runtime}}
The {{naclruntime}} provides the loader to run {{nacl}} applications built with the {{saigo}}.

{{NativeClientGoogleDeprecation}}

==Status==

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}} being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

The official releases for Unvanquished are already using the {{naclruntime}} on Linux for the {{code|amd64}} architecture, other systems are still using the Google NaCl Runtime.

==Sources==

The project for rebuilding the {{naclruntime}} can be found there:

* {{url|github.com/DaemonEngine/native_client}}

==Platform support==

{{NativeClientPlatformSupport}}

It has been verified that Linux on {{code|arm64}}, {{code|ppc64el}} and {{code|riscv64}} can run the {{code|amd64}} loader on [https://box86.org Box64], though on {{code|riscv64}} it is very slow. The '''Box64''' translation layer can also run on {{code|loong64}} but this has not been tested yet. The {{engine}} received patches to run Box64, but the user has to build the engine themselves and provides Box64. This is work-in-progress. Box64 integration is still work in progress (at some point we may ship Box64 with engines that can use it).

The NaCl loader (the virtual machine running the virtualised code) is available for three systems: Linux, Windows and macOS. The supported architectures differs per system:

* Linux: amd64, i686, armhf;
* Windows: amd64, i686;
* macOS: amd64.

It is possible to run native engines with other platforms when there is a compatibility layer to run the NaCl loader:

* Linux, arm64: running the armhf NaCl loader through built-in Linux Multiarch compatibility;
* macOS, arm64: running the amd64 NaCl loader through Rosetta2 compatibility;
* FreeBSD, amd64: running the Linux NaCl loader through built-in Linuxulator compatibility.

We provide the Multiarch libraries for running the armhf game on Linux arm64, no system modification is required on that part.

The Linux armhf NaCl loader requires a 4k PageSize kernel, this may require a system modification:

* {{url|github.com/Unvanquished/Unvanquished/issues/3286}}

There is work in progress to remove this restriction.

The Linux i686 and armhf NaCl loaders may run on FreeBSD using Linuxulator but it is not tested.

NaCl also supportrf 32-bit MIPS on Linux but this architecture is not supported by the {{engine}} and the {{game}} project, and is not supported by the {{saigo}}.

Template:Breakpad

2026-08-05T04:29:06Z

Illwieckz:

'''{{#ifeq: {{{link|}}}|no|Dæmon Breakpad|[[Tools/Breakpad|Dæmon Breakpad]]}}'''

Native Client

2026-08-05T04:28:27Z

Illwieckz:

{{DISPLAYTITLE:Native Client — Secure Native Code Sandbox Technology}}
Native Client (also known as NaCl) is a sandboxing technology by Google. It was used by Chrome extensions and Chrome apps. The {{engine}} uses Native Client to securely and portably run downloadable compiled games. It replaced the Q3VM (Quake 3 Virtual Machine) in the engine.

The Native Client documentation can be found on [https://chrome.jscn.org/docs/native-client/welcome-to-native-client/ chrome.jscn.org/docs/native-client/welcome-to-native-client/].

The NaCl support consists of:

* {{naclruntime}} — a modern Native Client runtime;
* {{saigo}} — a modern toolchain for Native Client;
* {{breakpad}} — an enhanced breakpad crash reporting library.

==Status==

'''Native Client''' or '''NaCl''' is the current technology used for securely virtualising the game code in the {{engine}}.

Server-side game logic NaCl support was first shipped in Alpha 27, released in April 2014. See the [https://unvanquished.net/moving-the-server-side-gamelogic-to-pnacl/ blog article by Kangz] and [https://unvanquished.net/alpha-27-flying-in-your-direction/ the release note by DSalt].

Client-side game logic NaCl support was first shipped in Alpha 37, released on March 2, 2015. See the [https://unvanquished.net/alpha-37-anniversary-edition/ release note by Kangz].

This completed the transition by porting the client VM to NaCl and this replaced entirely the legacy Quake III Q3VM system.

NaCl upstream development has slowed down since the competing solution [[WebAssembly]] became the industry standard, so it is very unlikely support for new systems and architecture would be added. To overcome this problem, we would have to switch to WebAssembly (that unfortunately may only support using a slow interpreter for some platforms NaCl supports, like i686 or armhf), but more importantly may still lack support for exceptions or {{code|setjmp/longjmp}} and then not be complete enough for our needs yet.

{{NativeClientIsDying}}

==Comparison==

{|
|+ Game VM comparison
|-
! !! Quake 3 / Tremulous !! Dæmon / Unvanquished
|-
| Technology || Q3VM || NaCl
|-
| Language || Old C (<ins>NOT</ins> Quake C) || Modern C / C++
|-
| Compiler || LCC (proprietary) || Clang (open-source)
|-
| System portability || Yes || Yes
|-
| Architecture portability || Yes || No
|-
| Secure sandbox || No || Yes
|}

With the Quake 3 engine and the Q3VM, the game code was programmed in C (it should not be confused with the scripting language of Quake 1 named QuakeC). This C code was real C was meant to be compiled with the proprietary LCC compiler, which only supported an old C, and the developer couldn't really rely on off-the-shelf libraries. That C code was compiled by LCC into {{code|.qvm}} binaries.

With the {{engine}}, the game code can be programmed in C or C++. That C/C++ code is compiled with Clang-based open source compilers supporting modern-enough C++ versions that makes possible to reuse off-the-shelf C++ libraries that may even be shared between the engine and the game source code. The C/C+ code is compiled into {{code|.nexe}} binarie.

Unlike QVMs, NaCl gamelogic runs in a secure sandbox. Native Client lets you run mods downloaded from the internet without giving them free reign on your computer. QVM was equivalent to running a DLL with no protection.

==Platform support==

{{NativeClientPlatformSupport}}

==NaCl Runtime==

See the {{naclruntime}} page for details.

==Rebuild effort==

{{NativeClientGoogleDeprecation}}

The Unvanquished team is working on rebuilding the {{nacl}} ecosystem to benefit from the updates implemented by Google over the years. This enables newer C and C++ versions, thanks to the Saigo compiler (from the {{saigo}} being based on Clang 21. It also makes sure everyone can rebuild the runtime and the toolchain.

The project for rebuilding the {{naclruntime}} can be found there:

* {{url|github.com/DaemonEngine/native_client}}

The official releases for Unvanquished are already using the {{naclruntime}} on Linux for the {{code|amd64}} architecture, other systems are still using the Google NaCl Runtime.

The project for rebuilding the {{saigo}} can be found there:

* {{url|github.com/DaemonEngine/saigo-release-scripts}}

It's already possible to build Unvanquished with a Saigo compiler rebuilt this way.

==Compilers==

===Google PNaCl SDK===

PNaCl Clang is the current NaCl compiler we use to build the nexe game binaries. It is based on an old Clang 3.6 and does not support C++ above C++14. To overcome some of the related limitations we may switch to Saigo.

The PNaCl compilation workflow is to build a single {{code|.pexe}} then to translate them to per-architecture {{code|.nexe}} (amd64, i686, armhf) using a specific translator tool.

The PNaCl SDK consists on Python-based wrappers around Clang internals. It was initially using now-obsolete and hard-to-find Python2 but we ported it to Python3 to extend its lifespan.

The provided PNaCl SDK runs on Linux, Windows and macOS systems, on amd64 architectures.

While the {{code|.pexe}} compiler itself runs on FreeBSD with the Linuxulator, the translator does not, meaning it's not possible to build {{code|.nexe}} binaries on FreeBSD.

PNaCl supports C++ exception. There exist newer PNaCl SDKs (from chromium canary releases) that do not support exceptions and may not provide more what we already have with latest stable PNaCl.

===Dæmon Saigo SDK===

Saigo is a new NaCl compiler based on latest Clang and supporting latest C++ standards. It compiles directly to {{code|.nexe}}.

See {{saigo}} for details.

The Unvanquished game code is now buildable with Saigo.

Saigo may not support C++ exceptions as far as we know but supports {{code|setjmp/longjmp}}.

Unlike PNaCl, Saigo wasn't released by Google, meaning a switch from PNaCl to Saigo required a convenient way to provide it to contributors. Google provided some nightly Linux amd64 Saigo toolchain snapshots that aren't easy to get without some Google scripts. The Saigo compiler itself isn't hard to build (same as Clang itself), the binutils are a bit more tricky but not that hard (10 years-old configure build). What is tricky to rebuild is the libc that requires some very old NaCl GCC. Fortunately there exists libc and libc++ snapshots provided by Google that can be reused with a self-built toolchain.

The Saigo compiler and NaCl binutils can be rebuilt to run natively on many platforms (Like Clang and GNU binutils), but they will always target the usual platforms as the NaCl loader is still the same: a more recent NaCl runtime is also buildable but doesn't bring any new platform support.

Moving to Saigo is considered as a migration step that can be achievable before migrating to [[WebAssembly]], as it allows us to migrate to a new C++ standard and update libraries we use without waiting for the migration to WebAssembly.

Some redesign of our CMake configuration for Saigo may help later when migrating to WebAssembly as it makes it more generic for different VM toolchains.

Here is a GitHub issue about the ongoing efforts for migrating to Saigo:

* {{url|github.com/Unvanquished/Unvanquished/issues/3197}}

==Interactive Debugging==

Most of the time it is easiest to debug with a native DLL. But if you have a problem that cannot be reproduced outside of NaCl, you may be forced to resort to the following tutorial.

These steps for attaching the NaCl debugger<ref>https://web.archive.org/web/20250909075554/https://www.chromium.org/nativeclient/how-tos/debugging-documentation/debugging-with-debug-stub-recommended/getting-started-with-debug-stub/</ref> have been tested on Windows with a PNaCl toolchain. They should also work on binaries built with Saigo, using the old PNaCl GDB. On Linux or Mac you may experience more difficulties due to the lack of support for old binaries (meaning nacl-gdb). illwieckz reports that on amd64 Linux in 2025, using the old GDB which is a 32-bit binary, debugging an amd64 nexe does not work (despite the documentation's claims of debugger platform independence), but debugging an i686 nexe does.

# Build the NaCl gamelogic with debugging symbols (build type Debug or RelWithDebInfo).
# Launch Daemon configured for NaCl debugging. For example, <code>./daemonded -set vm.sgame.type 1 -set vm.sgame.debug 1 +map chasm</code> When the relevant gamelogic starts, the engine should pause and emit the message <code>Waiting for GDB connection on localhost:4014</code>.
# Start NaCl GDB, e.g. <code>daemon\external_deps\windows-amd64-mingw_10\nacl-gdb.exe</code> This works better out of a command prompt rather than an MSYS window.
# Use the "file" command to tell the debugger where the binary with symbols is. For example, <code>file sgame-amd64.nexe</code>
# OPTIONAL, probably a waste of time: load the IRT (Integrated Runtime) symbols: <code>nacl-irt irt_core-amd64.nexe</code>
# Connect to the NaCl program with the command <code>target remote :4014</code>
# You should see a message like <code>0x000000000ffc00a0 in ?? ()</code> (or <code>0x000000000ffc00a0 in __pnacl_start ()</code> if you did step 5). This means the program is paused at the beginning.
# Set some breakpoints, e.g. <code>b G_RunFrame</code>. Alternatively, just wait for the debugger to break when the game crashes.
# Start the program by continuing (<code>c</code>).

==Postmortem Debugging==

See {{Tools|Breakpad}}.