Unvanquished - User contributions [en-gb]

MacOS Launch Services security restrictions

2026-03-07T07:25:17Z

Killing time: menu option to bypass quarantine removed

== Quarantine restrictions ==
Applications downloaded with a browser may are subject to quarantine restrictions.

=== Denying launch ===
If you double-click a quarantined app in Finder, it will refuse to run it. <s>This can be bypassed via Command+clicking on the application, selecting <b>Open</b> in the context menu, and clicking through a warning dialog.</s> In recent OS versions, there is no user-friendly way to bypass quarantine.<ref>https://developer.apple.com/news/?id=saqachfa</ref> Instead see the file attribute discussion below.

Not only applications, but also libraries can be denied launch. Sample text of an error popup:
<blockquote>
“SDL2.framework” cannot be opened because the developer cannot be verified.

macOS cannot verify that this app is free from malware.

Safari downloaded this file today at 06:18.
</blockquote>

In the terminal, the error looks as follows:
<pre>% ./daemon
dyld[8822]: Library not loaded: @rpath/SDL2.framework/Versions/A/SDL2
Referenced from: <71DD614C-D95F-37DD-A29E-765DA0AEEE48> /Users/slipher/Unvanquished/build-newsdl/daemon
Reason: tried: '/Users/slipher/Unvanquished/build-newsdl/SDL2.framework/Versions/A/SDL2' (code signature in <3E6D5145-6DE8-3734-95A7-AE31ED09A1A9> '/Users/slipher/Unvanquished/build-newsdl/SDL2.framework/Versions/A/SDL2' not valid for use in process: library load disallowed by system policy), '/Users/slipher/Unvanquished/build-newsdl/SDL2.framework/Versions/A/SDL2' (code signature in <3E6D5145-6DE8-3734-95A7-AE31ED09A1A9> '/Users/slipher/Unvanquished/build-newsdl/SDL2.framework/Versions/A/SDL2' not valid for use in process: library load disallowed by system policy), '/Library/Frameworks/SDL2.framework/Versions/A/SDL2' (no such file), '/System/Library/Frameworks/SDL2.framework/Versions/A/SDL2' (no such file, not in dyld cache)
zsh: abort ./daemon</pre>

=== App Translocation ===

For quarantined apps that are permitted to launch, there is another possible restriction called [https://lapcatsoftware.com/articles/app-translocation.html App Translocation].
If Unvanquished.app is started with app translocation, the beginning of the output looks as follows:
<pre>cmdline: -pakpath /private/var/folders/37/cwhvzf2j3_ngll0kwst_3k540000gn/T/AppTranslocation/97281FCC-20CC-45CE-8386-D8DF691593C7/d/pkg
tty console mode disabled
^3Warn: [FS] Ignoring path /private/var/folders/37/cwhvzf2j3_ngll0kwst_3k540000gn/T/AppTranslocation/97281FCC-20CC-45CE-8386-D8DF691593C7/d/pkg: No such file or directory
[FS] Lib path: /private/var/folders/37/cwhvzf2j3_ngll0kwst_3k540000gn/T/AppTranslocation/97281FCC-20CC-45CE-8386-D8DF691593C7/d/Unvanquished.app/Contents/MacOS
[FS] Home path: /Users/slipher/Library/Application Support/Unvanquished
[FS] Pak search path: /Users/slipher/Library/Application Support/Unvanquished/pkg</pre>

Daemon is not capable of running under app translocation.

=== The magic bits ===

The <code>com.apple.quarantine</code> extended file attribute is the root cause of all quarantine restrictions. It is added by browsers to downloaded applications. When you download an auto-unzipped .app, it is recursively applied to all files and directories within. A file's extended attributes can be viewed with the command<code>xattr <path></code>. The quarantine attribute can be (recursively) removed using <code>xattr -d -r <path></code>.

There is a launch services database flag that prevents denying launch even in the presence of the quarantine attribute. <s>It can be set by clicking through the dialog to launch despite the danger, or by moving the application in Finder.</s>

There is a launch services database flag that disables app translocation for a quarantined file that is allowed to launch. <s>It can be set by moving the application in the Finder.</s>

Launch services database info follows files across moves (whether by Finder or <code>mv</code>). It might be possible to see these launch services database flags somewhere in the output of <code>/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -dump</code>.

== Directory permissions ==

Sometimes you get a popup asking whether you want to allow the app to access, for example, Downloads or Documents. Example message: <b>"Unvanquished" would like to access files in your Downloads folder.</b> The application's file operation blocks while waiting for the user to respond to the dialog. Not sure what relation this has to quarantine restrictions.

<references />

Bug reporting

2026-01-26T17:10:33Z

Killing time: Actually remove UnvanquishedAssets

Please file any bugs you find on GitHub issue tracker.

{{note|content=<p>We have multiple issue trackers but don't worry if you don't know which one is the best for your specific need.</p><p>In doubt, report the bug on [https://github.com/Unvanquished/Unvanquished/issues github.com/Unvanquished/Unvanquished/issues].</p><p>
We can recreate more specific tickets in specific issue trackers and reword them once we know more about your problem.</p>}}

Before filing a bug report, please check the [[Troubleshooting]] page, browse the [https://forums.unvanquished.net/viewforum.php?f=6 support forums], and search the [https://github.com/Unvanquished/Unvanquished/issues default issue tracker] to see if your issue has been noticed or reported before.

Some of the tips on the [[Testing]] page may be useful to produce good reports.

==Issue trackers==

There are separate issue trackers for separate parts of the game and the project:

* '''Game''' (ℹ️ If in doubt, use this one):<br/>[https://github.com/Unvanquished/Unvanquished/issues github.com/Unvanquished/Unvanquished/issues]<br/>
* '''Official maps''':<br/>[https://github.com/UnvanquishedAssets/map-antares_src.dpkdir/issues Antares] [https://github.com/UnvanquishedAssets/map-chasm_src.dpkdir/issues Chasm] [https://github.com/UnvanquishedAssets/map-forlorn_src.dpkdir/issues Forlorn] [https://github.com/UnvanquishedAssets/map-parpax_src.dpkdir/issues Parpax] [https://github.com/UnvanquishedAssets/map-perseus_src.dpkdir/issues Perseus] [https://github.com/UnvanquishedAssets/map-plat23_src.dpkdir/issues Platform 23] [https://github.com/UnvanquishedAssets/map-spacetracks_src.dpkdir/issues Spacetracks] [https://github.com/UnvanquishedAssets/map-station15_src.dpkdir/issues Station 15] [https://github.com/UnvanquishedAssets/map-thunder_src.dpkdir/issues Thunder] [https://github.com/UnvanquishedAssets/map-vega_src.dpkdir/issues Vega] [https://github.com/UnvanquishedAssets/map-yocto_src.dpkdir/issues Yocto]
* '''Engine''' (rendering bugs…):<br/>[https://github.com/DaemonEngine/Daemon/issues github.com/DaemonEngine/Daemon/issues]
* '''Updater/launcher''':<br/>[https://github.com/Unvanquished/updater/issues github.com/Unvanquished/updater/issues]
* '''Master server''':<br/>[https://github.com/Unvanquished/unvanquished-master/issues github.com/Unvanquished/unvanquished-master/issues]
* '''Website''':<br/>[https://github.com/Unvanquished/unvanquished-infrastructure/issues github.com/Unvanquished/unvanquished-infrastructure/issues]

==Reporting issues==

Please try to do the following when writing a bug report:

* Describe the problem in detail. Carefully note what actually happens and what you expected to happen.
* Describe how to reproduce the problem: i.e., steps that the developers can follow to cause it to happen.
* Do not post console logs or error messages without any other accompanying explanation with the expectation that the developers will solve your problem for you; you must provide details!
* If the problem is best explained with a picture or video, please, take a [[Taking_screenshots|screenshot]] and/or [[Recording_demos|record a demo]]!

Please include hardware / software specs when you report your bug. Use the following template:

<pre>
### Hardware / Software

| Release |
|:--|:--
| Operating System |
| Video Card |
| Driver Type |
| Driver Version |
| OpenGL Version |
| Map tested |
</pre>

If you are on Linux, please also include fields for your kernel version (which you can obtain from <code>uname</code>) and driver type (i.e., proprietary or open source).

For example, your information might look like this:

<pre>
### Hardware / Software

| Release | v0.13.0
|:--|:--
| Operating System | Ubuntu 12.04 LTS
| Kernel Version | 3.2.0-38-generic
| Video Card | ATI Radeon HD 5670
| Driver Type | Proprietary (fglrx)
| Driver Version | 8.85-110419a118915C-ATI (Catalyst 11.5)
| OpenGL Version | 4.2.11903 Compatibility Profile
| Map tested | Star A.T.C.S.
</pre>

which will produce a table like so:

{| class="wikitable"
|-
! style="text-align:left;" | Release !! style="text-align:left;" | v0.13.0
|-
| Operating System || Ubuntu 12.04 LTS
|-
| Kernel Version || 3.2.0-38-generic
|-
| Video Card || ATI Radeon HD 5670
|-
| Driver Type || Proprietary (fglrx)
|-
| Driver Version || 8.85-110419a118915C-ATI (Catalyst 11.5)
|-
| OpenGL Version || 4.2.11903 Compatibility Profile
|-
| Map tested || Star A.T.C.S.
|-
|}

==Do's and Don'ts==

{{Note|content=Above all, try to make your report as concise as possible while still including all the necessary information!}}

* '''Do''' include the requested information listed above.
* '''Do''' describe the issue with the bug title. A title of just "Console", for example, does nothing to describe the issue at hand and, as such, makes the issue more difficult to return to for developers, as well as for developers to gauge the impact of the issue. Issues with titles such as "Opening the menu '''causes the game to crash'''" will be more likely to be read by a developer than the same issue titled "Menu bug", for example.
* '''Do not''' refer to forum posts or similar anecdotally without providing a link.
* '''Do not''' include extraneous information.
* '''Do''' check to ensure that your grammar and spelling is correct.
* '''Do''' use Markdown headers (begin a line with some number of pound signs, e.g., <code>###</code>) to delineate sections of your report.

==Formatting Tips & Tricks==

===Code Blocks===

To delineate a block of code (and enable special formatting such as syntax highlighting), begin and end the code block with three backticks (`):

```
/* code */
```

This makes reports with console output much easier to read and makes it unnecessary to rely on outside paste services.

To enable syntax highlighting, you must specify a language following the first set of backticks:

```c++
/* code */
```

The following language keywords are known to work:

* <code>diff</code>
* <code>javascript</code>
* <code>c</code>
* <code>c++</code>
* <code>python</code>

Bug reporting

2026-01-26T17:08:32Z

Killing time: /* Issue trackers */ don't encourage UnvanquishedAssets/issues; add maps

Please file any bugs you find on GitHub issue tracker.

{{note|content=<p>We have multiple issue trackers but don't worry if you don't know which one is the best for your specific need.</p><p>In doubt, report the bug on [https://github.com/Unvanquished/Unvanquished/issues github.com/Unvanquished/Unvanquished/issues].</p><p>
We can recreate more specific tickets in specific issue trackers and reword them once we know more about your problem.</p>}}

Before filing a bug report, please check the [[Troubleshooting]] page, browse the [https://forums.unvanquished.net/viewforum.php?f=6 support forums], and search the [https://github.com/Unvanquished/Unvanquished/issues default issue tracker] to see if your issue has been noticed or reported before.

Some of the tips on the [[Testing]] page may be useful to produce good reports.

==Issue trackers==

There are separate issue trackers for separate parts of the game and the project:

* '''Game''' (ℹ️ If in doubt, use this one):<br/>[https://github.com/Unvanquished/Unvanquished/issues github.com/Unvanquished/Unvanquished/issues]<br/>
* '''Game data''' (map, texture, models, sound file…):<br/>[https://github.com/UnvanquishedAssets/UnvanquishedAssets/issues github.com/UnvanquishedAssets/UnvanquishedAssets/issues]
* '''Official maps''':<br/>[https://github.com/UnvanquishedAssets/map-antares_src.dpkdir/issues Antares] [https://github.com/UnvanquishedAssets/map-chasm_src.dpkdir/issues Chasm] [https://github.com/UnvanquishedAssets/map-forlorn_src.dpkdir/issues Forlorn] [https://github.com/UnvanquishedAssets/map-parpax_src.dpkdir/issues Parpax] [https://github.com/UnvanquishedAssets/map-perseus_src.dpkdir/issues Perseus] [https://github.com/UnvanquishedAssets/map-plat23_src.dpkdir/issues Platform 23] [https://github.com/UnvanquishedAssets/map-spacetracks_src.dpkdir/issues Spacetracks] [https://github.com/UnvanquishedAssets/map-station15_src.dpkdir/issues Station 15] [https://github.com/UnvanquishedAssets/map-thunder_src.dpkdir/issues Thunder] [https://github.com/UnvanquishedAssets/map-vega_src.dpkdir/issues Vega] [https://github.com/UnvanquishedAssets/map-yocto_src.dpkdir/issues Yocto]
* '''Engine''' (rendering bugs…):<br/>[https://github.com/DaemonEngine/Daemon/issues github.com/DaemonEngine/Daemon/issues]
* '''Updater/launcher''':<br/>[https://github.com/Unvanquished/updater/issues github.com/Unvanquished/updater/issues]
* '''Master server''':<br/>[https://github.com/Unvanquished/unvanquished-master/issues github.com/Unvanquished/unvanquished-master/issues]
* '''Website''':<br/>[https://github.com/Unvanquished/unvanquished-infrastructure/issues github.com/Unvanquished/unvanquished-infrastructure/issues]

==Reporting issues==

Please try to do the following when writing a bug report:

* Describe the problem in detail. Carefully note what actually happens and what you expected to happen.
* Describe how to reproduce the problem: i.e., steps that the developers can follow to cause it to happen.
* Do not post console logs or error messages without any other accompanying explanation with the expectation that the developers will solve your problem for you; you must provide details!
* If the problem is best explained with a picture or video, please, take a [[Taking_screenshots|screenshot]] and/or [[Recording_demos|record a demo]]!

Please include hardware / software specs when you report your bug. Use the following template:

<pre>
### Hardware / Software

| Release |
|:--|:--
| Operating System |
| Video Card |
| Driver Type |
| Driver Version |
| OpenGL Version |
| Map tested |
</pre>

If you are on Linux, please also include fields for your kernel version (which you can obtain from <code>uname</code>) and driver type (i.e., proprietary or open source).

For example, your information might look like this:

<pre>
### Hardware / Software

| Release | v0.13.0
|:--|:--
| Operating System | Ubuntu 12.04 LTS
| Kernel Version | 3.2.0-38-generic
| Video Card | ATI Radeon HD 5670
| Driver Type | Proprietary (fglrx)
| Driver Version | 8.85-110419a118915C-ATI (Catalyst 11.5)
| OpenGL Version | 4.2.11903 Compatibility Profile
| Map tested | Star A.T.C.S.
</pre>

which will produce a table like so:

{| class="wikitable"
|-
! style="text-align:left;" | Release !! style="text-align:left;" | v0.13.0
|-
| Operating System || Ubuntu 12.04 LTS
|-
| Kernel Version || 3.2.0-38-generic
|-
| Video Card || ATI Radeon HD 5670
|-
| Driver Type || Proprietary (fglrx)
|-
| Driver Version || 8.85-110419a118915C-ATI (Catalyst 11.5)
|-
| OpenGL Version || 4.2.11903 Compatibility Profile
|-
| Map tested || Star A.T.C.S.
|-
|}

==Do's and Don'ts==

{{Note|content=Above all, try to make your report as concise as possible while still including all the necessary information!}}

* '''Do''' include the requested information listed above.
* '''Do''' describe the issue with the bug title. A title of just "Console", for example, does nothing to describe the issue at hand and, as such, makes the issue more difficult to return to for developers, as well as for developers to gauge the impact of the issue. Issues with titles such as "Opening the menu '''causes the game to crash'''" will be more likely to be read by a developer than the same issue titled "Menu bug", for example.
* '''Do not''' refer to forum posts or similar anecdotally without providing a link.
* '''Do not''' include extraneous information.
* '''Do''' check to ensure that your grammar and spelling is correct.
* '''Do''' use Markdown headers (begin a line with some number of pound signs, e.g., <code>###</code>) to delineate sections of your report.

==Formatting Tips & Tricks==

===Code Blocks===

To delineate a block of code (and enable special formatting such as syntax highlighting), begin and end the code block with three backticks (`):

```
/* code */
```

This makes reports with console output much easier to read and makes it unnecessary to rely on outside paste services.

To enable syntax highlighting, you must specify a language following the first set of backticks:

```c++
/* code */
```

The following language keywords are known to work:

* <code>diff</code>
* <code>javascript</code>
* <code>c</code>
* <code>c++</code>
* <code>python</code>

Main Page

2026-01-26T16:52:03Z

Killing time: typo

{{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#Channel_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|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|Stories]]
* [[Maps]] and [[Mods]]

</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> [[Projects|Tools and projects]] </h2>

* [[Wiki project resources]]
* [[Infrastructure]]
* [[Tools]]
* [[Projects#Unvanquished on the web|Unvanquished on the web]]

</div>

<div class="mainPageNewBox">

<h2> [[Install and play#Getting in contact|Getting in contact]] </h2>

* [[Chat]]
* [//forums.unvanquished.net Forums]
* [[Projects#Unvanquished on the 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__

Formats/Skin

2026-01-17T20:50:11Z

Killing time: /* Usage in Unvanquished */ fix link

A skin is used to display a [[Formats/Model|model]] with different textures than it was originally loaded with. Skin files conventionally have the suffix <code>.skin</code>.

== Usage in Unvanquished ==

Skins are used with [https://github.com/UnvanquishedAssets/res-players_src.dpkdir/tree/master/models/players/ human player models] to swap armors or add the helmet.

== Minimal .skin example ==
foo,<texture name>

For a model that has only a single texture, this skin file can be used to replace it with a different one. <code>foo</code> is an arbitrary word that has no effect. <code><texture name></code> should be replaced with the name of the desired [[Formats/Material|Q3 shader]] or an image path.

== Source code keywords ==
* Engine: <code>skin_t</code>
* Gamelogic: <code>trap_R_RegisterSkin</code>
* Both: <code>customSkin</code> (<code>refEntity_t</code> member)

Main Page

2025-10-13T23:44:45Z

Killing time: Linux packages link

{{DISPLAYTITLE:Unvanquished wiki}}
* If you need help about the game or the wiki, jump on [https://unvanquished.net/chat/ IRC or Matrix or Discord] (ses [[Chat#Channel_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|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|Stories]]
* [[Maps]] and [[Mods]]

</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> [[Projects|Tools and projects]] </h2>

* [[Wiki project resources]]
* [[Infrastructure]]
* [[Tools]]
* [[Projects#Unvanquished on the web|Unvanquished on the web]]

</div>

<div class="mainPageNewBox">

<h2> [[Install and play#Getting in contact|Getting in contact]] </h2>

* [[Chat]]
* [//forums.unvanquished.net Forums]
* [[Projects#Unvanquished on the 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__

Linux packages

2025-10-13T22:02:59Z

Killing time: Created page with "Besides the launcher and universal zip, Unvanquished distributions can also be found in some Linux package managers. These are not officially supported by the Unvanquished pro..."

Besides the launcher and universal zip, Unvanquished distributions can also be found in some Linux package managers. These are not officially supported by the Unvanquished project.

== Unvanquished update policy ==

The Unvanquished norm is that all players and server owners need to update at the same time when a new major version comes out (e.g. 0.54.x -> 0.55.0). Differing major versions are incompatible. So when using one of the packages below, you should double-check that it is up to date with the official release distributed by the [[launcher]].

== Packages ==

{| class="wikitable"
|-
! System !! Package Name !! Package Manager !! Script !! Maintainer
|-
| Arch Linux || <code>unvanquished</code> || [https://aur.archlinux.org/packages/unvanquished AUR] || [https://aur.archlinux.org/cgit/aur.git/tree/PKGBUILD?h=unvanquished source] || Viech
|-
| Flatpak || <code>net.unvanquished.Unvanquished</code> || [https://flathub.org/en/apps/net.unvanquished.Unvanquished Flathub] || [https://github.com/flathub/net.unvanquished.Unvanquished/blob/master/net.unvanquished.Unvanquished.yml source] || afontain, illwieckz
|-
| NixOS || <code>unvanquished</code> || [https://mynixos.com/nixpkgs/package/unvanquished Nix] || [https://github.com/NixOS/nixpkgs/blob/master/pkgs/by-name/un/unvanquished/package.nix source] || afontain
|}

== Packaging tips ==
* Due to the update policy, Unvanquished may not be suitable for package ecosystems such as Debian's where version stability is expected.
* Any .dpk file must be copied from the official release rather than built, because its hash must match when playing online.
* If you look at the universal zip, <code>pkg/*.dpk</code> plus the contents of the platform-specific zip, minus possibly <code>crash_server</code>, is the bare minimum for a usable install.
* Other nice-to-have bits are a desktop file, and server scripts from [https://github.com/Unvanquished/Unvanquished/tree/master/dist <code>dist/</code>].
* Supported architectures for Unvanquished are <code>amd64</code> (x86-64), <code>i686</code> (x86), <code>armhf</code> (32-bit ARM with hard float), and <code>arm64</code>.
* If downloads are discouraged/forbidden by the package system, you will need to bundle the NaCl runtime dependencies in the package.
* Besides the NaCl runtime and Unvanquished gamelogic, you probably want to avoid using pre-built binaries. Pass <code>-DUSE_EXTERNAL_DEPS_LIBS=0</code> to CMake to avoid this.

Formats/IQM

2025-05-28T23:33:14Z

Killing time: /* Specification */ fix outdated IQE spec

[[Category:Formats]]
[[Category:IQM]]
==Tools==

See [[Tools/IQM]].

==Inter-Quake Model==

{{Note|content='''IQM''' is the recommended model and animation format for the [[Engine|Dæmon engine]] and the [https://unvanquished.net Unvanquished game].}}

===Bone-based model and skeletal animation format===

The [http://sauerbraten.org/iqm/ Inter-Quake Model] (IQM) format was developed by Lee Salzman (aka eihrul) as a more modern alternative to the formats popularly used in the open-source community prior to its introduction.

The <code>.iqm</code> files are binary files.

The <code>.iqe</code> files are text counterpart. Unvanquished stores <code>.iqe</code> files in asset source repositories and ships <code>.iqm</code> files in <code>.dpk</code> archives.

Both IQM and IQE files can embed models with bones and skeletal animations.

===Adoption===

IQM format is popular in free open source games, mods and free open source game engines like Cube 2: Sauerbraten, Red Eclipse/Blue Nebula, Xonotic (DarkPlaces), Alien Arena, Warsow/Warfork (QFusion), Unvanquished (Dæmon), Ya3dag, FTEQW, ioquake3, and others. It became a de-facto standard for such free open source gaming projects.

IQM format is fully supported in Unvanquished workflow : in engine, asset build tools, level editor, map compiler, etc.

===Advantages of IQM over MD5===

MD5 format (<code>.md5mesh</code>/<code>.md5anim</code>) was the skeletal model and animation format used by Doom 3, which is also supported by the [[Engine|Dæmon Engine]] alongside IQM (MD5 was implemented first in XreaL, then IQM was implemented in Dæmon).

We recommend using IQM when possible. Advantages of IQM over MD5 are:

* Triangle adjacency data;
* Non-uniform joint scaling;
* Variable vertex attributes:
** Position (equivalent to MD2 and MD3 style of animation);
** Texture coordinates;
** Normals;
** Tangents;
** Weights;
** Colors;
* Animation and model files may be combined (if desired);
* A binary (“compiled”) format is available (no text parsing at run time).

===Specification===

* IQM Homepage:<br/>http://sauerbraten.org/iqm/
* IQM Binary format specification:<br/>http://sauerbraten.org/iqm/iqm.txt
* IQE Plain-text format specification:<br/>https://github.com/lsalzman/iqm/blob/master/iqe.txt
* IQM development kit and reference implementation by Lee Salzman:<br/>https://github.com/lsalzman/iqm

===Recommended tool===

The recommended tool to convert models to IQM format is [[Tools/Iqmtool|Iqmtool]].

===Implementation===

{{Note|content=The {{engine}} loads binary IQM format, the text-based IQE format is used in [[UnvanquishedAssets]] source repositories.}}

Dæmon developer gimhael [https://bugzilla.icculus.org/attachment.cgi?id=2673&action=diff submitted a patch] in 2011 to the [https://bugzilla.icculus.org/show_bug.cgi?id=4965 ioquake3 bug tracker]. Later in 2013, gimhael also [https://github.com/DaemonEngine/Daemon/commit/8b9a672024e97a793cea9f661c44a7b096936537 implemented] IQM in {{engine|link=no}} as well.

MinGW

2025-04-20T02:26:12Z

Killing time: /* Installation */ Note that Debian packages changed exception flavor

MinGW is a GCC-based compiler toolchain targeting Windows platforms. It is used to produce the Windows releases of Unvanquished. It can be quite complicated to use successfully, in part due to the existence of different compiler "flavors", and confusing naming schemes. This page serves as a guide to both MinGW in general, and specifically in application to building Daemon and Unvanquished. Throughout this page, "MinGW" will be used to refer to the [http://mingw-w64.org/ mingw-w64] project, which is a fork of the (now long-moribund) "original MinGW" project aiming to support both 32- and 64-bit builds. So beware: something having "64" in its name does not at all imply it is for 64-bit binaries! Same goes for "32".

== Flavors ==

=== Bitness: 32-bit or 64-bit ===

Whether to compile for 32-bit ("i686" in package names) or 64-bit ("x86-64" or "x86_64") architecture. 64-bit Windows versions are capable of running 32-bit executables in a mode called WOW (Windows-on-Windows).

=== Threading flavor ===
You can get <code>win32</code>, <code>posix</code> or <code>mcf</code> thread models. Daemon must be built with the <code>posix</code> flavor, because code that uses <code>std::thread</code> does not compile with either of the other flavors. In general there is no reason to use <code>win32</code>. However, it is unfortunately the default in the APT package manager. <code>mcf</code> first appears in the MinGW-W64-builds installer for version 13.2.0. It is supposed to have improved performance, but requires use of the nonstandard [https://gcc.gnu.org/onlinedocs/libstdc++/manual/ext_concurrency_impl.html gthread] interface.

=== Exception handling flavor ===

* <code>sjlj</code> (setjmp/longjmp) is available for both 32- and 64-bit builds. It has the drawback of significant runtime cost.
* <code>dwarf</code> is available only for 32-bit. It has good performance, but it is said to have a drawback that exceptions can't be propagated through code compiled with a different compiler (or C code?). However, propagating exceptions through C code shouldn't be needed for Daemon.
* <code>seh</code> (Structured Exception Handling) is available only for 64-bit. It has good performance and always works correctly, so it should always be used for 64-bit.

One way to identify which exception model code was built with is to check the libgcc dependency. You'll find for example <code>libgcc_s_seh-1.dll</code> for SEH, <code>libgcc_s_dw2-1.dll</code> for DWARF, or <code>libgcc_s_sjlj-1.dll</code> for sjlj. An easy way to make a C++ test program emit a libgcc dependency is to add a try/catch block.

=== Microsoft C runtime target ===

You can choose which one of the C stdlib/runtime implementations that come with Windows to dynamically link against.
* <code>msvcrt</code> is the traditional one.
* <code>ucrt</code> is first available in the MinGW-W64-builds installer for version 12.2.0. The [https://learn.microsoft.com/en-us/cpp/porting/upgrade-your-code-to-the-universal-crt UCRT] is only available in Windows 10 or higher.

For now, you can assume that everything uses <code>msvcrt</code> for the rest of the article.

=== Mixing flavors ===

Mixing different thread or exception flavors can cause problems, such as missing DLL dependencies, or exception handling not working. (Mixing C runtime flavors is probably bad too.)

For the <code>external_deps</code> libraries, efforts have been made to avoid depending on any thread-flavor-specific or exception-flavor-specific libraries, so it should be possible to use them with any flavor of MinGW. Exception handling glitches shouldn't be an issue since the Windows dependencies are C-only.

== Distributions ==

=== Cross-compiling from Linux ===

Most Linux package managers offer some form of MinGW package. Availability of different flavor combinations varies.

==== Installation ====
APT (Debian Buster or older):
<pre># 32-bit, sjlj. win32 threads are selected by default; switch it to posix
sudo apt install g++-mingw-w64-i686
sudo update-alternatives --set i686-w64-mingw32-gcc /usr/bin/i686-w64-mingw32-gcc-posix
sudo update-alternatives --set i686-w64-mingw32-g++ /usr/bin/i686-w64-mingw32-g++-posix

# 64-bit, SEH. win32 threads are selected by default; switch it to posix
sudo apt install g++-mingw-w64-x86-64
sudo update-alternatives --set x86_64-w64-mingw32-gcc /usr/bin/x86_64-w64-mingw32-gcc-posix
sudo update-alternatives --set x86_64-w64-mingw32-g++ /usr/bin/x86_64-w64-mingw32-g++-posix
</pre>

APT (Debian Bullseye or newer):
* <code>sudo apt install gcc-mingw-w64-i686-posix</code> (32-bit; posix; sjlj in Bullseye, dwarf in Bookworm)
* <code>sudo apt install gcc-mingw-w64-x86-64-posix</code> (64-bit, posix, SEH)

==== Usage ====

To build a CMake project, you need a "toolchain file". Sadly, there is no official toolchain file from MinGW or CMake. For Daemon and Unvanquished we use [https://github.com/DaemonEngine/Daemon/blob/master/cmake/cross-toolchain-mingw32.cmake this (32-bit)] and [https://github.com/DaemonEngine/Daemon/blob/master/cmake/cross-toolchain-mingw64.cmake this (64-bit)]. Use it by passing <code>-DCMAKE_TOOLCHAIN_FILE=<path></code> on the <code>cmake</code> command line.

=== MSYS2 ===

MSYS2 runs on Windows hosts and provides up-to-date 32-bit/DWARF/posix and 64-bit/SEH/posix toolchains. Building is done from a Bash shell in a partial emulation of a Linux environment, similar to Cygwin.

==== Installation ====

Download from [https://www.msys2.org].

Install dependencies to build Daemon (can be done from any MSYS2 shell flavor):
<pre>
# 32-bit
pacman -Sy mingw-w64-i686-gcc mingw64-i686-cmake make
# 64-bit
pacman -Sy mingw-w64-x86_64-gcc mingw64-x86_64-cmake make
</pre>

==== Usage ====
You must open a different MSYS2 shell flavor according to which architecture you want to target: "MSYS2 MinGW 32-bit" or "MSYS2 MinGW 64-bit". When invoking <code>cmake</code>, you must pass the flag <code>-G"MSYS Makefiles"</code>. When building Unvanquished, the flag <code>-DCBSE_PYTHON_PATH=<path></code> may be of interest, if you want to use a Python other than the one shipped with MSYS2. <code><path></code> should be in the Unix-emulation format, e.g. <code>/c/Python/python.exe</code>.

=== "MinGW-W64-builds" (Standalone Windows version) ===
This distribution (see [https://github.com/niXman/mingw-builds-binaries Github]) provides a toolchain that can be used from the Windows command prompt, without needing a Unix emulation layer. The installer allows you to choose from every valid combination of flavors.

==== Usage ====

Choose the <code>MinGW Makefiles</code> generator in CMake. The location of the toolchain used is determined by finding the first one in your PATH environment variable. Relative to the installation root, the PATH entry should be at <code>mingw32\bin</code> or <code>mingw64\bin</code>.

After running CMake, compile by running <code>mingw32-make</code> in the build directory.

== Built-in DLL dependencies ==

There are a few DLLs shipped as part of MinGW that most programs will depend on. These are also available as static libraries (a fully static binary can be produced with the <code>-static</code> flag), but dynamic is the default. These are:
* <code>libgcc</code>
* <code>libstdc++</code> (for C++ programs)
* <code>libssp</code> (if stack protection is enabled)
* <code>libwinpthread</code> (if threads are used)

<code>libstdc++</code> is both thread- and exception-flavor-dependent, but unlike <code>libgcc</code>, the DLL does not have the flavor written in the filename. This means that you can't easily tell if you have the right one (nor can the Windows executable loader). [https://github.com/lucasg/Dependencies Dependencies] is a good tool to investigate such issues.

When distributing a binary release of Daemon, you must ship these DLLs alongside the executable, else you will run into [https://github.com/Unvanquished/Unvanquished/issues/716 this issue]. Note that unlike Daemon's other DLL dependencies (from the <code>external_deps</code> package), the MinGW DLLs are not automatically copied to the build directory as part of the build process. See <code>extra_dll_list</code> and <code>findDll</code> in the [https://github.com/Unvanquished/release-scripts/blob/master/build-release Unvanquished release script].

== C ABI compability with MSVC ==

On 32-bit x86, GCC has a different default stack alignment (16 bytes) than MSVC (4 bytes). This can cause problems when MSVC-compiled code calls into GCC-compiled code and the alignment is less than expected. One solution, which we use to build MSVC-compatible <code>external_deps</code> DLLs, is to use a GCC flag (<code>-mpreferred-stack-boundary=</code>) to change the presumed stack alignment. Another, which we use to handle jumps from 3rd-party binaries to our (MinGW-built) code, is to put the annotation <code>__attribute__((force_align_arg_pointer))</code> on the functions which may be called with less alignment than expected, instructing the compiler to perform alignment when the function is called.

<code>-mms-bitfields</code> should be enabled to ensure that the layout of structs containing bitfields matches. This is on by default.

MinGW

2025-04-20T01:36:44Z

Killing time: /* Flavors */ new flavors

MinGW is a GCC-based compiler toolchain targeting Windows platforms. It is used to produce the Windows releases of Unvanquished. It can be quite complicated to use successfully, in part due to the existence of different compiler "flavors", and confusing naming schemes. This page serves as a guide to both MinGW in general, and specifically in application to building Daemon and Unvanquished. Throughout this page, "MinGW" will be used to refer to the [http://mingw-w64.org/ mingw-w64] project, which is a fork of the (now long-moribund) "original MinGW" project aiming to support both 32- and 64-bit builds. So beware: something having "64" in its name does not at all imply it is for 64-bit binaries! Same goes for "32".

== Flavors ==

=== Bitness: 32-bit or 64-bit ===

Whether to compile for 32-bit ("i686" in package names) or 64-bit ("x86-64" or "x86_64") architecture. 64-bit Windows versions are capable of running 32-bit executables in a mode called WOW (Windows-on-Windows).

=== Threading flavor ===
You can get <code>win32</code>, <code>posix</code> or <code>mcf</code> thread models. Daemon must be built with the <code>posix</code> flavor, because code that uses <code>std::thread</code> does not compile with either of the other flavors. In general there is no reason to use <code>win32</code>. However, it is unfortunately the default in the APT package manager. <code>mcf</code> first appears in the MinGW-W64-builds installer for version 13.2.0. It is supposed to have improved performance, but requires use of the nonstandard [https://gcc.gnu.org/onlinedocs/libstdc++/manual/ext_concurrency_impl.html gthread] interface.

=== Exception handling flavor ===

* <code>sjlj</code> (setjmp/longjmp) is available for both 32- and 64-bit builds. It has the drawback of significant runtime cost.
* <code>dwarf</code> is available only for 32-bit. It has good performance, but it is said to have a drawback that exceptions can't be propagated through code compiled with a different compiler (or C code?). However, propagating exceptions through C code shouldn't be needed for Daemon.
* <code>seh</code> (Structured Exception Handling) is available only for 64-bit. It has good performance and always works correctly, so it should always be used for 64-bit.

One way to identify which exception model code was built with is to check the libgcc dependency. You'll find for example <code>libgcc_s_seh-1.dll</code> for SEH, <code>libgcc_s_dw2-1.dll</code> for DWARF, or <code>libgcc_s_sjlj-1.dll</code> for sjlj. An easy way to make a C++ test program emit a libgcc dependency is to add a try/catch block.

=== Microsoft C runtime target ===

You can choose which one of the C stdlib/runtime implementations that come with Windows to dynamically link against.
* <code>msvcrt</code> is the traditional one.
* <code>ucrt</code> is first available in the MinGW-W64-builds installer for version 12.2.0. The [https://learn.microsoft.com/en-us/cpp/porting/upgrade-your-code-to-the-universal-crt UCRT] is only available in Windows 10 or higher.

For now, you can assume that everything uses <code>msvcrt</code> for the rest of the article.

=== Mixing flavors ===

Mixing different thread or exception flavors can cause problems, such as missing DLL dependencies, or exception handling not working. (Mixing C runtime flavors is probably bad too.)

For the <code>external_deps</code> libraries, efforts have been made to avoid depending on any thread-flavor-specific or exception-flavor-specific libraries, so it should be possible to use them with any flavor of MinGW. Exception handling glitches shouldn't be an issue since the Windows dependencies are C-only.

== Distributions ==

=== Cross-compiling from Linux ===

Most Linux package managers offer some form of MinGW package. Availability of different flavor combinations varies.

==== Installation ====
APT (Debian Buster or older):
<pre># 32-bit, sjlj. win32 threads are selected by default; switch it to posix
sudo apt install g++-mingw-w64-i686
sudo update-alternatives --set i686-w64-mingw32-gcc /usr/bin/i686-w64-mingw32-gcc-posix
sudo update-alternatives --set i686-w64-mingw32-g++ /usr/bin/i686-w64-mingw32-g++-posix

# 64-bit, SEH. win32 threads are selected by default; switch it to posix
sudo apt install g++-mingw-w64-x86-64
sudo update-alternatives --set x86_64-w64-mingw32-gcc /usr/bin/x86_64-w64-mingw32-gcc-posix
sudo update-alternatives --set x86_64-w64-mingw32-g++ /usr/bin/x86_64-w64-mingw32-g++-posix
</pre>

APT (Debian Bullseye or newer):
* <code>sudo apt install gcc-mingw-w64-i686-posix</code> (32-bit, posix, sjlj)
* <code>sudo apt install gcc-mingw-w64-x86-64-posix</code> (64-bit, posix, SEH)

==== Usage ====

To build a CMake project, you need a "toolchain file". Sadly, there is no official toolchain file from MinGW or CMake. For Daemon and Unvanquished we use [https://github.com/DaemonEngine/Daemon/blob/master/cmake/cross-toolchain-mingw32.cmake this (32-bit)] and [https://github.com/DaemonEngine/Daemon/blob/master/cmake/cross-toolchain-mingw64.cmake this (64-bit)]. Use it by passing <code>-DCMAKE_TOOLCHAIN_FILE=<path></code> on the <code>cmake</code> command line.

=== MSYS2 ===

MSYS2 runs on Windows hosts and provides up-to-date 32-bit/DWARF/posix and 64-bit/SEH/posix toolchains. Building is done from a Bash shell in a partial emulation of a Linux environment, similar to Cygwin.

==== Installation ====

Download from [https://www.msys2.org].

Install dependencies to build Daemon (can be done from any MSYS2 shell flavor):
<pre>
# 32-bit
pacman -Sy mingw-w64-i686-gcc mingw64-i686-cmake make
# 64-bit
pacman -Sy mingw-w64-x86_64-gcc mingw64-x86_64-cmake make
</pre>

==== Usage ====
You must open a different MSYS2 shell flavor according to which architecture you want to target: "MSYS2 MinGW 32-bit" or "MSYS2 MinGW 64-bit". When invoking <code>cmake</code>, you must pass the flag <code>-G"MSYS Makefiles"</code>. When building Unvanquished, the flag <code>-DCBSE_PYTHON_PATH=<path></code> may be of interest, if you want to use a Python other than the one shipped with MSYS2. <code><path></code> should be in the Unix-emulation format, e.g. <code>/c/Python/python.exe</code>.

=== "MinGW-W64-builds" (Standalone Windows version) ===
This distribution (see [https://github.com/niXman/mingw-builds-binaries Github]) provides a toolchain that can be used from the Windows command prompt, without needing a Unix emulation layer. The installer allows you to choose from every valid combination of flavors.

==== Usage ====

Choose the <code>MinGW Makefiles</code> generator in CMake. The location of the toolchain used is determined by finding the first one in your PATH environment variable. Relative to the installation root, the PATH entry should be at <code>mingw32\bin</code> or <code>mingw64\bin</code>.

After running CMake, compile by running <code>mingw32-make</code> in the build directory.

== Built-in DLL dependencies ==

There are a few DLLs shipped as part of MinGW that most programs will depend on. These are also available as static libraries (a fully static binary can be produced with the <code>-static</code> flag), but dynamic is the default. These are:
* <code>libgcc</code>
* <code>libstdc++</code> (for C++ programs)
* <code>libssp</code> (if stack protection is enabled)
* <code>libwinpthread</code> (if threads are used)

<code>libstdc++</code> is both thread- and exception-flavor-dependent, but unlike <code>libgcc</code>, the DLL does not have the flavor written in the filename. This means that you can't easily tell if you have the right one (nor can the Windows executable loader). [https://github.com/lucasg/Dependencies Dependencies] is a good tool to investigate such issues.

When distributing a binary release of Daemon, you must ship these DLLs alongside the executable, else you will run into [https://github.com/Unvanquished/Unvanquished/issues/716 this issue]. Note that unlike Daemon's other DLL dependencies (from the <code>external_deps</code> package), the MinGW DLLs are not automatically copied to the build directory as part of the build process. See <code>extra_dll_list</code> and <code>findDll</code> in the [https://github.com/Unvanquished/release-scripts/blob/master/build-release Unvanquished release script].

== C ABI compability with MSVC ==

On 32-bit x86, GCC has a different default stack alignment (16 bytes) than MSVC (4 bytes). This can cause problems when MSVC-compiled code calls into GCC-compiled code and the alignment is less than expected. One solution, which we use to build MSVC-compatible <code>external_deps</code> DLLs, is to use a GCC flag (<code>-mpreferred-stack-boundary=</code>) to change the presumed stack alignment. Another, which we use to handle jumps from 3rd-party binaries to our (MinGW-built) code, is to put the annotation <code>__attribute__((force_align_arg_pointer))</code> on the functions which may be called with less alignment than expected, instructing the compiler to perform alignment when the function is called.

<code>-mms-bitfields</code> should be enabled to ensure that the layout of structs containing bitfields matches. This is on by default.

Compiling the source

2025-03-30T17:58:42Z

Killing time:

==Dependencies==

{{Note|content=In case this happens to become outdated, the up-to-date documentation can be found in the {{SourceFile|parameters=#unvanquished|README.md}} file in source repository.}}

The game requires some dependencies to be built, which are the same on all systems:

* cmake
* python3-yaml
* python3-jinja2
* A C++14 able compiler (those are known to work: clang (>= 3.5), gcc (>= 4.8), visual studio (>= 2019))
* zlib1g
* libgmp
* nettle
* libcurl4-gnutls
* libsdl2
* libglew
* libpng
* libjpeg-turbo8
* libwebp
* libfreetype6
* liblua5.3
* libopenal
* libogg
* libvorbis
* libopusfile

Those are optional:

* libncursesw5

==macOS==

First, you need to [[Getting_the_source|acquire the source code]].

Regardless of what interface you may use to compile the source, you will need [http://www.cmake.org/cmake/resources/software.html CMake] to generate makefiles. You will also need to install [https://developer.apple.com/xcode/ Xcode]. At a minimum, you must install the "Xcode command-line tools" in order to compile anything. You may also install Xcode proper, if you wish to use that IDE.

Once you have the source code and the tools installed, you may actually proceed to compile the source. You have several options:
* '''Compile the source at the command line'''. This is the easiest if you would just like to compile the game to use yourself and you do not intend to work on the code.
* '''Compile the source using an IDE'''. This is preferred if you intend on developing the source.
** Xcode is Apple's flagship IDE.
** [http://qt-project.org/downloads QtCreator] is cross-platform and provides real-time feedback of syntax errors, a Vim mode, as well as other features.
** [http://www.codeblocks.org/ Code::Blocks] is also cross-platform but lacks some of the features of Xcode and QtCreator.

===Dependencies===

Precompiled static libs are provided for all dependencies. CMake downloads them at configure time and extracts to <code>daemon/external_deps/macos-amd64-default_<i><version></i>/</code>. These were produced by the <code>external_deps/build.sh</code> script, which you could also use to build them yourself if you want to for some reason.

===Configuring with CMake===

# Run CMake.
# Enter the location of the source code.
# Enter the location in which you would like to build the source code. This should be a different directory.
# Click "Configure". You will be prompted as to which generator you would like to use. If you have Xcode installed, choose that. Wait while the configuration process runs. You may have to set the following:
## If you have selected to generate Xcode project files, make the <code>SDLMAIN_LIBRARY</code> field blank. This option is not available if you have the generator set to Unix makefiles.
# Click "Generate".
# You may now close CMake.

===Compiling===

====With Xcode====

<ol>
<li>Either start Xcode and open the project file (in the build directory you specified) or double-click the project file in Finder.</li>
<li>Open the project file created by CMake, which should be in the build directory you specified.</li>
<li>Change the active target to "ALL_BUILD" and click Product→Build.</li>
</ol>

====With Unix Makefiles====

<ul>
<li>Start Terminal (Applications → Utilities → Terminal).</li>
<li>Type the following commands:
<pre>
$ cd /path/to/Unvanquished-build
$ make
</pre>
If you are on a multi-core or multi-processor machine, you may speed up the process by passing the <code>-j</code> argument followed by the number of available cores to <code>make</code>; e.g., <code>make -j4</code>. Note that doing so makes reading error messages more difficult, as multiple instances of the compiler will print to the screen at once, causing information to appear out of order.
</li>
</ul>

===Testing the build===

====With Xcode 4====

To test the game, select the "client" scheme from the combo box on the toolbar, and click the run button or press {{Hotkey|MacCommand}}{{Hotkey|R}}.

=== Building for arm64 (Apple Silicon) architecture ===

Our CMake scripts default to amd64 architecture, but you can also make a native build for the latest ARM-based Macs. Albeit while still relying on Rosetta to run amd64-based Native Client gamelogic binaries.
<pre>
# Install Daemon + Unvanquished dependencies (no pre-built ones for this architecture)
brew install nettle sdl2 libogg libvorbis opus opusfile web freetype glew openal-soft

cmake path/to/source -DCMAKE_OSX_ARCHITECTURES=arm64 -DOpenAL_ROOT=$(brew --prefix openal-soft)

# If you want to run NaCl (assumes you have built amd64 at least once to download its deps):
cp path/to/daemon/external_deps/macos-amd64-default_10/{nacl_loader,irt_core-amd64.nexe} .
</pre>

==Windows==

===Visual Studio===

CMake can generate Visual Studio projects for Unvanquished.

# Add _NO_DEBUG_HEAP=1 to your environment variables otherwise performance under the debugger [http://www.massimpressionsprojects.com/dev/altdevblog/2011/07/27/the-unexpected-performance-of-debug-builds/ will be terrible]
# Run CMake with the source directory as the base directory of your source code (which should contain the directory <code>src</code>), and the build directory as a subdirectory of the source directory named <code>build</code>.
# Click the <b>Open Project</b> button. Or if you used CMake from the command line, open <code>build/Unvanquished.sln</code> in Visual Studio.
# In Visual Studio, choose your desired build type (default: <b>Debug</b>) from the drop-down menu in the top bar. <b>Debug</b> runs assertions and has complete debug information, but is slower. <b>RelWithDebInfo</b> is fast and still fairly usable with the debugger, but assertions don't run and sometimes you can't see the value of a local variable.
# Use Build → Build Solution to compile the code. Or just press {{Hotkey|F5}} to build and run, but beware: this will not automatically build cgame or sgame! Only engine changes are automatically rebuilt when you run something from Visual Studio.

====Important Notes====

* Due to limitations with CMake, the startup project cannot be specified. This must be set manually to debug the client with Visual Studio:
** Right click on client and select "Set as Startup project".

===MinGW===

It is possible to produce a Windows build of Unvanquished with [[MinGW]], as either a Windows or a Linux user. See [[MinGW#Distributions]] for detailed information about the toolchains available for installation.

====Instructions for native Windows build with MSYS2====

<ol>

<li> Install MSYS2. </li>
<li> Open the ''MSYS2 MinGW 32-bit'' or ''MSYS2 MinGW 64-bit'' terminal, depending on which bitness you want to build. </li>
</li> Install toolchain:
<pre>
# For 32-bit replace x86_64 with i686
pacman -Sy && pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake make
</pre> </li>
<li> Run CMake. If you're building Unvanquished, you may want to use the <code>-DCBSE_PYTHON_PATH=<path></code> option in case you want to use a different Python rather than the one in MSYS2. <pre>
mkdir mybuild && cd mybuild
cmake -G "MSYS Makefiles" somepath/Unvanquished
</pre> </li>
<li> Build:
<pre> make -j4 </pre>

If you would like verbose output (useful to see compiler flags), set the <code>VERBOSE</code> environment variable before running Make.
<pre>
export VERBOSE=1
</pre>

</li>
</ol>

You may find that the game (or some part of the MSYS2 toolchain!) fails to start due to missing DLL dependencies. Two helpful tools are:
<ul>
<li> The strace command in MSYS2, e.g. <code>strace ./daemon</code> </li>
<li> [https://github.com/lucasg/Dependencies Dependencies] (a Windows GUI program) </li>
</ul>

When distributing MinGW binaries, you need to distribute some additional DLLs besides the ones in the build folder. See [[MinGW#Built-in_DLL_dependencies]].

====MSYS2 Clang====
In MSYS2, it is possible to build with Clang, rather than GCC as shown as in the above instructions. However, some of our pre-built libraries are incompatible. You need to use the ones from pacman instead.

<ol>
<li> Create a deps folder with incompatible packages removed. This assumes that the latest version of the prebuilt deps for the mingw package of the appropriate bitness has already been extracted to the <code>windows-${ARCH}-mingw_${VERSION}</code> directory. In this example, we use <code>windows-amd64-mingw_8</code>. <pre>
cd somepath/daemon/external_deps
mkdir msysclang
cp windows-amd64-mingw_8 -R msysclang
find msysclang -depth -name '*freetype*' -o -name '*png*' -o name '*curl*' -o -name '*lua*' | grep -v pnacl | xargs rm -r
</pre> </li>
<li> Install those deps from Pacman: <pre>
# For Daemon
pacman -Sy && pacman -S mingw-w64-clang-x86_64-freetype mingw-w64-clang-x86_64-curl mingw-w64-clang-x86_64-libpng
# For Unvanquished
pacman -Sy && pacman -S mingw-w64-clang-x86_64-freetype mingw-w64-clang-x86_64-lua
</pre> </li>
<li>
Use the deps folder you made when configuring the build: <pre>
CC=clang CXX=clang++ cmake -G "MSYS Makefiles" -DEXTERNAL_DEPS_DIR=somepath/daemon/external_deps/msysclang /c/path/to/source
</pre>
If you see a download progress bar upon invoking CMake, you did the deps stuff wrong.
</li>
</ol>

===QtCreator===

# Install MinGW and follow the above instructions, except select Code::Blocks as the generator.
# Start QtCreator, and select "Open File or Project…" from the File menu.
# Navigate to your source directory and open CMakeLists.txt.
# At the CMake Wizard, select the same build directory you already configured using CMake. (If you did not chose Code::Blocks as the generator, you will have to start over again, as QtCreator requires a Code::Blocks project file in order to compile the source.)
# Ensure that a generator is selected in the combo box, and click "Run CMake". If there is no generator listed, see the [[#Troubleshooting|troubleshooting]] section below.
# Click "Finish" to close the wizard.

You should now be able to compile, run, and debug the code using QtCreator.

====Troubleshooting====

If at the "Run CMake" prompt of the the CMake Wizard, select "Run CMake" and are warned that no generator was selected, and notice that there are no generators in the combo box, you will likely have to [http://doc.qt.digia.com/qtcreator-2.4/creator-tool-chains.html manually configure your toolchain]. Select "Options…" from the "Tools" menu, then navigate to "Build & Run".

At the options window,
* Go to the "Kits" tab, and mouse over the "Desktop (default)" kit under "Manual". If there were any errors in configuring this kit, they will be displayed in the tool tip. If there are problems, select the kit. You may need to manually specify the location of the MinGW debugger, for example, which is typically <code>C:\MinGW\bin\gdb.exe</code>.
* Go to the "Compilers" tab, and ensure that MinGW is present. If not, you will need to add it manually.

==Linux==

===Dependencies===

{{TODO|This may be incomplete.}}

====Debian/Ubuntu====

sudo apt-get install build-essential cmake libcurl4-gnutls-dev \
libglew-dev libgmp-dev nettle-dev zlib1g-dev libncursesw5-dev \
libsdl2-dev libopenal-dev libjpeg-dev libpng-dev libwebp-dev \
libogg-dev libvorbis-dev libopusfile-dev \
libfreetype6-dev \
liblua5.3-dev \
python3-yaml python3-jinja2

If the version of WebP supplied by your version of Debian or Ubuntu is older than v0.2.0, you will need to [https://code.google.com/p/webp/downloads/detail?name=libwebp-0.2.0.tar.gz download] and [https://developers.google.com/speed/webp/docs/compiling#unix compile it from source]. After compiling and installing with <code>sudo make install</code>, in CMake, you'll need to set <code>WEBP_INCLUDE_DIR</code> to <code>/usr/local/include/webp</code> and <code>WEBP_LIBRARY</code> to <code>/usr/local/lib/libwebp.so</code>.

Developpment package name may differs, for example <code>libgmp-dev</code> may be named <code>libgmp3-dev</code> and <code>libglew-dev</code> may be named <code>libglew1.7-dev</code>.

We have a <code>debian</code> directory in the source tree, you can check what's missing this way.

cd <var>path/to/unvanquished</var>
dpkg-checkbuilddeps

Then install the listed packages this way:

sudo apt-get install <var>package list</var>

The <code>dpkg-checkbuilddeps</code> command produces no output if you already have the required dependencies.

Note that you only need <code>debhelper</code> to build <code>.deb</code> files.

====Fedora====

Line 1 of the packages is basic dev tools. Lines 2-3 are Daemon dependencies. Line 4 is (additional) Unvanquished dependencies.

$ sudo dnf install \
cmake gcc gcc-c++ \
{freetype,glew,gmp,mesa-libGL,ncurses,nettle,openal-soft,opus,opusfile,SDL2}-devel \
lib{curl,jpeg-turbo,png12,vorbis,webp}-devel \
lua-devel python3-pyyaml python3-jinja2

====Gentoo====

$ emerge curl freetype glew gmp jpeg ncurses media-sound/opus-tools libogg openal libpng libsdl libvorbis sys-libs/zlib

====openSUSE====

$ sudo install zypper gcc gcc-c++ Mesa-libGL-devel SDL-devel libjpeg8-devel \
libpng12-devel glew-devel webp-devel ncurses-devel gmp-devel libcurl-devel \
libnettle-devel openal-soft-devel libvorbis-devel

The latest version of WebP must be installed manually (FIXME: why, if there is webp-devel in the zypper package list?):

$ cd Unvanquished/daemon/external_deps
$ ./build.sh linux-amd64-default webp naclsdk naclports
$ ./build.sh linux-amd64-default install

You must disable curses (set <code>USE_CURSES</code> appropriately in CMake) as failing to do so will cause Unvanquished to crash on startup.

===Configuring the code with CMake===

After you have [[Getting the source|acquired the source code]], you can proceed to compile. Unvanquished uses CMake, so you must have that installed.

====Using ccmake (curses-based front-end)====

On Debian or Ubuntu:

$ sudo apt-get install cmake-curses-gui

On Gentoo you should set the '''ncurses''' USE flag either globally or individually, just for cmake.
To add the USE flag globally, edit the USE array in /etc/make.conf for it to include '''ncurses'''.
To only install cmake with ncurses functionality, you could do the following:

$ echo 'dev-util/cmake ncurses' >> /etc/portage/package.use && emerge cmake

Note that in Ubuntu, <code>cmake-curses-gui</code> is in Universe, which you may have to enable with <code>software-properties-gtk</code>. Make sure to reload the software sources with <code>sudo apt-get update</code> afterwards.

Optionally: to use clang (rather than the default gcc and g++ compilers) export the CC and CXX variables before running cmake:

$ export CC="clang"
$ export CXX="clang++ -stdlib=libc++ -lc++abi"

Next, configure the codebase.

$ cd <var>/path/to/unvanquished</var>
$ mkdir build
$ cd build
$ ccmake ..

In Debian or Ubuntu you can build a package this way (you need <code>devscripts</code> and <code>fakeroot</code> packages):

$ cd <var>/path/to/unvanquished</var>
$ fakeroot dpkg-buildpackage -b -uc
$ sudo dpkg -i <var>../unvanquished_*.deb</var>

Once in <code>ccmake</code>, use the following keys:

* Press {{Hotkey|c}} to configure. If an error occurs during this phase, make note of it and press {{Hotkey|e}} to dismiss it.
* Use the up and down arrow keys to navigate the compilation options.
* Press {{Hotkey|Enter}} to enable or disable boolean options (i.e., on/off) or to edit textual options.
** Press {{Hotkey|Esc}} when editing a textual option to cancel the change.

Once you have finished the configuration process, press {{Hotkey|C}} again, then {{Hotkey|G}} to generate the makefile.

====Using cmake-qt-gui (graphical front-end)====

This graphical front end for cmake has its own package you must install:

=====Debian/Ubuntu=====

$ sudo apt-get install cmake-qt-gui

=====Gentoo=====

With the '''qt4''' USE flag enabled:

$ emerge cmake

Once installed, run with <code>cmake-gui</code>.

[[Image:Cmake-qt-gui.png|thumb]]

# Set the path where you have the source code downloaded.
# Set the path where you would like to build the engine. This may be the same directory if you wish.
# Click 'Configure'.
# Click 'Generate'.

====Unnecessary libraries====

Regardless of which front-end to cmake you use, you may want to disable some libraries that are not strictly necessary:

* <code>USE_BREAKPAD</code> — Disabling this will cause the game to not produce crashdumps on failure.
* <code>USE_CURSES</code> — Disabling this will cause the external (not in-game) console to not use curses; it will not be scrollable and will be similar to the console in the original Tremulous. This does in no way affect gameplay.

===Compiling===

$ cd <var>path/to/unvanquished/build</var>
$ make -j4

The <code>-j</code> switch to make allows you to speed up the compilation process by running it in multiple threads; set the number following this to the number of cores your processor(s) have.

==FreeBSD==

While building on FreeBSD is usually very similar to building on Linux, the PNaCl toolchain not being native to FreeBSD means not everything can be built on FreeBSD. See the [[Systems/FreeBSD]] page for details and dedicated instructions.

==Acquiring the Game Files==

===Acquiring mandatory game files===

The game files are not in the Git repository, and must be downloaded separately. They must be saved to the [[Game locations|data location]] for your system.

Linux users may use the <code>download-paks</code> script that is distributed with the source code, which requires one of curl, wget or aria2 to be installed:

$ cd <var>path/to/unvanquished/build</var>
$ ../download-paks pkg

Otherwise, the set of necessary packages can be extracted from the [https://github.com/Unvanquished/Unvanquished/releases latest release], or downloaded a la carte from the [http://dl.unvanquished.net/pkg/ package index].

Testing

2025-01-28T15:33:10Z

Killing time: new section: Testing old versions

[[Category:Testing]]
==Reporting bugs==

Please see the [[Bug_reporting|bug reporting]] page. This page is about helping modders and developers testing their changes.

==Debugging==

To create a debug build, change <code>CMAKE_BUILD_TYPE</code> in CMake from <code>Release</code> to <code>Debug</code>, then [[Compiling_the_source|compile]].

You may find it necessary to set <code>in_nograb</code> to <code>1</code> to disable pointer grabbing so that you may use your debugger.

===Debugging with gdb===

Start gdb as follows:

$ gdb --args ./daemon +devmap chasm

If the program segfaults, a backtrace is very useful to the developers in determining the source of the problem. At the debugger prompt, type <code>bt</code>:

(gdb) bt

===Debugging with Xcode===

With Xcode 4, even if you did not build the game with Xcode, you may still use its facilities for debugging.

# Open any project. If necessary, create a new one. It may contain anything.
# Click "Product" on the menu bar and navigate to "Attach to Process". Look for "daemon" listed under "Applications".

After a moment, the application will be ready for debugging.

See the [https://developer.apple.com/library/mac/#documentation/ToolsLanguages/Conceptual/Xcode4UserGuide/060-Debug_Your_App/debug_app.html#//apple_ref/doc/uid/TP40010215-CH3-SW1 Xcode 4 User Guide] for more information.

==Live Testing==

===Starting a testing session===

Start the game, and enter the following command:

/devmap <var>map-name</var>

===Adding bots===

Like fish in a fish bowl, they can bring some activity in a map.

/bot fill 5 # add 5 bots

You can also have a look at all the <code>g_bot_*</code> cvars, they are quite interesting. There is even a graphical user interface for these!

===Moving around with ease and spawning anywhere===

You can pass through walls and fly around using <code>/noclip</code>, and you can spawn anywhere you want using <code>/devteam h</code> for humans or <code>/teamteam a</code> for aliens. That's very practical and can allow you to start from an empty map.

To load an empty map without having the game finishing immediately, you can use <code>g_neverEnd</code>. This can help porting maps.

===The <code>/give</code> command===

The /give will give you an easy way to test situations without being blocked by funds or team advancement.

/team a # join aliens
/give momentum # give all the momentum you can to your team
/give bp 100 # get 100 build points free
/give funds # get rich quick! I swear it's not a pyramid scheme!
/give all # get all personal things you can get, in addition to money (BP and momentum are independant)

You can also combine several commands into one, for example you can test advanced dragoon really quickly

=== Some misc useful cvars===

* <code>cg_drawSpeed</code> to see how fast you are moving, <code>/set cg_drawSpeed 2</code> even brings an histogram.
* <code>cg_drawBBOX</code> to see how big or small the bounding box are
* <code>cg_drawDebugDistance</code> to give you an idea of how far away of you a distance of "100 quake units" is
* <code>timescale</code> setting this will make everything faster, or slower. Be careful that if you set it too low (say less than 0.1) the graphical console will take a lot of time to visibly appear, but you can still type in it. For example to do <code>/timescale 1</code> again.
* <code>g_freeFundPeriod</code> to change how often you and other clients are gifted money. This can be an alternative to making bots ignore limits that can give a bit more diversity in their choices and behaviours (rich bots will always rush, for example)

==Debugging Graphics==

* <code>cg_draw2D</code> can allow you to disable 2D drawing. It may be useful if you want to ignore 2D performances from your benchmarks.

There probably exist proprietary tools for your platform. For example AMD used to have gDEBugger, and [https://gpuopen.com/archived/gpu-perfstudio/ GPU PerfStudio] proprietary debuggers.

===apitrace===

[https://apitrace.github.io/ apitrace] is an open-source tool that records every graphics API call made by an application. After the application has closed, you can step through individual calls to the graphics API, allowing you to
* see the result exactly as it would appear following each call,
* see graphs of API usage, and
* inspect buffers.

Linux users can install it from their package manager, for example:

sudo apt install apitrace-tracers apitrace-gui

Windows users can [http://people.freedesktop.org/~jrfonseca/apitrace/ download a build].

==General Tips==

===Miscellaneous===

* To stress test the engine's ability to display a large number of buildables, you can tweak <code>g_BPInitialBudget</code> and build as much as you wish.
* To determine what file was loaded for a particular asset (e.g., to determine if files are being read from a particular {{Formats|DPK}} archive) use the <code>/which</code> command with the relative path to the asset as an argument. You can use tab-completion.

For example, this means that you are effectively the new version of an UI file:

/which ui/shared/circlemenu.rcss
File "ui/shared/circlemenu.rcss" found in "/home/me/unv/Unvanquished/pkg/unvanquished_src.dpkdir/"

==Viewing Runtime Information==

The engine and game logic provide a number of commands for viewing information about its current state.

==Testing materials and textures==

See {{Subpage|Materials}}.

==Testing maps==

See {{Subpage|Maps}}.

==Testing models==

See {{Subpage|Models}}.

==Testing old versions of Unvanquished==

https://dl.unvanquished.net/release/ has universal zips of past releases. It is missing all versions before 0.17.

https://gitlab.com/slipher/unvanquished-timemachine is a way to test multiple versions of Unvanquished more conveniently, without any unzipping or other install step. But it has only x86 Windows binaries. Some versions older than 0.17 are present.

Formats/Particle

2025-01-22T10:35:59Z

Killing time: tools are not real

[[Category:Formats]]
[[Category:Mapping]]
Particle effects work differently than in Quake 3 but the same as Tremulous. Please see the [https://web.archive.org/web/20200416190204/http://tremulous.net/manual/#x1-130003.2 Tremulous documentation] ([https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf pdf]) for information on creating particle effects for now.

Particle files must be located in the VFS at <code>scripts/*.particle</code>. A particle file may specify any number of particle systems.

Particle format is game-specific (mods may modify it).

To look for examples of how some particle feature is used, you may use this [https://users.unvanquished.net/~slipher/particle-keyword-directory.txt particle keyword directory].

== How it works ==
A particle renders as either a polygon with the specified texture(s), or a model.

A texture-based particle is rendered as a square polygon oriented opposite to the view direction. The square may be rotated around the view axis, if specified in the particle file. Rotation means the corners of the square aren't aligned with the corners of the window.

There is a correspondence between (texture-based) particles and [[Formats/Trail|trails]], and the two types of autosprite shaders: particles are to <code>deformVertex autosprite</code> as trails are to <code>deformVertex autosprite2</code>. <code>deformVertex autosprite</code> polygons can be placed in maps. They must be square and are automatically rotated so that, like particles, they are oriented opposite the view axis. Meanwhile trails and autosprite2 polygons rotate to face the viewer (NOT the view direction!), but only around a single axis.

== Discouraged features in particle files ==
<code>realLight</code> should not be used. This causes the particle to be lit using a sample from the lightgrid. This is a bad idea because it results in synchronous queries between the cgame and the renderer. Plus, it does not respond to realtime lights. Use a shader with light mapping enabled instead.

== Tools (which do not actually deal with particle systems) ==

There is a so-called [https://www.quake3world.com/forum/viewtopic.php?t=37893 particle effects editor] for Quake 3 that will likely need much modification to work with the Tremulous-style particle effects system. Source code is available from [https://github.com/FS-NulL/New-Quake-3-Particle-Studio GitHub]. A very brief tutorial on its usage by Frozen Sand (creators of Urban Terror) is [https://www.moddb.com/games/world-of-padman/downloads/frozen-sand-particle-studio-v10 also available]. But in fact "Quake 3 Arena has no support for 'real' particle systems. This program emulates them by using shader FX."<ref>https://www.quake3stuff.com/freebrief/asp/viewpage.asp?url=../q3a/tools/ps/manual/basic/whatis.vp</ref> Indeed, the quake3world.com forum post speaks of exporting to a <code>.shader</code>.

An older particle effects editor (not updated in many years) was also available. Dead link: <s>http://www.mods-r-us.net/freebrief/q3a/ps/index.html</s>

Formats/Particle

2025-01-21T11:26:38Z

Killing time: how it works, discouraged reallight

[[Category:Formats]]
[[Category:Mapping]]
Particle effects work differently than in Quake 3 but the same as Tremulous. Please see the [https://web.archive.org/web/20200416190204/http://tremulous.net/manual/#x1-130003.2 Tremulous documentation] ([https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf pdf]) for information on creating particle effects for now.

Particle files must be located in the VFS at <code>scripts/*.particle</code>. A particle file may specify any number of particle systems.

Particle format is game-specific (mods may modify it).

To look for examples of how some particle feature is used, you may use this [https://users.unvanquished.net/~slipher/particle-keyword-directory.txt particle keyword directory].

== How it works ==
A particle renders as either a polygon with the specified texture(s), or a model.

A texture-based particle is rendered as a square polygon oriented opposite to the view direction. The square may be rotated around the view axis, if specified in the particle file. Rotation means the corners of the square aren't aligned with the corners of the window.

There is a correspondence between (texture-based) particles and [[Formats/Trail|trails]], and the two types of autosprite shaders: particles are to <code>deformVertex autosprite</code> as trails are to <code>deformVertex autosprite2</code>. <code>deformVertex autosprite</code> polygons can be placed in maps. They must be square and are automatically rotated so that, like particles, they are oriented opposite the view axis. Meanwhile trails and autosprite2 polygons rotate to face the viewer (NOT the view direction!), but only around a single axis.

== Discouraged features in particle files ==
<code>realLight</code> should not be used. This causes the particle to be lit using a sample from the lightgrid. This is a bad idea because it results in synchronous queries between the cgame and the renderer. Plus, it does not respond to realtime lights. Use a shader with light mapping enabled instead.

== Tools (outdated) ==

There is a [https://www.quake3world.com/forum/viewtopic.php?t=37893 particle effects editor] for Quake 3 that will likely need much modification to work with the Tremulous-style particle effects system. Source code is available from [https://github.com/FS-NulL/New-Quake-3-Particle-Studio GitHub]. A very brief tutorial on its usage by Frozen Sand (creators of Urban Terror) is [https://www.moddb.com/games/world-of-padman/downloads/frozen-sand-particle-studio-v10 also available].

An older particle effects editor (not updated in many years) was also available. Dead link: <s>http://www.mods-r-us.net/freebrief/q3a/ps/index.html</s>

Tools/Breakpad

2025-01-17T01:33:25Z

Killing time: link Native CLient

Breakpad is the technology for generating and analyzing crash dumps for the Daemon 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 <i>native executable</i> 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: explain how to use this). }}

== Configuration ==

The 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 repo for Daemon Engine is at https://github.com/DaemonEngine/breakpad. If you have already checked out Daemon, then it is located in the <code>libs/breakpad/</code> submodule there. cd into this repo.

Daemon's Breakpad fork is based on https://github.com/jon-turney/google-breakpad, with only minor changes. Jon Turney's version adds MinGW support. It is in turn a fork of Chromium's Breakpad https://chromium.googlesource.com/breakpad/breakpad.

=== 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

2025-01-16T09:29:39Z

Killing time: /* Interactive Debugging */ breaking on crash actually works fine

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

It replaced the Q3VM (Quake3 Virtual Machine) in the engine.

Unlike Q3VM for which the {{code|.qvm}} binaries were limited to be produced with the old C supported by the proprietary LCC compiler, the {{code|.nexe}} NaCl binaries can be compiled with Clang-based open source compilers supporting modern-enough C++ versions and allowing to reuse off-the-shelf C++ libraries that may even be shared between the engine and the game source code.

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.

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/].

==Platforms==

{| style="margin:auto"
|+ Platform NaCl compatibility
|-
! colspan="4" | Linux !! colspan="2" | Windows !! colspan="2" | macOS !! FreeBSD
|-
! amd64 || i686 || arm64 || armhf || amd64 || i686 || amd64 || arm64 || amd64
|-
| ✅️ native || ✅️ native || ☑️ through armhf<br/>compatibility || ✅️ native || ✅️ native || ✅️ native || ✅️ native || ☑️ through amd64<br/>compatibility || ☑️ through Linux<br/>compatibility
|}

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 32-bit compatibility;
* macOS, arm64: running the amd64 NaCl loader through Rosetta2 compatibility;
* FreeBSD, amd64: running the Linux NaCl loader through built-in Linuxulator compatibility.

The Linux armhf NaCl loader requires a 4k PageSize kernel:

* https://github.com/Unvanquished/Unvanquished/issues/3286

The Linux i686 and armhf NaCl loaders may run on FreeBSD using Linuxulator but it is not tested.

NaCl also supports 32-bit MIPS on Linux but this architecture is not supported by the {{engine}} and the {{game}} project.

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 also lacks support for some platforms NaCl supports, like i686 or armhf, but more importantly lacks support for exceptions or {{code|setjmp/longjmp}} and then isn't complete enough for our needs yet.

==Compilers==

===PNaCl Clang===

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.

===Saigo===

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

Unlike PNaCl, Saigo do not provide released binaries, meaning a switch to Saigo requires a convenient way to provide it to contributors.

For now it has been successful to build an {{code|sgame.nexe}} (server game binary) with Saigo and run it, so with more efforts it may be possible to also build the {{code|cgame.exe}} (client game binary) as well and drop PNaCl.

Google provides some nightly Linux amd64 Saigo toolchain snapshots that aren't easy to get without some Google scripts.

The Saigo compiler and other related toolchain tools should build everywhere their upstream build, but only targeting the usual platforms, as the nacl_loader is basically the same: a more recent nacl_loader is also buildable but doesn't bring new platform supports.

The Saigo compiler itself isn't hard to build (same as Clang itself), what is more complex is to get the toolchain and the libc/libc++ to build.

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

Moving to Saigo is considered as a migration step that can be achievablebefore 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 at migrating to Saigo:

* https://github.com/Unvanquished/Unvanquished/issues/3197

The workspace for our attempt to rebuild and repackage Saigo is there:

* https://github.com/DaemonEngine/DaemonSaigoNativeClientToolkit

== 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://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 [[Breakpad]].

Native Client

2025-01-16T08:27:15Z

Killing time: mention secure sandboxing

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

It replaced the Q3VM (Quake3 Virtual Machine) in the engine.

Unlike Q3VM for which the {{code|.qvm}} binaries were limited to be produced with the old C supported by the proprietary LCC compiler, the {{code|.nexe}} NaCl binaries can be compiled with Clang-based open source compilers supporting modern-enough C++ versions and allowing to reuse off-the-shelf C++ libraries that may even be shared between the engine and the game source code.

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.

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/].

==Platforms==

{| style="margin:auto"
|+ Platform NaCl compatibility
|-
! colspan="4" | Linux !! colspan="2" | Windows !! colspan="2" | macOS !! FreeBSD
|-
! amd64 || i686 || arm64 || armhf || amd64 || i686 || amd64 || arm64 || amd64
|-
| ✅️ native || ✅️ native || ☑️ through armhf<br/>compatibility || ✅️ native || ✅️ native || ✅️ native || ✅️ native || ☑️ through amd64<br/>compatibility || ☑️ through Linux<br/>compatibility
|}

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 32-bit compatibility;
* macOS, arm64: running the amd64 NaCl loader through Rosetta2 compatibility;
* FreeBSD, amd64: running the Linux NaCl loader through built-in Linuxulator compatibility.

The Linux armhf NaCl loader requires a 4k PageSize kernel:

* https://github.com/Unvanquished/Unvanquished/issues/3286

The Linux i686 and armhf NaCl loaders may run on FreeBSD using Linuxulator but it is not tested.

NaCl also supports 32-bit MIPS on Linux but this architecture is not supported by the {{engine}} and the {{game}} project.

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 also lacks support for some platforms NaCl supports, like i686 or armhf, but more importantly lacks support for exceptions or {{code|setjmp/longjmp}} and then isn't complete enough for our needs yet.

==Compilers==

===PNaCl Clang===

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.

===Saigo===

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

Unlike PNaCl, Saigo do not provide released binaries, meaning a switch to Saigo requires a convenient way to provide it to contributors.

For now it has been successful to build an {{code|sgame.nexe}} (server game binary) with Saigo and run it, so with more efforts it may be possible to also build the {{code|cgame.exe}} (client game binary) as well and drop PNaCl.

Google provides some nightly Linux amd64 Saigo toolchain snapshots that aren't easy to get without some Google scripts.

The Saigo compiler and other related toolchain tools should build everywhere their upstream build, but only targeting the usual platforms, as the nacl_loader is basically the same: a more recent nacl_loader is also buildable but doesn't bring new platform supports.

The Saigo compiler itself isn't hard to build (same as Clang itself), what is more complex is to get the toolchain and the libc/libc++ to build.

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

Moving to Saigo is considered as a migration step that can be achievablebefore 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 at migrating to Saigo:

* https://github.com/Unvanquished/Unvanquished/issues/3197

The workspace for our attempt to rebuild and repackage Saigo is there:

* https://github.com/DaemonEngine/DaemonSaigoNativeClientToolkit

== 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://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>
# Start the program by continuing (<code>c</code>).

Caveat: the debugger does NOT catch fatal errors like segmentation fault or division by 0. You will have to rely on postmortem debugging for that.

== Postmortem Debugging ==

See [[Breakpad]].

Native Client

2025-01-16T08:21:36Z

Killing time: /* Interactive Debugging */ update with illwieckz's findings

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

It replaced the Q3VM (Quake3 Virtual Machine) in the engine.

Unlike Q3VM for which the {{code|.qvm}} binaries were limited to be produced with the old C supported by the proprietary LCC compiler, the {{code|.nexe}} NaCl binaries can be compiled with Clang-based open source compilers supporting modern-enough C++ versions and allowing to reuse off-the-shelf C++ libraries that may even be shared between the engine and the game source code.

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/].

==Platforms==

{| style="margin:auto"
|+ Platform NaCl compatibility
|-
! colspan="4" | Linux !! colspan="2" | Windows !! colspan="2" | macOS !! FreeBSD
|-
! amd64 || i686 || arm64 || armhf || amd64 || i686 || amd64 || arm64 || amd64
|-
| ✅️ native || ✅️ native || ☑️ through armhf<br/>compatibility || ✅️ native || ✅️ native || ✅️ native || ✅️ native || ☑️ through amd64<br/>compatibility || ☑️ through Linux<br/>compatibility
|}

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 32-bit compatibility;
* macOS, arm64: running the amd64 NaCl loader through Rosetta2 compatibility;
* FreeBSD, amd64: running the Linux NaCl loader through built-in Linuxulator compatibility.

The Linux armhf NaCl loader requires a 4k PageSize kernel:

* https://github.com/Unvanquished/Unvanquished/issues/3286

The Linux i686 and armhf NaCl loaders may run on FreeBSD using Linuxulator but it is not tested.

NaCl also supports 32-bit MIPS on Linux but this architecture is not supported by the {{engine}} and the {{game}} project.

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 also lacks support for some platforms NaCl supports, like i686 or armhf, but more importantly lacks support for exceptions or {{code|setjmp/longjmp}} and then isn't complete enough for our needs yet.

==Compilers==

===PNaCl Clang===

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.

===Saigo===

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

Unlike PNaCl, Saigo do not provide released binaries, meaning a switch to Saigo requires a convenient way to provide it to contributors.

For now it has been successful to build an {{code|sgame.nexe}} (server game binary) with Saigo and run it, so with more efforts it may be possible to also build the {{code|cgame.exe}} (client game binary) as well and drop PNaCl.

Google provides some nightly Linux amd64 Saigo toolchain snapshots that aren't easy to get without some Google scripts.

The Saigo compiler and other related toolchain tools should build everywhere their upstream build, but only targeting the usual platforms, as the nacl_loader is basically the same: a more recent nacl_loader is also buildable but doesn't bring new platform supports.

The Saigo compiler itself isn't hard to build (same as Clang itself), what is more complex is to get the toolchain and the libc/libc++ to build.

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

Moving to Saigo is considered as a migration step that can be achievablebefore 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 at migrating to Saigo:

* https://github.com/Unvanquished/Unvanquished/issues/3197

The workspace for our attempt to rebuild and repackage Saigo is there:

* https://github.com/DaemonEngine/DaemonSaigoNativeClientToolkit

== 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://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>
# Start the program by continuing (<code>c</code>).

Caveat: the debugger does NOT catch fatal errors like segmentation fault or division by 0. You will have to rely on postmortem debugging for that.

== Postmortem Debugging ==

See [[Breakpad]].

Native Client

2025-01-16T05:40:17Z

Killing time: nacl debugging tutorial

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

It replaced the Q3VM (Quake3 Virtual Machine) in the engine.

Unlike Q3VM for which the {{code|.qvm}} binaries were limited to be produced with the old C supported by the proprietary LCC compiler, the {{code|.nexe}} NaCl binaries can be compiled with Clang-based open source compilers supporting modern-enough C++ versions and allowing to reuse off-the-shelf C++ libraries that may even be shared between the engine and the game source code.

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/].

==Platforms==

{| style="margin:auto"
|+ Platform NaCl compatibility
|-
! colspan="4" | Linux !! colspan="2" | Windows !! colspan="2" | macOS !! FreeBSD
|-
! amd64 || i686 || arm64 || armhf || amd64 || i686 || amd64 || arm64 || amd64
|-
| ✅️ native || ✅️ native || ☑️ through armhf<br/>compatibility || ✅️ native || ✅️ native || ✅️ native || ✅️ native || ☑️ through amd64<br/>compatibility || ☑️ through Linux<br/>compatibility
|}

The NaCl loader (the virtual machine running the virtualized 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 32-bit compatibility;
* macOS:
** arm64, running the amd64 NaCl loader through Rosetta2 compatibility.
* FreeBSD:
** amd64, running the Linux NaCl loader through built-in Linuxulator compatibility.

The Linux i686 and armhf NaCl loaders may run on FreeBSD using Linuxulator but it is not tested.

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 also lacks support for some platforms NaCl supports, like i686 or armhf).

NaCl also supports 32-bit MIPS on Linux but this architecture is not supported by the {{engine}} and the {{game}} project.

==Compilers==

===PNaCl===

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

===Saigo===

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

Unlike PNaCl, Saigo do not provide released binaries, meaning a switch to Saigo requires a convenient way to provide it to contributors.

For now it has been successful to build an {{code|sgame.nexe}} (server game binary) with Saigo and run it, so with more efforts it may be possible to also build the {{code|cgame.exe}} (client game binary) as well and drop PNaCl.

Google provides some nightly Linux amd64 Saigo toolchain snapshots that aren't easy to get without some Google scripts.

The Saigo compiler and other related toolchain tools should build everywhere their upstream build, but only targeting the usual platforms, as the nacl_loader is basically the same: a more recent nacl_loader is also buildable but doesn't bring new platform supports.

The Saigo compiler itself isn't hard to build (same as Clang itself), what is more complex is to get the toolchain and the libc/libc++ to build.

Saigo may not support C++ exceptions as far as we know.

Moving to Saigo can be considered as a first step before migrating to [[WebAssembly]], as it would allow us to migrate to a new C++ standard before migrating to WebAssembly, and the redesign of our CMake configuration for Saigo may help later when migrating to WebAssembly.

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

* https://github.com/DaemonEngine/Daemon/issues/795

== 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://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. It is not yet known whether the Saigo toolchain admits any interactive debugging. On Linux or Mac you may experience more difficulties due to the lack of support for old binaries (meaning nacl-gdb).

# 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>
# Start the program by continuing (<code>c</code>).

Caveat: the debugger does NOT catch fatal errors like segmentation fault or division by 0. You will have to rely on postmortem debugging for that.

== Postmortem Debugging ==

See [[Breakpad]].

Formats/Trail

2025-01-09T04:29:39Z

Killing time: link trail-keyword-directory

[[Category:Formats]]
[[Category:Mapping]]
Trail effects work the same as Tremulous. Please see the [https://web.archive.org/web/20200416190204/http://tremulous.net/manual/#x1-140003.3 Tremulous documentation] ([https://dl.unvanquished.net/docs/20060317-000.tremulous-manual.pdf pdf]) for information on creating particle effects for now.

Trail format is game-specific (mods may modify it).

To look for examples of how some trail feature is used, you may use this [https://users.unvanquished.net/~slipher/trail-keyword-directory.txt trail keyword directory].

Formats/Particle

2025-01-09T04:27:50Z

Killing time: link particle-keyword-directory

Continuous integration

2024-11-19T12:14:35Z

Killing time: macos image bump

[[Category:Infrastructure]]
Continuous integration (CI) refers to the automated builds that run each time someone opens or modifies a pull request against, or modifies the code of, the Unvanquished and Daemon source code repositories on GitHub.

We use the following CI services:
* Appveyor, for building with MSVC on Windows. Its configuration is found in the file {{code|.appveyor.yml}} in the repository root.
* Azure Pipelines. Its configuration is found in the file {{code|azure-pipelines.yml}} in the repository root. It handles Mac native builds on [https://github.com/actions/virtual-environments/blob/main/images/macos/macos-14-Readme.md macOS 14.x] and Linux native and NaCl builds on [https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2004-Readme.md Ubuntu 20.04] (Focal).
* GitHub CodeQL. Its configuration is found in the file {{code|.github/workflows/codeql.yml}} in the repository. Its purpose is to scan the source code for vulnerabilities, and for that purpose it starts by building the source tree using the latest LTS Ubuntu distribution provided by the platform ([https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2004-Readme.md Ubuntu 22.04]) and the default compiler of this platform.

In some Daemon builds, we run the unit tests. These builds have been configured to use the Release configuration so that the unit tests are closer to production builds.

== Build matrix ==

{|
! colspan="9" | {{engine}}
|-
! Service
! Host
! Target
! Compiler
! Generator
! Build Type
! WERROR
! PCH
! Unit tests
|-
| Appveyor || Windows amd64 || Windows amd64 || VS 2019 || Visual Studio || Release || Yes || No || Yes
|-
| Appveyor || Windows amd64 || Windows i686 || VS 2019 || Visual Studio || Release || Yes || No || Yes
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Windows amd64 || MinGW 9.3 || Ninja || Debug || Yes || No || No
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 || GCC 9.4 || Ninja || Release || Yes || No || Yes
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 || Clang 11.0 || Ninja || Release || Yes || No || Yes
|-
| Azure Pipelines || macOS-14 amd64 || macOS amd64 || AppleClang 15.0 || Make || Release || Yes || No || Yes
|-
| GitHub Actions CodeQL || ubuntu-latest || Linux amd64 || GCC (floating) || Ninja || Release || No || Yes || No
|}
<br>
{|
! colspan="8" | {{game}}
|-
! Service
! Host
! Target
! Compiler
! Generator
! Build Type
! WERROR
! PCH
|-
| Appveyor || Windows amd64 || Windows i686 DLL || VS 2019 || NMake || Debug || Yes || No
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 DLL || GCC 8.4 || Ninja || Debug || Yes || No
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 DLL || Clang 11.0 || Ninja || Debug || Yes || No
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || NaCl all NEXE || PNaCl Clang 3.6 || Ninja || Debug || Yes || No
|-
| Azure Pipelines || macOS-14 amd64 || macOS amd64 DLL || AppleClang 15.0 || Make || Debug || Yes || No
|-
| GitHub Actions CodeQL || ubuntu-latest || Linux amd64 DLL+EXE || GCC (floating) || Ninja || Release || No || Yes
|}

“WERROR” indicates whether the {{code|USE_WERROR}} option is on, which gives a failing building build status if there are warnings in our code. Note that {{code|USE_WERROR}} only applies to ”our” code in {{code|src/}}, so you may still see warnings from stuff in {{code|libs/}}.

“PCH” indicates whether the precompiled header is enabled.

Continuous integration

2024-11-19T00:02:13Z

Killing time: /* Build matrix */ Unvanquished macos bump

[[Category:Infrastructure]]
Continuous integration (CI) refers to the automated builds that run each time someone opens or modifies a pull request against, or modifies the code of, the Unvanquished and Daemon source code repositories on GitHub.

We use the following CI services:
* Appveyor, for building with MSVC on Windows. Its configuration is found in the file {{code|.appveyor.yml}} in the repository root.
* Azure Pipelines. Its configuration is found in the file {{code|azure-pipelines.yml}} in the repository root. It handles Mac native builds on [https://github.com/actions/virtual-environments/blob/main/images/macos/macos-11-Readme.md macOS 11.x] and Linux native and NaCl builds on [https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2004-Readme.md Ubuntu 20.04] (Focal).
* GitHub CodeQL. Its configuration is found in the file {{code|.github/workflows/codeql.yml}} in the repository. Its purpose is to scan the source code for vulnerabilities, and for that purpose it starts by building the source tree using the latest LTS Ubuntu distribution provided by the platform ([https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2004-Readme.md Ubuntu 22.04]) and the default compiler of this platform.

In some Daemon builds, we run the unit tests. These builds have been configured to use the Release configuration so that the unit tests are closer to production builds.

== Build matrix ==

{|
! colspan="9" | {{engine}}
|-
! Service
! Host
! Target
! Compiler
! Generator
! Build Type
! WERROR
! PCH
! Unit tests
|-
| Appveyor || Windows amd64 || Windows amd64 || VS 2019 || Visual Studio || Release || Yes || No || Yes
|-
| Appveyor || Windows amd64 || Windows i686 || VS 2019 || Visual Studio || Release || Yes || No || Yes
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Windows amd64 || MinGW 9.3 || Ninja || Debug || Yes || No || No
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 || GCC 9.4 || Ninja || Release || Yes || No || Yes
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 || Clang 11.0 || Ninja || Release || Yes || No || Yes
|-
| Azure Pipelines || macOS-11 amd64 || macOS amd64 || AppleClang 13.0 || Make || Release || Yes || No || Yes
|-
| GitHub Actions CodeQL || ubuntu-latest || Linux amd64 || GCC (floating) || Ninja || Release || No || Yes || No
|}
<br>
{|
! colspan="8" | {{game}}
|-
! Service
! Host
! Target
! Compiler
! Generator
! Build Type
! WERROR
! PCH
|-
| Appveyor || Windows amd64 || Windows i686 DLL || VS 2019 || NMake || Debug || Yes || No
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 DLL || GCC 8.4 || Ninja || Debug || Yes || No
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 DLL || Clang 11.0 || Ninja || Debug || Yes || No
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || NaCl all NEXE || PNaCl Clang 3.6 || Ninja || Debug || Yes || No
|-
| Azure Pipelines || macOS-14 amd64 || macOS amd64 DLL || AppleClang 15.0 || Make || Debug || Yes || No
|-
| GitHub Actions CodeQL || ubuntu-latest || Linux amd64 DLL+EXE || GCC (floating) || Ninja || Release || No || Yes
|}

“WERROR” indicates whether the {{code|USE_WERROR}} option is on, which gives a failing building build status if there are warnings in our code. Note that {{code|USE_WERROR}} only applies to ”our” code in {{code|src/}}, so you may still see warnings from stuff in {{code|libs/}}.

“PCH” indicates whether the precompiled header is enabled.

Formats/Behavior tree

2024-11-14T12:08:23Z

Killing time: /* Syntax Reference */ move concurrent after other branching nodes

[[Category:Formats]]
[[Category:Bots]]
Behavior trees file format is game-specific (mods may modify it).

= Introduction =

Bot behaviors are decided individually, at each "frame" (read: server's main loop passage), starting from a root node. Evaluation stops at a node which returns STATUS_RUNNING, or when the root node returns success or failure. An overview can be found in the [https://en.wikipedia.org/wiki/Behavior_tree_(artificial_intelligence,_robotics_and_control) Wikipedia article].

= Syntax Reference =

Behavior trees use a specific syntax, which obey following rules (guessed from actual implementation and some C++ readings):

* Each node or leaf returns either <code>STATUS_SUCCESS</code>, <code>STATUS_FAILURE</code> or <code>STATUS_RUNNING</code>.
* whitespace has no semantic meaning
* comments (C and C++-style) can either:
:* start with <code>//</code> and go to the end of line
:* start with <code>/*</code> and go to next <code>*/</code>, including out of current line. These do not nest.
* actions and conditions taking parameters must enclose those withing parentheses, separated with commas (i.e. <code>roamInRadius( E_H_REACTOR, 500 )</code>)
* if an action or a condition does not need parameters, parentheses are optional
* strings start and end with a double quote <code>"</code>
* values can't be stored or modified (additions, subtractions, multiplications, etc)
* no user-defined function (but files can be included, and C++ functions can be written in the game logic and be used in the behavior tree)
* each possible path should (TODO: verify, even if I fail to understand why one would break that willingly) end by one or more action

Note:

It is not possible to do mathematical operations such as additions, multiplications, divisions, ...

== Keywords ==

There are several keywords:

* behavior
* action
* sequence
* selector
* fallback
* concurrent
* decorator
* condition

== The <code>behavior</code> keyword ==

behavior NAME

Include named behavior at current place. This does not make a new copy of the referenced tree, so if you include the same behavior more than once, node-specific state (e.g. timers) will be shared between the includes.

== The <code>action</code> keyword ==

action NAME

action NAME()

action NAME( param )

action NAME( param1, param2, ..., paramN )

Leaves of the tree, they trigger an action from the bot.

=== List of actions ===

Titles provide a link to more detailed pages.
TODO: have something more time-resilient (one page per call, with it's changelog, maybe?)

==== 0.53.1 ====

* activateUpgrade
* aimAtGoal
* alternateStrafe
* buy
* changeGoal
* classDodge
* deactivateUpgrade
* equip
* evolve
* evolveTo
* fight
* fireWeapon
* flee
* gesture
* heal
* jump
* moveInDir
* moveTo
* moveToGoal
* repair
* resetStuckTime
* roam
* roamInRadius
* rush
* say
* strafeDodge
* suicide
* teleport

=== Creating new actions ===

Actions are exported in the <code>AIActionMap_s AIActions[]</code> C array.
Actions always return a status.
Actions can take a variable number of parameters (they have minimum and maximum parameter numbers).
Parameter types are not described by API.

== The <code>sequence</code> keyword ==

sequence
{
NODE_1
NODE_2
...
NODE_N
}

Sequential nodes evaluate each children one after the other, as long as they return <code>STATUS_SUCCESS</code>.
Return last child's status.

* Sequence breaks if a child returns <code>STATUS_RUNNING</code>
* Starts at last <code>STATUS_RUNNING</code>, if any. Nodes that completed successfully in a previous frame are not rerun, as long as the sequence is running continually.

== The <code>selector</code> keyword ==

selector
{
NODE_1
NODE_2
...
NODE_N
}

Selector nodes evaluate each children one after the other, as long as they return <code>STATUS_FAILURE</code>.
Return last child's status.
Unlike sequence, this node is stateless: it does not restart from the last <code>STATUS_RUNNING</code>.

== The <code>fallback</code> keyword ==

fallback
{
NODE_1
NODE_2
...
NODE_N
}

Fallback nodes start by evaluating the first children, and switch to the next one if a child returns <code>STATUS_FAILURE</code>. It will continue from the last <code>STATUS_RUNNING</code> child.
Return last child's status.

Difference with sequence:

* Sequence switch to the next child on <code>STATUS_SUCCESS</code>, while fallback switch to the next child on code>STATUS_SUCCESS</code>

Difference with selector:
* Starts at last <code>STATUS_RUNNING</code>, if any

== {{Discouraged}} The <code>concurrent</code> keyword ==

This is a very niche node type, for experts only! As of 0.55.1, the return value is wrong: it may return STATUS_SUCCESS while there are running nodes (should be fixed for 0.56).

concurrent
{
NODE_1
NODE_2
...
NODE_N
}

Concurrent nodes evaluate each children until one returns <code>STATUS_FAILURE</code>. Along with <code>decorator return</code>, it is one of two ways that BT evaluation can continue after a node evaluates to <code>STATUS_RUNNING</code>. It is most similar to <code>sequence</code>, except the different treatment of running nodes. It is much less useful than it sounds first, because the behavior tree can only remember one long-running action at a time. If you have two long-running actions in a concurrent node, they will NOT work correctly, constantly forgetting their goals. So usage of concurrent is limited to combining one-shot actions with a single long-running one. freem discovered the following use case:

concurrent
{
action fight
decorator return( STATUS_SUCCESS )
{
condition goalType == ET_BUILDABLE && goalTeam == TEAM_ALIENS && inAttackRange( E_GOAL )
{
action moveInDir( MOVE_BACKWARD )
}
}
}

== The <code>decorator</code> keyword ==

decorator TYPE( VALUE )
{
NODE_1
NODE_2
...
NODE_N
}

Decorator nodes alters their children's behavior.
Decorator types:

* return
* invert
* timer

== The <code>return</code> decorator ==

Force children nodes to return a specific value

== The <code>invert</code> decorator ==

An <code>invert</code> node will negate the return value of its node, <code>STATUS_SUCCESS<code> is turned into <code>STATUS_FAILURE</code> and <code>STATUS_FAILURE</code> is turned into <code>STATUS_SUCCESS</code>. <code>STATUS_RUNNING</code> is unaffected.

== The <code>timer</code> keyword ==

On encountering a <code>timer( <i>N</i> )</code> node, <code>STATUS_FAILURE</code> is immediately returned if the timer's child node has already returned <code>STATUS_FAILURE</code> within the last N milliseconds.

The node may run more often than every N milliseconds if it keeps returning success.

== The <code>condition</code> keyword ==

condition EXPRESSION

condition EXPRESSION
{
NODE
}

The first form immediately returns ''EXPRESSION'' as its status: <code>STATUS_SUCCESS</code> for true and <code>STATUS_FAILURE</code> for false.

The second form returns <code>STATUS_FAILURE</code> if the expression is false, or otherwise the child's status. Note that ''EXPRESSION'' is re-evaluated every frame. If it becomes false at any time during execution of the child node, the child subtree aborts and the condition node returns failure.

The idiom
sequence {
condition EXPRESSION
action myLongRunningAction
}
is used to check a condition once before starting an action, but in subsequent continue doing the action without re-evaluating the condition.

Note:

* only executes a single child.
* EXPRESSION can include function calls.

== Operators ==

Operators are listed in the <code>AIOpMap_s conditionOps[]</code> array.
operators sorted by precedence (1st have higher priority):
* "!"
* "<"
* "<="
* ">"
* ">="
* "=="
* "!="
* "&&"
* "||"

== Functions ==

Return value is "boxed" (<code>AIBox<T>()</code>) in the C++ code.
Conditions are exported in the <code>AIConditionMap_s conditionFuncs[]</code> array.

=== List of functions (as of 0.53.1) ===

* alertedToEnemy
* aliveTime
* baseRushScore
* buildingIsDamaged
* canEvolveTo
* class
* cvar
* directPathTo
* distanceTo
* goalBuildingType
* goalIsDead
* goalTeam
* goalType
* haveUpgrade
* haveWeapon
* healScore
* inAttackRange
* isVisible
* matchTime
* momentum
* percentAmmo
* percentHealth
* random
* skill
* stuckTime
* team
* teamateHasWeapon
* weapon

== Pre-defined symbols ==

Some values are pre-defined and usable as action's or function's parameters.

Those are exported by calling a macro named 'D' (yes, I know).
List of exported symbols:

* human upgrades (including medkit)
* human weapons (excluding blaster)
* team names (aliens, humans, and none)
* alien buildings
* human buildings
* <code>E_GOAL</code>
* <code>E_ENEMY</code>
* <code>E_DAMAGEDBUILDING</code>
* <code>E_SELF</code>
* classes (human ones, alien ones, and <code>PCL_NONE</code>)
* moves (forward, backward, right, left)
* some say commands (all, team, area, area_team)
* task/check status names (running, success, failure)

== Notes ==

Parameters needs to be (un)wrapped in C++ before being accessed.

Parameters can be of the following (C) types:
* float
* int (probably better assume 32 bit signed integers)
* string (probably better assume null-terminated)

To provide a value to an action or check, the C++ code must UnBox (<code>AIUnBox<T>()</code>) it.

Formats/Behavior tree

2024-11-14T09:54:29Z

Killing time: /* {{Discouraged}} The concurrent keyword */ describe a valid use case

[[Category:Formats]]
[[Category:Bots]]
Behavior trees file format is game-specific (mods may modify it).

= Introduction =

Bot behaviors are decided individually, at each "frame" (read: server's main loop passage), starting from a root node. Evaluation stops at a node which returns STATUS_RUNNING, or when the root node returns success or failure. An overview can be found in the [https://en.wikipedia.org/wiki/Behavior_tree_(artificial_intelligence,_robotics_and_control) Wikipedia article].

= Syntax Reference =

Behavior trees use a specific syntax, which obey following rules (guessed from actual implementation and some C++ readings):

* Each node or leaf returns either <code>STATUS_SUCCESS</code>, <code>STATUS_FAILURE</code> or <code>STATUS_RUNNING</code>.
* whitespace has no semantic meaning
* comments (C and C++-style) can either:
:* start with <code>//</code> and go to the end of line
:* start with <code>/*</code> and go to next <code>*/</code>, including out of current line. These do not nest.
* actions and conditions taking parameters must enclose those withing parentheses, separated with commas (i.e. <code>roamInRadius( E_H_REACTOR, 500 )</code>)
* if an action or a condition does not need parameters, parentheses are optional
* strings start and end with a double quote <code>"</code>
* values can't be stored or modified (additions, subtractions, multiplications, etc)
* no user-defined function (but files can be included, and C++ functions can be written in the game logic and be used in the behavior tree)
* each possible path should (TODO: verify, even if I fail to understand why one would break that willingly) end by one or more action

Note:

It is not possible to do mathematical operations such as additions, multiplications, divisions, ...

== Keywords ==

There are several keywords:

* behavior
* action
* sequence
* selector
* fallback
* concurrent
* decorator
* condition

== The <code>behavior</code> keyword ==

behavior NAME

Include named behavior at current place. This does not make a new copy of the referenced tree, so if you include the same behavior more than once, node-specific state (e.g. timers) will be shared between the includes.

== The <code>action</code> keyword ==

action NAME

action NAME()

action NAME( param )

action NAME( param1, param2, ..., paramN )

Leaves of the tree, they trigger an action from the bot.

=== List of actions ===

Titles provide a link to more detailed pages.
TODO: have something more time-resilient (one page per call, with it's changelog, maybe?)

==== 0.53.1 ====

* activateUpgrade
* aimAtGoal
* alternateStrafe
* buy
* changeGoal
* classDodge
* deactivateUpgrade
* equip
* evolve
* evolveTo
* fight
* fireWeapon
* flee
* gesture
* heal
* jump
* moveInDir
* moveTo
* moveToGoal
* repair
* resetStuckTime
* roam
* roamInRadius
* rush
* say
* strafeDodge
* suicide
* teleport

=== Creating new actions ===

Actions are exported in the <code>AIActionMap_s AIActions[]</code> C array.
Actions always return a status.
Actions can take a variable number of parameters (they have minimum and maximum parameter numbers).
Parameter types are not described by API.

== {{Discouraged}} The <code>concurrent</code> keyword ==

This is a very niche node type, for experts only! As of 0.55.1, the return value is wrong: it may return STATUS_SUCCESS while there are running nodes (should be fixed for 0.56).

concurrent
{
NODE_1
NODE_2
...
NODE_N
}

Concurrent nodes evaluate each children until one returns <code>STATUS_FAILURE</code>. Along with <code>decorator return</code>, it is one of two ways that BT evaluation can continue after a node evaluates to <code>STATUS_RUNNING</code>. It is most similar to <code>sequence</code>, except the different treatment of running nodes. It is much less useful than it sounds first, because the behavior tree can only remember one long-running action at a time. If you have two long-running actions in a concurrent node, they will NOT work correctly, constantly forgetting their goals. So usage of concurrent is limited to combining one-shot actions with a single long-running one. freem discovered the following use case:

concurrent
{
action fight
decorator return( STATUS_SUCCESS )
{
condition goalType == ET_BUILDABLE && goalTeam == TEAM_ALIENS && inAttackRange( E_GOAL )
{
action moveInDir( MOVE_BACKWARD )
}
}
}

== The <code>sequence</code> keyword ==

sequence
{
NODE_1
NODE_2
...
NODE_N
}

Sequential nodes evaluate each children one after the other, as long as they return <code>STATUS_SUCCESS</code>.
Return last child's status.

* Sequence breaks if a child returns <code>STATUS_RUNNING</code>
* Starts at last <code>STATUS_RUNNING</code>, if any. Nodes that completed successfully in a previous frame are not rerun, as long as the sequence is running continually.

== The <code>selector</code> keyword ==

selector
{
NODE_1
NODE_2
...
NODE_N
}

Selector nodes evaluate each children one after the other, as long as they return <code>STATUS_FAILURE</code>.
Return last child's status.
Unlike sequence, this node is stateless: it does not restart from the last <code>STATUS_RUNNING</code>.

== The <code>fallback</code> keyword ==

fallback
{
NODE_1
NODE_2
...
NODE_N
}

Fallback nodes start by evaluating the first children, and switch to the next one if a child returns <code>STATUS_FAILURE</code>. It will continue from the last <code>STATUS_RUNNING</code> child.
Return last child's status.

Difference with sequence:

* Sequence switch to the next child on <code>STATUS_SUCCESS</code>, while fallback switch to the next child on code>STATUS_SUCCESS</code>

Difference with selector:
* Starts at last <code>STATUS_RUNNING</code>, if any

== The <code>decorator</code> keyword ==

decorator TYPE( VALUE )
{
NODE_1
NODE_2
...
NODE_N
}

Decorator nodes alters their children's behavior.
Decorator types:

* return
* invert
* timer

== The <code>return</code> decorator ==

Force children nodes to return a specific value

== The <code>invert</code> decorator ==

An <code>invert</code> node will negate the return value of its node, <code>STATUS_SUCCESS<code> is turned into <code>STATUS_FAILURE</code> and <code>STATUS_FAILURE</code> is turned into <code>STATUS_SUCCESS</code>. <code>STATUS_RUNNING</code> is unaffected.

== The <code>timer</code> keyword ==

On encountering a <code>timer( <i>N</i> )</code> node, <code>STATUS_FAILURE</code> is immediately returned if the timer's child node has already returned <code>STATUS_FAILURE</code> within the last N milliseconds.

The node may run more often than every N milliseconds if it keeps returning success.

== The <code>condition</code> keyword ==

condition EXPRESSION

condition EXPRESSION
{
NODE
}

The first form immediately returns ''EXPRESSION'' as its status: <code>STATUS_SUCCESS</code> for true and <code>STATUS_FAILURE</code> for false.

The second form returns <code>STATUS_FAILURE</code> if the expression is false, or otherwise the child's status. Note that ''EXPRESSION'' is re-evaluated every frame. If it becomes false at any time during execution of the child node, the child subtree aborts and the condition node returns failure.

The idiom
sequence {
condition EXPRESSION
action myLongRunningAction
}
is used to check a condition once before starting an action, but in subsequent continue doing the action without re-evaluating the condition.

Note:

* only executes a single child.
* EXPRESSION can include function calls.

== Operators ==

Operators are listed in the <code>AIOpMap_s conditionOps[]</code> array.
operators sorted by precedence (1st have higher priority):
* "!"
* "<"
* "<="
* ">"
* ">="
* "=="
* "!="
* "&&"
* "||"

== Functions ==

Return value is "boxed" (<code>AIBox<T>()</code>) in the C++ code.
Conditions are exported in the <code>AIConditionMap_s conditionFuncs[]</code> array.

=== List of functions (as of 0.53.1) ===

* alertedToEnemy
* aliveTime
* baseRushScore
* buildingIsDamaged
* canEvolveTo
* class
* cvar
* directPathTo
* distanceTo
* goalBuildingType
* goalIsDead
* goalTeam
* goalType
* haveUpgrade
* haveWeapon
* healScore
* inAttackRange
* isVisible
* matchTime
* momentum
* percentAmmo
* percentHealth
* random
* skill
* stuckTime
* team
* teamateHasWeapon
* weapon

== Pre-defined symbols ==

Some values are pre-defined and usable as action's or function's parameters.

Those are exported by calling a macro named 'D' (yes, I know).
List of exported symbols:

* human upgrades (including medkit)
* human weapons (excluding blaster)
* team names (aliens, humans, and none)
* alien buildings
* human buildings
* <code>E_GOAL</code>
* <code>E_ENEMY</code>
* <code>E_DAMAGEDBUILDING</code>
* <code>E_SELF</code>
* classes (human ones, alien ones, and <code>PCL_NONE</code>)
* moves (forward, backward, right, left)
* some say commands (all, team, area, area_team)
* task/check status names (running, success, failure)

== Notes ==

Parameters needs to be (un)wrapped in C++ before being accessed.

Parameters can be of the following (C) types:
* float
* int (probably better assume 32 bit signed integers)
* string (probably better assume null-terminated)

To provide a value to an action or check, the C++ code must UnBox (<code>AIUnBox<T>()</code>) it.

GPU compatibility matrix

2024-11-13T08:34:32Z

Killing time: /* Comprehensive analysis */ update required extensions

{{KnownGraphicalBugs}}

This table gathers test results about various hardware and software configurations, <span style="background-color: green !important; color: white !important; padding: .25em .5em;">passed</span> means nothing wrong is noticed and frame rate is at least <u>60 fps</u> on common scene, <span style="background-color: lightgreen !important; color: green !important; padding: .25em .5em;">playable</span> means at least <u>30 fps</u>.

All those tests were driven by Unvanquished developers or under Unvanquished developer supervision.

See [[#Comprehensive_analysis|below]] for analysis, specific definitions and meanings.
{{GPU compatibility matrix}}

<br/><hr/><br/>

== Comprehensive analysis ==

The minimal configuration for the Unvanquished game is OpenGL 2.1. This includes cards like ATI R300 (Radeon X300, etc.), Nvidia NV40 (Curie, Geforce 6000 series), Intel GMA Gen 3 (3100) and 4 (X3100), etc. Unvanquished uses complex models and that may produce some slow-downs on such OpenGL 2.1 hardware. Such hardware is meant to be running with the {{code|lowest}} graphics preset on very low resolutions like {{code|640×480}}, with some high end cards from those generations it may be possible to use the {{code|low}} or even {{code|medium}} graphics preset and run some “HD Ready” {{code|1280×720}} or even “Full HD” {{code|1920×1080}} resolutions.

Full performance (given advanced graphical effects are disabled) starts with OpenGL 3.2 devices, this includes AMD/ATI TeraScale GPU, Intel HD Graphics (HD 4000), and Nvidia Tesla-based GPUs. They are expected to sustain the {{code|high}} graphics preset with a “Full HD” {{code|1920×1080}} resolutions. Some high-end cards from this generation may even sustain the {{code|ultra}} graphics presets and/or a 2K resolution.

To play at 4K resolution with an {{code|ultra}}, high-end AMD GCN/RDNA and devices from similar generations from other vendors are recommended. For example an AMD R9 390X from 2015 can handle <code>ultra</code> preset with 4K resolution at 144Hz. An AMD R7 Embedded in R series APU can handle 2K resolution with <code>medium</code> preset (no realtime light and relief mapping disabled) as well as Intel UHD.

Minimal configuration to run the Dæmon engine is OpenGL 2.1 with <code>ARB_half_float_vertex</code> or <code>EXT_framebuffer_object</code> + <code>EXT_framebuffer_blit</code>. It includes ATI/AMD GPU starting with R300 (Radeon X300), Intel GPU starting with GMA965 (X3100) on Linux and macOS, HD Graphics on Windows, Nvidia starting with Curie (NV40, Geforce 6xxx).

Speaking about OpenGL 2.1, Wikipedia says the GMA965 Windows driver only supports OpenGL 1.5 and then would not reach the requirements for running the Dæmon engine and then Unvanquished on this platform (it would only run on Linux). If you plan to make a game using the Damon engine and to support those older cards, it's better if your animated models don't have more than 41 bones (or you provide additional low quality models with less bones).

== How to contribute ==

This matrix is generated from a cell sheet. Do not edit it by hand, Please ask <code>illwieckz</code> for access to the cell sheet.

Please sort your contributions by brand (ATI/AMD, Intel, Nvidia, Via…) then by launch date (from newer to older).

The table also documents who may be able to reproduce a special configuration, please put your nick name and tell how much it is easy for you to reproduce a test on it (see below for keywords to use).

Please tell at least, brand, model, model launch date (look at Wikipedia), host, memory size, the operating system, the driver (kernel mode and user mode), OpenGL and GLSL version, Unvanquished version you tested, the status, the preset and the resolution you validated and eventual notes.

If you find out the code name and related micro architecture, please note it, same with form factor and bus.

Other data are less relevant for diagnostic and are only useful to get a better picture of the tested hardware, don't hesitate to write down as much info as you can.

Append the <code>~</code> character to version number if you're testing a preversion. For example use <code>0.52~</code> to tell you tested against the to-be-released 0.52 version.

Put a single <code>-</code> character in cell you don't have data for (do not leave empty cells). When you describe multiple configuration for the same piece of hardware, use the <code>↑</code> character to tell the cell uses the same value as the previous line.

== Definitions ==

=== Status ===

* '''hang''': the computer becomes unresponsive, requiring a hard reset;
* '''crash''': the game is terminated by the operating system on some unrecoverable failure;
* '''missing''': the game exits by itself because of some requirement not being met;
* '''broken''': the game loads maps but graphical bugs affecting gameplay are seen;
* '''glitchy''': the game loads maps but graphical bugs non-affecting gameplay are seen;
* '''slow''': the game is rendered properly but slowly with less than 30 fps;
* '''playable''': nothing wrong is noticed and frame rate is at least 30 fps but less than 60 fps;
* '''passed''': nothing wrong is noticed and frame rate is at least 60 fps.

=== Availability ===

* '''lost''': tester has lost access to the hardware;
* '''foreign''': tester has access to the hardware but does not own it;
* '''unplugged''': tester owns the hardware but testing requires to plug the hardware in a computer;
* '''unconfigured''': hardware is plugged in a computer but making use of it requires software changes;
* '''configured''': hardware and software are ready to use for testing.

=== Notes ===

* '''extfbo''': this GPU provides {{code|EXT_framebuffer_object}} instead of {{code|ARB_framebuffer_object}};
* '''fakefps''': game displays high frame rate number but the experience is stuttering;
* '''hickups''': performance is globally correct, but sometimes the framerate drops a bit for a very short time;
* '''lowsky''': lowering texture size using at least <code>r_picmip 1</code> is required to avoid skybox graphical glitches;
* '''lowtex''': lowering texture size using at least <code>r_picmip 1</code> is required to avoid a computer hang;
* '''mesamain''': running the driver from Mesa {{code|main}} at the time of the test was required to get the game running or avoid major rendering bugs;
* '''noaccel''': no OpenGL hardware acceleration is implemented;
* '''nogather''': <code>GL_ARB_texture_gather</code> is wrongly advertised by the driver to be supported by this hardware, making the engine crash at startup (Nvidia proprietary driver bug). The engine ships some workaround for this driver bug, if you experience the crash on version 0.52 and later but can properly start the game with <code>-set r_arb_texture_gather 0</code> engine command line option, please reopen issue [https://github.com/DaemonEngine/Daemon/issues/368 Daemon#368];
* '''nohalfloatvertex''': missing <code>ARB_half_float_vertex</code> OpenGL extension;
* '''nohyperz''': <code>R600_DEBUG=nohyperz</code> environment variable is required to be set to avoid graphical glitches, see issues [https://github.com/DaemonEngine/Daemon/issues/343 Daemon#343] and [https://gitlab.freedesktop.org/mesa/mesa/-/issues/3290 Mesa#3290];
* '''norgtc''': <code>GL_ARB_texture_compression_rgtc</code> extension is not supported on this hardware, some texture may be loaded with swapped channels, especially normal maps. Engine implements special algorithms to workaround this, see issue [https://github.com/DaemonEngine/Daemon/issues/375 Daemon#375];
* '''nvidiagarbage''': this driver is so bad you have to be very lucky to get at least a desktop drawn on screen before the computer hangs. With or without the game, after some screen freezes and display server crashes the kernel will complain about the card having disconnected itself from the PCIe bus. This issue was verified on multiple cards of this generations that are known to run for months without crashing when using free open source drivers instead;
* '''slowmodel''': models with a lot of bones are known to induce severe frame drop on such hardware, see issue [https://github.com/Unvanquished/Unvanquished/issues/1207 Unvanquished#1207];
* '''tinyalu''': this hardware has a very small ALU (arithmetic logic unit), dynamic lighting must be disabled with <code>r_dynamicLight 0</code> to prevent the driver to abort GLSL shader compilation that may lead to an engine crash, see issue [https://github.com/DaemonEngine/Daemon/issues/344 Daemon#344].

=== Bus ===

* '''PCI''': [https://en.wikipedia.org/wiki/Peripheral_Component_Interconnect Peripheral Component Interconnect], slow multi-purpose bus for add-on cards, obsolete;
* '''PCI-X''': [https://en.wikipedia.org/wiki/PCI-X Peripheral Component Interconnect eXtended], enhanced version of PCI for servers and workstations, obsolete;
* '''AGP''': [https://en.wikipedia.org/wiki/Accelerated_Graphics_Port Accelerated Graphics Port], high-speed bus designed for graphic cards, obsolete;
* '''FSB''': [https://en.wikipedia.org/wiki/Front-side_bus Front-side bus], high-speed Intel system bus for CPUs, sometime used with onboard GPUs (example: GeForce 7050 + nForce 610i/630i);
* '''HT''': [https://en.wikipedia.org/wiki/HyperTransport HyperTransport], high-speed AMD system bus for CPUs, sometime used with onboard GPUs (example: GeForce 6150 LE + nForce 430);
* '''chip''': Internal bus of a [https://en.wikipedia.org/wiki/System_on_a_chip system on a chip] (SoC), the exact communication bus technology is usually poorly documented;
* '''PCIe''': [https://en.wikipedia.org/wiki/PCI_Express PCI Express], high-speed multi-purpose bus for add-on cards and on-board devices, recommended;
* '''CXL''': [https://en.wikipedia.org/wiki/Compute_Express_Link, Compute Express Link], high-speed multi-purpose bus for add-on cards;
* '''TB''': [https://fr.wikipedia.org/wiki/Thunderbolt_(interface) ThunderBolt], high speed cable combining PCI Express and DisplayPort or USB-C to connect external PCI Express cards like GPUs.

=== Form factor ===

* '''discrete''': full height workstation extension card, with dedicated graphics memory;
* '''lowprofile''': low profile workstation extension card, with dedicated graphics memory;
* '''MXM''': [https://en.wikipedia.org/wiki/Mobile_PCI_Express_Module Mobile PCI Express module], laptop extension card, with dedicated graphics memory;
* '''onboard''': dedicated GPU on motherboard, low end ones may share memory with the CPU;
* '''integrated''': GPU integrated in CPU package or chipset, likely sharing memory with the CPU;
* '''SoC''': System on a chip, with the GPU likely sharing memory with the CPU;

=== Micro architecture ===

* '''USSA''': ATi Unified Superscalar Shader Architecture;
* '''GCN''': AMD Graphics Core Next;
* '''RDNA''': AMD Radeon DNA;
* '''GMA''': Intel Graphics Media Accelerator;
* '''GT''': Intel Graphics Technology.

=== Memory glossary ===

* '''HM''': HyperMemory, ATi technology using main memory when GPU memory is full;
* '''TC''': TurboCache, Nvidia technology using main memory when GPU memory is full;
* '''AR''': AcceleRAM, S3 technology using main memory when GPU memory is full.

== Useful resources ==

* [https://mesamatrix.net/ Mesa Matrix]
* [https://en.wikipedia.org/wiki/List_of_AMD_graphics_processing_units Wikipedia list of AMD graphics processing units]
* [https://en.wikipedia.org/wiki/List_of_AMD_accelerated_processing_units Wikipedia list of AMD accelerated processing units]
* [https://www.x.org/wiki/RadeonFeature/ X.Org Radeon feature matrix and decoder ring]
* [https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units Wikipedia list of Intel graphics processing units]
* [https://en.wikipedia.org/wiki/List_of_Nvidia_graphics_processing_units Wikipedia list of Nvidia graphics processing units]
* [https://nouveau.freedesktop.org/wiki/MesaDrivers/ Mesa Nouveau drivers]
* [https://nouveau.freedesktop.org/wiki/CodeNames/ Mesa Nouveau decoder ring]
* [https://opengl.gpuinfo.org/ User-submitted reports of OpenGL version and feature availability]

Compiling the source

2024-10-27T14:38:22Z

Killing time: /* macOS */ arm64 instructions

==Dependencies==

{{Note|content=In case this happens to become outdated, the up-to-date documentation can be found in the {{SourceFile|parameters=#unvanquished|README.md}} file in source repository.}}

The game requires some dependencies to be built, which are the same on all systems:

* cmake
* python3-yaml
* python3-jinja2
* A C++11 able compiler (those are known to work: clang (>= 3.5), gcc (>= 4.8), visual studio (>= 2019))
* zlib1g
* libgmp
* nettle
* libcurl4-gnutls
* libsdl2
* libglew
* libpng
* libjpeg-turbo8
* libwebp
* libfreetype6
* liblua5.3
* libopenal
* libogg
* libvorbis
* libopusfile

Those are optional:

* libncursesw5

==macOS==

First, you need to [[Getting_the_source|acquire the source code]].

Regardless of what interface you may use to compile the source, you will need [http://www.cmake.org/cmake/resources/software.html CMake] to generate makefiles. You will also need to install [https://developer.apple.com/xcode/ Xcode]. At a minimum, you must install the "Xcode command-line tools" in order to compile anything. You may also install Xcode proper, if you wish to use that IDE.

Once you have the source code and the tools installed, you may actually proceed to compile the source. You have several options:
* '''Compile the source at the command line'''. This is the easiest if you would just like to compile the game to use yourself and you do not intend to work on the code.
* '''Compile the source using an IDE'''. This is preferred if you intend on developing the source.
** Xcode is Apple's flagship IDE.
** [http://qt-project.org/downloads QtCreator] is cross-platform and provides real-time feedback of syntax errors, a Vim mode, as well as other features.
** [http://www.codeblocks.org/ Code::Blocks] is also cross-platform but lacks some of the features of Xcode and QtCreator.

===Dependencies===

Precompiled static libs are provided for all dependencies. CMake downloads them at configure time and extracts to <code>daemon/external_deps/macos-amd64-default_<i><version></i>/</code>. These were produced by the <code>external_deps/build.sh</code> script, which you could also use to build them yourself if you want to for some reason.

===Configuring with CMake===

# Run CMake.
# Enter the location of the source code.
# Enter the location in which you would like to build the source code. This should be a different directory.
# Click "Configure". You will be prompted as to which generator you would like to use. If you have Xcode installed, choose that. Wait while the configuration process runs. You may have to set the following:
## If you have selected to generate Xcode project files, make the <code>SDLMAIN_LIBRARY</code> field blank. This option is not available if you have the generator set to Unix makefiles.
# Click "Generate".
# You may now close CMake.

===Compiling===

====With Xcode====

<ol>
<li>Either start Xcode and open the project file (in the build directory you specified) or double-click the project file in Finder.</li>
<li>Open the project file created by CMake, which should be in the build directory you specified.</li>
<li>Change the active target to "ALL_BUILD" and click Product→Build.</li>
</ol>

====With Unix Makefiles====

<ul>
<li>Start Terminal (Applications → Utilities → Terminal).</li>
<li>Type the following commands:
<pre>
$ cd /path/to/Unvanquished-build
$ make
</pre>
If you are on a multi-core or multi-processor machine, you may speed up the process by passing the <code>-j</code> argument followed by the number of available cores to <code>make</code>; e.g., <code>make -j4</code>. Note that doing so makes reading error messages more difficult, as multiple instances of the compiler will print to the screen at once, causing information to appear out of order.
</li>
</ul>

===Testing the build===

====With Xcode 4====

To test the game, select the "client" scheme from the combo box on the toolbar, and click the run button or press {{Hotkey|MacCommand}}{{Hotkey|R}}.

=== Building for arm64 (Apple Silicon) architecture ===

Our CMake scripts default to amd64 architecture, but you can also make a native build for the latest ARM-based Macs. Albeit while still relying on Rosetta to run amd64-based Native Client gamelogic binaries.
<pre>
# Install Daemon + Unvanquished dependencies (no pre-built ones for this architecture)
brew install nettle sdl2 libogg libvorbis opus opusfile web freetype glew openal-soft

cmake path/to/source -DCMAKE_OSX_ARCHITECTURES=arm64 -DOpenAL_ROOT=$(brew --prefix openal-soft)

# If you want to run NaCl (assumes you have built amd64 at least once to download its deps):
cp path/to/daemon/external_deps/macos-amd64-default_10/{nacl_loader,irt_core-amd64.nexe} .
</pre>

==Windows==

===Visual Studio===

CMake can generate Visual Studio projects for Unvanquished.

# Add _NO_DEBUG_HEAP=1 to your environment variables otherwise performance under the debugger [http://www.massimpressionsprojects.com/dev/altdevblog/2011/07/27/the-unexpected-performance-of-debug-builds/ will be terrible]
# Run CMake with the source directory as the base directory of your source code (which should contain the directory <code>src</code>), and the build directory as a subdirectory of the source directory named <code>build</code>.
# Click the <b>Open Project</b> button. Or if you used CMake from the command line, open <code>build/Unvanquished.sln</code> in Visual Studio.
# In Visual Studio, choose your desired build type (default: <b>Debug</b>) from the drop-down menu in the top bar. <b>Debug</b> runs assertions and has complete debug information, but is slower. <b>RelWithDebInfo</b> is fast and still fairly usable with the debugger, but assertions don't run and sometimes you can't see the value of a local variable.
# Use Build → Build Solution to compile the code. Or just press {{Hotkey|F5}} to build and run, but beware: this will not automatically build cgame or sgame! Only engine changes are automatically rebuilt when you run something from Visual Studio.

====Important Notes====

* Due to limitations with CMake, the startup project cannot be specified. This must be set manually to debug the client with Visual Studio:
** Right click on client and select "Set as Startup project".

===MinGW===

It is possible to produce a Windows build of Unvanquished with [[MinGW]], as either a Windows or a Linux user. See [[MinGW#Distributions]] for detailed information about the toolchains available for installation.

====Instructions for native Windows build with MSYS2====

<ol>

<li> Install MSYS2. </li>
<li> Open the ''MSYS2 MinGW 32-bit'' or ''MSYS2 MinGW 64-bit'' terminal, depending on which bitness you want to build. </li>
</li> Install toolchain:
<pre>
# For 32-bit replace x86_64 with i686
pacman -Sy && pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake make
</pre> </li>
<li> Run CMake. If you're building Unvanquished, you may want to use the <code>-DDAEMON_CBSE_PYTHON_PATH=<path></code> option in case you want to use a different Python rather than the one in MSYS2. <pre>
mkdir mybuild && cd mybuild
cmake -G "MSYS Makefiles" somepath/Unvanquished
</pre> </li>
<li> Build:
<pre> make -j4 </pre>

If you would like verbose output (useful to see compiler flags), set the <code>VERBOSE</code> environment variable before running Make.
<pre>
export VERBOSE=1
</pre>

</li>
</ol>

You may find that the game (or some part of the MSYS2 toolchain!) fails to start due to missing DLL dependencies. Two helpful tools are:
<ul>
<li> The strace command in MSYS2, e.g. <code>strace ./daemon</code> </li>
<li> [https://github.com/lucasg/Dependencies Dependencies] (a Windows GUI program) </li>
</ul>

When distributing MinGW binaries, you need to distribute some additional DLLs besides the ones in the build folder. See [[MinGW#Built-in_DLL_dependencies]].

====MSYS2 Clang====
In MSYS2, it is possible to build with Clang, rather than GCC as shown as in the above instructions. However, some of our pre-built libraries are incompatible. You need to use the ones from pacman instead.

<ol>
<li> Create a deps folder with incompatible packages removed. This assumes that the latest version of the prebuilt deps for the mingw package of the appropriate bitness has already been extracted to the <code>windows-${ARCH}-mingw_${VERSION}</code> directory. In this example, we use <code>windows-amd64-mingw_8</code>. <pre>
cd somepath/daemon/external_deps
mkdir msysclang
cp windows-amd64-mingw_8 -R msysclang
find msysclang -depth -name '*freetype*' -o -name '*png*' -o name '*curl*' -o -name '*lua*' | grep -v pnacl | xargs rm -r
</pre> </li>
<li> Install those deps from Pacman: <pre>
# For Daemon
pacman -Sy && pacman -S mingw-w64-clang-x86_64-freetype mingw-w64-clang-x86_64-curl mingw-w64-clang-x86_64-libpng
# For Unvanquished
pacman -Sy && pacman -S mingw-w64-clang-x86_64-freetype mingw-w64-clang-x86_64-lua
</pre> </li>
<li>
Use the deps folder you made when configuring the build: <pre>
CC=clang CXX=clang++ cmake -G "MSYS Makefiles" -DEXTERNAL_DEPS_DIR=somepath/daemon/external_deps/msysclang /c/path/to/source
</pre>
If you see a download progress bar upon invoking CMake, you did the deps stuff wrong.
</li>
</ol>

===QtCreator===

# Install MinGW and follow the above instructions, except select Code::Blocks as the generator.
# Start QtCreator, and select "Open File or Project…" from the File menu.
# Navigate to your source directory and open CMakeLists.txt.
# At the CMake Wizard, select the same build directory you already configured using CMake. (If you did not chose Code::Blocks as the generator, you will have to start over again, as QtCreator requires a Code::Blocks project file in order to compile the source.)
# Ensure that a generator is selected in the combo box, and click "Run CMake". If there is no generator listed, see the [[#Troubleshooting|troubleshooting]] section below.
# Click "Finish" to close the wizard.

You should now be able to compile, run, and debug the code using QtCreator.

====Troubleshooting====

If at the "Run CMake" prompt of the the CMake Wizard, select "Run CMake" and are warned that no generator was selected, and notice that there are no generators in the combo box, you will likely have to [http://doc.qt.digia.com/qtcreator-2.4/creator-tool-chains.html manually configure your toolchain]. Select "Options…" from the "Tools" menu, then navigate to "Build & Run".

At the options window,
* Go to the "Kits" tab, and mouse over the "Desktop (default)" kit under "Manual". If there were any errors in configuring this kit, they will be displayed in the tool tip. If there are problems, select the kit. You may need to manually specify the location of the MinGW debugger, for example, which is typically <code>C:\MinGW\bin\gdb.exe</code>.
* Go to the "Compilers" tab, and ensure that MinGW is present. If not, you will need to add it manually.

==Linux==

===Dependencies===

{{TODO|This may be incomplete.}}

====Debian/Ubuntu====

sudo apt-get install build-essential cmake libcurl4-gnutls-dev \
libglew-dev libgmp-dev nettle-dev zlib1g-dev libncursesw5-dev \
libsdl2-dev libopenal-dev libjpeg-dev libpng-dev libwebp-dev \
libogg-dev libvorbis-dev libopusfile-dev \
libfreetype6-dev \
liblua5.3-dev \
python3-yaml python3-jinja2

If the version of WebP supplied by your version of Debian or Ubuntu is older than v0.2.0, you will need to [https://code.google.com/p/webp/downloads/detail?name=libwebp-0.2.0.tar.gz download] and [https://developers.google.com/speed/webp/docs/compiling#unix compile it from source]. After compiling and installing with <code>sudo make install</code>, in CMake, you'll need to set <code>WEBP_INCLUDE_DIR</code> to <code>/usr/local/include/webp</code> and <code>WEBP_LIBRARY</code> to <code>/usr/local/lib/libwebp.so</code>.

Developpment package name may differs, for example <code>libgmp-dev</code> may be named <code>libgmp3-dev</code> and <code>libglew-dev</code> may be named <code>libglew1.7-dev</code>.

We have a <code>debian</code> directory in the source tree, you can check what's missing this way.

cd <var>path/to/unvanquished</var>
dpkg-checkbuilddeps

Then install the listed packages this way:

sudo apt-get install <var>package list</var>

The <code>dpkg-checkbuilddeps</code> command produces no output if you already have the required dependencies.

Note that you only need <code>debhelper</code> to build <code>.deb</code> files.

====Fedora====

Line 1 of the packages is basic dev tools. Lines 2-3 are Daemon dependencies. Line 4 is (additional) Unvanquished dependencies.

$ sudo dnf install \
cmake gcc gcc-c++ \
{freetype,glew,gmp,mesa-libGL,ncurses,nettle,openal-soft,opus,opusfile,SDL2}-devel \
lib{curl,jpeg-turbo,png12,vorbis,webp}-devel \
lua-devel python3-pyyaml python3-jinja2

====Gentoo====

$ emerge curl freetype glew gmp jpeg ncurses media-sound/opus-tools libogg openal libpng libsdl libvorbis sys-libs/zlib

====openSUSE====

$ sudo install zypper gcc gcc-c++ Mesa-libGL-devel SDL-devel libjpeg8-devel \
libpng12-devel glew-devel webp-devel ncurses-devel gmp-devel libcurl-devel \
libnettle-devel openal-soft-devel libvorbis-devel

The latest version of WebP must be installed manually (FIXME: why, if there is webp-devel in the zypper package list?):

$ cd Unvanquished/daemon/external_deps
$ ./build.sh linux-amd64-default webp naclsdk naclports
$ ./build.sh linux-amd64-default install

You must disable curses (set <code>USE_CURSES</code> appropriately in CMake) as failing to do so will cause Unvanquished to crash on startup.

===Configuring the code with CMake===

After you have [[Getting the source|acquired the source code]], you can proceed to compile. Unvanquished uses CMake, so you must have that installed.

====Using ccmake (curses-based front-end)====

On Debian or Ubuntu:

$ sudo apt-get install cmake-curses-gui

On Gentoo you should set the '''ncurses''' USE flag either globally or individually, just for cmake.
To add the USE flag globally, edit the USE array in /etc/make.conf for it to include '''ncurses'''.
To only install cmake with ncurses functionality, you could do the following:

$ echo 'dev-util/cmake ncurses' >> /etc/portage/package.use && emerge cmake

Note that in Ubuntu, <code>cmake-curses-gui</code> is in Universe, which you may have to enable with <code>software-properties-gtk</code>. Make sure to reload the software sources with <code>sudo apt-get update</code> afterwards.

Optionally: to use clang (rather than the default gcc and g++ compilers) export the CC and CXX variables before running cmake:

$ export CC="clang"
$ export CXX="clang++ -stdlib=libc++ -lc++abi"

Next, configure the codebase.

$ cd <var>/path/to/unvanquished</var>
$ mkdir build
$ cd build
$ ccmake ..

In Debian or Ubuntu you can build a package this way (you need <code>devscripts</code> and <code>fakeroot</code> packages):

$ cd <var>/path/to/unvanquished</var>
$ fakeroot dpkg-buildpackage -b -uc
$ sudo dpkg -i <var>../unvanquished_*.deb</var>

Once in <code>ccmake</code>, use the following keys:

* Press {{Hotkey|c}} to configure. If an error occurs during this phase, make note of it and press {{Hotkey|e}} to dismiss it.
* Use the up and down arrow keys to navigate the compilation options.
* Press {{Hotkey|Enter}} to enable or disable boolean options (i.e., on/off) or to edit textual options.
** Press {{Hotkey|Esc}} when editing a textual option to cancel the change.

Once you have finished the configuration process, press {{Hotkey|C}} again, then {{Hotkey|G}} to generate the makefile.

====Using cmake-qt-gui (graphical front-end)====

This graphical front end for cmake has its own package you must install:

=====Debian/Ubuntu=====

$ sudo apt-get install cmake-qt-gui

=====Gentoo=====

With the '''qt4''' USE flag enabled:

$ emerge cmake

Once installed, run with <code>cmake-gui</code>.

[[Image:Cmake-qt-gui.png|thumb]]

# Set the path where you have the source code downloaded.
# Set the path where you would like to build the engine. This may be the same directory if you wish.
# Click 'Configure'.
# Click 'Generate'.

====Unnecessary libraries====

Regardless of which front-end to cmake you use, you may want to disable some libraries that are not strictly necessary:

* <code>USE_BREAKPAD</code> — Disabling this will cause the game to not produce crashdumps on failure.
* <code>USE_CURSES</code> — Disabling this will cause the external (not in-game) console to not use curses; it will not be scrollable and will be similar to the console in the original Tremulous. This does in no way affect gameplay.

===Compiling===

$ cd <var>path/to/unvanquished/build</var>
$ make -j4

The <code>-j</code> switch to make allows you to speed up the compilation process by running it in multiple threads; set the number following this to the number of cores your processor(s) have.

==FreeBSD==

While building on FreeBSD is usually very similar to building on Linux, the PNaCl toolchain not being native to FreeBSD means not everything can be built on FreeBSD. See the [[Systems/FreeBSD]] page for details and dedicated instructions.

==Acquiring the Game Files==

===Acquiring mandatory game files===

The game files are not in the Git repository, and must be downloaded separately. They must be saved to the [[Game locations|data location]] for your system.

Linux users may use the <code>download-paks</code> script that is distributed with the source code, which requires one of curl, wget or aria2 to be installed:

$ cd <var>path/to/unvanquished/build</var>
$ ../download-paks pkg

Otherwise, the set of necessary packages can be extracted from the [https://github.com/Unvanquished/Unvanquished/releases latest release], or downloaded a la carte from the [http://dl.unvanquished.net/pkg/ package index].

Compiling the source

2024-10-27T14:20:45Z

Killing time: /* macOS - Bundling the Application */ NUKE NUKE NUKE

==Dependencies==

{{Note|content=In case this happens to become outdated, the up-to-date documentation can be found in the {{SourceFile|parameters=#unvanquished|README.md}} file in source repository.}}

The game requires some dependencies to be built, which are the same on all systems:

* cmake
* python3-yaml
* python3-jinja2
* A C++11 able compiler (those are known to work: clang (>= 3.5), gcc (>= 4.8), visual studio (>= 2019))
* zlib1g
* libgmp
* nettle
* libcurl4-gnutls
* libsdl2
* libglew
* libpng
* libjpeg-turbo8
* libwebp
* libfreetype6
* liblua5.3
* libopenal
* libogg
* libvorbis
* libopusfile

Those are optional:

* libncursesw5

==macOS==

First, you need to [[Getting_the_source|acquire the source code]].

Regardless of what interface you may use to compile the source, you will need [http://www.cmake.org/cmake/resources/software.html CMake] to generate makefiles. You will also need to install [https://developer.apple.com/xcode/ Xcode]. At a minimum, you must install the "Xcode command-line tools" in order to compile anything. You may also install Xcode proper, if you wish to use that IDE.

Once you have the source code and the tools installed, you may actually proceed to compile the source. You have several options:
* '''Compile the source at the command line'''. This is the easiest if you would just like to compile the game to use yourself and you do not intend to work on the code.
* '''Compile the source using an IDE'''. This is preferred if you intend on developing the source.
** Xcode is Apple's flagship IDE.
** [http://qt-project.org/downloads QtCreator] is cross-platform and provides real-time feedback of syntax errors, a Vim mode, as well as other features.
** [http://www.codeblocks.org/ Code::Blocks] is also cross-platform but lacks some of the features of Xcode and QtCreator.

===Dependencies===

Precompiled static libs are provided for all dependencies. CMake downloads them at configure time and extracts to <code>daemon/external_deps/macos-amd64-default_<i><version></i>/</code>. These were produced by the <code>external_deps/build.sh</code> script, which you could also use to build them yourself if you want to for some reason.

===Configuring with CMake===

# Run CMake.
# Enter the location of the source code.
# Enter the location in which you would like to build the source code. This should be a different directory.
# Click "Configure". You will be prompted as to which generator you would like to use. If you have Xcode installed, choose that. Wait while the configuration process runs. You may have to set the following:
## If you have selected to generate Xcode project files, make the <code>SDLMAIN_LIBRARY</code> field blank. This option is not available if you have the generator set to Unix makefiles.
# Click "Generate".
# You may now close CMake.

===Compiling===

====With Xcode====

<ol>
<li>Either start Xcode and open the project file (in the build directory you specified) or double-click the project file in Finder.</li>
<li>Open the project file created by CMake, which should be in the build directory you specified.</li>
<li>Change the active target to "ALL_BUILD" and click Product→Build.</li>
</ol>

====With Unix Makefiles====

<ul>
<li>Start Terminal (Applications → Utilities → Terminal).</li>
<li>Type the following commands:
<pre>
$ cd /path/to/Unvanquished-build
$ make
</pre>
If you are on a multi-core or multi-processor machine, you may speed up the process by passing the <code>-j</code> argument followed by the number of available cores to <code>make</code>; e.g., <code>make -j4</code>. Note that doing so makes reading error messages more difficult, as multiple instances of the compiler will print to the screen at once, causing information to appear out of order.
</li>
</ul>

===Testing the build===

====With Xcode 4====

To test the game, select the "client" scheme from the combo box on the toolbar, and click the run button or press {{Hotkey|MacCommand}}{{Hotkey|R}}.

==Windows==

===Visual Studio===

CMake can generate Visual Studio projects for Unvanquished.

# Add _NO_DEBUG_HEAP=1 to your environment variables otherwise performance under the debugger [http://www.massimpressionsprojects.com/dev/altdevblog/2011/07/27/the-unexpected-performance-of-debug-builds/ will be terrible]
# Run CMake with the source directory as the base directory of your source code (which should contain the directory <code>src</code>), and the build directory as a subdirectory of the source directory named <code>build</code>.
# Click the <b>Open Project</b> button. Or if you used CMake from the command line, open <code>build/Unvanquished.sln</code> in Visual Studio.
# In Visual Studio, choose your desired build type (default: <b>Debug</b>) from the drop-down menu in the top bar. <b>Debug</b> runs assertions and has complete debug information, but is slower. <b>RelWithDebInfo</b> is fast and still fairly usable with the debugger, but assertions don't run and sometimes you can't see the value of a local variable.
# Use Build → Build Solution to compile the code. Or just press {{Hotkey|F5}} to build and run, but beware: this will not automatically build cgame or sgame! Only engine changes are automatically rebuilt when you run something from Visual Studio.

====Important Notes====

* Due to limitations with CMake, the startup project cannot be specified. This must be set manually to debug the client with Visual Studio:
** Right click on client and select "Set as Startup project".

===MinGW===

It is possible to produce a Windows build of Unvanquished with [[MinGW]], as either a Windows or a Linux user. See [[MinGW#Distributions]] for detailed information about the toolchains available for installation.

====Instructions for native Windows build with MSYS2====

<ol>

<li> Install MSYS2. </li>
<li> Open the ''MSYS2 MinGW 32-bit'' or ''MSYS2 MinGW 64-bit'' terminal, depending on which bitness you want to build. </li>
</li> Install toolchain:
<pre>
# For 32-bit replace x86_64 with i686
pacman -Sy && pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake make
</pre> </li>
<li> Run CMake. If you're building Unvanquished, you may want to use the <code>-DDAEMON_CBSE_PYTHON_PATH=<path></code> option in case you want to use a different Python rather than the one in MSYS2. <pre>
mkdir mybuild && cd mybuild
cmake -G "MSYS Makefiles" somepath/Unvanquished
</pre> </li>
<li> Build:
<pre> make -j4 </pre>

If you would like verbose output (useful to see compiler flags), set the <code>VERBOSE</code> environment variable before running Make.
<pre>
export VERBOSE=1
</pre>

</li>
</ol>

You may find that the game (or some part of the MSYS2 toolchain!) fails to start due to missing DLL dependencies. Two helpful tools are:
<ul>
<li> The strace command in MSYS2, e.g. <code>strace ./daemon</code> </li>
<li> [https://github.com/lucasg/Dependencies Dependencies] (a Windows GUI program) </li>
</ul>

When distributing MinGW binaries, you need to distribute some additional DLLs besides the ones in the build folder. See [[MinGW#Built-in_DLL_dependencies]].

====MSYS2 Clang====
In MSYS2, it is possible to build with Clang, rather than GCC as shown as in the above instructions. However, some of our pre-built libraries are incompatible. You need to use the ones from pacman instead.

<ol>
<li> Create a deps folder with incompatible packages removed. This assumes that the latest version of the prebuilt deps for the mingw package of the appropriate bitness has already been extracted to the <code>windows-${ARCH}-mingw_${VERSION}</code> directory. In this example, we use <code>windows-amd64-mingw_8</code>. <pre>
cd somepath/daemon/external_deps
mkdir msysclang
cp windows-amd64-mingw_8 -R msysclang
find msysclang -depth -name '*freetype*' -o -name '*png*' -o name '*curl*' -o -name '*lua*' | grep -v pnacl | xargs rm -r
</pre> </li>
<li> Install those deps from Pacman: <pre>
# For Daemon
pacman -Sy && pacman -S mingw-w64-clang-x86_64-freetype mingw-w64-clang-x86_64-curl mingw-w64-clang-x86_64-libpng
# For Unvanquished
pacman -Sy && pacman -S mingw-w64-clang-x86_64-freetype mingw-w64-clang-x86_64-lua
</pre> </li>
<li>
Use the deps folder you made when configuring the build: <pre>
CC=clang CXX=clang++ cmake -G "MSYS Makefiles" -DEXTERNAL_DEPS_DIR=somepath/daemon/external_deps/msysclang /c/path/to/source
</pre>
If you see a download progress bar upon invoking CMake, you did the deps stuff wrong.
</li>
</ol>

===QtCreator===

# Install MinGW and follow the above instructions, except select Code::Blocks as the generator.
# Start QtCreator, and select "Open File or Project…" from the File menu.
# Navigate to your source directory and open CMakeLists.txt.
# At the CMake Wizard, select the same build directory you already configured using CMake. (If you did not chose Code::Blocks as the generator, you will have to start over again, as QtCreator requires a Code::Blocks project file in order to compile the source.)
# Ensure that a generator is selected in the combo box, and click "Run CMake". If there is no generator listed, see the [[#Troubleshooting|troubleshooting]] section below.
# Click "Finish" to close the wizard.

You should now be able to compile, run, and debug the code using QtCreator.

====Troubleshooting====

If at the "Run CMake" prompt of the the CMake Wizard, select "Run CMake" and are warned that no generator was selected, and notice that there are no generators in the combo box, you will likely have to [http://doc.qt.digia.com/qtcreator-2.4/creator-tool-chains.html manually configure your toolchain]. Select "Options…" from the "Tools" menu, then navigate to "Build & Run".

At the options window,
* Go to the "Kits" tab, and mouse over the "Desktop (default)" kit under "Manual". If there were any errors in configuring this kit, they will be displayed in the tool tip. If there are problems, select the kit. You may need to manually specify the location of the MinGW debugger, for example, which is typically <code>C:\MinGW\bin\gdb.exe</code>.
* Go to the "Compilers" tab, and ensure that MinGW is present. If not, you will need to add it manually.

==Linux==

===Dependencies===

{{TODO|This may be incomplete.}}

====Debian/Ubuntu====

sudo apt-get install build-essential cmake libcurl4-gnutls-dev \
libglew-dev libgmp-dev nettle-dev zlib1g-dev libncursesw5-dev \
libsdl2-dev libopenal-dev libjpeg-dev libpng-dev libwebp-dev \
libogg-dev libvorbis-dev libopusfile-dev \
libfreetype6-dev \
liblua5.3-dev \
python3-yaml python3-jinja2

If the version of WebP supplied by your version of Debian or Ubuntu is older than v0.2.0, you will need to [https://code.google.com/p/webp/downloads/detail?name=libwebp-0.2.0.tar.gz download] and [https://developers.google.com/speed/webp/docs/compiling#unix compile it from source]. After compiling and installing with <code>sudo make install</code>, in CMake, you'll need to set <code>WEBP_INCLUDE_DIR</code> to <code>/usr/local/include/webp</code> and <code>WEBP_LIBRARY</code> to <code>/usr/local/lib/libwebp.so</code>.

Developpment package name may differs, for example <code>libgmp-dev</code> may be named <code>libgmp3-dev</code> and <code>libglew-dev</code> may be named <code>libglew1.7-dev</code>.

We have a <code>debian</code> directory in the source tree, you can check what's missing this way.

cd <var>path/to/unvanquished</var>
dpkg-checkbuilddeps

Then install the listed packages this way:

sudo apt-get install <var>package list</var>

The <code>dpkg-checkbuilddeps</code> command produces no output if you already have the required dependencies.

Note that you only need <code>debhelper</code> to build <code>.deb</code> files.

====Fedora====

Line 1 of the packages is basic dev tools. Lines 2-3 are Daemon dependencies. Line 4 is (additional) Unvanquished dependencies.

$ sudo dnf install \
cmake gcc gcc-c++ \
{freetype,glew,gmp,mesa-libGL,ncurses,nettle,openal-soft,opus,opusfile,SDL2}-devel \
lib{curl,jpeg-turbo,png12,vorbis,webp}-devel \
lua-devel python3-pyyaml python3-jinja2

====Gentoo====

$ emerge curl freetype glew gmp jpeg ncurses media-sound/opus-tools libogg openal libpng libsdl libvorbis sys-libs/zlib

====openSUSE====

$ sudo install zypper gcc gcc-c++ Mesa-libGL-devel SDL-devel libjpeg8-devel \
libpng12-devel glew-devel webp-devel ncurses-devel gmp-devel libcurl-devel \
libnettle-devel openal-soft-devel libvorbis-devel

The latest version of WebP must be installed manually (FIXME: why, if there is webp-devel in the zypper package list?):

$ cd Unvanquished/daemon/external_deps
$ ./build.sh linux-amd64-default webp naclsdk naclports
$ ./build.sh linux-amd64-default install

You must disable curses (set <code>USE_CURSES</code> appropriately in CMake) as failing to do so will cause Unvanquished to crash on startup.

===Configuring the code with CMake===

After you have [[Getting the source|acquired the source code]], you can proceed to compile. Unvanquished uses CMake, so you must have that installed.

====Using ccmake (curses-based front-end)====

On Debian or Ubuntu:

$ sudo apt-get install cmake-curses-gui

On Gentoo you should set the '''ncurses''' USE flag either globally or individually, just for cmake.
To add the USE flag globally, edit the USE array in /etc/make.conf for it to include '''ncurses'''.
To only install cmake with ncurses functionality, you could do the following:

$ echo 'dev-util/cmake ncurses' >> /etc/portage/package.use && emerge cmake

Note that in Ubuntu, <code>cmake-curses-gui</code> is in Universe, which you may have to enable with <code>software-properties-gtk</code>. Make sure to reload the software sources with <code>sudo apt-get update</code> afterwards.

Optionally: to use clang (rather than the default gcc and g++ compilers) export the CC and CXX variables before running cmake:

$ export CC="clang"
$ export CXX="clang++ -stdlib=libc++ -lc++abi"

Next, configure the codebase.

$ cd <var>/path/to/unvanquished</var>
$ mkdir build
$ cd build
$ ccmake ..

In Debian or Ubuntu you can build a package this way (you need <code>devscripts</code> and <code>fakeroot</code> packages):

$ cd <var>/path/to/unvanquished</var>
$ fakeroot dpkg-buildpackage -b -uc
$ sudo dpkg -i <var>../unvanquished_*.deb</var>

Once in <code>ccmake</code>, use the following keys:

* Press {{Hotkey|c}} to configure. If an error occurs during this phase, make note of it and press {{Hotkey|e}} to dismiss it.
* Use the up and down arrow keys to navigate the compilation options.
* Press {{Hotkey|Enter}} to enable or disable boolean options (i.e., on/off) or to edit textual options.
** Press {{Hotkey|Esc}} when editing a textual option to cancel the change.

Once you have finished the configuration process, press {{Hotkey|C}} again, then {{Hotkey|G}} to generate the makefile.

====Using cmake-qt-gui (graphical front-end)====

This graphical front end for cmake has its own package you must install:

=====Debian/Ubuntu=====

$ sudo apt-get install cmake-qt-gui

=====Gentoo=====

With the '''qt4''' USE flag enabled:

$ emerge cmake

Once installed, run with <code>cmake-gui</code>.

[[Image:Cmake-qt-gui.png|thumb]]

# Set the path where you have the source code downloaded.
# Set the path where you would like to build the engine. This may be the same directory if you wish.
# Click 'Configure'.
# Click 'Generate'.

====Unnecessary libraries====

Regardless of which front-end to cmake you use, you may want to disable some libraries that are not strictly necessary:

* <code>USE_BREAKPAD</code> — Disabling this will cause the game to not produce crashdumps on failure.
* <code>USE_CURSES</code> — Disabling this will cause the external (not in-game) console to not use curses; it will not be scrollable and will be similar to the console in the original Tremulous. This does in no way affect gameplay.

===Compiling===

$ cd <var>path/to/unvanquished/build</var>
$ make -j4

The <code>-j</code> switch to make allows you to speed up the compilation process by running it in multiple threads; set the number following this to the number of cores your processor(s) have.

==FreeBSD==

While building on FreeBSD is usually very similar to building on Linux, the PNaCl toolchain not being native to FreeBSD means not everything can be built on FreeBSD. See the [[Systems/FreeBSD]] page for details and dedicated instructions.

==Acquiring the Game Files==

===Acquiring mandatory game files===

The game files are not in the Git repository, and must be downloaded separately. They must be saved to the [[Game locations|data location]] for your system.

Linux users may use the <code>download-paks</code> script that is distributed with the source code, which requires one of curl, wget or aria2 to be installed:

$ cd <var>path/to/unvanquished/build</var>
$ ../download-paks pkg

Otherwise, the set of necessary packages can be extracted from the [https://github.com/Unvanquished/Unvanquished/releases latest release], or downloaded a la carte from the [http://dl.unvanquished.net/pkg/ package index].

Continuous integration

2024-10-27T00:49:18Z

Killing time: /* Build matrix */

[[Category:Infrastructure]]
Continuous integration (CI) refers to the automated builds that run each time someone opens or modifies a pull request against, or modifies the code of, the Unvanquished and Daemon source code repositories on GitHub.

We use the following CI services:
* Appveyor, for building with MSVC on Windows. Its configuration is found in the file {{code|.appveyor.yml}} in the repository root.
* Azure Pipelines. Its configuration is found in the file {{code|azure-pipelines.yml}} in the repository root. It handles Mac native builds on [https://github.com/actions/virtual-environments/blob/main/images/macos/macos-11-Readme.md macOS 11.x] and Linux native and NaCl builds on [https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2004-Readme.md Ubuntu 20.04] (Focal).
* GitHub CodeQL. Its configuration is found in the file {{code|.github/workflows/codeql.yml}} in the repository. Its purpose is to scan the source code for vulnerabilities, and for that purpose it starts by building the source tree using the latest LTS Ubuntu distribution provided by the platform ([https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2004-Readme.md Ubuntu 22.04]) and the default compiler of this platform.

In some Daemon builds, we run the unit tests. These builds have been configured to use the Release configuration so that the unit tests are closer to production builds.

== Build matrix ==

{|
! colspan="9" | {{engine}}
|-
! Service
! Host
! Target
! Compiler
! Generator
! Build Type
! WERROR
! PCH
! Unit tests
|-
| Appveyor || Windows amd64 || Windows amd64 || VS 2019 || Visual Studio || Release || Yes || No || Yes
|-
| Appveyor || Windows amd64 || Windows i686 || VS 2019 || Visual Studio || Release || Yes || No || Yes
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Windows amd64 || MinGW 9.3 || Ninja || Debug || Yes || No || No
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 || GCC 9.4 || Ninja || Release || Yes || No || Yes
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 || Clang 11.0 || Ninja || Release || Yes || No || Yes
|-
| Azure Pipelines || macOS-11 amd64 || macOS amd64 || AppleClang 13.0 || Make || Release || Yes || No || Yes
|-
| GitHub Actions CodeQL || ubuntu-latest || Linux amd64 || GCC (floating) || Ninja || Release || No || Yes || No
|}
<br>
{|
! colspan="8" | {{game}}
|-
! Service
! Host
! Target
! Compiler
! Generator
! Build Type
! WERROR
! PCH
|-
| Appveyor || Windows amd64 || Windows i686 DLL || VS 2019 || NMake || Debug || Yes || No
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 DLL || GCC 8.4 || Ninja || Debug || Yes || No
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 DLL || Clang 11.0 || Ninja || Debug || Yes || No
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || NaCl all NEXE || PNaCl Clang 3.6 || Ninja || Debug || Yes || No
|-
| Azure Pipelines || macOS-12 amd64 || macOS amd64 DLL || AppleClang 14.0 || Make || Debug || Yes || No
|-
| GitHub Actions CodeQL || ubuntu-latest || Linux amd64 DLL+EXE || GCC (floating) || Ninja || Release || No || Yes
|}

“WERROR” indicates whether the {{code|USE_WERROR}} option is on, which gives a failing building build status if there are warnings in our code. Note that {{code|USE_WERROR}} only applies to ”our” code in {{code|src/}}, so you may still see warnings from stuff in {{code|libs/}}.

“PCH” indicates whether the precompiled header is enabled.

Compiling the source

2024-10-22T08:55:54Z

Killing time: fedora deps update

==Dependencies==

{{Note|content=In case this happens to become outdated, the up-to-date documentation can be found in the {{SourceFile|parameters=#unvanquished|README.md}} file in source repository.}}

The game requires some dependencies to be built, which are the same on all systems:

* cmake
* python3-yaml
* python3-jinja2
* A C++11 able compiler (those are known to work: clang (>= 3.5), gcc (>= 4.8), visual studio (>= 2019))
* zlib1g
* libgmp
* nettle
* libcurl4-gnutls
* libsdl2
* libglew
* libpng
* libjpeg-turbo8
* libwebp
* libfreetype6
* liblua5.3
* libopenal
* libogg
* libvorbis
* libopusfile

Those are optional:

* libncursesw5

==macOS==

First, you need to [[Getting_the_source|acquire the source code]].

Regardless of what interface you may use to compile the source, you will need [http://www.cmake.org/cmake/resources/software.html CMake] to generate makefiles. You will also need to install [https://developer.apple.com/xcode/ Xcode]. At a minimum, you must install the "Xcode command-line tools" in order to compile anything. You may also install Xcode proper, if you wish to use that IDE.

Once you have the source code and the tools installed, you may actually proceed to compile the source. You have several options:
* '''Compile the source at the command line'''. This is the easiest if you would just like to compile the game to use yourself and you do not intend to work on the code.
* '''Compile the source using an IDE'''. This is preferred if you intend on developing the source.
** Xcode is Apple's flagship IDE.
** [http://qt-project.org/downloads QtCreator] is cross-platform and provides real-time feedback of syntax errors, a Vim mode, as well as other features.
** [http://www.codeblocks.org/ Code::Blocks] is also cross-platform but lacks some of the features of Xcode and QtCreator.

===Dependencies===

Precompiled static libs are provided for all dependencies. CMake downloads them at configure time and extracts to <code>daemon/external_deps/macos-amd64-default_<i><version></i>/</code>. These were produced by the <code>external_deps/build.sh</code> script, which you could also use to build them yourself if you want to for some reason.

===Configuring with CMake===

# Run CMake.
# Enter the location of the source code.
# Enter the location in which you would like to build the source code. This should be a different directory.
# Click "Configure". You will be prompted as to which generator you would like to use. If you have Xcode installed, choose that. Wait while the configuration process runs. You may have to set the following:
## If you have selected to generate Xcode project files, make the <code>SDLMAIN_LIBRARY</code> field blank. This option is not available if you have the generator set to Unix makefiles.
# Click "Generate".
# You may now close CMake.

===Compiling===

====With Xcode====

<ol>
<li>Either start Xcode and open the project file (in the build directory you specified) or double-click the project file in Finder.</li>
<li>Open the project file created by CMake, which should be in the build directory you specified.</li>
<li>Change the active target to "ALL_BUILD" and click Product→Build.</li>
</ol>

====With Unix Makefiles====

<ul>
<li>Start Terminal (Applications → Utilities → Terminal).</li>
<li>Type the following commands:
<pre>
$ cd /path/to/Unvanquished-build
$ make
</pre>
If you are on a multi-core or multi-processor machine, you may speed up the process by passing the <code>-j</code> argument followed by the number of available cores to <code>make</code>; e.g., <code>make -j4</code>. Note that doing so makes reading error messages more difficult, as multiple instances of the compiler will print to the screen at once, causing information to appear out of order.
</li>
</ul>

===Testing the build===

====With Xcode 4====

To test the game, select the "client" scheme from the combo box on the toolbar, and click the run button or press {{Hotkey|MacCommand}}{{Hotkey|R}}.

===Bundling the Application===

====With CPack====

CPack is able to create standalone bundles (as well as many other types of installers). However you must generate the files using Unix Makefiles instead of Xcode.

$ cd /path/to/Unvanquished-build
$ cpack -G Bundle

Some warnings will be printed however these can be safely ignored. There should be a file called Unvanquished.dmg in the Unvanquished-build folder.

====Manually====

{{Note|header=Important|content=
Please be aware that these instructions are very much out of date, and may not work. Also note that the dynamic library bundler does '''not''' work as intended and although you will be able to run your build on your machine, it will most likely not work on other machines. It is strongly suggested that you compile the source using Xcode.
}}

You'll find the Mac [http://macdylibbundler.sourceforge.net/ dynamic library bundler] to be quite useful (you must generate the files using Unix Makefiles instead of Xcode):

$ curl -L http://sourceforge.net/projects/macdylibbundler/files/macdylibbundler/0.4.1/dylibbundler0.4.1.zip/download > \
dylibbundler0.4.1.zip
$ unzip dylibbundler0.4.1.zip
$ cd dylibbundler
$ make
$ sudo make install

Once you've done that, you can proceed to create the application bundle. Note that these steps assume that you have downloaded the data files to <code>main/</code> as shown above:

<pre>
$ git=/path/to/Unvanquished-git-repo
$ build=/path/to/Unvanquished-build-dir
$ mkdir -pv Unvanquished.app/Contents/{libs,MacOS,Resources,Frameworks}
$ cp -r $build/main Unvanquished.app/Contents/MacOS
$ sips -s format tiff $git/debian/unvanquished.png --out temp.tiff
$ tiff2icns temp.tiff Unvanquished.app/Contents/Resources/Unvanquished.icns
$ rm temp.tiff
$ cp $build/daemon{,ded}.i386 $build/*.dylib Unvanquished.app/Contents/MacOS
$ cp -r /Library/Frameworks/SDL.framework Unvanquished.app/Contents/Frameworks
$ install_name_tool -id \
@executable_path/../Frameworks/SDL.framework/Versions/A/SDL \
Unvanquished.app/Contents/Frameworks/SDL.framework/Versions/A/SDL
$ install_name_tool -change @rpath/SDL.framework/Versions/A/SDL \
@executable_path/../Frameworks/SDL.framework/Versions/A/SDL \
Unvanquished.app/Contents/MacOS/daemon.i386
$ install_name_tool -change @rpath/SDL.framework/Versions/A/SDL \
@executable_path/../Frameworks/SDL.framework/Versions/A/SDL \
Unvanquished.app/Contents/MacOS/librendererGLi386.dylib
$ install_name_tool -change @rpath/SDL.framework/Versions/A/SDL \
@executable_path/../Frameworks/SDL.framework/Versions/A/SDL \
Unvanquished.app/Contents/MacOS/librendererGL3i386.dylib
$ for binary in Unvanquished.app/Contents/MacOS/*.{i386,dylib}; do
dylibbundler -b -x $binary -d $dest/Unvanquished.app/Contents/libs/; done
$ cp /usr/lib/libGLEW.1.7.0.dylib ./Unvanquished.app/Contents/libs/libGLEW.1.7.0.dylib
$ chmod +w ./Unvanquished.app/Contents/libs/libGLEW.1.7.0.dylib
$ install_name_tool -id @executable_path/../libs/libGLEW.1.7.0.dylib \
./Unvanquished.app/Contents/libs/libGLEW.1.7.0.dylib
$ install_name_tool -change /usr/lib/libGLEW.1.7.0.dylib \
@executable_path/../libs/libGLEW.1.7.0.dylib \
./Unvanquished.app/Contents/MacOS/daemon.i386
$ cat > Unvanquished.app/Contents/Info.plist <<\EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>CFBundleName</key>
<string>Unvanquished</string>
<key>CFBundleDisplayName</key>
<string>Unvanquished</string>
<key>CFBundleExecutable</key>
<string>daemon.i386</string>
<key>CFBundleIconFile</key>
<string>Unvanquished.icns</string>
<key>CFBundleIdentifier</key>
<string>net.Unvanquished</string>
<key>CFBundleInfoDictionaryVersion</key>
<string>6.0</string>
<key>CFBundlePackageType</key>
<string>APPL</string>
<key>CFBundleShortVersionString</key>
<string>0.4.0</string>
<key>CFBundleVersion</key>
<string>0.4.0</string>
</dict>
</plist>
EOF
</pre>

The contents of the completed application bundle should look like this:

[[File:Bundle_dir_Mac_OS_X.png]]

'''Note''': If you compiled SDL from source, you will not see a directory titled <code>SDL.framework</code>.

==Windows==

===Visual Studio===

CMake can generate Visual Studio projects for Unvanquished.

# Add _NO_DEBUG_HEAP=1 to your environment variables otherwise performance under the debugger [http://www.massimpressionsprojects.com/dev/altdevblog/2011/07/27/the-unexpected-performance-of-debug-builds/ will be terrible]
# Run CMake with the source directory as the base directory of your source code (which should contain the directory <code>src</code>), and the build directory as a subdirectory of the source directory named <code>build</code>.
# Click the <b>Open Project</b> button. Or if you used CMake from the command line, open <code>build/Unvanquished.sln</code> in Visual Studio.
# In Visual Studio, choose your desired build type (default: <b>Debug</b>) from the drop-down menu in the top bar. <b>Debug</b> runs assertions and has complete debug information, but is slower. <b>RelWithDebInfo</b> is fast and still fairly usable with the debugger, but assertions don't run and sometimes you can't see the value of a local variable.
# Use Build → Build Solution to compile the code. Or just press {{Hotkey|F5}} to build and run, but beware: this will not automatically build cgame or sgame! Only engine changes are automatically rebuilt when you run something from Visual Studio.

====Important Notes====

* Due to limitations with CMake, the startup project cannot be specified. This must be set manually to debug the client with Visual Studio:
** Right click on client and select "Set as Startup project".

===MinGW===

It is possible to produce a Windows build of Unvanquished with [[MinGW]], as either a Windows or a Linux user. See [[MinGW#Distributions]] for detailed information about the toolchains available for installation.

====Instructions for native Windows build with MSYS2====

<ol>

<li> Install MSYS2. </li>
<li> Open the ''MSYS2 MinGW 32-bit'' or ''MSYS2 MinGW 64-bit'' terminal, depending on which bitness you want to build. </li>
</li> Install toolchain:
<pre>
# For 32-bit replace x86_64 with i686
pacman -Sy && pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake make
</pre> </li>
<li> Run CMake. If you're building Unvanquished, you may want to use the <code>-DDAEMON_CBSE_PYTHON_PATH=<path></code> option in case you want to use a different Python rather than the one in MSYS2. <pre>
mkdir mybuild && cd mybuild
cmake -G "MSYS Makefiles" somepath/Unvanquished
</pre> </li>
<li> Build:
<pre> make -j4 </pre>

If you would like verbose output (useful to see compiler flags), set the <code>VERBOSE</code> environment variable before running Make.
<pre>
export VERBOSE=1
</pre>

</li>
</ol>

You may find that the game (or some part of the MSYS2 toolchain!) fails to start due to missing DLL dependencies. Two helpful tools are:
<ul>
<li> The strace command in MSYS2, e.g. <code>strace ./daemon</code> </li>
<li> [https://github.com/lucasg/Dependencies Dependencies] (a Windows GUI program) </li>
</ul>

When distributing MinGW binaries, you need to distribute some additional DLLs besides the ones in the build folder. See [[MinGW#Built-in_DLL_dependencies]].

====MSYS2 Clang====
In MSYS2, it is possible to build with Clang, rather than GCC as shown as in the above instructions. However, some of our pre-built libraries are incompatible. You need to use the ones from pacman instead.

<ol>
<li> Create a deps folder with incompatible packages removed. This assumes that the latest version of the prebuilt deps for the mingw package of the appropriate bitness has already been extracted to the <code>windows-${ARCH}-mingw_${VERSION}</code> directory. In this example, we use <code>windows-amd64-mingw_8</code>. <pre>
cd somepath/daemon/external_deps
mkdir msysclang
cp windows-amd64-mingw_8 -R msysclang
find msysclang -depth -name '*freetype*' -o -name '*png*' -o name '*curl*' -o -name '*lua*' | grep -v pnacl | xargs rm -r
</pre> </li>
<li> Install those deps from Pacman: <pre>
# For Daemon
pacman -Sy && pacman -S mingw-w64-clang-x86_64-freetype mingw-w64-clang-x86_64-curl mingw-w64-clang-x86_64-libpng
# For Unvanquished
pacman -Sy && pacman -S mingw-w64-clang-x86_64-freetype mingw-w64-clang-x86_64-lua
</pre> </li>
<li>
Use the deps folder you made when configuring the build: <pre>
CC=clang CXX=clang++ cmake -G "MSYS Makefiles" -DEXTERNAL_DEPS_DIR=somepath/daemon/external_deps/msysclang /c/path/to/source
</pre>
If you see a download progress bar upon invoking CMake, you did the deps stuff wrong.
</li>
</ol>

===QtCreator===

# Install MinGW and follow the above instructions, except select Code::Blocks as the generator.
# Start QtCreator, and select "Open File or Project…" from the File menu.
# Navigate to your source directory and open CMakeLists.txt.
# At the CMake Wizard, select the same build directory you already configured using CMake. (If you did not chose Code::Blocks as the generator, you will have to start over again, as QtCreator requires a Code::Blocks project file in order to compile the source.)
# Ensure that a generator is selected in the combo box, and click "Run CMake". If there is no generator listed, see the [[#Troubleshooting|troubleshooting]] section below.
# Click "Finish" to close the wizard.

You should now be able to compile, run, and debug the code using QtCreator.

====Troubleshooting====

If at the "Run CMake" prompt of the the CMake Wizard, select "Run CMake" and are warned that no generator was selected, and notice that there are no generators in the combo box, you will likely have to [http://doc.qt.digia.com/qtcreator-2.4/creator-tool-chains.html manually configure your toolchain]. Select "Options…" from the "Tools" menu, then navigate to "Build & Run".

At the options window,
* Go to the "Kits" tab, and mouse over the "Desktop (default)" kit under "Manual". If there were any errors in configuring this kit, they will be displayed in the tool tip. If there are problems, select the kit. You may need to manually specify the location of the MinGW debugger, for example, which is typically <code>C:\MinGW\bin\gdb.exe</code>.
* Go to the "Compilers" tab, and ensure that MinGW is present. If not, you will need to add it manually.

==Linux==

===Dependencies===

{{TODO|This may be incomplete.}}

====Debian/Ubuntu====

sudo apt-get install build-essential cmake libcurl4-gnutls-dev \
libglew-dev libgmp-dev nettle-dev zlib1g-dev libncursesw5-dev \
libsdl2-dev libopenal-dev libjpeg-dev libpng-dev libwebp-dev \
libogg-dev libvorbis-dev libopusfile-dev \
libfreetype6-dev \
liblua5.3-dev \
python3-yaml python3-jinja2

If the version of WebP supplied by your version of Debian or Ubuntu is older than v0.2.0, you will need to [https://code.google.com/p/webp/downloads/detail?name=libwebp-0.2.0.tar.gz download] and [https://developers.google.com/speed/webp/docs/compiling#unix compile it from source]. After compiling and installing with <code>sudo make install</code>, in CMake, you'll need to set <code>WEBP_INCLUDE_DIR</code> to <code>/usr/local/include/webp</code> and <code>WEBP_LIBRARY</code> to <code>/usr/local/lib/libwebp.so</code>.

Developpment package name may differs, for example <code>libgmp-dev</code> may be named <code>libgmp3-dev</code> and <code>libglew-dev</code> may be named <code>libglew1.7-dev</code>.

We have a <code>debian</code> directory in the source tree, you can check what's missing this way.

cd <var>path/to/unvanquished</var>
dpkg-checkbuilddeps

Then install the listed packages this way:

sudo apt-get install <var>package list</var>

The <code>dpkg-checkbuilddeps</code> command produces no output if you already have the required dependencies.

Note that you only need <code>debhelper</code> to build <code>.deb</code> files.

====Fedora====

Line 1 of the packages is basic dev tools. Lines 2-3 are Daemon dependencies. Line 4 is (additional) Unvanquished dependencies.

$ sudo dnf install \
cmake gcc gcc-c++ \
{freetype,glew,gmp,mesa-libGL,ncurses,nettle,openal-soft,opus,opusfile,SDL2}-devel \
lib{curl,jpeg-turbo,png12,vorbis,webp}-devel \
lua-devel python3-pyyaml python3-jinja2

====Gentoo====

$ emerge curl freetype glew gmp jpeg ncurses media-sound/opus-tools libogg openal libpng libsdl libvorbis sys-libs/zlib

====openSUSE====

$ sudo install zypper gcc gcc-c++ Mesa-libGL-devel SDL-devel libjpeg8-devel \
libpng12-devel glew-devel webp-devel ncurses-devel gmp-devel libcurl-devel \
libnettle-devel openal-soft-devel libvorbis-devel

The latest version of WebP must be installed manually (FIXME: why, if there is webp-devel in the zypper package list?):

$ cd Unvanquished/daemon/external_deps
$ ./build.sh linux-amd64-default webp naclsdk naclports
$ ./build.sh linux-amd64-default install

You must disable curses (set <code>USE_CURSES</code> appropriately in CMake) as failing to do so will cause Unvanquished to crash on startup.

===Configuring the code with CMake===

After you have [[Getting the source|acquired the source code]], you can proceed to compile. Unvanquished uses CMake, so you must have that installed.

====Using ccmake (curses-based front-end)====

On Debian or Ubuntu:

$ sudo apt-get install cmake-curses-gui

On Gentoo you should set the '''ncurses''' USE flag either globally or individually, just for cmake.
To add the USE flag globally, edit the USE array in /etc/make.conf for it to include '''ncurses'''.
To only install cmake with ncurses functionality, you could do the following:

$ echo 'dev-util/cmake ncurses' >> /etc/portage/package.use && emerge cmake

Note that in Ubuntu, <code>cmake-curses-gui</code> is in Universe, which you may have to enable with <code>software-properties-gtk</code>. Make sure to reload the software sources with <code>sudo apt-get update</code> afterwards.

Optionally: to use clang (rather than the default gcc and g++ compilers) export the CC and CXX variables before running cmake:

$ export CC="clang"
$ export CXX="clang++ -stdlib=libc++ -lc++abi"

Next, configure the codebase.

$ cd <var>/path/to/unvanquished</var>
$ mkdir build
$ cd build
$ ccmake ..

In Debian or Ubuntu you can build a package this way (you need <code>devscripts</code> and <code>fakeroot</code> packages):

$ cd <var>/path/to/unvanquished</var>
$ fakeroot dpkg-buildpackage -b -uc
$ sudo dpkg -i <var>../unvanquished_*.deb</var>

Once in <code>ccmake</code>, use the following keys:

* Press {{Hotkey|c}} to configure. If an error occurs during this phase, make note of it and press {{Hotkey|e}} to dismiss it.
* Use the up and down arrow keys to navigate the compilation options.
* Press {{Hotkey|Enter}} to enable or disable boolean options (i.e., on/off) or to edit textual options.
** Press {{Hotkey|Esc}} when editing a textual option to cancel the change.

Once you have finished the configuration process, press {{Hotkey|C}} again, then {{Hotkey|G}} to generate the makefile.

====Using cmake-qt-gui (graphical front-end)====

This graphical front end for cmake has its own package you must install:

=====Debian/Ubuntu=====

$ sudo apt-get install cmake-qt-gui

=====Gentoo=====

With the '''qt4''' USE flag enabled:

$ emerge cmake

Once installed, run with <code>cmake-gui</code>.

[[Image:Cmake-qt-gui.png|thumb]]

# Set the path where you have the source code downloaded.
# Set the path where you would like to build the engine. This may be the same directory if you wish.
# Click 'Configure'.
# Click 'Generate'.

====Unnecessary libraries====

Regardless of which front-end to cmake you use, you may want to disable some libraries that are not strictly necessary:

* <code>USE_BREAKPAD</code> — Disabling this will cause the game to not produce crashdumps on failure.
* <code>USE_CURSES</code> — Disabling this will cause the external (not in-game) console to not use curses; it will not be scrollable and will be similar to the console in the original Tremulous. This does in no way affect gameplay.

===Compiling===

$ cd <var>path/to/unvanquished/build</var>
$ make -j4

The <code>-j</code> switch to make allows you to speed up the compilation process by running it in multiple threads; set the number following this to the number of cores your processor(s) have.

==FreeBSD==

While building on FreeBSD is usually very similar to building on Linux, the PNaCl toolchain not being native to FreeBSD means not everything can be built on FreeBSD. See the [[Systems/FreeBSD]] page for details and dedicated instructions.

==Acquiring the Game Files==

===Acquiring mandatory game files===

The game files are not in the Git repository, and must be downloaded separately. They must be saved to the [[Game locations|data location]] for your system.

Linux users may use the <code>download-paks</code> script that is distributed with the source code, which requires one of curl, wget or aria2 to be installed:

$ cd <var>path/to/unvanquished/build</var>
$ ../download-paks pkg

Otherwise, the set of necessary packages can be extracted from the [https://github.com/Unvanquished/Unvanquished/releases latest release], or downloaded a la carte from the [http://dl.unvanquished.net/pkg/ package index].

MacOS Launch Services security restrictions

2024-10-21T09:00:57Z

Killing time: Created page with "== Quarantine restrictions == Applications downloaded with a browser may are subject to quarantine restrictions. === Denying launch === If you double-click a quarantined app..."

== Quarantine restrictions ==
Applications downloaded with a browser may are subject to quarantine restrictions.

=== Denying launch ===
If you double-click a quarantined app in Finder, it will refuse to run it. This can be bypassed via Command+clicking on the application, selecting <b>Open</b> in the context menu, and clicking through a warning dialog.

Not only applications, but also libraries can be denied launch. Sample text of an error popup:
<blockquote>
“SDL2.framework” cannot be opened because the developer cannot be verified.

macOS cannot verify that this app is free from malware.

Safari downloaded this file today at 06:18.
</blockquote>

In the terminal, the error looks as follows:
<pre>% ./daemon
dyld[8822]: Library not loaded: @rpath/SDL2.framework/Versions/A/SDL2
Referenced from: <71DD614C-D95F-37DD-A29E-765DA0AEEE48> /Users/slipher/Unvanquished/build-newsdl/daemon
Reason: tried: '/Users/slipher/Unvanquished/build-newsdl/SDL2.framework/Versions/A/SDL2' (code signature in <3E6D5145-6DE8-3734-95A7-AE31ED09A1A9> '/Users/slipher/Unvanquished/build-newsdl/SDL2.framework/Versions/A/SDL2' not valid for use in process: library load disallowed by system policy), '/Users/slipher/Unvanquished/build-newsdl/SDL2.framework/Versions/A/SDL2' (code signature in <3E6D5145-6DE8-3734-95A7-AE31ED09A1A9> '/Users/slipher/Unvanquished/build-newsdl/SDL2.framework/Versions/A/SDL2' not valid for use in process: library load disallowed by system policy), '/Library/Frameworks/SDL2.framework/Versions/A/SDL2' (no such file), '/System/Library/Frameworks/SDL2.framework/Versions/A/SDL2' (no such file, not in dyld cache)
zsh: abort ./daemon</pre>

=== App Translocation ===

For quarantined apps that are permitted to launch, there is another possible restriction called [https://lapcatsoftware.com/articles/app-translocation.html App Translocation].
If Unvanquished.app is started with app translocation, the beginning of the output looks as follows:
<pre>cmdline: -pakpath /private/var/folders/37/cwhvzf2j3_ngll0kwst_3k540000gn/T/AppTranslocation/97281FCC-20CC-45CE-8386-D8DF691593C7/d/pkg
tty console mode disabled
^3Warn: [FS] Ignoring path /private/var/folders/37/cwhvzf2j3_ngll0kwst_3k540000gn/T/AppTranslocation/97281FCC-20CC-45CE-8386-D8DF691593C7/d/pkg: No such file or directory
[FS] Lib path: /private/var/folders/37/cwhvzf2j3_ngll0kwst_3k540000gn/T/AppTranslocation/97281FCC-20CC-45CE-8386-D8DF691593C7/d/Unvanquished.app/Contents/MacOS
[FS] Home path: /Users/slipher/Library/Application Support/Unvanquished
[FS] Pak search path: /Users/slipher/Library/Application Support/Unvanquished/pkg</pre>

Daemon is not capable of running under app translocation.

=== The magic bits ===

The <code>com.apple.quarantine</code> extended file attribute is the root cause of all quarantine restrictions. It is added by browsers to downloaded applications. When you download an auto-unzipped .app, it is recursively applied to all files and directories within. A file's extended attributes can be viewed with the command<code>xattr <path></code>. The quarantine attribute can be (recursively) removed using <code>xattr -d -r <path></code>.

There is a launch services database flag that prevents denying launch even in the presence of the quarantine attribute. It can be set by clicking through the dialog to launch despite the danger, or by moving the application in Finder.

There is a launch services database flag that disables app translocation for a quarantined file that is allowed to launch. It can be set by moving the application in the Finder.

Launch services database info follows files across moves (whether by Finder or <code>mv</code>). It might be possible to see these launch services database flags somewhere in the output of <code>/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -dump</code>.

== Directory permissions ==

Sometimes you get a popup asking whether you want to allow the app to access, for example, Downloads or Documents. Example message: <b>"Unvanquished" would like to access files in your Downloads folder.</b> The application's file operation blocks while waiting for the user to respond to the dialog. Not sure what relation this has to quarantine restrictions.

Compatibility

2024-10-05T13:21:49Z

Killing time: More specific assets policy; misc edits

= Inter-module compatibility =

Unvanquished has many software components: engine binaries, based on the Daemon repository (client and server); gamelogic binaries, based on the Unvanquished repository (cgame and sgame); and various other files shipped in DPKs, which may be used by any of the binaries. Currently, all components are on a single release cycle. A given user normally has only one version of the client installed, but different servers may distribute differing versions of the other components via the auto-download mechanism. This means many different combinations of versions of the components are possible. It can be difficult to reason about which combinations will work correctly, and even which combinations ought to be allowed.

In the rest of this article, "Unvanquished" refers to the eponymous Git repository, not the game.

== Desired use cases ==
=== Use cases we want to support ===
* <b>Develop on next-release branch (e.g. <code>0.52.0/sync</code>) of all repos (Daemon, Unvanquished)</b>
* <b>Develop on master branch of all repos</b>
* <b>Build client from latest master and connect to latest-release servers</b> <br> We should be able to play with everyone on a client with the latest bug fixes.
* <b>Build server from latest master and host with latest-release DPKs</b> <br> Likewise with a server.
* <b>Host a server with gamelogic and assets build from latest master.</b>
* <b>Develop Unvanquished on master, using latest-release DPKs</b> <br> Development for simple cases should be accessible, not requiring <code>-pakpath</code> flags etc. Compatibility with the latest-release <code>unvanquished</code> DPK doesn't need to be perfect; it's OK if there are a few warnings or slightly messed up things in the UI. But it should be usable for basic experimentation.

=== Use cases we don't really care about ===
* <i>Using cgame and sgame built from different commits.</i>
* <i>Asset development with latest-release gamelogic.</i>

== Per-repository guidance ==

=== Daemon ===

Adding, modifying, or removing an IPC call must be done on the next-release branch. Likewise for any changes to serialization procedures or structs passed through IPC.

When developing Daemon master, you need to keep in mind compatibility with both the latest release and the current master of the gamelogic.

=== Unvanquished ===

Try to keep the submodule pointer to Daemon at a commits which is compatible with the Unvanquished commit containing them. We want to get a harmonious set of components when we do a recursive checkout of some Unvanquished commit.

Changing the <code>playerState_t</code> netcode is acceptable because the netcode table is stored in the gamelogic and we recommend always building cgame and sgame together.

It's OK to put gameplay changes on master.

=== *.dpkdir repos from UnvanquishedAssets ===

Changes to the master branch should be compatible with the master gamelogic, but need not be compatible with the last-release gamelogic. The master branch of assets should be compatible with either the master engine or the latest-release engine. If an asset requires an engine newer than the last release to work, it should go in a next-release branch.

If possible, we want to avoid any situation where developers are required to use any unreleased stuff from these to get a working setup.

MinGW

2024-09-30T00:40:45Z

Killing time: CBSE_PYTHON_PATH

MinGW is a GCC-based compiler toolchain targeting Windows platforms. It is used to produce the Windows releases of Unvanquished. It can be quite complicated to use successfully, in part due to the existence of different compiler "flavors", and confusing naming schemes. This page serves as a guide to both MinGW in general, and specifically in application to building Daemon and Unvanquished. Throughout this page, "MinGW" will be used to refer to the [http://mingw-w64.org/ mingw-w64] project, which is a fork of the (now long-moribund) "original MinGW" project aiming to support both 32- and 64-bit builds. So beware: something having "64" in its name does not at all imply it is for 64-bit binaries! Same goes for "32".

== Flavors ==

=== Bitness: 32-bit or 64-bit ===

Whether to compile for 32-bit ("i686" in package names) or 64-bit ("x86-64" or "x86_64") architecture. 64-bit Windows versions are capable of running 32-bit executables in a mode called WOW (Windows-on-Windows).

=== Threading flavor ===
You can get <code>win32</code> or <code>posix</code> thread models. Daemon must be built with the <code>posix</code> flavor, because code that uses <code>std::thread</code> does not compile with <code>win32</code>. In general there is no reason to use <code>win32</code>. However, it is unfortunately the default in the APT package manager.

=== Exception handling flavor ===

* <code>sjlj</code> (setjmp/longjmp) is available for both 32- and 64-bit builds. It has the drawback of significant runtime cost.
* <code>dwarf</code> is available only for 32-bit. It has good performance, but it is said to have a drawback that exceptions can't be propagated through code compiled with a different compiler (or C code?). However, propagating exceptions through C code shouldn't be needed for Daemon.
* <code>seh</code> (Structured Exception Handling) is available only for 64-bit. It has good performance and always works correctly, so it should always be used for 64-bit.

One way to identify which exception model code was built with is to check the libgcc dependency. You'll find for example <code>libgcc_s_seh-1.dll</code> for SEH, <code>libgcc_s_dw2-1.dll</code> for DWARF, or <code>libgcc_s_sjlj-1.dll</code> for sjlj. An easy way to make a C++ test program emit a libgcc dependency is to add a try/catch block.

=== Mixing flavors ===

Mixing different thread or exception flavors can cause problems, such as missing DLL dependencies, or exception handling not working.

For the <code>external_deps</code> libraries, efforts have been made to avoid depending on any thread-flavor-specific or exception-flavor-specific libraries, so it should be possible to use them with any flavor of MinGW. Exception handling glitches shouldn't be an issue since the Windows depencies are C-only.

== Distributions ==

=== Cross-compiling from Linux ===

Most Linux package managers offer some form of MinGW package. Availability of different flavor combinations varies.

==== Installation ====
APT (Debian Buster or older):
<pre># 32-bit, sjlj. win32 threads are selected by default; switch it to posix
sudo apt install g++-mingw-w64-i686
sudo update-alternatives --set i686-w64-mingw32-gcc /usr/bin/i686-w64-mingw32-gcc-posix
sudo update-alternatives --set i686-w64-mingw32-g++ /usr/bin/i686-w64-mingw32-g++-posix

# 64-bit, SEH. win32 threads are selected by default; switch it to posix
sudo apt install g++-mingw-w64-x86-64
sudo update-alternatives --set x86_64-w64-mingw32-gcc /usr/bin/x86_64-w64-mingw32-gcc-posix
sudo update-alternatives --set x86_64-w64-mingw32-g++ /usr/bin/x86_64-w64-mingw32-g++-posix
</pre>

APT (Debian Bullseye or newer):
* <code>sudo apt install gcc-mingw-w64-i686-posix</code> (32-bit, posix, sjlj)
* <code>sudo apt install gcc-mingw-w64-x86-64-posix</code> (64-bit, posix, SEH)

==== Usage ====

To build a CMake project, you need a "toolchain file". Sadly, there is no official toolchain file from MinGW or CMake. For Daemon and Unvanquished we use [https://github.com/DaemonEngine/Daemon/blob/master/cmake/cross-toolchain-mingw32.cmake this (32-bit)] and [https://github.com/DaemonEngine/Daemon/blob/master/cmake/cross-toolchain-mingw64.cmake this (64-bit)]. Use it by passing <code>-DCMAKE_TOOLCHAIN_FILE=<path></code> on the <code>cmake</code> command line.

=== MSYS2 ===

MSYS2 runs on Windows hosts and provides up-to-date 32-bit/DWARF/posix and 64-bit/SEH/posix toolchains. Building is done from a Bash shell in a partial emulation of a Linux environment, similar to Cygwin.

==== Installation ====

Download from [https://www.msys2.org].

Install dependencies to build Daemon (can be done from any MSYS2 shell flavor):
<pre>
# 32-bit
pacman -Sy mingw-w64-i686-gcc mingw64-i686-cmake make
# 64-bit
pacman -Sy mingw-w64-x86_64-gcc mingw64-x86_64-cmake make
</pre>

==== Usage ====
You must open a different MSYS2 shell flavor according to which architecture you want to target: "MSYS2 MinGW 32-bit" or "MSYS2 MinGW 64-bit". When invoking <code>cmake</code>, you must pass the flag <code>-G"MSYS Makefiles"</code>. When building Unvanquished, the flag <code>-DCBSE_PYTHON_PATH=<path></code> may be of interest, if you want to use a Python other than the one shipped with MSYS2. <code><path></code> should be in the Unix-emulation format, e.g. <code>/c/Python/python.exe</code>.

=== "MinGW-W64-builds" (Standalone Windows version) ===
This distribution (see [https://github.com/niXman/mingw-builds-binaries Github]) provides a toolchain that can be used from the Windows command prompt, without needing a Unix emulation layer. The installer allows you to choose from every valid combination of flavors.

==== Usage ====

Choose the <code>MinGW Makefiles</code> generator in CMake. The location of the toolchain used is determined by finding the first one in your PATH environment variable. Relative to the installation root, the PATH entry should be at <code>mingw32\bin</code> or <code>mingw64\bin</code>.

After running CMake, compile by running <code>mingw32-make</code> in the build directory.

== Built-in DLL dependencies ==

There are a few DLLs shipped as part of MinGW that most programs will depend on. These are also available as static libraries (a fully static binary can be produced with the <code>-static</code> flag), but dynamic is the default. These are:
* <code>libgcc</code>
* <code>libstdc++</code> (for C++ programs)
* <code>libssp</code> (if stack protection is enabled)
* <code>libwinpthread</code> (if threads are used)

<code>libstdc++</code> is both thread- and exception-flavor-dependent, but unlike <code>libgcc</code>, the DLL does not have the flavor written in the filename. This means that you can't easily tell if you have the right one (nor can the Windows executable loader). [https://github.com/lucasg/Dependencies Dependencies] is a good tool to investigate such issues.

When distributing a binary release of Daemon, you must ship these DLLs alongside the executable, else you will run into [https://github.com/Unvanquished/Unvanquished/issues/716 this issue]. Note that unlike Daemon's other DLL dependencies (from the <code>external_deps</code> package), the MinGW DLLs are not automatically copied to the build directory as part of the build process. See <code>extra_dll_list</code> and <code>findDll</code> in the [https://github.com/Unvanquished/release-scripts/blob/master/build-release Unvanquished release script].

== C ABI compability with MSVC ==

On 32-bit x86, GCC has a different default stack alignment (16 bytes) than MSVC (4 bytes). This can cause problems when MSVC-compiled code calls into GCC-compiled code and the alignment is less than expected. One solution, which we use to build MSVC-compatible <code>external_deps</code> DLLs, is to use a GCC flag (<code>-mpreferred-stack-boundary=</code>) to change the presumed stack alignment. Another, which we use to handle jumps from 3rd-party binaries to our (MinGW-built) code, is to put the annotation <code>__attribute__((force_align_arg_pointer))</code> on the functions which may be called with less alignment than expected, instructing the compiler to perform alignment when the function is called.

<code>-mms-bitfields</code> should be enabled to ensure that the layout of structs containing bitfields matches. This is on by default.

Tools/Breakpad

2024-09-18T22:42:17Z

Killing time: mention gdbserver cvar

Breakpad is the technology for generating and analyzing crash dumps for the Daemon 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 <i>native executable</i> 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: explain how to use this). }}

== Configuration ==

The 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 repo for Daemon Engine is at https://github.com/DaemonEngine/breakpad. If you have already checked out Daemon, then it is located in the <code>libs/breakpad/</code> submodule there. cd into this repo.

Daemon's Breakpad fork is based on https://github.com/jon-turney/google-breakpad, with only minor changes. Jon Turney's version adds MinGW support. It is in turn a fork of Chromium's Breakpad https://chromium.googlesource.com/breakpad/breakpad.

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

MinGW

2024-09-16T21:24:39Z

Killing time: /* "MinGW-W64-builds" (Standalone Windows version) */ this distribution was resurrected yay

MinGW is a GCC-based compiler toolchain targeting Windows platforms. It is used to produce the Windows releases of Unvanquished. It can be quite complicated to use successfully, in part due to the existence of different compiler "flavors", and confusing naming schemes. This page serves as a guide to both MinGW in general, and specifically in application to building Daemon and Unvanquished. Throughout this page, "MinGW" will be used to refer to the [http://mingw-w64.org/ mingw-w64] project, which is a fork of the (now long-moribund) "original MinGW" project aiming to support both 32- and 64-bit builds. So beware: something having "64" in its name does not at all imply it is for 64-bit binaries! Same goes for "32".

== Flavors ==

=== Bitness: 32-bit or 64-bit ===

Whether to compile for 32-bit ("i686" in package names) or 64-bit ("x86-64" or "x86_64") architecture. 64-bit Windows versions are capable of running 32-bit executables in a mode called WOW (Windows-on-Windows).

=== Threading flavor ===
You can get <code>win32</code> or <code>posix</code> thread models. Daemon must be built with the <code>posix</code> flavor, because code that uses <code>std::thread</code> does not compile with <code>win32</code>. In general there is no reason to use <code>win32</code>. However, it is unfortunately the default in the APT package manager.

=== Exception handling flavor ===

* <code>sjlj</code> (setjmp/longjmp) is available for both 32- and 64-bit builds. It has the drawback of significant runtime cost.
* <code>dwarf</code> is available only for 32-bit. It has good performance, but it is said to have a drawback that exceptions can't be propagated through code compiled with a different compiler (or C code?). However, propagating exceptions through C code shouldn't be needed for Daemon.
* <code>seh</code> (Structured Exception Handling) is available only for 64-bit. It has good performance and always works correctly, so it should always be used for 64-bit.

One way to identify which exception model code was built with is to check the libgcc dependency. You'll find for example <code>libgcc_s_seh-1.dll</code> for SEH, <code>libgcc_s_dw2-1.dll</code> for DWARF, or <code>libgcc_s_sjlj-1.dll</code> for sjlj. An easy way to make a C++ test program emit a libgcc dependency is to add a try/catch block.

=== Mixing flavors ===

Mixing different thread or exception flavors can cause problems, such as missing DLL dependencies, or exception handling not working.

For the <code>external_deps</code> libraries, efforts have been made to avoid depending on any thread-flavor-specific or exception-flavor-specific libraries, so it should be possible to use them with any flavor of MinGW. Exception handling glitches shouldn't be an issue since the Windows depencies are C-only.

== Distributions ==

=== Cross-compiling from Linux ===

Most Linux package managers offer some form of MinGW package. Availability of different flavor combinations varies.

==== Installation ====
APT (Debian Buster or older):
<pre># 32-bit, sjlj. win32 threads are selected by default; switch it to posix
sudo apt install g++-mingw-w64-i686
sudo update-alternatives --set i686-w64-mingw32-gcc /usr/bin/i686-w64-mingw32-gcc-posix
sudo update-alternatives --set i686-w64-mingw32-g++ /usr/bin/i686-w64-mingw32-g++-posix

# 64-bit, SEH. win32 threads are selected by default; switch it to posix
sudo apt install g++-mingw-w64-x86-64
sudo update-alternatives --set x86_64-w64-mingw32-gcc /usr/bin/x86_64-w64-mingw32-gcc-posix
sudo update-alternatives --set x86_64-w64-mingw32-g++ /usr/bin/x86_64-w64-mingw32-g++-posix
</pre>

APT (Debian Bullseye or newer):
* <code>sudo apt install gcc-mingw-w64-i686-posix</code> (32-bit, posix, sjlj)
* <code>sudo apt install gcc-mingw-w64-x86-64-posix</code> (64-bit, posix, SEH)

==== Usage ====

To build a CMake project, you need a "toolchain file". Sadly, there is no official toolchain file from MinGW or CMake. For Daemon and Unvanquished we use [https://github.com/DaemonEngine/Daemon/blob/master/cmake/cross-toolchain-mingw32.cmake this (32-bit)] and [https://github.com/DaemonEngine/Daemon/blob/master/cmake/cross-toolchain-mingw64.cmake this (64-bit)]. Use it by passing <code>-DCMAKE_TOOLCHAIN_FILE=<path></code> on the <code>cmake</code> command line.

=== MSYS2 ===

MSYS2 runs on Windows hosts and provides up-to-date 32-bit/DWARF/posix and 64-bit/SEH/posix toolchains. Building is done from a Bash shell in a partial emulation of a Linux environment, similar to Cygwin.

==== Installation ====

Download from [https://www.msys2.org].

Install dependencies to build Daemon (can be done from any MSYS2 shell flavor):
<pre>
# 32-bit
pacman -Sy mingw-w64-i686-gcc mingw64-i686-cmake make
# 64-bit
pacman -Sy mingw-w64-x86_64-gcc mingw64-x86_64-cmake make
</pre>

==== Usage ====
You must open a different MSYS2 shell flavor according to which architecture you want to target: "MSYS2 MinGW 32-bit" or "MSYS2 MinGW 64-bit". When invoking <code>cmake</code>, you must pass the flag <code>-G"MSYS Makefiles"</code>. When building Unvanquished, the flag <code>-DDAEMON_CBSE_PYTHON_PATH=<path></code> may be of interest, if you want to use a Python other than the one shipped with MSYS2. <code><path></code> should be in the Unix-emulation format, e.g. <code>/c/Python/python.exe</code>.

=== "MinGW-W64-builds" (Standalone Windows version) ===
This distribution (see [https://github.com/niXman/mingw-builds-binaries Github]) provides a toolchain that can be used from the Windows command prompt, without needing a Unix emulation layer. The installer allows you to choose from every valid combination of flavors.

==== Usage ====

Choose the <code>MinGW Makefiles</code> generator in CMake. The location of the toolchain used is determined by finding the first one in your PATH environment variable. Relative to the installation root, the PATH entry should be at <code>mingw32\bin</code> or <code>mingw64\bin</code>.

After running CMake, compile by running <code>mingw32-make</code> in the build directory.

== Built-in DLL dependencies ==

There are a few DLLs shipped as part of MinGW that most programs will depend on. These are also available as static libraries (a fully static binary can be produced with the <code>-static</code> flag), but dynamic is the default. These are:
* <code>libgcc</code>
* <code>libstdc++</code> (for C++ programs)
* <code>libssp</code> (if stack protection is enabled)
* <code>libwinpthread</code> (if threads are used)

<code>libstdc++</code> is both thread- and exception-flavor-dependent, but unlike <code>libgcc</code>, the DLL does not have the flavor written in the filename. This means that you can't easily tell if you have the right one (nor can the Windows executable loader). [https://github.com/lucasg/Dependencies Dependencies] is a good tool to investigate such issues.

When distributing a binary release of Daemon, you must ship these DLLs alongside the executable, else you will run into [https://github.com/Unvanquished/Unvanquished/issues/716 this issue]. Note that unlike Daemon's other DLL dependencies (from the <code>external_deps</code> package), the MinGW DLLs are not automatically copied to the build directory as part of the build process. See <code>extra_dll_list</code> and <code>findDll</code> in the [https://github.com/Unvanquished/release-scripts/blob/master/build-release Unvanquished release script].

== C ABI compability with MSVC ==

On 32-bit x86, GCC has a different default stack alignment (16 bytes) than MSVC (4 bytes). This can cause problems when MSVC-compiled code calls into GCC-compiled code and the alignment is less than expected. One solution, which we use to build MSVC-compatible <code>external_deps</code> DLLs, is to use a GCC flag (<code>-mpreferred-stack-boundary=</code>) to change the presumed stack alignment. Another, which we use to handle jumps from 3rd-party binaries to our (MinGW-built) code, is to put the annotation <code>__attribute__((force_align_arg_pointer))</code> on the functions which may be called with less alignment than expected, instructing the compiler to perform alignment when the function is called.

<code>-mms-bitfields</code> should be enabled to ensure that the layout of structs containing bitfields matches. This is on by default.

Continuous integration

2024-09-10T05:11:51Z

Killing time: /* Build matrix */ fix unv appveyor generator

[[Category:Infrastructure]]
Continuous integration (CI) refers to the automated builds that run each time someone opens or modifies a pull request against, or modifies the code of, the Unvanquished and Daemon source code repositories on GitHub.

We use the following CI services:
* Appveyor, for building with MSVC on Windows. Its configuration is found in the file {{code|.appveyor.yml}} in the repository root.
* Azure Pipelines. Its configuration is found in the file {{code|azure-pipelines.yml}} in the repository root. It handles Mac native builds on [https://github.com/actions/virtual-environments/blob/main/images/macos/macos-11-Readme.md macOS 11.x] and Linux native and NaCl builds on [https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2004-Readme.md Ubuntu 20.04] (Focal).
* GitHub CodeQL. Its configuration is found in the file {{code|.github/workflows/codeql.yml}} in the repository. Its purpose is to scan the source code for vulnerabilities, and for that purpose it starts by building the source tree using the latest LTS Ubuntu distribution provided by the platform ([https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2004-Readme.md Ubuntu 22.04]) and the default compiler of this platform.

In some Daemon builds, we run the unit tests. These builds have been configured to use the Release configuration so that the unit tests are closer to production builds.

== Build matrix ==

{|
! colspan="9" | {{engine}}
|-
! Service
! Host
! Target
! Compiler
! Generator
! Build Type
! WERROR
! PCH
! Unit tests
|-
| Appveyor || Windows amd64 || Windows amd64 || VS 2019 || Visual Studio || Release || Yes || No || Yes
|-
| Appveyor || Windows amd64 || Windows i686 || VS 2019 || Visual Studio || Release || Yes || No || Yes
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Windows amd64 || MinGW 9.3 || Ninja || Release || Yes || No || No
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 || GCC 9.4 || Ninja || Release || Yes || No || Yes
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 || Clang 11.0 || Ninja || Release || Yes || No || Yes
|-
| Azure Pipelines || macOS-11 amd64 || macOS amd64 || AppleClang 13.0 || Make || Release || Yes || No || Yes
|-
| GitHub Actions CodeQL || ubuntu-latest || Linux amd64 || GCC (floating) || Ninja || Release || No || Yes || No
|}
<br>
{|
! colspan="8" | {{game}}
|-
! Service
! Host
! Target
! Compiler
! Generator
! Build Type
! WERROR
! PCH
|-
| Appveyor || Windows amd64 || Windows i686 DLL || VS 2019 || NMake || Debug || Yes || No
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 DLL || GCC 8.4 || Ninja || Debug || Yes || No
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 DLL || Clang 11.0 || Ninja || Debug || Yes || No
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || NaCl all NEXE || PNaCl Clang 3.6 || Ninja || Debug || Yes || No
|-
| Azure Pipelines || macOS-12 amd64 || macOS amd64 DLL || AppleClang 14.0 || Make || Debug || Yes || No
|-
| GitHub Actions CodeQL || ubuntu-latest || Linux amd64 DLL+EXE || GCC (floating) || Ninja || Release || No || Yes
|}

“WERROR” indicates whether the {{code|USE_WERROR}} option is on, which gives a failing building build status if there are warnings in our code. Note that {{code|USE_WERROR}} only applies to ”our” code in {{code|src/}}, so you may still see warnings from stuff in {{code|libs/}}.

“PCH” indicates whether the precompiled header is enabled.

Testing/Maps

2024-08-24T17:23:06Z

Killing time: Greatly expand the page

[[Category:Testing]]
[[Category:Mapping]]
==Finding gameplay testers==
To publicly test your maps, make a thread [https://forums.unvanquished.net/viewforum.php?f=9 on forums] to share your work-in-progress work and some server admins will probably host it ;-).

==Cheat commands and cvars==
* To fly around the map, use the <code>\noclip</code> command.<br/>If you find that you are moving too slowly (or too fast), you may change the speed with <code>cg_flySpeed</code>.
* To spawn as granger or ckit in your current location, use <code>/devteam a</code> or <code>/devteam h</code>.
* To make yourself invincible, use the <code>\god</code> command.
* To stop buildables from attacking, use the <code>\notarget</code> command.
* See [[Map Layouts]] for buildable layout management commands.

===Some rendering debugging cvars===
* To lock the state of PVS, set <code>r_lockpvs</code> to <code>1</code>. Be aware of the difference between this and <code>r_novis</code>: this disables any ''updates'' to the state of the PVS buffer  but PVS is still in effect; this can make flying outside of a map difficult.
* To disable PVS entirely, set <code>r_novis</code> to <code>1</code>.
* To disable PVS for entities, set <code>sv_novis</code> to <code>1</code>.

{{Note|header=Developer Note|content=
The reason that enabling/disabling PVS for entities is controlled with a separate cvar from the world is that the server is responsible for determining when to send information about entities to the client. The server considers two things:
* if the entity is within radar range of the player, and
* if the entity is potentially visible to the player.
The server will send the position of an entity if it meets one or both of these conditions.}}

* [Engine version 0.55+] If parts of the map seem too bright, try setting <code>r_forceLegacyOverbrightClamping 1</code> to see if it looks better with this cvar that makes lighting more like older versions.
* If things are not being rendered that should be, try setting <code>r_nocull 1</code> to disable CPU-side culling of surfaces.

=== For debugging map entities ===
* Set <code>cg_drawEntityInfo 1</code> to identify an entity's class and number by looking at it
* <code>/listEntities</code> to print details of all entities in the console
* <code>/showEntity <num></code> to print detailed information about a single entity
* Set <code>g_debugEntities</code> to some value between 1 and 3 to get more logging
* <code>/entityFire <num></code>

=== For debugging bot navigation problems ===
* <code>/navedit enable <classname></code> to show the navigation mesh

=== For toggling rendering of specific things ===
Disabling rendering of X may help to answer questions such as "Is this thing I'm looking at an X?" or "Is everything messed up because rendering of X is going haywire?"

* Set <code>r_drawWorld 0</code> to disable rendering of the fixed part of the world
* Set <code>r_drawEntities 0</code> to disable the complement of r_drawWorld?
* Set <code>r_noCurves 1</code> to disable patches (SF_GRID surfaces)
* Set <code>r_noFog 1</code> to disable fog
* Set <code>r_noportals 1</code> to disable mirrors/portals

=== For testing maps from games other than Unvanquished or Tremulous ===
* Set <code>g_neverEnd 1</code> to avoid the game instantly ending due to lack of an Unvanquished layout.
* Set <code>fs_legacypaks 1</code> to load .pk3 packages. The way this works is that all .pk3 packages in the pakpath are loaded -- there is no concept of dependencies.
* Set <code>r_dpMaterial 1</code> and <code>r_dpBlend 1</code> for testing DarkPlaces engine (Xonotic) maps

=== More obscure rendering debugging cvars ===
These can be difficult to interpret and are probably rarely useful.
* Set <code>r_showLightGrid 1</code> to visualize the lightgrid.
* Set <code>r_showEntityTransforms 1</code> to see bounding boxes of renderer "entities" (these do not necessarily to gamelogic/map entities)
* Set <code>r_showBspNodes</code> between 1 and 3 to see BSP divisions.
* Set <code>r_showTris 1</code> to see outlines of all triangles. Might want to combine with <code>cg_draw2d 0</code> to reduce noise
* Set <code>r_showSky 1</code> to draw the sky on top of everything else

== Replacing the entity lump ==
You can put a file named <code>maps/$mapname$.ent</code> in the VFS to override the entity lump in the BSP with one of your own choosing.

Maps

2024-08-24T15:35:26Z

Killing time: /* Map repositories */ add list of links to all paks on unvanquished.net

[[Category:Maps]]

== Map repositories ==

Places you can download DPKs or source repositories for various maps.

=== Ready-to-play DPKs for Unvanquished ===

All of the URLs here are HTTP servers used to provide automatic downloads when a player connects to a server but lacks a needed pak, so they will have other kinds of paks besides maps. You can find these URLs by setting <code>/logs.level.client.pakDownload debug</code> in the console and connecting to a server while missing a pak, then looking for the console line starting <code>Debug: Checking for PAKSERVER in </code>. The rest of the line is the download base URL.

Excluding the "official" maps in the Unvanquished release, the vast majority of available maps were originally made for Tremulous or other games. The owners of servers mentioned here have generally done some testing and touch-ups to ensure the maps work correctly in Unvanquished, but not everything works 100%.

* Official maps: https://dl.unvanquished.net/pkg/
* Maps from the server "Map&Bot Testing EU" run by Sweet: https://users.unvanquished.net/~sweet/pkg/. 350 maps as of November 2023.
* Maps from the server "deadbeef" run by bmorel: http://deadbeef.fr/unvanquished/. 313 maps as of November 2023. Has a directory with [[Levelshot|levelshots]].

=== Tremulous maps in original form (.pk3) ===

You can also find a bunch of maps from Tremulous: [https://dl.unvanquished.net/mercenaries-guild/public_html/maps/].
Despite this link being on official's Unvanquished's server, those are *not* officially supported and require modifications to be played. If you are lucky, you can get them working (locally) by simply renaming them in your own unvanquished/pkg folder like this: {{code|map-${name}_${version}.dpk}}.
And despite all this, there is no guarantee those will work, and even less that they'll be bug-free.

Feel free to meet us on [https://unvanquished.net/chat/] to ask what needs to be done to have those more widely used by server owners!

=== Complete list of paks available from unvanquished.net ===

https://users.unvanquished.net/~slipher/pak-duplicate-report.txt contains links to all paks (maps and otherwise) that can be downloaded from any place on the unvanquished.net server. Includes both pk3 and dpk paks. Beware, this contains all sorts of junk, like invalid zip files or maps that don't work properly in any version of the game.

=== Source repositories ===

Git repositories with sources (.map files). For mappers and project maintainers. Must be built with NetRadiant or Urcheon to be playable.

* Official maps are in the [https://github.com/UnvanquishedAssets UnvanquishedAssets] organization on Github. The map <code>$mapname$</code> can be found at <code><nowiki>https://github.com/UnvanquishedAssets/map-$mapname$_src.dpkdir</nowiki></code>.
* [https://github.com/InterstellarOasis/InterstellarOasis Interstellar Oasis] is a collection of "first-class" source ports by illwieckz of Tremulous maps. These are unofficial maps, but the work is done by one of the Unvanquished project heads.
* [https://github.com/Masmblr?tab=repositories Masmblr's Github] has source repositories for 26 Tremulous maps created by himself.

==Official Unvanquished Maps==

These maps are distributed with the default installation

{|class="wikitable"
|-
! Name and Description
! Levelshot
|-

| '''Antares'''
* Varied rooms and corridors
by Pevel

{{Subpage|Antares}}
|[[File:antares.jpg|400px]]
|-

|'''Chasm'''
* Two route design
* Medium sized
* Outside area
by Supertanker

{{Subpage|Chasm}}
|[[File:Levelshots-Snowstation-b4.jpg|400px]]
|-

| '''Forlorn'''
* Varied rooms and corridors
by EmperorJack

{{Subpage|Forlorn}}
|[[File:Forlorn.jpg|400px]]
|-

| '''Parpax'''
* Medium sized
* Many branching paths
* Crawl spaces and piping
* Elevators
by Viech

{{Subpage|Parpax}}
|[[File:Levelshots-Parpax_compressed.jpg|400px]]
|-

|'''Perseus'''
* Medium sized
by Pevel

{{Subpage|Perseus}}
|[[File:Perseus.jpg|400px]]
|-

| '''Platform 23'''
* Symmetrical
* Replacement for ATCS
* Two route design
by EmperorJack

{{Subpage|Plat23}}
|[[File:Levelshots-Plat23-b11.jpg|400px]]
|-

|'''Spacetracks'''
* Varied rooms, corridors and layers
* Many Elevators
* Crawl spaces
by Supertanker

{{Subpage|Spacetracks}}
|[[ File:Levelshots-Spacetracks-r1.jpg |400px]]
|-

| '''Station15'''
* Varied rooms and corridors
* Elevators
by Supertanker

{{Subpage|Station15}}
|[[File:Levelshots-Station15-r1.jpg|400px]]
|-

| '''Thunder'''
* Very large
by EmperorJack

{{Subpage|Thunder}}
|[[File:Levelshot-thunder.jpeg|400px]]
|-

| '''Vega'''
* Large
by Ingar

{{Subpage|Vega}}
|[[File:vega.jpg|400px]]
|-

| '''Yocto'''
* Vertical
by Pevel

{{Subpage|Yocto}}
|[[File:Levelshot-Yocto-b1a.jpg|400px]]
|-

|}

=Gentrified Maps=

Maps that were born in Tremulous.

{|class="wikitable"
|-
! Name and Description
! Levelshot
|-

| '''.:U.T:C.S:.'''
* Symmetrical
* Two route design
* Small

{{Subpage|UTCS}}
| [[File:Levelshot-Utcs.jpg|400px]]
|-

| '''Arachnid 2'''
* Varied rooms, corridors and layers
* Crawl spaces and piping
* Medium sized

{{Subpage|Arachnid}}
| [[File:Levelshots-Arachnid2.jpg|400px]]
|-

|'''Beyond Derelict'''
* Varied rooms, corridors and layers
* Crawl spaces
* Large
by Danny "Megabite" Marcus

{{Subpage|Derelict}}
|[[File:Levelshots-Derelict.jpg|400px]]
|-

|'''Karith Station 2'''
* Varied rooms, corridors and layers
* Outside area
* Crawl spaces
* Large
* Elevators
by Godmil

{{Subpage|Karith}}
|[[File:Levelshots-Karith.jpg|400px]]
|-

| '''Meep'''
* Varied rooms, corridors and layers
* Crawl spaces
* Medium sized
By Catalyc

{{Subpage|Meep}}
|[[File:Levelshots-Meep.jpg|400px]]
|-

| '''Methane (beta 1)'''
* Large
* Vertically complex
by Ingar

{{Subpage|Methane}}
|[[File:Levelshots-Methane-beta1.jpg|400px]]
|-

|'''Nano!'''
* Very Small
* Symmetrical
by Ingar

{{Subpage|Nano}}
|[[File:Levelshots-Nano.jpg|400px]]
|-

|'''Nexus 6'''
* Varied rooms, corridors and layers
* Crawl spaces
* Medium sized

{{Subpage|Nexus}}
|[[File:Levelshots-Nexus6.jpg|400px]]
|-

|'''Niveus : Outpost 652'''
* Varied rooms, corridors and layers
* Medium sized

{{Subpage|Niveus}}
|[[File:Levelshots-Niveus.jpg|400px]]
|-

|'''Orion I - communication ship (beta 2)'''
* Varied rooms, corridors and layers with some vents
* Medium sized
by Xenom[GER]

{{Subpage|Orion}}
|[[File:Levelshots-Orion.jpg|400px]]
|-

|'''Procyon - '''
* Varied rooms, corridors and layers and vents
* Large sized
by Ingar

{{Subpage|Procyon}}
|[[File:Levelshots-procyon.jpg|400px]]
|-

|'''Sirius - '''
* Varied rooms, corridors and layers
* Large sized
by Ingar

{{Subpage|Sirius}}
|[[File:Levelshots-sirius.jpg|400px]]
|-

|'''Tremor'''
* Medium sized
* Large rooms and corridors
* Crawl spaces (underground section)
by Vedacon

{{Subpage|Tremor}}
|[[File:Levelshots-Tremor.jpg|400px]]
|-

|'''Uranium124 '''
* Varied rooms, corridors and layers
* Small sized
by CoderNem

{{Subpage|Uranium124}}
|[[File:Levelshots-uranium124.jpg|400px]]
|-

|}

==community maps==

Maps produced (and not already listed) by the community which are known to work for unvanquished, for both tremulous and unvanquished.

Licences of images is the same as the map itself, this will be updated later.
This section have lot of things to do, including adding author's names, licencing informations, simple map descriptions, etc.

{|class="wikitable"
|-
! Name and Description
! Levelshot
|-

|'''area3'''
|[[File:Levelshots-area3.jpg|400px]]
|-

|'''atcshd'''
|[[File:Levelshots-atcshd.jpg|400px]]
|-

|'''ctcs'''
|[[File:Levelshots-ctcs.jpg|400px]]
|-

|'''dretchstorm'''
|[[File:Levelshots-dretchstorm.jpg|400px]]
|-

|'''fortification'''
|[[File:Levelshots-fortification.jpg|400px]]
|-

|'''hamunaptra'''
|[[File:Levelshots-hamunaptra.png|400px]]
|-

|'''hangar28'''
|[[File:Levelshots-hangar28.jpg|400px]]
|-

|'''jota'''
|[[File:Levelshots-jota.jpg|400px]]
|-

|'''openfield'''
|[[File:Levelshots-openfield.jpg|400px]]
|-

|'''peorongateb3'''
|[[File:Levelshots-peorongateb3.jpg|400px]]
|-

|'''ptcs2'''
|[[File:Levelshots-ptcs2.jpg|400px]]
|-

|'''rsmse'''
|[[File:Levelshots-rsmse.jpg|400px]]
|-

|'''stahl'''
|[[File:Levelshots-stahl.jpg|400px]]
|-

|'''terminus'''
|[[File:Levelshots-terminus.jpg|400px]]
|-

|'''transit'''
|[[File:Levelshots-transit.jpg|400px]]
|-

|'''uncreation'''
|[[File:Levelshots-uncreation.jpg|400px]]
|-

|'''urbanp2'''
|[[File:Levelshots-urbanp2.jpg|400px]]
|-

|'''usstremor'''
|[[File:Levelshots-usstremor.jpg|400px]]
|-

|}

Coding convention

2024-07-16T02:26:40Z

Killing time: remove "(legacy)" from quake style

This is the style guide for Unvanquished's and Daemon's source code.

The first rule of style is to follow the style of the surrounding code. If there is a clear convention in the local region of code, continue to use it (with the possible exception of "Obsolete conventions" below). There are two broadly used style conventions, whose particularities are described in the "Quake style" and "New style" sections below.

See also [[Reformatting the source]] and [[Coding with intrinsics]].

== Spacing ==

There is a space between a control structure keyword (e.g. <code>while</code>) and the following <code>(</code>, if applicable.

The curly braces surrounding class, struct, and function definitions go on their own lines.

Consider adding breaking the line if the line is longer than 100 characters (assuming tab width 4?).

Control blocks without braces are discouraged. If you need an if followed by only one line use something like that:

<pre class="green">
if ( foo )
{
bar;
}
</pre>

== Naming conventions ==

* Function names (including member functions) and class names are <code>CamelCase</code>.
* Variable and function argument names are <code>camelCase</code>.
* Struct data members are <code>camelCase</code>.
* Class data members are <code>camelCase_</code> (with a trailing underscore).

Functions that are used by other files have a "namespace" of some kind, either a C++ namespace, or a prefix like <code>G_</code> or <code>FS_</code>. Follow the style of the surrounding code.

Functions that are only used within the same file are marked <code>static</code> and need not have a namespace.

== Other trivialities ==

* When defining a type alias, use <code class="green">using A = B;</code>, not <code class="red">typedef B A;</code>.

* Declare variables as close to the point of first use as possible.

* Do not write <code>void</code> in the parentheses of functions that take zero arguments.

* Always use <code>override</code> for member functions that override a virtual member function.

* <code>struct</code> is usually used for structures that have only public fields and no member functions. <code>class</code> is usually used for structures that have at least one private member and at least one member function. <br><br>Do not add member functions to structs that have a large number of fields and a poorly defined scope of responsibility.

== Quake style ==
This style is found in files inherited from Tremulous (and often further from Quake 3).

* There is always a space after <code>(</code> or <code>[</code> and before <code>)</code> or <code>]</code>, EXCEPT when the parentheses or brackets are empty.
* The curly braces <code>{ }</code> of control structures always go on their own lines.
* File names are <code>snake_case.cpp</code>

=== Obsolete conventions ===
These conventions are often found in Quake-style files, but are '''discouraged''' even for new code in those files.
<ul>
<li>Function banner comments, like this:
<pre class="red">/*
================
GL_TextureMode
================
*/</pre>
There is no need to write the name of a function in a comment preceding it. Documentation about what the function does or how it is implemented is of course welcome.</li>
<li> All local variables declared at the beginning of the function. This exists because old C compilers required variables to be declared at the beginning.</li>
<li>Vertical alignment in lists of function declarations or variable declarations, e.g.
<pre class="red">foo varName;
foobar varName2;</pre></li>
</ul>

== New style ==
This style is commonly found in the BSD-licensed files in Daemon (which are often more-recently created ones). Although it is "new", that does not necessarily mean it is better; many contributors prefer the Quake style.

* No space after <code>(</code> or <code>[</code>, nor before <code>)</code> or <code>]</code>.
* The opening <code>{</code> of a control structure goes on the same line as the <code>if</code>/<code>else</code>/<code>while</code>/etc.
* File names are <code>CamelCase.cpp</code>

== Assertions, self-documentation and dependency reduction ==

* When a function takes a pointer as parameter, if this pointer should never be NULL, use an assertion to test it. (Or use a reference instead?) It helps at debugging, but also to document the code.
* When a function takes a pointer to a struct for read-only access, please mark it as a const pointer.
* If a function only needs a subpart of a struct, pass only that subpart (by example, if you only use gentity_t->playerState_t, only give it a playerState_t*)

== Refactoring ==

when refactoring, if you need to guarantee elements to be accessed together, move them in sub-class. This will help keep consistency with old code while allowing to progressively modernize codebase.
New classes should have theirs own headers and implementation files (explicitly listed in the CMakeLists.txt), except if small.

=== Function and API evolutions ===

Some changes are usually desired, but might have bad side effects like performance cost or different behaviors. Here is a small list of those:

* prefer <code>Str::IsEqual</code> and <code>Str::IsIEqual</code> to <code>Q_stricmp</code> or <code>strcmp</code>. Those need to size of the strings though, which might impact performances in a non negligible (and bad) way.
* prefer to use glm instead of the old Quake vector API (vec3_t, VectorCopy, VectorMA</code>, etc) when possible. But keep in mind that <code>glm::normalize( v )</code> will not handle cases where v have components values of zero.

Continuous integration

2024-06-24T03:19:31Z

Killing time: /* Build matrix */

[[Category:Infrastructure]]
Continuous integration (CI) refers to the automated builds that run each time someone opens or modifies a pull request against, or modifies the code of, the Unvanquished and Daemon source code repositories on GitHub.

We use the following CI services:
* Appveyor, for building with MSVC on Windows. Its configuration is found in the file {{code|.appveyor.yml}} in the repository root.
* Azure Pipelines. Its configuration is found in the file {{code|azure-pipelines.yml}} in the repository root. It handles Mac native builds on [https://github.com/actions/virtual-environments/blob/main/images/macos/macos-11-Readme.md macOS 11.x] and Linux native and NaCl builds on [https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2004-Readme.md Ubuntu 20.04] (Focal).
* GitHub CodeQL. Its configuration is found in the file {{code|.github/workflows/codeql.yml}} in the repository. Its purpose is to scan the source code for vulnerabilities, and for that purpose it starts by building the source tree using the latest LTS Ubuntu distribution provided by the platform ([https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2004-Readme.md Ubuntu 22.04]) and the default compiler of this platform.

In some Daemon builds, we run the unit tests. These builds have been configured to use the Release configuration so that the unit tests are closer to production builds.

== Build matrix ==

{|
! colspan="9" | {{engine}}
|-
! Service
! Host
! Target
! Compiler
! Generator
! Build Type
! WERROR
! PCH
! Unit tests
|-
| Appveyor || Windows amd64 || Windows amd64 || VS 2019 || Visual Studio || Release || Yes || No || Yes
|-
| Appveyor || Windows amd64 || Windows i686 || VS 2019 || Visual Studio || Release || Yes || No || Yes
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Windows amd64 || MinGW 9.3 || Ninja || Release || Yes || No || No
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 || GCC 9.4 || Ninja || Release || Yes || No || Yes
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 || Clang 11.0 || Ninja || Release || Yes || No || Yes
|-
| Azure Pipelines || macOS-11 amd64 || macOS amd64 || AppleClang 13.0 || Make || Release || Yes || No || Yes
|-
| GitHub Actions CodeQL || ubuntu-latest || Linux amd64 || GCC (floating) || Ninja || Release || No || Yes || No
|}
<br>
{|
! colspan="8" | {{game}}
|-
! Service
! Host
! Target
! Compiler
! Generator
! Build Type
! WERROR
! PCH
|-
| Appveyor || Windows amd64 || Windows i686 DLL || VS 2019 || Visual Studio || Debug || Yes || No
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 DLL || GCC 8.4 || Ninja || Debug || Yes || No
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 DLL || Clang 11.0 || Ninja || Debug || Yes || No
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || NaCl all NEXE || PNaCl Clang 3.6 || Ninja || Debug || Yes || No
|-
| Azure Pipelines || macOS-12 amd64 || macOS amd64 DLL || AppleClang 14.0 || Make || Debug || Yes || No
|-
| GitHub Actions CodeQL || ubuntu-latest || Linux amd64 DLL+EXE || GCC (floating) || Ninja || Release || No || Yes
|}

“WERROR” indicates whether the {{code|USE_WERROR}} option is on, which gives a failing building build status if there are warnings in our code. Note that {{code|USE_WERROR}} only applies to ”our” code in {{code|src/}}, so you may still see warnings from stuff in {{code|libs/}}.

“PCH” indicates whether the precompiled header is enabled.

UI/Lua in the UI

2024-06-15T22:22:33Z

Killing time: rocket vs rmlui updates

[[Category:UI]]
Lua scripting can be used in the RmlUi-based UI, similar to how JavaScript can be used on a web page.

Older versions of the RmlUi library were called libRocket, which explains the prevalence of the word "Rocket" in the code.

= Documentation resources =

The [https://mikke89.github.io/RmlUiDoc/pages/lua_manual.html RmlUi Lua Manual] is useful. Note that the version of RmlUi we are using is out of date.

It's also possible to read the librocket.com documentation in the Internet Archive/Wayback Machine.

Grepping for examples in the Samples folder (<code>libs/RmlUi/Samples</code>) may be helpful.

Note that these resources are all far from comprehensive. Many Lua facilities, it seems, can only be discovered by searching the RmlUi source.

=Tips=
The cgame command <code>luarocket</code> can be used to execute Lua snippets. Global variables set from any of the documents are accessible. You can print things with <code>print()</code>.

=Pitfalls=

==Bugs==

Setting the <code>inner_rml</code> attribute of an Element does not work if the string is longer than 1023 characters.

==Other==

All RML documents (or perhaps all documents in a context?) share a common set of global variables. This means that function names and global variable names need to be unique across the whole program. Also, importing a Lua script via <code><nowiki><script src="..." /></nowiki></code> in one document imports it in all documents.

Although Lua usually uses 1-based indexing for arrays, libRocket's Lua APIs are mostly 0-based. For functions that return a list, this has the consequence that the length operator <code>#</code> returns the wrong result.

Continuous integration

2024-04-21T20:22:53Z

Killing time: it's vs not nmake

[[Category:Infrastructure]]
Continuous integration (CI) refers to the automated builds that run each time someone opens or modifies a pull request against, or modifies the code of, the Unvanquished and Daemon source code repositories on GitHub.

We use the following CI services:
* Appveyor, for building with MSVC on Windows. Its configuration is found in the file {{code|.appveyor.yml}} in the repository root.
* Azure Pipelines. Its configuration is found in the file {{code|azure-pipelines.yml}} in the repository root. It handles Mac native builds on [https://github.com/actions/virtual-environments/blob/main/images/macos/macos-11-Readme.md macOS 11.x] and Linux native and NaCl builds on [https://github.com/actions/virtual-environments/blob/main/images/linux/Ubuntu2004-Readme.md Ubuntu 20.04] (Focal).

In some Daemon builds, we run the unit tests. These builds have been configured to use the Release configuration so that the unit tests are closer to production builds.

== Build matrix ==

{|
! colspan="9" | {{engine}}
|-
! Service
! Host
! Target
! Compiler
! Generator
! Build Type
! WERROR
! PCH
! Unit tests
|-
| Appveyor || Windows amd64 || Windows amd64 || VS 2019 || Visual Studio || Release || Yes || off || Yes
|-
| Appveyor || Windows amd64 || Windows i686 || VS 2019 || Visual Studio || Release || Yes || off || Yes
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Windows amd64 || Mingw 9.3 || Ninja || Release || Yes || off || No
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 || GCC 9.4 || Ninja || Release || Yes || off || Yes
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 || Clang 11.0 || Ninja || Release || Yes || off || Yes
|-
| Azure Pipelines || macOS-11 amd64 || macOS amd64 || AppleClang 13.0 || Make || Release || Yes || No || Yes
|}
<br>
{|
! colspan="8" | {{game}}
|-
! Service
! Host
! Target
! Compiler
! Generator
! Build Type
! WERROR
! PCH
|-
| Appveyor || Windows amd64 || Windows i686 DLL || VS 2019 || Visual Studio || Debug || Yes || off
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 DLL || GCC 8.4 || Ninja || Debug || Yes || off
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || Linux amd64 DLL || Clang 11.0 || Ninja || Debug || Yes || off
|-
| Azure Pipelines || Ubuntu-20.04 amd64 || NaCl all NEXE || PNaCl Clang 3.6 || Ninja || Debug || Yes || off
|-
| Azure Pipelines || macOS-11 amd64 || macOS amd64 DLL || AppleClang 13.0 || Make || Debug || Yes || No
|}

“WERROR” indicates whether the {{code|USE_WERROR}} option is on, which gives a failing building build status if there are warnings in our code. Note that {{code|USE_WERROR}} only applies to ”our” code in {{code|src/}}, so you may still see warnings from stuff in {{code|libs/}}.

“PCH” indicates whether the precompiled header is enabled.

Entities

2024-02-20T06:18:20Z

Killing time: link entity directory

This page lists types of ''BSP entities'', sometimes known as ''map entities''. A BSP entity is defined by a list of key-value pairs in the entity lump of a BSP file.

Entity keys with a preceding underscore ("_") character are keys read by the compiler. Keys with no preceding underscore are read by both the compiler and the game. See the [http://en.wikibooks.org/wiki/Q3Map2/Entity_keys q3map2] documentation for more information. The worldspawn and <code>light</code> entities are also read by the renderer.

To find examples of maps where a particular entity is used, you can search for it [https://users.unvanquished.net/~slipher/map-entity-directory.txt here]. This list is generated by [https://github.com/slipher/source-tools/mapents.py a script].

==General Entities==

===Game Entities===

* {{Subpage|worldspawn}}
* {{Subpage|Buildables}}

===Compiler Entities===

* {{Subpage|Lights}} — Might also be used by the renderer for dynamic lighting. 
* {{Subpage|info_null}} — Can be used for lights, but should not be used for anything else.
* {{Subpage|func_group}} — Used for grouping world brushes in the map editor.
* {{Subpage|misc_model}}
* {{Subpage|_decal}}
* {{Subpage|_skybox}}

==Control Entities==

{{EntityTableHeader}}
|-
| || {{Subpage|ctrl_limited}} || || ET_GENERAL || testing || testing || testing
|-
| || {{Subpage|ctrl_relay}} || || ET_GENERAL || testing || extending || extending
|-
| || {{Subpage|ctrl_script}} || || ET_GENERAL || colspan="3" | reserved for future use
|}

==Environment Entities==

{{EntityTableHeader|Scope}}
|-
| {{icon_gfx}} || {{Subpage|env_animated_model}} || position ||
|-
| {{icon_gfx}} || {{Subpage|env_lens_flare}} || position || ET_LIGHTFLARE || testing || unclear || unclear
|-
| {{icon_gfx}} || {{Subpage|env_particle_system}} || position || || testing || extending || extending
|-
| {{icon_source_point}} || {{Subpage|env_portal_camera}} || position ||
|-
| {{icon_gfx}} || {{Subpage|env_portal_surface}} || position || ET_PORTAL
|-
| {{icon_physics}} || {{Subpage|env_rumble}} || global || || testing || extending || extending
|-
| {{icon_sound}} || {{Subpage|env_speaker}} || position || ET_SPEAKER || testing || extending || extending
|}

==Functional Entities==

{{EntityTableHeader}}
|-
| || {{Subpage|func_bobbing}} || mover || || colspan="3" | unclear
|-
| || {{Subpage|func_button}} || trigger-mover || ET_MOVER || colspan="3" | unclear
|-
| || {{Subpage|func_destructable}} || (non) mover || || colspan="3" | planning
|-
| || {{Subpage|func_door}} || trigger-mover || ET_MOVER || colspan="3" | unclear
|-
| || {{Subpage|func_door_model}} || trigger-mover || || colspan="3" | unclear
|-
| || {{Subpage|func_door_rotating}} || trigger-mover || ET_MOVER || colspan="3" | unclear
|-
| || {{Subpage|func_dynamic}} || ? || || colspan="3" | unclear
|-
| {{icon_null}} || {{Subpage|func_group}} || NULL || NULL || colspan="3" | mapeditor and mapcompiler domain
|-
| || {{Subpage|func_pendulum}} || mover || || colspan="3" | unclear
|-
| || {{Subpage|func_plat}} || trigger-mover || || colspan="3" | unclear
|-
| || {{Subpage|func_rotating}} || mover || ET_MOVER || colspan="3" | unclear
|-
| || {{Subpage|func_spawn}} || (non) mover || || colspan="3" | planning
|-
| || {{Subpage|func_static}} || (non) mover || || colspan="3" | unclear
|-
| || {{Subpage|func_train}} || mover || ET_MOVER || colspan="3" | unclear
|}

==Game Entities==

{{EntityTableHeader|Scope}}
|-
| || {{Subpage|game_end}} || global || testing || testing || testing
|-
| || {{Subpage|game_score}} || player || testing || testing || testin
|}

==Information Entities==

Info entities only provide positional information for things controlled by other processes. 

{{EntityTableHeader|Role}}
|-
| {{icon_source_point}} || {{Subpage|info_alien_intermission}} || source point || ET_GENERAL || colspan="3" | subject to change
|-
| {{icon_source_point}} || {{Subpage|info_human_intermission}} || source point || ET_GENERAL || colspan="3" | subject to change
|-
| {{icon_null}} || {{Subpage|info_null}} || target point || NULL || colspan="3" | mapcompiler domain
|-
| || {{Subpage|info_player_deathmatch}} || point || || colspan="3" | subject to change
|-
| || {{Subpage|info_player_intermission}} || point || ET_GENERAL || colspan="3" | subject to change
|-
| || {{Subpage|info_player_start}} || point || || colspan="3" | subject to change
|}

==Light Entities==
Also see [[Light entities]]

{{EntityTableHeader|Time}}
|-
| {{icon_null}} || {{Subpage|light}}
|-
| {{icon_null}} || {{Subpage|lightJunior}}
|}

==Pos Entities==

{{EntityTableHeader}}
|-
| {{icon_position}} || {{Subpage|path_corner}} || || ET_GENERAL || colspan="3" | subject to change
|}

==Sensor Entities==
Sensor fire an event (usually towards targets) when aware of another entity, event, or gamestate.

Sensors often can be targeted to toggle, activate or deactivate their function of perceiving other entities.

{{EntityTableHeader|Awareness}}
|-
| {{icon_sensor_state}} || {{Subpage|sensor_end}}
| gamestate
|
| Testing || Extending ||| Extending
|-
| {{icon_sensor_state}} || {{Subpage|sensor_stage}}
| gamestate
|
| Stable || Testing || Testing
|-
| {{icon_sensor_state}} || {{Subpage|sensor_start}}
| gamestate
|
| Testing || Testing || Testing
|-
| {{icon_sensor_state}} || {{Subpage|sensor_timer}}
| gamestate
|
| Testing || Testing || Testing
|-
| {{icon_sensor_area}} || {{Subpage|sensor_touch}}
| entity
|
| Testing || Extending ||| Extending
|}

==Target Entities==

Targets perform no action by themselves. Instead, they are targeted by other entities.

{{EntityTableHeader|Scope}}
|-
| {{icon_state}} || {{Subpage|target_hurt}} || activator || || colspan="3" | subject to change
|-
| {{icon_state}} || {{Subpage|target_kill}} || activator || ET_GENERAL || colspan="3" | subject to change
|-
| {{icon_position}} || {{Subpage|target_location}} || position || ET_LOCATION || colspan="3" | subject to change
|-
| {{icon_target_point}} || {{Subpage|target_position}} || position || ET_GENERAL || colspan="3" | subject to change
|-
| ? || {{Subpage|target_print}} || configurable || ET_GENERAL || colspan="3" | subject to change
|-
| {{icon_physics}} || {{Subpage|target_push}} || activator || || colspan="3" | subject to change
|-
| {{icon_physics}} || {{Subpage|target_teleporter}} || activator || || colspan="3" | subject to change
|}

==Trigger Entities==

Triggers cause a defined effect when aware of another entity, event, or gamestate.

In that sense it's like an integration of a sensor and a target and might in some cases be modeled by a combination of them.
Triggers carry often the benefit of being predicted client-side (since no entity chains have to be resolved first) such as ({{Subpage|trigger_push}} and {{Subpage|trigger_teleport}}).

{{EntityTableHeader}}
|-
| {{icon_reflect}} || {{Subpage|trigger_ammo}}
| ||
| colspan="3" | Subject to change
|-
| {{icon_physics}} || {{Subpage|trigger_gravity}}
| ||
| colspan="3" | Subject to change
|-
| {{icon_reflect}} || {{Subpage|trigger_heal}}
| ||
| colspan="3" | Subject to change
|-
| {{icon_reflect}} || {{Subpage|trigger_hurt}}
|
| ET_GENERAL
| colspan="3" | Subject to change
|-class="deprecated"
| {{icon_deprecated|icon_sensor_area}} || {{Subpage|trigger_multiple}}
|
| ET_GENERAL
| colspan="3" | Subject to change
|-
| {{icon_physics}} || {{Subpage|trigger_push}}
|
| <code>ET_PUSH_TRIGGER</code>
| colspan="3" | unclear
|-
| {{icon_physics}} || {{Subpage|trigger_teleport}}
|
| <code>ET_TELEPORT_TRIGGER</code>
| colspan="3" | unclear
|}

Template:KnownGraphicalBugs

2023-12-08T14:52:26Z

Killing time: update your graphics driver

{{Note|header=Known workarounds and fixes|content=
* {{ATI}}: If you run a very old Radeon HD 2000 or HD 3000 from 2007 or 2008 on Linux, you may have to set <code>R600_DEBUG=nohyperz</code> environment variable, see ''nohyperz'' mention in [[#Notes|Notes]].}}
{{Note|header=Known bugs|content=
* {{Intel}}: People reported some [https://github.com/DaemonEngine/Daemon/issues/909 distorted textures] with Intel UHD on both Windows and Linux. We [https://gitlab.freedesktop.org/mesa/mesa/-/issues/10224 reported it] to driver developers.

If you encounter a rendering bug, update your graphics driver. If the bug still occurs with the latest driver, please check [https://github.com/DaemonEngine/Daemon/issues?q=is%3Aopen+label%3AA-Renderer+label%3AT-Bug here] if it is already known and if yes, please tell us what graphic chip and operating system you use.

The place to report new graphical bugs is [https://github.com/DaemonEngine/Daemon/issues/new here], see the [[Bug reporting]] page for advices.}}

GPU compatibility matrix

2023-12-08T14:38:39Z

Killing time: /* Useful resources */ gpuinfo.org

{{KnownGraphicalBugs}}

This table gathers test results about various hardware and software configurations, <span style="background-color: green !important; color: white !important; padding: .25em .5em;">passed</span> means nothing wrong is noticed and frame rate is at least <u>60 fps</u> on common scene, <span style="background-color: lightgreen !important; color: green !important; padding: .25em .5em;">playable</span> means at least <u>30 fps</u>.

All those tests were driven by Unvanquished developers or under Unvanquished developer supervision.

See [[#Comprehensive_analysis|below]] for analysis, specific definitions and meanings.
{{GPU compatibility matrix}}

<br/><hr/><br/>

== Comprehensive analysis ==

Minimal configuration for the Unvanquished game is OpenGL 3.2. Unvanquished can run on OpenGL 2.1 hardware but this would not be playable because because we use models with more than 41 bones and OpenGL 2.1 cards can't accelerate them enough. It will run but it will be slow.

Decent performance (given advanced graphical effects are disabled) starts with AMD/ATI TeraScale GPU, Intel HD Graphics (HD 4000), Nvidia Tesla-based GPUs. Though, it is strongly discouraged to buy GT218-based GPU like the Geforce 210 one as the proprietary driver for them is known to be buggy, requiring the engine to implement workarounds for it (save a game developer, do not buy this GPU!).

To play at 4K resolutions, high-end AMD GCN/RDNA is recommended: AMD R9 390X from 2015 can handle <code>ultra</code> preset with 4K resolution at 144Hz. AMD R7 Embedded in R series APU can handle 2K resolution with <code>medium</code> preset (no realtime light and relief mapping disabled) as well as Intel UHD.

Minimal configuration to run the Dæmon engine is OpenGL 2.1 with <code>ARB_half_float_vertex</code> and <code>ARB_framebuffer_object</code> (<code>EXT_framebuffer_object</code> is not enough). It includes ATI/AMD GPU starting with R300 (Radeon X300), Intel GPU starting with GMA965 (X3100) on Linux and macOS, HD Graphics on Windows, Nvidia starting with Curie (NV40, Geforce 6xxx). Wikipedia says the GMA965 Windows driver only supports OpenGL 1.5 and then would not reach the requirements for running Unvanquished on this platform. If you plan to make a game using Damon engine supporting those older cards, make sure your animated models don't have more than 41 bones.

== How to contribute ==

This matrix is generated from a cell sheet. Do not edit it by hand, Please ask <code>illwieckz</code> for access to the cell sheet.

Please sort your contributions by brand (ATI/AMD, Intel, Nvidia, Via…) then by launch date (from newer to older).

The table also documents who may be able to reproduce a special configuration, please put your nick name and tell how much it is easy for you to reproduce a test on it (see below for keywords to use).

Please tell at least, brand, model, model launch date (look at Wikipedia), host, memory size, the operating system, the driver (kernel mode and user mode), OpenGL and GLSL version, Unvanquished version you tested, the status, the preset and the resolution you validated and eventual notes.

If you find out the code name and related micro architecture, please note it, same with form factor and bus.

Other data are less relevant for diagnostic and are only useful to get a better picture of the tested hardware, don't hesitate to write down as much info as you can.

Append the <code>~</code> character to version number if you're testing a preversion. For example use <code>0.52~</code> to tell you tested against the to-be-released 0.52 version.

Put a single <code>-</code> character in cell you don't have data for (do not leave empty cells). When you describe multiple configuration for the same piece of hardware, use the <code>↑</code> character to tell the cell uses the same value as the previous line.

== Definitions ==

=== Status ===

* '''hang''': the computer becomes unresponsive, requiring a hard reset;
* '''crash''': the game is terminated by the operating system on some unrecoverable failure;
* '''missing''': the game exits by itself because of some requirement not being met;
* '''broken''': the game loads maps but graphical bugs affecting gameplay are seen;
* '''glitchy''': the game loads maps but graphical bugs non-affecting gameplay are seen;
* '''slow''': the game is rendered properly but slowly with less than 30 fps;
* '''playable''': nothing wrong is noticed and frame rate is at least 30 fps but less than 60 fps;
* '''passed''': nothing wrong is noticed and frame rate is at least 60 fps.

=== Availability ===

* '''lost''': tester has lost access to the hardware;
* '''foreign''': tester has access to the hardware but does not own it;
* '''unplugged''': tester owns the hardware but testing requires to plug the hardware in a computer;
* '''unconfigured''': hardware is plugged in a computer but making use of it requires software changes;
* '''configured''': hardware and software are ready to use for testing.

=== Notes ===

* '''extfbo''': this GPU provides {{code|ARB_framebuffer_object}} instead of {{code|ARB_framebuffer_object}};
* '''fakefps''': game displays high frame rate number but the experience is stuttering;
* '''hickups''': performance is globally correct, but sometime the framerate drops a bit for a very short time;
* '''lowsky''': lowering texture size using at least <code>r_picmip 1</code> is required to avoid skybox graphical glitches;
* '''lowtex''': lowering texture size using at least <code>r_picmip 1</code> is required to avoid a computer hang;
* '''mesamain''': running the driver from Mesa {{code|main}} at the time of the test was required to get the game running or avoid major rendering bugs;
* '''noaccel''': no OpenGL hardware acceleration is implemented;
* '''nogather''': <code>GL_ARB_texture_gather</code> is wrongly advertised by the driver to be supported by this hardware, making the engine crash at startup (Nvidia proprietary driver bug). The engine ships some workaround for this driver bug, if you experience the crash on version 0.52 and later but can properly start the game with <code>-set r_arb_texture_gather 0</code> engine command line option, please reopen issue [https://github.com/DaemonEngine/Daemon/issues/368 Daemon#368];
* '''nohalfloatvertex''': missing <code>ARB_half_float_vertex</code> OpenGL extension;
* '''nohyperz''': <code>R600_DEBUG=nohyperz</code> environment variable is required to be set to avoid graphical glitches, see issues [https://github.com/DaemonEngine/Daemon/issues/343 Daemon#343] and [https://gitlab.freedesktop.org/mesa/mesa/-/issues/3290 Mesa#3290];
* '''norgtc''': <code>GL_ARB_texture_compression_rgtc</code> extension is not supported on this hardware, some texture may be loaded with swapped channels, especially normal maps. Engine implements special algorithms to workaround this, see issue [https://github.com/DaemonEngine/Daemon/issues/375 Daemon#375];
* '''nvidiagarbage''': this driver is so bad you have to be very lucky to get at least a desktop drawn on screen before the computer hangs. With or without the game, after some screen freezes and display server crashes the kernel will complain about the card having disconnected itself from the PCIe bus. This issue was verified on multiple cards of this generations that are known to run for months without crashing when using free open source drivers instead;
* '''slowmodel''': models with a lot of bones are known to induce severe frame drop on such hardware, see issue [https://github.com/Unvanquished/Unvanquished/issues/1207 Unvanquished#1207];
* '''tinyalu''': this hardware has a very small ALU (arithmetic logic unit), dynamic lighting must be disabled with <code>r_dynamicLight 0</code> to prevent the driver to abort GLSL shader compilation that may lead to an engine crash, see issue [https://github.com/DaemonEngine/Daemon/issues/344 Daemon#344].

=== Bus ===

* '''PCI''': [https://en.wikipedia.org/wiki/Peripheral_Component_Interconnect Peripheral Component Interconnect], slow multi-purpose bus for add-on cards, obsolete;
* '''PCI-X''': [https://en.wikipedia.org/wiki/PCI-X Peripheral Component Interconnect eXtended], enhanced version of PCI for servers and workstations, obsolete;
* '''AGP''': [https://en.wikipedia.org/wiki/Accelerated_Graphics_Port Accelerated Graphics Port], high-speed bus designed for graphic cards, obsolete;
* '''FSB''': [https://en.wikipedia.org/wiki/Front-side_bus Front-side bus], high-speed Intel system bus for CPUs, sometime used with onboard GPUs (example: GeForce 7050 + nForce 610i/630i);
* '''HT''': [https://en.wikipedia.org/wiki/HyperTransport HyperTransport], high-speed AMD system bus for CPUs, sometime used with onboard GPUs (example: GeForce 6150 LE + nForce 430);
* '''chip''': Internal bus of a [https://en.wikipedia.org/wiki/System_on_a_chip system on a chip] (SoC), the exact communication bus technology is usually poorly documented;
* '''PCIe''': [https://en.wikipedia.org/wiki/PCI_Express PCI Express], high-speed multi-purpose bus for add-on cards and on-board devices, recommended;
* '''CXL''': [https://en.wikipedia.org/wiki/Compute_Express_Link, Compute Express Link], high-speed multi-purpose bus for add-on cards;
* '''TB''': [https://fr.wikipedia.org/wiki/Thunderbolt_(interface) ThunderBolt], high speed cable combining PCI Express and DisplayPort or USB-C to connect external PCI Express cards like GPUs.

=== Form factor ===

* '''discrete''': full height workstation extension card, with dedicated graphics memory;
* '''lowprofile''': low profile workstation extension card, with dedicated graphics memory;
* '''MXM''': [https://en.wikipedia.org/wiki/Mobile_PCI_Express_Module Mobile PCI Express module], laptop extension card, with dedicated graphics memory;
* '''onboard''': dedicated GPU on motherboard, low end ones may share memory with the CPU;
* '''integrated''': GPU integrated in CPU package or chipset, likely sharing memory with the CPU;
* '''SoC''': System on a chip, with the GPU likely sharing memory with the CPU;

=== Micro architecture ===

* '''USSA''': ATi Unified Superscalar Shader Architecture;
* '''GCN''': AMD Graphics Core Next;
* '''RDNA''': AMD Radeon DNA;
* '''GMA''': Intel Graphics Media Accelerator;
* '''GT''': Intel Graphics Technology.

=== Memory glossary ===

* '''HM''': HyperMemory, ATi technology using main memory when GPU memory is full;
* '''TC''': TurboCache, Nvidia technology using main memory when GPU memory is full;
* '''AR''': AcceleRAM, S3 technology using main memory when GPU memory is full.

== Useful resources ==

* [https://mesamatrix.net/ Mesa Matrix]
* [https://en.wikipedia.org/wiki/List_of_AMD_graphics_processing_units Wikipedia list of AMD graphics processing units]
* [https://en.wikipedia.org/wiki/List_of_AMD_accelerated_processing_units Wikipedia list of AMD accelerated processing units]
* [https://www.x.org/wiki/RadeonFeature/ X.Org Radeon feature matrix and decoder ring]
* [https://en.wikipedia.org/wiki/List_of_Intel_graphics_processing_units Wikipedia list of Intel graphics processing units]
* [https://en.wikipedia.org/wiki/List_of_Nvidia_graphics_processing_units Wikipedia list of Nvidia graphics processing units]
* [https://nouveau.freedesktop.org/wiki/MesaDrivers/ Mesa Nouveau drivers]
* [https://nouveau.freedesktop.org/wiki/CodeNames/ Mesa Nouveau decoder ring]
* [https://opengl.gpuinfo.org/ User-submitted reports of OpenGL version and feature availability]

Template:KnownGraphicalBugs

2023-12-08T14:30:42Z

Killing time:

{{Note|header=Known workarounds and fixes|content=
* {{ATI}}: If you run a very old Radeon HD 2000 or HD 3000 from 2007 or 2008 on Linux, you may have to set <code>R600_DEBUG=nohyperz</code> environment variable, see ''nohyperz'' mention in [[#Notes|Notes]].}}
{{Note|header=Known bugs|content=
* {{Intel}}: People reported some [https://github.com/DaemonEngine/Daemon/issues/909 distorted textures] with Intel UHD on both Windows and Linux. We [https://gitlab.freedesktop.org/mesa/mesa/-/issues/10224 reported it] to driver developers.

If you encounter a rendering bug, please check [https://github.com/DaemonEngine/Daemon/issues?q=is%3Aopen+label%3AA-Renderer+label%3AT-Bug here] if it is already known and if yes, please tell us what graphic chip and operating system you use.

The place to report new graphical bugs is [https://github.com/DaemonEngine/Daemon/issues/new here], see the [[Bug reporting]] page for advices.}}

Template:KnownGraphicalBugs

2023-12-08T14:29:34Z

Killing time: remove confetti bug (never affected anyone besides me)

{{Note|header=Known workarounds and fixes|content=
* {{ATI}}: If you run a very old Radeon HD 2000 or HD 3000 from 2007 or 2008 on Linux, you may have to set <code>R600_DEBUG=nohyperz</code> environment variable, see ''nohyperz'' mention in [[#Notes|Notes]].
{{Note|header=Known bugs|content=
* {{Intel}}: People reported some [https://github.com/DaemonEngine/Daemon/issues/909 distorted textures] with Intel UHD on both Windows and Linux. We [https://gitlab.freedesktop.org/mesa/mesa/-/issues/10224 reported it] to driver developers.

If you encounter a rendering bug, please check [https://github.com/DaemonEngine/Daemon/issues?q=is%3Aopen+label%3AA-Renderer+label%3AT-Bug here] if it is already known and if yes, please tell us what graphic chip and operating system you use.

The place to report new graphical bugs is [https://github.com/DaemonEngine/Daemon/issues/new here], see the [[Bug reporting]] page for advices.}}

Formats/Known regressions since Tremulous

2023-12-08T10:49:08Z

Killing time: /* Regressions that don't make the game look broken */ lightingpsecular issue link

[[Category:Formats]]
As a mapper or someone creating assets for the game, you may be aware of those pitfalls that can be considered as regressions when comparing with Tremulous or Quake Ⅲ.

See also the [[Formats/Limitations that are not regressions|Limitations that are not regressions]] page for things that are not regressions.

== Regressions that may make the game look broken ==

=== Missing portal blending ===

Portal blending is not implemented yet in the renderer.

What happens is that the renderer that was used in Quake Ⅲ and Tremulous were OpenGL 1 renderers, and the Dæmon engine renderer is an OpenGL 3+ renderer. The difference between OpenGL 1 and OpenGL 3+ is similar to the difference between OpenGL 4.6 and Vulkan. Those renderers are different software. Everything from the OpenGL 1 renderer had to be re-implemented in OpenGL 3+ renderer with new code.

So the lack of portable blending is not technically a regression as the code never existed in the renderer to begin with. It also means there is no bug in our code.

Though, we fully agree this means a map ported from Tremulous that was using that feature will look broken and that then can be considered as a regression from a player or mapper point of view.

From the code point of view, this is a feature request and we need someone to implement it. We are looking for renderer developers and OpenGL 3+ specialist to implement the feature in our engine.

=== "Autosprite" shaders don't work ===
See [https://github.com/DaemonEngine/Daemon/issues/322 Daemon#322].

== Regressions with fixes implemented but not released yet ==

{{TODO|Remove this once Dæmon 0.54.1 is out.}}

=== Missing RoQ video ===

RoQ video support was removed long time ago as Unvanquished did not make use of it.

Later the last remaining video format was removed, it was a format from an alternate reality that never happened : OGM with Vorbis and Theora. OGM with Vorbis and Theora is '''''not''''' OGG with Vorbis and Theora. The OGM format was a hack purposed for DivX piracy scene to mux XviD video with Vorbis audio, and while OGM with XviD was pretty popular, no one known tool can produce OGM with Vorbis and Theora. illwieckz tried a bunch of current and old software from the era and none was able to produce OGM with Theora and Vorbis. Neither oggenc from vorbis-tools, neither ogmtools, neither ffmpeg (recent and old), neither mencoder, neither OggMux, neither OGMMuxer, neither VirtualDubMod (modded VirtualDub for OGM support), neither ffdshow with OGM, Theora and Vorbis codecs. The only remaining thing untested is some obscure Visual Studio plugin that was mentioned in some places but for which no one file was found yet. We know something existed since Smokin' Guns game uses such OGM with Theora and Vorbis title video. That's all.

Once that cursed OGM with Theora and Vorbis format was removed, the Theora codec was dead code and the Video support was dead code. This dead code was removed at some point because of being dead code.

The removal of Video playing feature and the removal of RoQ support without alternative was controversial, and Dæmon 0.54.1 will bring back {{code|videoMap}} support with RoQ format.

== Regressions that may make the game look broken, but with workaround ==

=== Stereo sound effect not being positional ===

Currently only mono sound files are played properly as positional audio, stereo sound files are played ''in your face''. We need to fix this.

A simple workaround can be applied when repackaging the files: just convert the positional stereo sound as mono, this would make no difference to the player (stereo positional sound is meaningless anyway).

== Regressions that don't make the game look broken ==

=== Missing alphaGen lightingSpecular ===

The {{code|alphaGen lightingSpecular}} was a subtle effect applied on some textures. This feature being missing doesn't break the rendering of the texture and if you look at the surface you may not notice something is wrong, unless you do comparative screenshots with Tremulous and Unvanquished. [https://github.com/DaemonEngine/Daemon/issues/213 Github issue]

Implementing this feature has very low priority as there is no impact on gameplay and textures don't look bad without it. The game doesn't look broken without it and one cannot know the feature is missing just by playing the game, unless some warning tells it in log.

Formats/Known regressions since Tremulous

2023-12-07T18:18:52Z

Killing time: /* Regressions that may make the game look broken */ autosprite

[[Category:Formats]]
As a mapper or someone creating assets for the game, you may be aware of those pitfalls that can be considered as regressions when comparing with Tremulous or Quake Ⅲ.

See also the [[Formats/Limitations that are not regressions|Limitations that are not regressions]] page for things that are not regressions.

== Regressions that may make the game look broken ==

=== Missing portal blending ===

Portal blending is not implemented yet in the renderer.

What happens is that the renderer that was used in Quake Ⅲ and Tremulous were OpenGL 1 renderers, and the Dæmon engine renderer is an OpenGL 3+ renderer. The difference between OpenGL 1 and OpenGL 3+ is similar to the difference between OpenGL 4.6 and Vulkan. Those renderers are different software. Everything from the OpenGL 1 renderer had to be re-implemented in OpenGL 3+ renderer with new code.

So the lack of portable blending is not technically a regression as the code never existed in the renderer to begin with. It also means there is no bug in our code.

Though, we fully agree this means a map ported from Tremulous that was using that feature will look broken and that then can be considered as a regression from a player or mapper point of view.

From the code point of view, this is a feature request and we need someone to implement it. We are looking for renderer developers and OpenGL 3+ specialist to implement the feature in our engine.

=== "Autosprite" shaders don't work ===
See [https://github.com/DaemonEngine/Daemon/issues/322 Daemon#322].

== Regressions with fixes implemented but not released yet ==

{{TODO|Remove this once Dæmon 0.54.1 is out.}}

=== Missing RoQ video ===

RoQ video support was removed long time ago as Unvanquished did not make use of it.

Later the last remaining video format was removed, it was a format from an alternate reality that never happened : OGM with Vorbis and Theora. OGM with Vorbis and Theora is '''''not''''' OGG with Vorbis and Theora. The OGM format was a hack purposed for DivX piracy scene to mux XviD video with Vorbis audio, and while OGM with XviD was pretty popular, no one known tool can produce OGM with Vorbis and Theora. illwieckz tried a bunch of current and old software from the era and none was able to produce OGM with Theora and Vorbis. Neither oggenc from vorbis-tools, neither ogmtools, neither ffmpeg (recent and old), neither mencoder, neither OggMux, neither OGMMuxer, neither VirtualDubMod (modded VirtualDub for OGM support), neither ffdshow with OGM, Theora and Vorbis codecs. The only remaining thing untested is some obscure Visual Studio plugin that was mentioned in some places but for which no one file was found yet. We know something existed since Smokin' Guns game uses such OGM with Theora and Vorbis title video. That's all.

Once that cursed OGM with Theora and Vorbis format was removed, the Theora codec was dead code and the Video support was dead code. This dead code was removed at some point because of being dead code.

The removal of Video playing feature and the removal of RoQ support without alternative was controversial, and Dæmon 0.54.1 will bring back {{code|videoMap}} support with RoQ format.

== Regressions that may make the game look broken, but with workaround ==

=== Stereo sound effect not being positional ===

Currently only mono sound files are played properly as positional audio, stereo sound files are played ''in your face''. We need to fix this.

A simple workaround can be applied when repackaging the files: just convert the positional stereo sound as mono, this would make no difference to the player (stereo positional sound is meaningless anyway).

== Regressions that don't make the game look broken ==

=== Missing alphaGen lightingSpecular ===

The {{code|alphaGen lightingSpecular}} was a subtle effect applied on some textures. This feature being missing doesn't break the rendering of the texture and if you look at the surface you may not notice something is wrong, unless you do comparative screenshots with Tremulous and Unvanquished.

Implementing this feature has very low priority as there is no impact on gameplay and textures don't look bad without it. The game don't look broken without it and one cannot know the feature is missing just by playing the game, unless some warning tells it in log.

MinGW

2023-12-06T14:28:39Z

Killing time: /* C ABI compability with MSVC */ more detail

MinGW is a GCC-based compiler toolchain targeting Windows platforms. It is used to produce the Windows releases of Unvanquished. It can be quite complicated to use successfully, in part due to the existence of different compiler "flavors", and confusing naming schemes. This page serves as a guide to both MinGW in general, and specifically in application to building Daemon and Unvanquished. Throughout this page, "MinGW" will be used to refer to the [http://mingw-w64.org/ mingw-w64] project, which is a fork of the (now long-moribund) "original MinGW" project aiming to support both 32- and 64-bit builds. So beware: something having "64" in its name does not at all imply it is for 64-bit binaries! Same goes for "32".

== Flavors ==

=== Bitness: 32-bit or 64-bit ===

Whether to compile for 32-bit ("i686" in package names) or 64-bit ("x86-64" or "x86_64") architecture. 64-bit Windows versions are capable of running 32-bit executables in a mode called WOW (Windows-on-Windows).

=== Threading flavor ===
You can get <code>win32</code> or <code>posix</code> thread models. Daemon must be built with the <code>posix</code> flavor, because code that uses <code>std::thread</code> does not compile with <code>win32</code>. In general there is no reason to use <code>win32</code>. However, it is unfortunately the default in the APT package manager.

=== Exception handling flavor ===

* <code>sjlj</code> (setjmp/longjmp) is available for both 32- and 64-bit builds. It has the drawback of significant runtime cost.
* <code>dwarf</code> is available only for 32-bit. It has good performance, but it is said to have a drawback that exceptions can't be propagated through code compiled with a different compiler (or C code?). However, propagating exceptions through C code shouldn't be needed for Daemon.
* <code>seh</code> (Structured Exception Handling) is available only for 64-bit. It has good performance and always works correctly, so it should always be used for 64-bit.

One way to identify which exception model code was built with is to check the libgcc dependency. You'll find for example <code>libgcc_s_seh-1.dll</code> for SEH, <code>libgcc_s_dw2-1.dll</code> for DWARF, or <code>libgcc_s_sjlj-1.dll</code> for sjlj. An easy way to make a C++ test program emit a libgcc dependency is to add a try/catch block.

=== Mixing flavors ===

Mixing different thread or exception flavors can cause problems, such as missing DLL dependencies, or exception handling not working.

For the <code>external_deps</code> libraries, efforts have been made to avoid depending on any thread-flavor-specific or exception-flavor-specific libraries, so it should be possible to use them with any flavor of MinGW. Exception handling glitches shouldn't be an issue since the Windows depencies are C-only.

== Distributions ==

=== Cross-compiling from Linux ===

Most Linux package managers offer some form of MinGW package. Availability of different flavor combinations varies.

==== Installation ====
APT (Debian Buster or older):
<pre># 32-bit, sjlj. win32 threads are selected by default; switch it to posix
sudo apt install g++-mingw-w64-i686
sudo update-alternatives --set i686-w64-mingw32-gcc /usr/bin/i686-w64-mingw32-gcc-posix
sudo update-alternatives --set i686-w64-mingw32-g++ /usr/bin/i686-w64-mingw32-g++-posix

# 64-bit, SEH. win32 threads are selected by default; switch it to posix
sudo apt install g++-mingw-w64-x86-64
sudo update-alternatives --set x86_64-w64-mingw32-gcc /usr/bin/x86_64-w64-mingw32-gcc-posix
sudo update-alternatives --set x86_64-w64-mingw32-g++ /usr/bin/x86_64-w64-mingw32-g++-posix
</pre>

APT (Debian Bullseye or newer):
* <code>sudo apt install gcc-mingw-w64-i686-posix</code> (32-bit, posix, sjlj)
* <code>sudo apt install gcc-mingw-w64-x86-64-posix</code> (64-bit, posix, SEH)

==== Usage ====

To build a CMake project, you need a "toolchain file". Sadly, there is no official toolchain file from MinGW or CMake. For Daemon and Unvanquished we use [https://github.com/DaemonEngine/Daemon/blob/master/cmake/cross-toolchain-mingw32.cmake this (32-bit)] and [https://github.com/DaemonEngine/Daemon/blob/master/cmake/cross-toolchain-mingw64.cmake this (64-bit)]. Use it by passing <code>-DCMAKE_TOOLCHAIN_FILE=<path></code> on the <code>cmake</code> command line.

=== MSYS2 ===

MSYS2 runs on Windows hosts and provides up-to-date 32-bit/DWARF/posix and 64-bit/SEH/posix toolchains. Building is done from a Bash shell in a partial emulation of a Linux environment, similar to Cygwin.

==== Installation ====

Download from [https://www.msys2.org].

Install dependencies to build Daemon (can be done from any MSYS2 shell flavor):
<pre>
# 32-bit
pacman -Sy mingw-w64-i686-gcc mingw64-i686-cmake make
# 64-bit
pacman -Sy mingw-w64-x86_64-gcc mingw64-x86_64-cmake make
</pre>

==== Usage ====
You must open a different MSYS2 shell flavor according to which architecture you want to target: "MSYS2 MinGW 32-bit" or "MSYS2 MinGW 64-bit". When invoking <code>cmake</code>, you must pass the flag <code>-G"MSYS Makefiles"</code>. When building Unvanquished, the flag <code>-DDAEMON_CBSE_PYTHON_PATH=<path></code> may be of interest, if you want to use a Python other than the one shipped with MSYS2. <code><path></code> should be in the Unix-emulation format, e.g. <code>/c/Python/python.exe</code>.

=== "MinGW-W64-builds" (Standalone Windows version) ===
This distribution (see [https://sourceforge.net/projects/mingw-w64/ Sourceforge]) provides a toolchain that can be used from the Windows command prompt, without needing a Unix emulation layer. The installer allows you to choose from every valid combination of flavors. Caveat: the builds are currently somewhat outdated. At the time of writing (Febrary 2021), the newest available gcc version is 8.1.0.

==== Usage ====

Choose the <code>MinGW Makefiles</code> generator in CMake. The location of the toolchain used is determined by finding the first one in your PATH environment variable. Relative to the installation root, the PATH entry should be at <code>mingw32\bin</code> or <code>mingw64\bin</code>.

After running CMake, compile by running <code>mingw32-make</code> in the build directory.

==== Work around linker error with <code>difftime</code> ====

To build Unvanquished 0.52 or higher, a small hack is needed to avoid a linker error, because Lua depends on an MSVCRT function which was not added to MinGW's import lib yet as of 8.1.0. Since you are on Windows, you can link to mscvrt.dll directly. In the CMake GUI, check "Advanced" and find the variable <code>CMAKE_CXX_STANDARD_LIBRARIES</code>. Add <code> C:/windows/system32/msvcrt.dll</code> at the end of the list (or <code> C:/windows/syswow64/msvcrt.dll</code> if you are building a 32-bit binary on a 64-bit system).

== Built-in DLL dependencies ==

There are a few DLLs shipped as part of MinGW that most programs will depend on. These are also available as static libraries (a fully static binary can be produced with the <code>-static</code> flag), but dynamic is the default. These are:
* <code>libgcc</code>
* <code>libstdc++</code> (for C++ programs)
* <code>libssp</code> (if stack protection is enabled)
* <code>libwinpthread</code> (if threads are used)

<code>libstdc++</code> is both thread- and exception-flavor-dependent, but unlike <code>libgcc</code>, the DLL does not have the flavor written in the filename. This means that you can't easily tell if you have the right one (nor can the Windows executable loader). [https://github.com/lucasg/Dependencies Dependencies] is a good tool to investigate such issues.

When distributing a binary release of Daemon, you must ship these DLLs alongside the executable, else you will run into [https://github.com/Unvanquished/Unvanquished/issues/716 this issue]. Note that unlike Daemon's other DLL dependencies (from the <code>external_deps</code> package), the MinGW DLLs are not automatically copied to the build directory as part of the build process. See <code>extra_dll_list</code> and <code>findDll</code> in the [https://github.com/Unvanquished/release-scripts/blob/master/build-release Unvanquished release script].

== C ABI compability with MSVC ==

On 32-bit x86, GCC has a different default stack alignment (16 bytes) than MSVC (4 bytes). This can cause problems when MSVC-compiled code calls into GCC-compiled code and the alignment is less than expected. One solution, which we use to build MSVC-compatible <code>external_deps</code> DLLs, is to use a GCC flag (<code>-mpreferred-stack-boundary=</code>) to change the presumed stack alignment. Another, which we use to handle jumps from 3rd-party binaries to our (MinGW-built) code, is to put the annotation <code>__attribute__((force_align_arg_pointer))</code> on the functions which may be called with less alignment than expected, instructing the compiler to perform alignment when the function is called.

<code>-mms-bitfields</code> should be enabled to ensure that the layout of structs containing bitfields matches. This is on by default.