vera/nuclide
4
0
Fork 0
Code Issues 32 Pull requests Projects Releases Packages Activity

The mother of experimental commits.

Browse source
This commit is contained in:
Marco Cawthorne 2024-06-22 00:24:13 -07:00
parent bab74ba6fd
commit 8ace54224c
Signed by: eukara
GPG key ID: CE2032F0A2882A22
1519 changed files with 363951 additions and 17463 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
.gitignore vendored
View file

@ -1,8 +1,11 @@
*~
Documentation/html/
ThirdParty/
darkstar/
noffice/
pvk/
czero/
czeror/
ship/
src/client/cstrike.new
src/server/cstrike.new
@ -29,6 +32,8 @@ entities.def
csqccore.txt
*.log
ssqccore.txt
fullchain.pem
privkey.pem
menucore.txt
conhistory.txt
condump.txt

15
Documentation/Bots.md Normal file
View file

@ -0,0 +1,15 @@
# Bots {#bots}
Bots are CPU controlled opponents. They can be useful for development, debugging but can also fun to play with.
They're fake clients, traversing the level, and acting upon objectives they either figure out themselves, or are told to to act a certain way.
We encourage any multiplayer game to support them, because they often also fill in the function of balancing teams. There's a whole slew of benefits of supporting bots, and players will generally thank you for including them.
## Technical Info
Bots are handled by BotLib, located under `src/botlib/` in the source tree.
Nuclide's BotLib takes some inspiration from **Quake III Arena** its bots, but shares no code or specific ideas or implementations. We do not use **AAS** for navigation, we leverage the route/pathfinding system **FTEQW** provides. Bots also share some code with regular NPC/Monster type entities through the use of the NSNavAI class.
Games are allowed to handle how they want to integrate bots themselves, but for development purposes there are ways to force bots to spawn also.

97
Documentation/Bots/BotOverview.md
View file

@ -1,97 +0,0 @@
# Bots
Bots are CPU controlled opponents. They can be useful for development, debugging but can also fun to play with.
They're fake clients, traversing the level, and acting upon objectives they either figure out themselves, or are told to to act a certain way.
We encourage any multiplayer game to support them, because they often also fill in the function of balancing teams. There's a whole slew of benefits of supporting bots, and players will generally thank you for including them.
## Technical Info
Bots are handled by BotLib, located under `src/botlib/` in the source tree.
Nuclide's BotLib takes some inspiration from **Quake III Arena** its bots, but shares no code or specific ideas or implementations. We do not use **AAS** for navigation, we leverage the route/pathfinding system **FTEQW** provides. Bots also share some code with regular NPC/Monster type entities through the use of the NSNavAI class.
Games are allowed to handle how they want to integrate bots themselves, but for development purposes there are ways to force bots to spawn also.
# Bot profiles
Nuclide has support for bot profiles, like in **Quake III Arena**. They work differently although they appear compatible by design. You can define them in a script that looks something like this and is located at `scripts/bots.txt` in your game directory:
```
{
name Albert
model zombie01
topcolor 0xeff
bottomcolor 0xff0020
}
{
name Susie
model police02
topcolor 0xff6b00
bottomcolor 0xff0b00
}
{
name Dog
funname ^4D^2o^1g
model dog01
topcolor 0x9200ff
bottomcolor 0xc800ff
}
```
Only the `name` key is required. The only other special key is `funname` which sets the nickname to be different from the internal name. The other keys are set as user info (setinfo) keys on the bot client.
This will allow games to add whatever extra keys they wish that they can then recognize anywhere in the client/server codebase. No additional networking or APIs necessary. Simply query bot properties via their userinfo.
# Bot Console Commands
## addBot [profile name]
Adds a bot to the current game.
## killAllBots
Force kills and respawns bots in the current game.
## resetAllBotsGoals
Force reset bots current trajectory and goals.
# Bot Console Variables
## bot_enable
Enable (1) or disable (0) usage of bots in the game. Default is 1.
## bot_pause
Enable (1) or disable (0) an interrupt for the Bot AIs thinking. Default is 0.
## bot_noChat
Enable (1) or disable (0) a suppression of any bot chatter. Default is 0.
## bot_fastChat
Enable (1) or disable (0) bot chatter that does not stop other inputs. Default is 0.
## bot_debug
Enable (1) or disable (0) bot debug features that otherwise won't work. Default is 0.
## bot_developer
Enable (1) or disable (0) bot debug text in console. Default is 0.
## bot_minClients
When set, ensures to fill the server with this many players/bots. Default is -1.
## bot_aimless
Enable (1) or disable (0) bot not knowing where to go. Will keep generating a new place to walk to.
## bot_crouch
Enable (1) or disable (0) the forcing of bots crouching down.
## bot_walk
Enable (1) or disable (0) the restriction of bots to walking speed.
## bot_prone
Enable (1) or disable (0) the forcing of bots to crawl/prone.
## bot_dont_shoot
Enable (1) or disable (0) bot pacifist mode.

53
Documentation/Bots/Commands.md Normal file
View file

@ -0,0 +1,53 @@
# Bots {#bots}
## Console Commands {#bot_commands}
### addBot [profile name]
Adds a bot to the current game.
### killAllBots
Force kills and respawns bots in the current game.
### resetAllBotsGoals
Force reset bots current trajectory and goals.
## Bot Console Variables
### bot_enable
Enable (1) or disable (0) usage of bots in the game. Default is 1.
### bot_pause
Enable (1) or disable (0) an interrupt for the Bot AIs thinking. Default is 0.
### bot_noChat
Enable (1) or disable (0) a suppression of any bot chatter. Default is 0.
### bot_fastChat
Enable (1) or disable (0) bot chatter that does not stop other inputs. Default is 0.
### bot_debug
Enable (1) or disable (0) bot debug features that otherwise won't work. Default is 0.
### bot_developer
Enable (1) or disable (0) bot debug text in console. Default is 0.
### bot_minClients
When set, ensures to fill the server with this many players/bots. Default is -1.
### bot_aimless
Enable (1) or disable (0) bot not knowing where to go. Will keep generating a new place to walk to.
### bot_crouch
Enable (1) or disable (0) the forcing of bots crouching down.
### bot_walk
Enable (1) or disable (0) the restriction of bots to walking speed.
### bot_prone
Enable (1) or disable (0) the forcing of bots to crawl/prone.
### bot_dont_shoot
Enable (1) or disable (0) bot pacifist mode.

31
Documentation/Bots/Profiles.md Normal file
View file

@ -0,0 +1,31 @@
# Bots {#bots}
## Profiles {#bot_profiles}
Nuclide has support for bot profiles, like in **Quake III Arena**. They work differently although they appear compatible by design. You can define them in a script that looks something like this and is located at `scripts/bots.txt` in your game directory:
```
{
name Albert
model zombie01
topcolor 0xeff
bottomcolor 0xff0020
}
{
name Susie
model police02
topcolor 0xff6b00
bottomcolor 0xff0b00
}
{
name Dog
funname ^4D^2o^1g
model dog01
topcolor 0x9200ff
bottomcolor 0xc800ff
}
```
Only the `name` key is required. The only other special key is `funname` which sets the nickname to be different from the internal name. The other keys are set as user info (setinfo) keys on the bot client.
This will allow games to add whatever extra keys they wish that they can then recognize anywhere in the client/server codebase. No additional networking or APIs necessary. Simply query bot properties via their userinfo.

3
Documentation/Bots/Waypoints.md Normal file
View file

@ -0,0 +1,3 @@
# Bots {#bots}
## Bot Waypoints {#bot_waypoints}

299
Documentation/Building.md
View file

@ -2,267 +2,96 @@
## Preface
If you don't plan on modifying the engine, then you probably shouldn't! You can grab binaries from [FTEQW](https://www.fteqw.org) and move them into the Nuclide directory under `./bin`.
If you're on Microsoft Windows, you will most likely not be running the `nuclide` launch script anyway, so feel free to move the `fteqw.exe` into the root of the Nuclide directory, and run that as-is instead.
It will mount the game directories specified in the `default.fmf` file, which you can tweak as needed. [For more information, read the relevant documentation regarding launching Nuclide](Documentation/Launching.md)
## Building the Engine {#engine}
The **build_engine.sh** will do that for you. It will still ask you to have at least
a certain amount of dependencies installed (such as the **GCC**, **GNU make** and the **X11/SDL**
headers for your platform.
### Optional: Building release binaries
You'll have to manually go into `src/engine/engine` and issue:
```
$ make m-rel FTE_CONFIG=yourgameconfig
```
If you want to cross-compile to different platforms, you can pass the `FTE_TARGET` variable and select from **win32**, **win64**, **linux32**, **linux64** or **SDL2**.
For example, this will build a release binary of **The Wastes** for Win32, using the configuration specified inside `src/engine/engine/common/config_wastes.h`:
```
$ make m-rel FTE_CONFIG=wastes FTE_TARGET=win32
```
The resulting binary can be found inside the `src/engine/engine/release` directory.
**Note**: The **SDL2** target will require you to set the **ARCH** environment to the target of your choosing.
## Building the Level Editor {#editor}
Handled by **build_editor.sh**.
## Building Game-Logic {#game}
You can build the game source tree with **build_game.sh**.
The script also takes a parameter. If you specify:
```
./build_game.sh valve
```
then it will only build the game-logic for the `valve` directory.
Otherwise, it will iterate through all of the game directories, look for a Makefile and build its default target.
It'll try use the **fteqcc** binary that's in the *./bin/* directory.
So make sure to build run **build_engine.sh** first.
Some distributions may carry the **fteqcc** compiler, but it usually is a very ancient version
that's probably not going to build any of this.
## Custom Configuration {#config}
There's a **build.cfg** file with which you can tweak build parameters of the various **build_** scripts.
For example, this is where you select between X11 and SDL2 builds. There you can specify which engine revision
you want to build and also which plugins you want to build along with it.
It's well commented, so I encourage you to check it out. However on some platforms, changing those settings
might introduce additional setup/dependency steps.
## Additional Information {#notes}
The game-logic is written in QuakeC, it is thus platform and architecture independent.
You do not need to rebuild the logic for each and every platform.
The results will be identical.
If you don't plan on modifying the engine, then you can grab binaries
from [FTEQW](https://www.fteqw.org) and move them into the root
directory.
## Dependencies
### Debian / Raspbian
#### FTE
Nuclide is entirely game-logic oriented, so it only requires a working
QuakeC compiler. In our case [FTEQCC](https://www.fteqcc.org/). Which
you can also build with:
```
apt-get install libgl-dev gnutls-dev
$ make fteqcc
```
#### SDL2
The resulting binary `./fteqcc` will then be used to build the
game-logic related targets.
Besides a working **C** compiler, such as `gcc` or `clang`, the QuakeC compiler shouldn't need any other dependencies. [Click here for a full list of dependencies for the various optional components.](Documentation/Dependencies.md)
> [!tip]
> `make help` will always show a list of available targets, including their purpose.
## Keeping Up-To-Date
You can issue the following to check for updates of tools/dependencies:
```
apt-get install libsdl2-dev
$ make update
```
#### GLX / X11 (part of libsdl2-dev)
## Building Game-Logic {#build-game}
You can build games by running the following command:
```
apt-get install libx11-dev libxcursor-dev libxrender-dev
$ make game GAME=base
```
#### Plugin: ODE
Adjust the **GAME** argument to select which game you want to
build. The game `base` is the assumed, default target.
Usually, the resulting files are `progs.dat`, `csprogs.dat` and
(sometimes) `menu.dat`. Those are the libraries dealing with the
**Server**, **Client** and **Menu** aspect of the game respectively.
They are accompanied by name-matching `.lno` files. These contain
extra debugging information helpful to the engine. *They can be
stripped from a shipping build of your game.*
> [!tip]
> You do not need to rebuild the logic for each and every platform.
> The results will be identical, since QuakeC is not machine code.
## Building the Engine {#build-engine}
Issue the following to build a generic version of the engine [FTEQW](https://www.fteqw.org/):
```
apt-get install autoconf automake libtool
$ make fteqw
```
#### Plugin: FFMPEG
Which you can then run with `./fteqw -game base`. [For more information on launching games, mods, check out the page on Launching](Documentation/Launching.md).
Some engine features are only available as a plugin. See `$ make help` for info on how to build them.
### Optional: Custom Branding & Features
If you want to build a custom version of the engine,
with custom branding and the ability to strip unneeded
functionality out of the binary, you can make a copy of
`ThirdParty/fteqw/engine/common/config_fteqw.h`, adjust it and save
it under your game directory as `engine.h`. When issuing the command:
```
apt-get install libavformat-dev libswscale-dev
$ make engine GAME=yourgame
```
### OpenBSD
It will then look for `yourgame/engine.h`, and build a copy of FTEQW
against it. The output will normally be something along the lines of
`yourgame_x64`. The name can be changed by passing `NAME=YourGame`
to the make program.
#### FTE
## Building the Level Editor {#build-editor}
Issue the following to build [GtkRadiant](https://icculus.org/gtkradiant):
```
pkg_add git
$ make radiant
```
#### SDL2
A launcher will be created in the root directory allowing you to launch it via `./radiant`.
```
pkg_add sdl2
```
#### Plugin: FFMPEG
```
pkg_add ffmpeg
```
### Arch Linux
#### FTE
```
pacman -S make gcc Xorg git
```
#### Plugin: ODE
```
pacman -S zip automake autoconf
```
#### Plugin: FFMPEG
```
pacman -S ffmpeg4.4
```
*Note:* You will have to manually build this plugin due to FFMPEG breaking ABI between releases and Arch's rolling release nature.
1) Edit build.cfg and change `FFMPEG=YES` to `NO`
2) Browse to src/engine/engine
3) Run this command:
`make plugins-rel NATIVE_PLUGINS="ffmpeg" AV_BASE=/usr/include/ffmpeg4.4/ AV_LDFLAGS="-l:libavcodec.so.58 -l:libavformat.so.58 -l:libavutil.so.56 -l:libswscale.so.5"`
4) Copy over `fteplug_ffmpeg.so` to the `bin` folder where nuclide and the build scripts are.
#### SDL2
```
pacman -S sdl2
```
#### WorldSpawn
```
pacman -S pkgconf gtk2 gtkglext
```
### OpenSUSE
#### Nuclide
```
zypper in git
```
#### FTE
```
zypper in make gcc gcc-c++ mesa-libGL-devel libgnutls-devel alsa-devel libopus-devel speex-devel libvorbis-devel
```
#### SDL2
```
zypper in libSDL2-devel
```
#### GLX / X11
```
zypper in libX11-devel libXcursor-devel libXrandr-devel
```
#### Plugin: ODE
```
zypper in autoconf automake libtool zip
```
#### Plugin: FFMPEG
```
zypper in ffmpeg-4-libavformat-devel ffmpeg-4-libswscale-devel
```
#### Worldspawn
```
zypper in make gtkglext-devel libxml2-devel libjpeg8-devel minizip-devel
```
### Fedora
#### FTE
```
dnf install make gcc gcc-c++ mesa-libGL-devel gnutls-devel alsa-devel libopus-devel speex-devel libvorbis-devel
```
#### SDL2
```
dnf install SDL2-devel
```
#### GLX / X11 (part of libsdl2-dev)
```
dnf install libX11-devel libXcursor-devel libXrender-devel
```
#### Plugin: ODE
```
dnf install autoconf automake libtool zip
```
#### Plugin: FFMPEG
*Note:* You will have to manually build this plugin due to FFMPEG breaking ABI between releases as well as install a custom repository since Fedora ships only latest versions of FFMPEG.
First, you will need to install the RPM Fusion if you don't have it. We recommend reading their official guide: https://rpmfusion.org/Configuration
Then, you can install the required version of FFMPEG:
```
dnf install compat-ffmpeg4-devel
```
Now to build:
1) Edit build.cfg and change `FFMPEG=YES` to `NO`
2) Browse to src/engine/engine
3) Run this command:
`make plugins-rel NATIVE_PLUGINS="ffmpeg" AV_BASE=/usr/include/compat-ffmpeg4 AV_LDFLAGS="-l:libavcodec.so.58 -l:libavformat.so.58 -l:libavutil.so.56 -l:libswscale.so.5"`
4) Copy over `fteplug_ffmpeg.so` to the `bin` folder where nuclide and the build scripts are.
#### Worldspawn
```
dnf install make pkgconf gtkglext-devel libxml2-devel libjpeg-turbo-devel minizip-devel
```
For documentation regarding Radiant and general id Tech level design, [you can visit this page](https://icculus.org/gtkradiant/documentation.html).

4
Documentation/Contributing.md
View file

@ -24,6 +24,10 @@ Most of the behaviour is rather predictable, other is not.
This is why some of the parts of Nuclide, which emulate entities/frameworks
from other games may feel a bit off. It's because it's all implemented by eye.
## Rule #3
Code that was generated by a large language model or similar technology is not welcome, due to unclear copyright.
# Other notes
Game specific features need to be put into game-specific directories.

6
Documentation/Decl.md Normal file
View file

@ -0,0 +1,6 @@
# Defs/Declarations {#scripting}
Explanation of declaration-based subsystems within Nuclide.
These usually contain key/value pair type parameters (and more, depending on the type)
within the game. They help a great deal in managing complexity between reusable components. That way the game code can focus on everything that's not unique.

6
Documentation/Constants.md → Documentation/Decl/Constants.md
View file

@ -1,4 +1,6 @@
# Constants
# Decl/Defs {#scripting}
## Constants
Often you want to be able to use aliases for values inside your **EntityDef** files.
@ -21,4 +23,4 @@ entityDef weapon_glock {
"inv_item" "$WEAPON_GLOCK"
[...]
}
```
```

24
Documentation/Sound/EFX.md → Documentation/Decl/EFX.md
View file

@ -1,18 +1,28 @@
# Sound: EFX {#EFX}
# Decl/Defs {#scripting}
## EFX
## EFXDefs {#efxdefs}
EFX is a system in [OpenAL](OpenAL.md) that delivers high quality sound reverberation. It is the successor to Creative's [Environmental Audio Extensions](EAX.md).
### History {#efxdefs_history}
#### Creative's Environmental Audio Extensions (EAX) {#eax}
Creative Technology's **Environmental Audio Extensions**, also known as **EAX**, attempted to create more ambiance within video games by more accurately simulating a real-world audio environment.
The release of Windows Vista deprecated the DirectSound3D API on which EAX relied on in 2007, so Creative Technology encouraged the move to OpenAL's EFX.
#### EFX {#efx}
EFX is a system in [OpenAL](https://www.openal.org/) that delivers high quality sound reverberation. It is the successor to @ref eax.
**Nuclide** offers abstraction for new and old entities relying on **digital signal processing**.
## Entities interacting with EFX
### Entities interacting with EFX
**env_sound** is most commonly used to change the environmental sound processing of a room/area.
In GoldSrc, it'll specify which enumeration of DSP preset to use for audio playback, in Nuclide however we just map it to a definitions file in the filesystem. See **EFX files** below.
## EFX defintion files
### EFX defintion files
Entities that specify a EFX type, usually want to load one from a file.
@ -46,13 +56,13 @@ Here's an example one, `efx/city.efx`:
Most of the parameters are self explanatory.
## Console Variables
### Console Variables
With the cvar `s_al_debug` set to 1 you'll get an overlay of information about which EFX file is currently being used, as well as what every single parameter is set to.
You can refresh EFX definitions with a map restart.
## Legacy translation table
### Legacy translation table
*This section describes behaviour specific to converting entities from Half-Life based levels into the Nuclide environment.*

106
Documentation/Decl/Sentences.md Normal file
View file

@ -0,0 +1,106 @@
# Decl/Defs {#scripting}
## Sentences {#sentences}
Sentences are the voice-acting backbone of the sound system.
The definitions for each games' voice acting are stored inside
`sound/sentences.txt`.
One **keyword**, referred to as the **Sentence**, substitutes a range of voiced samples. Sometimes spanning multiple *real sentences*.
In addition, it is capable of playing a random **Sentence** from a group of **Sentences**.
Due to their versatility, they should be used exclusively to deliver spoken dialog in the game.
### Syntax {#sentences_syntax}
Within a **Sentences** definition file, each new line is a new **Sentence** entry.
The syntax:
`SENTENCE [PARAMETERS] SAMPLES`
And here a practical, advanced, real-world example of a **Sentence**:
```
MALETEST (vol50) attention(p120) male/hello how are you
```
The above example lists 5 samples that'll get played. One sample (the first) is special in that it gets pitch shifted up by 20%. All of them play at %50 volume.
If a sample is not in a sub-directory, it'll be assumed to be part of
the **vox/** sub-directory under **sound/**, or the last valid path of a previous sample.
As a demonstration, the following, minimized samples:
```
attention male/hello how are you
```
will unpack to become the following samples:
```
vox/attention.wav male/hello.wav male/how.wav male/are.wav male/you.wav
```
*When parameters are surrounded by spaces, this means they apply to all
current samples.* They can be overwritten later down the parsing.
When a parameter is attached to the end of a sample:
```
attention(p120)
```
...then this parameter only applies to said keyword.
Whereas...
```
(p120) attention everyone alive
```
Will apply the pitch effect to all three succeeding samples.
### Parameters {#sentences_parameters}
- (pXX) = Pitch. Valid values are from 50 to 150. **Default**: 100
- (vXX) = Volume. Valid values are from 0 to 100. **Default**: 100
- (sXX) = Start point in %. E.g. 10 skips the first 10% of the sample. **Default**: 0
- (eXX) = End point in %. E.g. 75 ends playback 75% into the sample. **Default**: 100
- (tXX) = Time shift/compression in %. 100 is unaltered speed, wheras 50 plays the sample back in half the time.
### Random Sentences {#sentences_random}
When naming your **Sentences**, enumerate them, starting with the number **0**.
An example syntax would be as follows:
```
TEST0 yes
TEST1 no
TEST2 maybe
```
And when referring to this **Group** of Sentences, simply refer to the name without the enumeration at the end:
```
"sentence" "!TEST"
```
### Entity Usage {#sentences_usage}
When referencing a **Sentence** level designers are asked to prefix keys referring to them with an exclamation mark ( **!** ).
You'll find this in **scripted_sentence** type entities:
```
"sentence" "!GM_SUIT"
```
which in turn, will look up **GM_SUIT**:
```
GM_SUIT gman/gman_suit
```
This will also apply to any other entity that supports working with **Sentences**, like **ambient_generic**.

9
Documentation/Sound/SoundDefs.md → Documentation/Decl/SoundDefs.md
View file

@ -1,4 +1,7 @@
# Sound: soundDef
# Decl/Defs {#scripting}
## SoundDefs {#sounddefs}
Nuclide mimics the sound defintion spec from **id Tech 4** somewhat, albeit
with some changes/enhancements. We call them **soundDefs**.
@ -52,7 +55,7 @@ Let's take a look at another one:
This one has multiple sound files specified, which means that **Nuclide** will randomly choose one to play.
## Commands {#commands}
### Commands {#commands}
| | | |
|-----------------|-------------------------|-------------------------------------------------------------------------------------------------------------|
@ -77,7 +80,7 @@ This one has multiple sound files specified, which means that **Nuclide** will r
| distshader | <string> | Which sound def to play to everyone who is out of playback reach of this one. |
| sample | <string> | Adds a sample to play to the list. Will only play one at a time. |
## Power to the developer {#power_to_the_developer}
### Power to the developer {#power_to_the_developer}
Unlike the implementation in **id Tech 4**, all of the sound defs handling
is done in the game-logic and is therefore exposed to all developers.

18
Documentation/Surf_data.md → Documentation/Decl/SurfData.md
View file

@ -1,11 +1,13 @@
# Surface Properties
# Decl/Defs {#scripting}
## Surface Properties {#surfdata}
**Surfaces** are being abstracted into one API with the help of **SurfData**
helper functions and large parts of NSSurfacePropEntity.
# Preface {#preface}
### Preface {#surfdata_preface}
## The problem {#the_problem}
#### The problem {#surfdata_problem}
We need to define how a surface, speak a texture-mapped triangle,
behaves when being interacted with.
@ -14,14 +16,14 @@ behaves when being interacted with.
- What sounds does it make when it collides with other objects?
- What physical properties does it have that make it special?
## History {#history}
#### History {#surfdata_history}
In GoldSrc and similar engines, you'd specify
which material is used through 3 ways:
- The surface is a map texture, with a short material character
definition inside `sound/materials.txt` defining what the surface is
made of. See (MatGoldSrc.md) for details.
made of. See @ref gsmaterials for details.
- The entity itself offers a list of materials to choose from for
impact/breaking properties. For example `func_breakable` has the
`material` key. Which then tells the rest of the codebase that this
@ -40,7 +42,7 @@ uses special particle effects for impacts, or sounds - the sound it
makes when it scrapes across the floor or gets shaken - the weight of
the object and the friction it deals with.
## Understanding the new way {#understanding_the_new_way}
#### Understanding the new way {#surfdata_understanding_the_new_way}
So in Nuclide, there's a few options too as to how you're able to define
what property anything is made of.
@ -65,7 +67,7 @@ below.
Also, if an entity does not specify the material character inside the
script, Nuclide will figure it out on a surrounding surfaceparm basis.
# Scripting {#scripting}
### Scripting {#surfdata_scripting}
Scripts are formatted like our soundDefs:
@ -109,4 +111,4 @@ Available keys are:
"audioroughnessfactor" <float>
"scrapeRoughThreshold" <float>
"impactHardThreshold" <float>
"audioHardMinVelocity" <float>
"audioHardMinVelocity" <float>

208
Documentation/Dependencies.md Normal file
View file

@ -0,0 +1,208 @@
# Dependencies
Here we *attempt* to document the dependencies you may require to
build certain aspects yourself, on various different platforms.
### Debian / Raspbian
#### FTEQW
```
> apt-get install libgl-dev gnutls-dev
```
#### SDL2
```
# apt-get install libsdl2-dev
```
#### GLX / X11 (part of libsdl2-dev)
```
# apt-get install libx11-dev libxcursor-dev libxrender-dev
```
#### Plugin: ODE
```
# apt-get install autoconf automake libtool
```
#### Plugin: FFMPEG
```
# apt-get install libavformat-dev libswscale-dev
```
### OpenBSD
#### FTE
```
# pkg_add git
```
#### SDL2
```
# pkg_add sdl2
```
#### Plugin: FFMPEG
```
# pkg_add ffmpeg
```
### Arch Linux
#### FTE
```
# pacman -S make gcc Xorg git
```
#### Plugin: ODE
```
# pacman -S zip automake autoconf
```
#### Plugin: FFMPEG
> [!important]
> You will have to manually build this plugin due to FFMPEG
> breaking ABI between releases and Arch's rolling release nature.
First install the legacy version of **ffmpeg**:
```
# pacman -S ffmpeg4.4
```
Then browse to `ThirdParty/fteqw/engine` and run this command:
```
$ make plugins-rel NATIVE_PLUGINS="ffmpeg" AV_BASE=/usr/include/ffmpeg4.4/ AV_LDFLAGS="-l:libavcodec.so.58 -l:libavformat.so.58 -l:libavutil.so.56 -l:libswscale.so.5"
```
Last, copy over `fteplug_ffmpeg_*.so` to the root directory where the
engine binaries (and other plugins) are.
#### SDL2
```
# pacman -S sdl2
```
#### WorldSpawn
```
# pacman -S pkgconf gtk2 gtkglext
```
### OpenSUSE
#### Nuclide
```
# zypper in git
```
#### FTE
```
# zypper in make gcc gcc-c++ mesa-libGL-devel libgnutls-devel alsa-devel libopus-devel speex-devel libvorbis-devel
```
#### SDL2
```
# zypper in libSDL2-devel
```
#### GLX / X11
```
# zypper in libX11-devel libXcursor-devel libXrandr-devel
```
#### Plugin: ODE
```
# zypper in autoconf automake libtool zip
```
#### Plugin: FFMPEG
```
# zypper in ffmpeg-4-libavformat-devel ffmpeg-4-libswscale-devel
```
#### Worldspawn
```
# zypper in make gtkglext-devel libxml2-devel libjpeg8-devel minizip-devel
```
### Fedora
#### FTE
```
# dnf install make gcc gcc-c++ mesa-libGL-devel gnutls-devel alsa-devel libopus-devel speex-devel libvorbis-devel
```
#### SDL2
```
# dnf install SDL2-devel
```
#### GLX / X11 (part of libsdl2-dev)
```
# dnf install libX11-devel libXcursor-devel libXrender-devel
```
#### Plugin: ODE
```
# dnf install autoconf automake libtool zip
```
#### Plugin: FFMPEG
> [!important]
> You will have to manually build this plugin due to FFMPEG
> breaking ABI between releases as well as install a custom repository
> since Fedora ships only latest versions of FFMPEG.
First, you will need to install the RPM Fusion if you
don't have it. We recommend reading their official guide:
https://rpmfusion.org/Configuration
Then, you can install the required version of FFMPEG:
```
# dnf install compat-ffmpeg4-devel
```
Now to build:
1. Browse to `ThirdParty/fteqw/engine`
2. Run this command:
```
$ make plugins-rel NATIVE_PLUGINS="ffmpeg" AV_BASE=/usr/include/compat-ffmpeg4 AV_LDFLAGS="-l:libavcodec.so.58 -l:libavformat.so.58 -l:libavutil.so.56 -l:libswscale.so.5"
```
Last, copy over `fteplug_ffmpeg.so` to the root directory where the
engine binaries (and other plugins) are.
#### Worldspawn
```
# dnf install make pkgconf gtkglext-devel libxml2-devel libjpeg-turbo-devel minizip-devel
```

45
Documentation/EntityDef.md
View file

@ -1,45 +0,0 @@
# EntityDef
## Overview
In **id Tech 4**, we have been introduced to external entity definitions. They are pretty straightforward by merely being a set of default values for an existing entity class.
This can be used in a variety of ways.
- Create new entity classes with new behaviour without any code
- Create a base class that other entityDefs can inherit from
- Create prefabs that get updated across all maps
This system can also be used in combination with [MapTweaks](Documentation/MapTweaks.md), where an entityDef is used instead of a base class depending on the parameters you decide to test.
## Syntax
Let's take a look at an example **EntityDef**:
```
entityDef item_health_small {
"spawnclass" "item_health"
"spawnflags" "1"
}
```
This is from the port of *Deathmatch Classic*, and will ensure that **item_health_small** from *Quake III Arena* gets spawned as an **item_health** with its *spawnflags* set to the one that will make it a small health pickup.
You can have as many key/value pairs as you like. However, you can only specify one *spawnclass* and you cannot do circular inheritance.
## Special Keys
These are reserved keys and are meant to be used by the **build_game.sh** script to generate an entities.def file for your game.
| Key | Description |
|--------------------|------------------------------------------------------------------------|
| editor_usage | Description text used by the editor. |
| editor_model | Model to use in the editor. |
| editor_var **KEY** | Description text for the specified key. |
| editor_color | Normalized color vector defining the bounding box color in the editor. |
| editor_mins | Vector defining the mins of the entity bounding box. |
| editor_maxs | Vector defining the maxs of the entity bounding box. |
# References
- [id.sdk page on Entity Defs](http://icculus.org/~marco/notmine/id-dev/www.iddevnet.com/doom3/entitydefs.html)

360
Documentation/EntityGuide.md
View file

@ -2,363 +2,3 @@
# Overview
[ambient_generic](@ref ambient_generic)
[button_target](@ref button_target)
[cycler](@ref cycler)
[cycler_sprite](@ref cycler_sprite)
[cycler_weapon](@ref cycler_weapon)
[cycler_wreckage](@ref cycler_wreckage)
[env_beam](@ref env_beam)
[env_beverage](@ref env_beverage)
[env_bubbles](@ref env_bubbles)
[env_cascade_light](@ref env_cascade_light)
[env_cubemap](@ref env_cubemap)
[env_explosion](@ref env_explosion)
[env_fade](@ref env_fade)
[env_fire](@ref env_fire)
[env_fog](@ref env_fog)
[env_fog_controller](@ref env_fog_controller)
[env_funnel](@ref env_funnel)
[env_global](@ref env_global)
[env_glow](@ref env_glow)
[env_hudhint](@ref env_hudhint)
[env_instructor_hint](@ref env_instructor_hint)
[env_laser](@ref env_laser)
[env_message](@ref env_message)
[env_model](@ref env_model)
[env_muzzleflash](@ref env_muzzleflash)
[env_particle](@ref env_particle)
[env_physexplosion](@ref env_physexplosion)
[env_projectedtexture](@ref env_projectedtexture)
[env_render](@ref env_render)
[env_shake](@ref env_shake)
[env_shockwave](@ref env_shockwave)
[env_shooter](@ref env_shooter)
[env_smoker](@ref env_smoker)
[env_sound](@ref env_sound)
[env_soundscape](@ref env_soundscape)
[env_spark](@ref env_spark)
[env_sprite](@ref env_sprite)
[env_steam](@ref env_steam)
[env_sun](@ref env_sun)
[func_areaportal](@ref func_areaportal)
[func_areaportalwindow](@ref func_areaportalwindow)
[func_breakable](@ref func_breakable)
[func_brush](@ref func_brush)
[func_button](@ref func_button)
[func_conveyor](@ref func_conveyor)
[func_detail](@ref func_detail)
[func_detail_illusionary](@ref func_detail_illusionary)
[func_door](@ref func_door)
[func_door_rotating](@ref func_door_rotating)
[func_dustcloud](@ref func_dustcloud)
[func_dustmotes](@ref func_dustmotes)
[func_friction](@ref func_friction)
[func_group](@ref func_group)
[func_guntarget](@ref func_guntarget)
[func_healthcharger](@ref func_healthcharger)
[func_illusionary](@ref func_illusionary)
[func_ladder](@ref func_ladder)
[func_lod](@ref func_lod)
[func_monitor](@ref func_monitor)
[func_monsterclip](@ref func_monsterclip)
[func_mortar_field](@ref func_mortar_field)
[func_pendulum](@ref func_pendulum)
[func_physbox](@ref func_physbox)
[func_plat](@ref func_plat)
[func_platrot](@ref func_platrot)
[func_pushable](@ref func_pushable)
[func_recharge](@ref func_recharge)
[func_rot_button](@ref func_rot_button)
[func_rotating](@ref func_rotating)
[func_smokevolume](@ref func_smokevolume)
[func_tank](@ref func_tank)
[func_tankcontrols](@ref func_tankcontrols)
[func_tankmortar](@ref func_tankmortar)
[func_trackchange](@ref func_trackchange)
[func_tracktrain](@ref func_tracktrain)
[func_train](@ref func_train)
[func_traincontrols](@ref func_traincontrols)
[func_vehicle](@ref func_vehicle)
[func_vehiclecontrols](@ref func_vehiclecontrols)
[func_wall](@ref func_wall)
[func_wall_toggle](@ref func_wall_toggle)
[game_counter](@ref game_counter)
[game_counter_set](@ref game_counter_set)
[game_end](@ref game_end)
[game_player_equip](@ref game_player_equip)
[game_player_hurt](@ref game_player_hurt)
[game_player_team](@ref game_player_team)
[game_score](@ref game_score)
[game_team_master](@ref game_team_master)
[game_team_set](@ref game_team_set)
[game_text](@ref game_text)
[game_zone_player](@ref game_zone_player)
[gibshooter](@ref gibshooter)
[info_hint](@ref info_hint)
[info_intermission](@ref info_intermission)
[info_landmark](@ref info_landmark)
[info_node](@ref info_node)
[info_node_air](@ref info_node_air)
[info_notnull](@ref info_notnull)
[info_null](@ref info_null)
[info_particle_system](@ref info_particle_system)
[info_player_coop](@ref info_player_coop)
[info_player_deathmatch](@ref info_player_deathmatch)
[info_player_start](@ref info_player_start)
[info_teleport_destination](@ref info_teleport_destination)
[info_waypoint](@ref info_waypoint)
[infodecal](@ref infodecal)
[item_food](@ref item_food)
[light](@ref light)
[light_dynamic](@ref light_dynamic)
[light_environment](@ref light_environment)
[light_surface](@ref light_surface)
[logic_achievement](@ref logic_achievement)
[logic_auto](@ref logic_auto)
[logic_case](@ref logic_case)
[logic_relay](@ref logic_relay)
[logic_timer](@ref logic_timer)
[momentary_door](@ref momentary_door)
[momentary_rot_button](@ref momentary_rot_button)
[monster_furniture](@ref monster_furniture)
[monster_generic](@ref monster_generic)
[monstermaker](@ref monstermaker)
[multi_manager](@ref multi_manager)
[multisource](@ref multisource)
[path_corner](@ref path_corner)
[path_track](@ref path_track)
[phys_ballsocket](@ref phys_ballsocket)
[phys_constraint](@ref phys_constraint)
[phys_constraintsystem](@ref phys_constraintsystem)
[phys_convert](@ref phys_convert)
[phys_hinge](@ref phys_hinge)
[phys_keepupright](@ref phys_keepupright)
[phys_rope](@ref phys_rope)
[phys_slideconstraint](@ref phys_slideconstraint)
[player_loadsaved](@ref player_loadsaved)
[player_weaponstrip](@ref player_weaponstrip)
[point_camera](@ref point_camera)
[point_message](@ref point_message)
[point_servercommand](@ref point_servercommand)
[point_spotlight](@ref point_spotlight)
[point_trigger](@ref point_trigger)
[prop_dynamic](@ref prop_dynamic)
[prop_physics](@ref prop_physics)
[prop_physics_multiplayer](@ref prop_physics_multiplayer)
[prop_rope](@ref prop_rope)
[prop_static](@ref prop_static)
[prop_vehicle_driveable](@ref prop_vehicle_driveable)
[random_speaker](@ref random_speaker)
[random_trigger](@ref random_trigger)
[script_brushmodel](@ref script_brushmodel)
[script_model](@ref script_model)
[script_origin](@ref script_origin)
[script_struct](@ref script_struct)
[script_vehicle](@ref script_vehicle)
[scripted_sentence](@ref scripted_sentence)
[scripted_sequence](@ref scripted_sequence)
[sky_camera](@ref sky_camera)
[speaker](@ref speaker)
[targ_speaker](@ref targ_speaker)
[target_cdaudio](@ref target_cdaudio)
[trigger_auto](@ref trigger_auto)
[trigger_autosave](@ref trigger_autosave)
[trigger_camera](@ref trigger_camera)
[trigger_cdaudio](@ref trigger_cdaudio)
[trigger_changelevel](@ref trigger_changelevel)
[trigger_changetarget](@ref trigger_changetarget)
[trigger_counter](@ref trigger_counter)
[trigger_endsection](@ref trigger_endsection)
[trigger_gravity](@ref trigger_gravity)
[trigger_hurt](@ref trigger_hurt)
[trigger_look](@ref trigger_look)
[trigger_monsterjump](@ref trigger_monsterjump)
[trigger_multiple](@ref trigger_multiple)
[trigger_once](@ref trigger_once)
[trigger_playerfreeze](@ref trigger_playerfreeze)
[trigger_push](@ref trigger_push)
[trigger_relay](@ref trigger_relay)
[trigger_teleport](@ref trigger_teleport)
[trigger_transition](@ref trigger_transition)
[worldspawn](@ref worldspawn)

BIN
Documentation/Images/Nuclide.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 2.6 KiB

BIN
Documentation/Images/env_cascade_light.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 131 KiB

BIN
Documentation/Images/func_healthcharger.jpg Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 11 KiB

BIN
Documentation/Images/func_recharge.jpg Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 11 KiB

0
Documentation/Materials/commands/gl_blendmodes.jpg → Documentation/Images/gl_blendmodes.jpg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 73 KiB

After

Width:  |  Height:  |  Size: 73 KiB

0
Documentation/Materials/hl_impact.jpg → Documentation/Images/hl_impact.jpg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 7.1 KiB

After

Width:  |  Height:  |  Size: 7.1 KiB

0
Documentation/Materials/q3a_material.jpg → Documentation/Images/q3a_material.jpg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 26 KiB

After

Width:  |  Height:  |  Size: 26 KiB

0
Documentation/Sound/sounds_attenuation.png → Documentation/Images/sounds_attenuation.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 25 KiB

After

Width:  |  Height:  |  Size: 25 KiB

0
Documentation/Materials/source_metal.jpg → Documentation/Images/source_metal.jpg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.9 KiB

After

Width:  |  Height:  |  Size: 6.9 KiB

0
Documentation/Materials/source_plaster.jpg → Documentation/Images/source_plaster.jpg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 6.7 KiB

After

Width:  |  Height:  |  Size: 6.7 KiB

0
Documentation/Materials/source_wood.jpg → Documentation/Images/source_wood.jpg
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 11 KiB

After

Width:  |  Height:  |  Size: 11 KiB

52
Documentation/Launching.md
View file

@ -1,58 +1,12 @@
# Launching
## For development...
For development, use the `nuclide` launch script inside the root directory.
You run `./fteqw` with a parameter specifying the game directory:
```
$ ./nuclide
$ ./fteqw -game base
```
Running it on its own will mount only the directory `platform/`. As that's the default defined inside the file `./default.fmf`.
You can mount an additional mod over it like so:
```
$ ./nuclide -game some_other_mod
```
If you wanted to mount multiple game dirs, you could in theory do it like so:
```
$ ./nuclide -game first_mod -game second_mod -game third_mod
```
And it'll load those directories in order.
However, if you'd like to be very specific in how a game is run/branded/launched
you should really use **FTE Manifest** files.
Simply plop one into your game directory with the name `manifest.fmf`, then launch
nuclide like so:
```
$ ./nuclide first_mod
```
and it will load `first_mod/manifest.fmf`. You can supply arguments to it by putting them into the second parameter with quotes like so:
```
$ ./nuclide first_mod "-window +set sv_cheats 1"
```
However, we advise you only do this for development. If you want proper multiplayer compatibility (slightly different filesystem mount setups can confuse client-server negotation) please use the built-in **Custom game** menu to ensure maximum compatibility to other clients.
If you are running a dedicated server and have issues with multiple game directories, check the value of the cvar `sv_gamedir` on the server. It is meant to be a semicolon separated list of game directories, if multiple ones are supposed to be mounted.
## For release...
You'll want to compile a custom build of the engine with your branding.
Inside `src/engine/engine/common/` you can find a config file named `config_wastes.h`,
which is a good example of how you can customize your engine binaries and filesystem mount-points.
That way you **avoid** shipping a default.fmf file.
**How to compile a custom config build**: You pass `FTE_CONFIG=wastes` to the make environment when building an engine binary - if you wanted to build with the `config_wastes.h` file. [For more information check out the building section](Building.md)
If you [built a custom branded version of the engine](@ref build-engine), you can run that as is.
## Mod/Game Setup

36
Documentation/MapTweaks.md
View file

@ -1,36 +0,0 @@
# MapTweaks
## Overview
This is a very customizable system that applies changes to levels/maps depending on a variable amount of parameters. It was invented specifically for Nuclide and designed to work together with [EntityDefs](Documentation/EntityDef.md).
## Syntax
All MapTweaks are defined within `scripts/maptweaks.txt`.
Let's take a look at an example **MapTweak**:
```
hldm_tweak
{
when-cvar deathmatch equals 2
when-serverinfo *bspversion equals 30
replace weapon_gauss info_null
replace weapon_egon info_null
}
```
The `hldm_tweaks` is just a user-defined name. It doesn't affect functionality.
The `when-cvar` and `when-serverinfo` lines are **checks**. each one is checked individually and only if all are positive will the `replace` lines take effect.
You can have as many lines in there as you like.
Other than `equals`, you can also use one of the following keywords when comparing values:
- **less-than**
- **greater-than**
- **is-not**
At this time, `when-cvar` and `when-serverinfo` only do comparisons on numbers. So you cannot check for strings at this time.

16
Documentation/Materials/MatOverview.md → Documentation/Materials.md
View file

@ -1,4 +1,4 @@
# Materials
# Material System(s) {#materials}
**Materials**, also formerly known **Q3 shaders** or wrongly referred to as just **shaders** are scripts that define texture and surface properties.
@ -6,9 +6,9 @@
In the id Tech series of engines, **id Tech 3/Quake III Arena** was the first to introduce such a system, wrongly referred to back then as **shaders**. This was before vertex and fragment shaders were commonplace in the video-game asset pipeline.
![from pulsing tubes to various animated materials in Quake III Arena](q3a_material.jpg)
![id Tech 3 showcased pulsing tubes and various animated materials. Quake III Arena is property of id Software.](q3a_material.jpg)
They effectively merged the Quake texture-prefix hacks and Quake II .wal surface flags into one plain text format.
They effectively merged the Quake texture-prefix based hacks and **Quake II** .wal surface flags into one plain text format.
Starting with **id Tech 4/Doom III** in 2004, the name of **shader** was changed to **material** to avoid confusion with proper GPU oriented vertex and fragment shaders.
@ -24,18 +24,18 @@ If you want to have a surface that looks and acts like water, then you have to w
### When using older BSP formats...
Then you can still use modern materials! While the engine may load a texture from a **.bsp** or **.wad** file directly, it will still (albeit internally) create a material for it.
Then you can still use modern materials! While the engine may load a texture from a **bsp** or **wad** file directly, it will still (albeit internally) create a material for it.
When ingame, look at your surface you want to replace with the console variable **r_showshaders** set to **1* - and you will see the path and the contents of the material you're looking at. You can use that information to override rendering for practically any surface, even when using old fileformats.
When ingame, look at your surface you want to replace with the console variable `r_showshaders` set to `1` - and you will see the path and the contents of the material you're looking at. You can use that information to override rendering for practically any surface, even when using old fileformats.
## Usage
When the engine looks for a texture, it will look for a material file in the file-tree first, then it will attempt to 'make one up' if only an image file is present. A rendereable surface will **always** have a material. The question is whether you provide it, or if the engine has to automatically generate one internally.
When the engine looks for a texture, it will look for a material file in the filesystem first, then it will attempt to 'make one up' if only an image file is present. A renderable surface will **always** have a material. The question is whether you provide it, or if the engine has to automatically generate one internally.
The file extension for materials in Nuclide is .mat. There are two ways of defining materials:
- A large .shader script file containing multiple materials inside the **./scripts/** folder (not recommended)
- One small .mat file with the same path as the texture. E.g: **models/weapons/handcannon/w_handcannon/w_handcannon.mat** handles **models/weapons/handcannon/w_handcannon/w_handcannon.tga**
- A large .shader script file containing multiple materials inside the `<gamedir>/scripts/` folder (not recommended)
- One small .mat file with the same path as the texture. E.g: `models/weapons/handcannon/w_handcannon/w_handcannon.mat` handles `models/weapons/handcannon/w_handcannon/w_handcannon.tga`
A material file consists of a series of surface attributes (global scope) and rendering instructions formatted within braces ("{" and "}"). Below you can see a simple example of syntax and format for a single process, including the VMAP keywords or 'Surface Parameters', which follow the first bracket and a single bracketed 'stage':

17
Documentation/Materials/Commands.md Normal file
View file

@ -0,0 +1,17 @@
# Material Command List {#mat_commands}
Here is a list of all the commands that can be contained within a material definition file, like a **mat** or a **shader** file.
There are three different kinds of commands:
- Surface Specific
- Stage/Layer Specific
- vmap Specific
Surface specific commands affect the entire surface, or sometimes whole brush-volume it belongs to. Example commands may be @ref surfaceparm.
Stage/Layer specific commands only affect one part of the rendering stage. Generally anything within a sub-block of braces (`{ }`) is a stage. It defines a layer to draw on top of the surface.
Due to how simple most surfaces are, you don't have to define a stage. It is often enough to set @ref mat_program, @ref diffuseMap and you're rendering a surface handled entirely by the GPU.
Some operations, such as @ref deformVertexes or @ref tcMod are done on the CPU. While you can use those, know that moving that action into a [Shader Program](@ref shaders) is recommended.

60
Documentation/Materials/MatGoldSrc.md → Documentation/Materials/GoldSrc.md
View file

@ -1,14 +1,16 @@
# "Materials" in GoldSrc
# Material System(s) {#materials}
## GoldSrc Material System {#gsmaterials}
In the GoldSrc games "Material" definitions handle what footsteps and what impact sounds are played against each texture in the game-world.
![Generic bullet impact effect in Half-Life](hl_impact.jpg)
![Generic bullet impact effect in Half-Life. Half-Life belongs to Valve Corporation.](hl_impact.jpg)
So when you walk on dirt, you can hear the difference; or when you shoot wood with a gun it will sound like wood.
**Note:** While Nuclide supports this for legacy BSP files, please define the surface properties inside your [material](Documentation/Materials/MatOverview.md) using the **surfaceprop** command.
## Details
### Details
Usually, a game in the GoldSrc engine would provide a `sound/materials.txt` file, where each line defines the properties for a single (or a series of) textures by starting with a material id character, followed by whitespace, followed by a name matching pattern.
@ -30,9 +32,9 @@ When you then walk around your level, the footstep will then be aware of you bei
Porting levels can sometimes be a bit more work than it first appears to be at first glance as a result!
## Later Enhancements
### Later Enhancements
### Community additions
#### Community additions
In stock GoldSrc games, the `sound/materials.txt` can be overwritten by a modification but it couldn't be dynamically extended in any way.
This means there was no possibility of map specific materials, and mods could not inherit Half-Life's materials, so mods would always have to manage a nearly duplicate file if they desired custom material definitions.
@ -52,7 +54,7 @@ worldspawn entity key named 'materials_file' with the value `PATH_TO/FILE.txt`
**All these methods are supported by Nuclide**, as one goal is to implement
conventions by not only Valve but the community as well!
### Nuclide additions
#### Nuclide additions
In addition Nuclide has also implemented a way of giving modifications
their own *inheritable* materials file:
@ -70,7 +72,7 @@ while the Nuclide method should be used for **mods** or **map packs**.
purposes. It is inefficient for modern projects as there are much better
standards already supported in Nuclide.
# Material List
## Material List
In Nuclide, this is the currently supported list of material IDs:
@ -93,7 +95,7 @@ In Nuclide, this is the currently supported list of material IDs:
| W | Wood |
| Y | Glass |
## Game differences
### Game differences
Different games/mods can ship with different material properties.
To make your life easier, you can edit **scripts/surfaceproperties.txt** and define
@ -102,9 +104,9 @@ This way you can add new materials to existing legacy maps without writing a lin
Listed below are definitions for various games and mods. Only the changes and additions are listed since the rest are identical.
## GoldSrc Games/Mods
### GoldSrc Games/Mods
### Arrangement
#### Arrangement
| Material ID | Material Name |
|-------------------|---------------------|
@ -115,7 +117,7 @@ Listed below are definitions for various games and mods. Only the changes and ad
| X | Yellow Texture |
| Z | Black Texture |
### Counter-Strike
#### Counter-Strike
| Material ID | Material Name |
|-------------------|---------------------|
@ -124,7 +126,7 @@ Listed below are definitions for various games and mods. Only the changes and ad
*Afraid of Monsters: DC, Natural Selection, and Snow War uses the same definitions.*
### Cry of Fear
#### Cry of Fear
| Material ID | Material Name |
|-------------------|---------------------|
@ -138,7 +140,7 @@ Listed below are definitions for various games and mods. Only the changes and ad
| Y | Broken Glass |
| Z | Carpet |
### Gunman Chronicles
#### Gunman Chronicles
| Material ID | Material Name |
|-------------------|---------------------|
@ -147,7 +149,7 @@ Listed below are definitions for various games and mods. Only the changes and ad
| V | Sand |
| W | Unknown/Unused? |
### Firearms
#### Firearms
| Material ID | Material Name |
|-------------------|-----------------------------------------|
@ -155,13 +157,13 @@ Listed below are definitions for various games and mods. Only the changes and ad
| N | Snow |
| U | No impact or decals, just smoke effects |
### Heart of Evil
#### Heart of Evil
| Material ID | Material Name |
|-------------------|---------------------|
| U | Mud |
### Hostile Intent
#### Hostile Intent
| Material ID | Material Name |
|-------------------|---------------------|
@ -172,20 +174,20 @@ Listed below are definitions for various games and mods. Only the changes and ad
| U | Mud |
| Z | Grass |
### Household DEATH!
#### Household DEATH!
| Material ID | Material Name |
|-------------------|---------------------|
| H | Wood (Creaky) |
| I | Grass |
### Night at the Office
#### Night at the Office
| Material ID | Material Name |
|-------------------|---------------------|
| T | Carpet |
### Opposing Force
#### Opposing Force
| Material ID | Material Name |
|-------------------|---------------------|
@ -193,7 +195,7 @@ Listed below are definitions for various games and mods. Only the changes and ad
*Science and Industry uses the same definitions as Opposing Force.*
### Poke646
#### Poke646
| Material ID | Material Name |
|-------------------|---------------------|
@ -201,7 +203,7 @@ Listed below are definitions for various games and mods. Only the changes and ad
| T | Wood/Tile |
| G | Carpet/Grass |
### Wasteland Half-Life
#### Wasteland Half-Life
| Material ID | Material Name |
|-------------------|---------------------|
@ -213,7 +215,7 @@ Listed below are definitions for various games and mods. Only the changes and ad
*The Wastes uses the same definitions.*
## Source Engine Games/Mods
### Source Engine Games/Mods
While Source has materials describing a surface with its own **$surfaceprop** command, the GoldSrc way of describing materials with a 1-character symbol is still used to define which **impact effect** to use.
@ -225,7 +227,7 @@ The **Material ID** is used via the `gamematerial` command inside **scripts/surf
Be aware that a Source engine game may actually have more surface materials than this, these are *solely the IDs associated with impact effects*.
### Alien Swarm
#### Alien Swarm
| Material ID | Material Name |
|-------------------|---------------------|
@ -233,7 +235,7 @@ Be aware that a Source engine game may actually have more surface materials than
**Alien Swarm: Reactive Drop uses the same definitions.**
### Counter-Strike: Global Offensive
#### Counter-Strike: Global Offensive
| Material ID | Material Name |
|-------------------|---------------------------|
@ -242,7 +244,7 @@ Be aware that a Source engine game may actually have more surface materials than
| 13 | Sand Barrel (Penetration) |
| 14 | Metal Shield |
### Half-Life 2
#### Half-Life 2
| Material ID | Material Name |
|-------------------|---------------------|
@ -257,14 +259,14 @@ Be aware that a Source engine game may actually have more surface materials than
| X | Fake |
| - | No Decal |
### Half-Life 2: Episode 2
#### Half-Life 2: Episode 2
| Material ID | Material Name |
|-------------------|---------------------|
| E | Antlion Egg Sacks |
| Z | Adviser Shield |
### Insurgency
#### Insurgency
| Material ID | Material Name |
|-------------------|---------------------|
@ -272,7 +274,7 @@ Be aware that a Source engine game may actually have more surface materials than
*Day of Infamy uses the same definitions.*
### Left 4 Dead
#### Left 4 Dead
| Material ID | Material Name |
|-------------------|---------------------|
@ -292,7 +294,7 @@ Be aware that a Source engine game may actually have more surface materials than
| 9 | Upholstery |
| 10 | Puddle |
### Portal 2
#### Portal 2
| Material ID | Material Name |
|-------------------|---------------------|

4
Documentation/Materials/MatCommands.md
View file

@ -1,4 +0,0 @@
# Materials: Commands {#mat_commands}
These are all the important material commands that affect the renderer in some shape or form.
[For material commands that affect the compiling process, look over here.](Documentation/Materials/MatVMap.md)

4
Documentation/Materials/MatVMap.md
View file

@ -1,4 +0,0 @@
# Materials: VMap Commands {#mat_vmap}
The following commands are alter specific behaviour during the **BSP** compilation process.
These are not respected by the engine, the renderer or the game-logic.

10
Documentation/Materials/commands/alphafunc.md → Documentation/Materials/StageCommands/alphafunc.md
View file

@ -1,10 +1,12 @@
# Materials: Commands {#mat_commands}
## alphafunc
### Syntax
# Material Command List {#mat_commands}
### alphafunc {#alphafunc}
#### Syntax
**alphaFunc <func>**
### Overview
#### Overview
Determines the alpha test function used when rendering this surface.

14
Documentation/Materials/commands/alphagen.md → Documentation/Materials/StageCommands/alphagen.md
View file

@ -1,17 +1,19 @@
# Materials: Commands {#mat_commands}
## alphagen
### Syntax
# Material Command List {#mat_commands}
### alphagen {#alphaGen}
#### Syntax
**alphaGen <func>**
### Overview
#### Overview
The alpha channel can be specified like the [rgb channels](rgbgen.md). If not specified, it
defaults to 1.0.
### Functions {#functions}
#### Functions
#### portal {#portal}
##### portal
This rendering stage keyword is used in conjunction with the
[surfaceparm](surfaceparm.md) keyword

30
Documentation/Materials/commands/blendfunc.md → Documentation/Materials/StageCommands/blendfunc.md
View file

@ -1,44 +1,46 @@
# Materials: Commands {#mat_commands}
## blendfunc
# Material Command List {#mat_commands}
### blendFunc {#blendFunc}
![OpenGL blending cheat-sheet](gl_blendmodes.jpg "from zanir.wz.cz/?p=60")
### Syntax
#### Syntax
**blendFunc <simplefunc>**
**blendFunc <srcBlend> <destBlend>**
### Overview
#### Overview
Blend functions are the keyword commands that tell the renderer how
graphic layers are to be mixed together.
### Usage
#### Usage
#### Simplified blend functions {#simplified_blend_functions}
#### Simplified blend functions
The most common blend functions are set up here as simple commands, and
should be used unless you really know what you are doing.
##### add {#add}
###### add
This is a shorthand command for `blendFunc GL_ONE GL_ONE`. Effects like
fire and energy are additive.
##### filter {#filter}
###### filter
This is a shorthand command that can be substituted for either
`blendFunc GL_DST_COLOR GL_ZERO` or `blendFunc GL_ZERO GL_SRC_COLOR`. A
filter will always result in darker pixels than what is behind it, but
it can also remove color selectively. Lightmaps are filters.
##### blend {#blend}
###### blend
Shorthand for `blendFunc GL_SRC_ALPHA GL_ONE_MINUS_SRC_ALPHA`. This is
conventional transparency, where part of the background is mixed with
part of the texture.
#### Explicit blend functions {#explicit_blend_functions}
##### Explicit blend functions
Getting a handle on this concept is absolutely key to understanding all
shader manipulation of graphics.
@ -78,7 +80,7 @@ A general rule is that any Source Blend other than **GL_ONE** (or
**GL_SRC_ALPHA** where the alpha channel is entirely white) will cause
the Source to become darker.
##### Source Blend <srcBlend> {#source_blend}
###### Source Blend <srcBlend>
The following values are valid for the Source Blend part of the
equation.
@ -104,7 +106,7 @@ equation.
except that the value in the alpha channel is inverted by
subtracting it from one.(i.e. A=1.0 - SRC.A)
##### Destination Blend <dstBlend> {#destination_blend}
###### Destination Blend <dstBlend>
The following values are valid for the Destination Blend part of the
equation.
@ -127,7 +129,7 @@ equation.
except that the value in the alpha channel is inverted by
subtracting it from one. (i.e. A=1.0 - SRC.A).
##### Doing the Math: The Final Result {#doing_the_math_the_final_result}
###### Doing the Math: The Final Result
The product of the Source side of the equation is added to the product
of the Destination side of the equation. The sum is then placed into the
@ -136,7 +138,7 @@ Ultimately, the equation creates a modified color value that is used by
other functions to define what happens in the texture when it is
displayed in the game world.
#### Default Blend Function {#default_blend_function}
##### Default Blend Function
If no blendFunc is specified then no blending will take place. That's
just a fact of life.

9
Documentation/Materials/commands/depthfunc.md → Documentation/Materials/StageCommands/depthfunc.md
View file

@ -1,10 +1,11 @@
# Materials: Commands {#mat_commands}
## depthfunc
### Syntax
# Material Command List {#mat_commands}
### depthFunc {#depthFunc}
#### Syntax
**depthFunc <func>**
### Overview
#### Overview
This controls the depth comparison function used while rendering.

10
Documentation/Materials/commands/depthwrite.md → Documentation/Materials/StageCommands/depthwrite.md
View file

@ -1,10 +1,12 @@
# Materials: Commands {#mat_commands}
## depthwrite
### Syntax
# Material Command List {#mat_commands}
### depthWrite {#depthWrite}
#### Syntax
**depthWrite**
### Overview
#### Overview
By default, writes to the depth buffer when
[depthFunc](depthfunc.md) passes will happen

6
Documentation/Materials/commands/program.md → Documentation/Materials/StageCommands/program.md
View file

@ -1,5 +1,7 @@
# Materials: Commands {#mat_commands}
## program
# Material Command List {#mat_commands}
### program {#mat_program}
**program** defines which GLSL/HLSL shader to load for a defined
material. It also accepts arguments that will recompile a shader with
certain permutations. This is kinda ugly,

44
Documentation/Materials/commands/rgbgen.md → Documentation/Materials/StageCommands/rgbgen.md
View file

@ -1,12 +1,14 @@
# Materials: Commands {#mat_commands}
## rgbgen
### Syntax
# Material Command List {#mat_commands}
### rgbGen {#rgbGen}
#### Syntax
**rgbGen <func>**
**rgbGen wave <func> <base> <amp><phase> <freq>**
### Overview
#### Overview
Defines what vertex colors are set to for any given surface.
@ -16,9 +18,9 @@ be selected, depending on which blend modes are used.
Valid <func> parameters are const, wave, identity, identityLighting,
entity, oneMinusEntity, fromVertex, and lightingDiffuse.
### Functions {#functions}
#### Functions
#### const {#const}
##### const
Follow this up with a vector of the color that you'd like the vertex
colors to be set as. An example for green would be:
@ -26,45 +28,45 @@ colors to be set as. An example for green would be:
rgbGen const 0.0 1.0 0.0
```
#### identityLighting {#identitylighting}
##### identityLighting
Colors will be (1.0,1.0,1.0) if running without overbright bits (NT,
linux, windowed modes), or (0.5, 0.5, 0.5) if running with overbright.
Overbright allows a greater color range at the expense of a loss of
precision. Additive and blended stages will get this by default.
#### identity {#identity}
##### identity
Colors are assumed to be all white (1.0,1.0,1.0). All filters stages
(lightmaps, etc) will get this by default.
#### entity {#entity}
##### entity
Colors are grabbed from the entity's .colormod field.
#### oneMinusEntity {#oneminusentity}
##### oneMinusEntity
Colors are grabbed from 1.0 minus the entity's .colormod field.
#### entityLighting {#entitylighting}
##### entityLighting
Introduced by [FTE](FTE), same as entity, but will receive
lighting similar to identityLighting on top of it.
#### vertex {#vertex}
##### vertex
Colors are filled in directly by the data from the map or model files.
This is used for blending brushes and patches. It was used at one point
to store primitive lighting, in case the lightmapped rendering path was
to expensive (this is no longer available).
#### oneMinusVertex {#oneminusvertex}
##### oneMinusVertex
As rgbGen vertex, but inverted.
Design Note: This keyword would probably not be used by a level designer
#### lightingDiffuse {#lightingdiffuse}
##### lightingDiffuse
Colors are computed using a standard diffuse lighting equation. It uses
the vertex normals to illuminate the object correctly.
@ -74,7 +76,7 @@ values to be computed for a dynamic model (i.e. non-map object) in the
world using regular in-game lighting. For example, you would specify on
materials for items, characters, weapons, etc.
#### wave <func> <base> <amp><phase> <freq> {#wave}
##### wave <func> <base> <amp><phase> <freq>
Colors are generated using the specified waveform. An affected texture
with become darker and lighter, but will not change hue. Hue stays
@ -82,7 +84,7 @@ constant. Note that the rgb values for color will not go below 0 (black)
or above 1 (white). Valid waveforms are **sin**, **triangle**,
**square**, **sawtooth** and **inversesawtooth**.
##### <func> {#section}
###### <func>
- **Sin**: color flows smoothly through changes.
- **Triangle**: color changes at a constant rate and spends no
@ -96,23 +98,23 @@ or above 1 (white). Valid waveforms are **sin**, **triangle**,
making the ascent immediate (like a square wave) and the decay fall
off like a triangle wave.
##### <base> {#section_1}
###### <base>
Baseline value. The initial RGB formula of a color (normalized).
##### <amp> {#section_2}
###### <amp>
Amplitude. This is the degree of change from the baseline value. In some
cases you will want values outside the 0.0 to 1.0 range, but it will
induce clamping (holding at the maximum or minimum value for a time
period) instead of continuous change.
##### <phase> {#section_3}
###### <phase>
See the explanation for phase under the waveforms heading of Key
Concepts.
##### <freq> {#section_4}
###### <freq>
Frequency. This is a value (NOT normalized) that indicates peaks per
second.
second.

18
Documentation/Materials/commands/tcgen.md → Documentation/Materials/StageCommands/tcgen.md
View file

@ -1,24 +1,26 @@
# Materials: Commands {#mat_commands}
## tcgen
### Syntax
# Material Command List {#mat_commands}
### tcGen {#tcGen}
#### Syntax
**tcGen <coordinate source>**
### Overview
#### Overview
Specifies how texture coordinates are generated and where they come
from. Valid functions are **base**, **lightmap** and **environment**.
### Sources {#sources}
#### Sources {#sources}
#### base {#base}
##### base {#base}
Base texture coordinates from the original art.
#### lightmap {#lightmap}
##### lightmap {#lightmap}
Lightmap texture coordinates.
#### environment {#environment}
##### environment {#environment}
Make this object environment mapped.

26
Documentation/Materials/commands/tcmod.md → Documentation/Materials/StageCommands/tcmod.md
View file

@ -1,10 +1,12 @@
# Materials: Commands {#mat_commands}
## tcmod
### Syntax
# Material Command List {#mat_commands}
### tcMod {#tcMod}
#### Syntax
**tcMod <func> [...]**
### Overview
#### Overview
Specifies how texture coordinates are modified after they are generated.
@ -28,9 +30,9 @@ specified. In otherwords, if you see:
Then the texture coordinates will be **scaled** then **scrolled**.
### Functions {#functions}
#### Functions
#### rotate <degrees per per second> {#rotate}
##### rotate <degrees per per second>
This keyword causes the texture coordinates to rotate. The value is
expressed in degrees rotated each second. A positive value means
@ -41,7 +43,7 @@ center point of the texture map, so you are rotating a texture with a
single repetition, be careful to center it on the brush (unless
off-center rotation is desired).
#### scale <sScale> <tScale> {#scale}
##### scale <sScale> <tScale>
Resizes (enlarges or shrinks) the texture coordinates by multiplying
them against the given factors of <sScale> and &lt;tScale). The values
@ -58,7 +60,7 @@ Example: `tcMod scale 0.5 2` would cause the texture to repeat twice
along its width, but expand to twice its height (in which case half of
the texture would be seen in the same area as the original)
#### scroll <sSpeed> <tSpeed> {#scroll}
##### scroll <sSpeed> <tSpeed>
Scrolls the texture coordinates with the given speeds. The values "s"
and "t" conform to the "x" and "y" values (respectively) as they are
@ -75,7 +77,7 @@ texture each second of travel.
**This should be the LAST tcMod in a stage.** Otherwise there maybe
popping or snapping visual effects in some materials.
#### stretch <func> <base> <amplitude> <phase> <frequency> {#stretch}
##### stretch <func> <base> <amplitude> <phase> <frequency>
Stretches the texture coordinates with the given function. Stretching is
defined as stretching the texture coordinate away from the center of the
@ -107,7 +109,7 @@ keyword.
wave.
- **Inversesawtooth**: this is the reverse of the sawtooth wave.
#### transform <m00> <m01> <m10> <m11> <t0> <t1> {#transform}
##### transform <m00> <m01> <m10> <m11> <t0> <t1>
Transforms each texture coordinate as follows:
@ -115,7 +117,7 @@ S' = s \* m00 + t \* m10 + t0 T' = s \* m01 + t \* m11 + t1
This is for use by programmers.
#### turb <base> <amplitude> <phase> <freq> {#turb}
##### turb <base> <amplitude> <phase> <freq>
Applies turbulence to the texture coordinate. Turbulence is a back and
forth churning and swirling effect on the texture.
@ -131,4 +133,4 @@ The parameters for this are defined as follows:
- **freq**: Frequency. This value is expressed as repetitions or
cycles of the wave per second. A value of one would cycle once per
second. A value of 10 would cycle 10 times per second. A value of
0.1 would cycle once every 10 seconds.
0.1 would cycle once every 10 seconds.

76
Documentation/Materials/SurfaceCommands/bemode.md Normal file
View file

@ -0,0 +1,76 @@
# Material Command List {#mat_commands}
### bemode {#bemode}
#### Syntax
**bemode <mode>**
#### Overview
Filters which back end rendering features are drawn on top of the material.
While you're not encouraged to be overriding this value, it is sometimes necessary.
#### Modes {#bemode_sides}
These are the different modes that we can specify.
##### rtlight {#bemode_rtlight}
All light types will be drawn onto this surface.
##### rtlight_only {#bemode_rtlight_only}
Dynamic lights only.
##### rtlight_smap {#bemode_rtlight_smap}
Shadowmaps only.
##### rtlight_spot {#bemode_rtlight_spot}
Spotlights only.
##### rtlight_cube {#bemode_rtlight_cube}
Cubemap lights only.
##### rtlight_cube_smap {#bemode_rtlight_cube_smap}
Cubemap lights and shadowmaps only.
##### rtlight_cube_spot {#bemode_rtlight_cube_spot}
Cubemap lights and spotlights only.
##### rtlight_spot_smap {#bemode_rtlight_spot_smap}
Spot lights and shadowmaps only.
##### rtlight_cube_spot_smap {#bemode_rtlight_cube_spot_smap}
Cubemap lights, spot lights and shadowmaps only.
##### crepuscular {#bemode_crepuscular}
For skies that might cast rays.
Those are rendered to a frame buffer object (with everything else being @ref bemode_depthdark) and is then applied to the screen as a post-processing effect.
##### depthonly {#bemode_depthonly}
Used mainly by shadow maps.
##### depthdark {#bemode_depthdark}
Black depth passes only.
Used to draw a black world, when `r_shadow_realtime_world_lightmaps` is `0` for example.
##### gbuffer {#bemode_gbuffer}
##### prelight {#bemode_prelight}
Deferred lighting only.
##### fog {#bemode_fog}
Fog layer only.

18
Documentation/Materials/commands/cull.md → Documentation/Materials/SurfaceCommands/cull.md
View file

@ -1,10 +1,12 @@
# Materials: Commands {#mat_commands}
## cull
### Syntax
# Material Command List {#mat_commands}
### cull {#cull}
#### Syntax
**cull <side>**
### Overview
#### Overview
Every surface of a polygon has two sides, a front and a back. Typically,
we only see the front or "out" side. For example, a solid block you only
@ -18,21 +20,21 @@ is not specified. However for items that should be inverted then the
value back should be used. To disable culling, the value disable or none
should be used. Only one cull instruction can be set for the material.
### Sides {#sides}
#### Sides {#cull_sides}
#### front {#front}
##### front {#cull_front}
**This is the default value.** The front or "outside" of the polygon is
not drawn in the world. It is used if the keyword `"cull "` appears in
the content instructions without a <side> value or if the keyword cull
does not appear at all in the shader.
#### back {#back}
##### back {#cull_back}
Cull back removes the back or "inside" of a polygon from being drawn in
the world.
#### none {#none}
##### none {#cull_none}
Neither side of the polygon is removed. Both sides are drawn in the
game. Very useful for making panels or barriers that have no depth, such

36
Documentation/Materials/commands/deformvertexes.md → Documentation/Materials/SurfaceCommands/deformvertexes.md
View file

@ -1,10 +1,12 @@
# Materials: Commands {#mat_commands}
## deformvertexes
### Syntax
# Material Command List {#mat_commands}
### deformVertexes {#deformVertexes}
#### Syntax
**deformVertexes <func>**
### Overview
#### Overview
This command performs a general deformation on the surface's vertexes,
changing the actual shape of the surface before drawing the shader
@ -12,9 +14,9 @@ passes. You can stack multiple deformVertexes commands to modify
positions in more complex ways, making an object move in two dimensions,
for instance.
### Functions {#functions}
#### Functions
#### wave <siv> <func> <base> <amplitude> <phase> <freq> {#wave}
##### wave <siv> <func> <base> <amplitude> <phase> <freq>
Designed for water surfaces, modifying the values differently at each
point.
@ -26,7 +28,7 @@ The "div" parameter is used to control the wave "spread" - a value equal
to the [tessSize](vmap_tesssize.md) of the
surface is a good default value.
#### normal <siv> <func> <base> <amplitude> <frequency> {#normal_amplitude}
##### normal <siv> <func> <base> <amplitude> <frequency>
This deformation affects the normals of a vertex without actually moving
it, which will effect later material options like lighting and
@ -38,12 +40,12 @@ in any of their calculations, there will be no visible effect.
that have been done with it: A small fluttering bat, falling leaves,
rain, flags.
#### bulge <bulgeWidth> <bulgeHeight> <bulgeSpeed> {#bulge}
##### bulge <bulgeWidth> <bulgeHeight> <bulgeSpeed>
This forces a bulge to move along the given s and t directions. Designed
for use on curved pipes.
#### move <x> <y> <z> <func> <base> <amplitude> <phase> <freq> {#move}
##### move <x> <y> <z> <func> <base> <amplitude> <phase> <freq>
This keyword is used to make a brush, curve patch or model appear to
move together as a unit. The **x** **y** and **z** values are the
@ -66,7 +68,7 @@ actually change position, it only appears to.
materials, all must have matching deformVertexes move values or **the
object will appear to tear itself apart!**
#### autosprite {#autosprite}
##### autosprite
This function can be used to make any given triangle quad (pair of
triangles that form a square rectangle) automatically behave like a
@ -81,7 +83,7 @@ texture with this material keyword must be square.
**Design Note**: This is best used on objects that would appear the same
regardless of viewing angle. An example might be a glowing light flare.
#### autosprite2 {#autosprite2}
##### autosprite2
Is a slightly modified "sprite" that only rotates around the middle of
its longest axis.
@ -89,11 +91,11 @@ its longest axis.
This allows you to make a pillar of fire that you can walk around, or an
energy beam stretched across the room.
### Notes {#notes}
#### Notes
Specific parameter definitions for deform keywords:
#### <siv> {#section}
##### <siv>
This is roughly defined as the size of the waves that occur. It is
measured in game units. Smaller values create agreater density of
@ -106,7 +108,7 @@ A value of 100.0 is a good default value (which means your
[tessSize](vmap_tesssize.md) should be close
to that for things tolook "wavelike").
#### <func> {#section_1}
##### <func>
This is the type of wave form being created. **sin** stands for sine
wave, a regular smoothly flowing wave. **triangle** is a wave with a
@ -116,20 +118,20 @@ frequency with no in between. The **sawtooth** wave has the ascent of a
triangle wave, but has the decay cut off sharply like a square wave. An
**inversesawtooth** wave reverses this.
#### <base> {#section_2}
##### <base>
This is the distance, in game units that the apparent surface of the
texture is displaced from the actual surface of the brush as placed in
the editor. A positive value appears above the brush surface. A negative
value appears below the brush surface.
#### <amplitude> {#section_3}
##### <amplitude>
The distance that the deformation moves away from the base value. See
Wave Forms in the introduction for a description of amplitude. <phase>
SeeWave Forms in the introduction for a description of phase)
#### <frequency> {#section_4}
##### <frequency>
See Wave Forms in the introduction for a description of frequency)

16
Documentation/Materials/SurfaceCommands/diffusemap.md Normal file
View file

@ -0,0 +1,16 @@
# Material Command List {#mat_commands}
### diffuseMap {#diffuseMap}
#### Syntax
**diffuseMap <texturepath/texturename>**
#### Overview
Specifies the default texture asset to use on the diffuse/albedo pass of
the material. This is the base texture in most cases. Some special
materials used for special effects and the like might not have one.
However surfaces such as floors, walls etc. certainly do. It will affect
which texture is used to get color information from for lighting passes,
etc.

12
Documentation/Materials/commands/fogparms.md → Documentation/Materials/SurfaceCommands/fogparms.md
View file

@ -1,10 +1,12 @@
# Materials: Commands {#mat_commands}
## fogparms
### Syntax
# Material Command List {#mat_commands}
### fogParms {#fogParms}
#### Syntax
**fogParms <red value> <green value> <blue value> <distance to opaque>**
### Overview
#### Overview
**Note**: you must also specify "surfaceparm fog" to cause
[vmap](vmap.md) to identify the surfaces inside the volume.
@ -21,7 +23,7 @@ observer. By making the height of the fog brush shorter than the
distance to opaque, the apparent density of the fog can be reduced
(because it never reaches the depth at which full opacity occurs).
### Notes {#notes}
#### Notes {#notes}
- The fog volume can only have one surface visible (from outside the
fog).

10
Documentation/Materials/commands/fte_clutter.md → Documentation/Materials/SurfaceCommands/fte_clutter.md
View file

@ -1,11 +1,13 @@
# Materials: Commands {#mat_commands}
## fte_clutter
### Syntax
# Material Command List {#mat_commands}
### fte_clutter {#fte_clutter}
#### Syntax
**fte_clutter <model> <spacing> <scale min> <scale max> <z offset>
<angle min> <angle max>**
### Overview
#### Overview
Similar to [vmap_surfaceModel (vmap_surfacemodel.md), however
it'll place models at runtime. The density can be controlled via the

17
Documentation/Materials/SurfaceCommands/fullbrightmap.md Normal file
View file

@ -0,0 +1,17 @@
# Material Command List {#mat_commands}
### fullbrightMap {#fullbrightMap}
#### Syntax
**fullbrightMap <texturepath/texturename>**
#### Overview
The texture is essentially a fullbright overlay on top of the
diffuse/albedomap.
Not all [Shaders](Shaders.md) support them. In some, like the
[unlit](unlit.md) shader, the
[diffusemap](diffusemap.md) is always
fullbright.

10
Documentation/Materials/commands/nomipmaps.md → Documentation/Materials/SurfaceCommands/nomipmaps.md
View file

@ -1,10 +1,12 @@
# Materials: Commands {#mat_commands}
## nomipmaps
### Syntax
# Material Command List {#mat_commands}
### noMipmaps {#noMipmaps}
#### Syntax
**noMipmaps**
### Overview
#### Overview
This implies [noPicMip](nopicmip.md), but
also prevents the generation of any lower resolution mipmaps for use by

10
Documentation/Materials/commands/nopicmip.md → Documentation/Materials/SurfaceCommands/nopicmip.md
View file

@ -1,10 +1,12 @@
# Materials: Commands {#mat_commands}
## nopicmip
### Syntax
# Material Command List {#mat_commands}
### noPicMip {#noPicMip}
#### Syntax
**noPicMip**
### Overview
#### Overview
This causes the texture to ignore user-set values for the gl_picmip cvar
command. The image will always be high resolution. Example: Used to keep

19
Documentation/Materials/SurfaceCommands/normalmap.md Normal file
View file

@ -0,0 +1,19 @@
# Material Command List {#mat_commands}
### normalMap {#normalMap}
#### Syntax
**normalMap <texturepath/texturename>**
#### Overview
Specifies the default texture to use for any normalmap operations. This
depends heavily on which [GLSL program](Shaders) is used
inside the later stages. The dynamic lights will use this to determine
height information for light and shadows. So sometimes you want to skip
setting this.
#### Creating normal maps to use with this command {#creating_normal_maps_to_use_with_this_command}
Check out our [Normal mapping guide](Normal_mapping_guide).

10
Documentation/Materials/commands/polygonoffset.md → Documentation/Materials/SurfaceCommands/polygonoffset.md
View file

@ -1,10 +1,12 @@
# Materials: Commands {#mat_commands}
## polygonoffset
### Syntax
# Material Command List {#mat_commands}
### polygonOffset {#polygonOffset}
#### Syntax
**polygonOffset <value>**
### Overview
#### Overview
Surfaces rendered with the polygonOffset keyword are rendered slightly
off the polygon's surface. This is typically used for wall markings and

10
Documentation/Materials/commands/portal.md → Documentation/Materials/SurfaceCommands/portal.md
View file

@ -1,10 +1,12 @@
# Materials: Commands {#mat_commands}
## portal
### Syntax
# Material Command List {#mat_commands}
### portal {#mat_portal}
#### Syntax
**portal**
### Overview
#### Overview
Specifies that this texture is the surface for a portal or mirror. In
the game map, a portal entity must be placed directly in front of the

12
Documentation/Materials/SurfaceCommands/reflectcube.md Normal file
View file

@ -0,0 +1,12 @@
# Material Command List {#mat_commands}
### reflectCube {#reflectCube}
#### Syntax
**reflectCube <texturepath/cubemapname>**
#### Overview
Specifies which cubemap to use on this material. By default, the engine
will pass the nearest in-world cubemap instead.

17
Documentation/Materials/SurfaceCommands/reflectmask.md Normal file
View file

@ -0,0 +1,17 @@
# Material Command List {#mat_commands}
### reflectMask {#reflectMask}
#### Syntax
**reflectMask <texturepath/texturename>**
#### Overview
Defines a texture that specifies which parts of a material will reveal a
reflective material, such as a
[cubemap](reflectcube.md). This applies to
standard FTEQW. In Nuclide the reflectmask is currently unused with the
included shaders. If you want to apply reflectivity to your materials,
use the alpha channel of your
[normalmap](normalmap.md) instead.

11
Documentation/Materials/commands/skyparms.md → Documentation/Materials/SurfaceCommands/skyparms.md
View file

@ -1,6 +1,8 @@
# Materials: Commands {#mat_commands}
## skyparms
### Overview
# Material Command List {#mat_commands}
### skyParms {#skyParms}
#### Overview
**skyParms <farbox> <cloudheight> <nearbox>**
@ -30,7 +32,8 @@ clouds are mapped. Good ranges are 64 to 256. The default value is 128.
clouds. This has not be tested in a long time, so it probably doesn't
actually work. Set to "-" to ignore.
### Example Sky Material {#example_sky_material}
#### Example Sky Material {#example_sky_material}
```
   // Vera Visions Material
   {

12
Documentation/Materials/commands/sort.md → Documentation/Materials/SurfaceCommands/sort.md
View file

@ -1,10 +1,12 @@
# Materials: Commands {#mat_commands}
## sort
### Syntax
# Material Command List {#mat_commands}
### sort {#sort}
#### Syntax
**sort <value>**
### Overview
#### Overview
Use this keyword to fine-tune the depth sorting of materials as they are
compared against other materials in the game world. The basic concept is
@ -17,7 +19,7 @@ and all other materials in sort "opaque", so you only need to specify
this when you are trying to work around a sorting problem with multiple
transparent surfaces in a scene.
### Values {#values}
#### Values {#values}
The value here can be either a numerical value or one of the keywords in
the following list (listed in order of mostly ascending priority):

14
Documentation/Materials/SurfaceCommands/specularmap.md Normal file
View file

@ -0,0 +1,14 @@
# Material Command List {#mat_commands}
### specularMap {#specularMap}
#### Syntax
**specularMap <texturepath/texturename>**
#### Overview
Can set the specularity of the surface in relation to dlights.
Specularity is the intensity of the light reflecting off the surface. In
special cases some [GLSL programs](Shaders) might use the
texture it for other purposes, too.

114
Documentation/Materials/commands/surfaceparm.md → Documentation/Materials/SurfaceCommands/surfaceparm.md
View file

@ -1,6 +1,8 @@
# Materials: Commands {#mat_commands}
## surfaceparm
### Overview
# Material Command List {#mat_commands}
### surfaceparm {#surfaceparm}
#### Overview
The surfaceparm keyword is not only read by the VMAP compiler, but also
by the renderer. A few keywords will only apply to any one of them.
@ -12,12 +14,12 @@ follows:
surfaceparm **fog**
```
### Behaviour Keywords {#behaviour_keywords}
#### Behaviour Keywords {#behaviour_keywords}
Commands that affect core functionality of a surface, or could impact
the entire room or the gameplay surrounding it.
#### areaportal {#areaportal}
##### areaportal {#areaportal}
A brush marked with this keyword functions as an area portal, a break in
the VMAP tree. It is typically placed on a very thin brush placed inside
@ -27,7 +29,7 @@ door is closed. It is also used by the BSPC (bot area file creation
compiler) in the same manner as a clusterportal. The brush must touch
all the structural brushes surrounding the areaportal.
#### clusterportal {#clusterportal}
##### clusterportal {#clusterportal}
A brush marked with this keyword function creates a subdivision of the
area file (.aas) used by the bots for navigation. It is typically placed
@ -37,56 +39,56 @@ process the entire map at once. As with the the areaportal parameter,
the affected brush must touch all the structural brushes surrounding the
areaportal.
#### donotenter {#donotenter}
##### donotenter {#donotenter}
Read as "do not enter." Like clusterportal, this is a bot-only property.
A brush marked with donotenter will not affect non-bot players, but bots
will not enter it. It should be used only when bots appear to have
difficulty navigating around some map features.
#### lava {#lava}
##### lava {#lava}
Assigns to the texture the game properties set for lava. This affects
both the surface and the content of a brush.
#### nodamage {#nodamage}
##### nodamage {#nodamage}
The player takes no damage if he falls onto a texture with this
surfaceparm
#### nosteps {#nosteps}
##### nosteps {#nosteps}
The player makes no sound when walking on this texture.
#### nonsolid {#nonsolid}
##### nonsolid {#nonsolid}
This attribute indicates a brush, which does not block the movement of
entities in the game world. It applied to triggers, hint brushes and
similar brushes. This affects the content of a brush.
#### origin {#origin}
##### origin {#origin}
Used on the "origin" texture. Rotating entities need to contain an
origin brush in their construction. The brush must be rectangular (or
square). The origin point is the exact center of the origin brush.
#### playerclip {#playerclip}
##### playerclip {#playerclip}
Blocks player movement through a nonsolid texture. Other game world
entities can pass through a brush marked playerclip. The intended use
for this is to block the player but not block projectiles like rockets.
#### slick {#slick}
##### slick {#slick}
This surfaceparm included in a texture should give it significantly
reduced friction.
#### slime {#slime}
##### slime {#slime}
Assigns to the texture the game properties for slime. This affects both
the surface and the content of a brush.
#### structural {#structural}
##### structural {#structural}
This surface attribute causes a brush to be seen by the VMAP process as
a possible break-point in a BSP tree. It is used as a part of the
@ -94,63 +96,63 @@ material for the "hint" texture. Generally speaking, any opaque texture
not marked as "detail" is, by default, structural, so you shouldn't need
to specify this.
#### water {#water}
##### water {#water}
Assigns to the texture the game properties for water.
#### climb {#climb}
##### climb {#climb}
Marks the desired surface as a climbable surface. This currently affects
the entire volume.
#### vehicleclip {#vehicleclip}
##### vehicleclip {#vehicleclip}
Blocks all movement of vehicle entities through this surface.
#### leakssteam {#leakssteam}
##### leakssteam {#leakssteam}
When this surface is impacted, steam will leak out temporarily. Specific
to The Wastes 1.3.
#### leakswater {#leakswater}
##### leakswater {#leakswater}
When this surface is impacted, water will leak out temporarily. Specific
to The Wastes 1.3.
#### fl_r1 {#fl_r1}
##### fl_r1 {#fl_r1}
Reserved for custom games. This can be anything.
#### fl_r2 {#fl_r2}
##### fl_r2 {#fl_r2}
Reserved for custom games. This can be anything.
#### fl_r3 {#fl_r3}
##### fl_r3 {#fl_r3}
Reserved for custom games. This can be anything.
#### fl_r4 {#fl_r4}
##### fl_r4 {#fl_r4}
Reserved for custom games. This can be anything.
#### fl_r5 {#fl_r5}
##### fl_r5 {#fl_r5}
Reserved for custom games. This can be anything.
#### fl_r6 {#fl_r6}
##### fl_r6 {#fl_r6}
Reserved for custom games. This can be anything.
#### fl_r7 {#fl_r7}
##### fl_r7 {#fl_r7}
Reserved for custom games. This can be anything.
### Rendering Keywords {#rendering_keywords}
#### Rendering Keywords {#rendering_keywords}
Commands that affect rendering of a surface, or the how surfaces are
made to look by the compiler. These do not affect gameplay function.
#### alphashadow {#alphashadow}
##### alphashadow {#alphashadow}
This keyword applied to a texture on a brush, patch or model will cause
the lighting phase of the VMAP process to use the texture's alpha
@ -161,14 +163,14 @@ texture. Fine lines may not cast acceptable shadows. It appears to work
best with well-defined silhouettes and wider lines within the texture.
Most of our tattered banners use this to cast tattered shadows.
#### fog {#fog}
##### fog {#fog}
Fog defines the brush as being a "fog" brush. This is a VMAP function
that chops and identifies all geometry inside the brush. The General
material keyword fogparms must also be specified to tell how to draw the
fog.
#### lightfilter {#lightfilter}
##### lightfilter {#lightfilter}
Causes the VMAP light stage to use the texture's RGB and alpha channels
to generate colored alpha shadows in the lightmap. For example, this can
@ -176,33 +178,33 @@ be used to create the colored light effect cast by stained glass
windows. This can be used with surfaceparm alphashadow if an alpha is to
be respected.
#### nodlight {#nodlight}
##### nodlight {#nodlight}
Read as "No DeeLight". A texture containing this parameter will not be
affected or lit by dynamic lights, such as weapon effects. The VMAP
compiler doesn't really care about this, but the renderer does.
#### nodraw {#nodraw}
##### nodraw {#nodraw}
A texture marked with nodraw will not visually appear in the game world.
Most often used for triggers, clip brushes, origin brushes, and so on.
Light will pass through it, therefore beware of bleeding issues when
using nodraw/caulk textures with this.
#### nodraw2 {#nodraw2}
##### nodraw2 {#nodraw2}
Same as nodraw, but the engine won't draw it, whereas the VMAP compiler
will react to the surface. So unlike nodraw, light will not pass through
these surfaces.
#### noimpact {#noimpact}
##### noimpact {#noimpact}
World entities will not impact on this texture. No explosions occur when
projectiles strike this surface and no marks will be left on it. Sky
textures are usually marked with this texture so those projectiles will
not hit the sky and leave marks.
#### nomarks {#nomarks}
##### nomarks {#nomarks}
Projectiles will explode upon contact with this surface, but will not
leave marks. Blood will also not mark this surface. This is useful to
@ -212,85 +214,85 @@ Blob shadows (aka **r_shadows 1**) also counts as a mark. So any surface
that you don't want to see affected by shadows should receive this
surfaceparm.
#### nolightmap {#nolightmap}
##### nolightmap {#nolightmap}
This texture does not have a lightmap phase. It is not affected by the
ambient lighting of the world around it. It does not require the
addition of an rgbGen identity keyword in that stage.
#### trans {#trans}
##### trans {#trans}
Light will pass through this surface, but only if either alphashadow or
lightfilter are applied. Tells VMAP that pre-computed visibility should
not be blocked by this surface. Generally, any materials that have
blendfuncs should be marked as surfaceparm trans.
### Material Related Keywords {#material_related_keywords}
#### Material Related Keywords {#material_related_keywords}
Specifies which impact effects and footstep sounds are played when
interacting with a given surface. Only one of them can be given at once:
#### alien {#alien}
##### alien {#alien}
Defines that the surface is of an 'alien' material. Affects impact sound
and effects.
#### flesh {#flesh}
##### flesh {#flesh}
Defines that the surface is of flesh. Affects impact sound and effects.
#### foliage {#foliage}
##### foliage {#foliage}
Defines that the surface is foliage. Affects impact sound and effects.
#### computer {#computer}
##### computer {#computer}
Defines that the surface is of computer parts. Affects impact sound and
effects.
#### dirt {#dirt}
##### dirt {#dirt}
Defines that the surface is of dirt. Affects impact sound and effects.
#### vent {#vent}
##### vent {#vent}
Defines that the surface is a vent. Affects impact sound and effects.
#### grate {#grate}
##### grate {#grate}
Defines that the surface is a grate. Affects impact sound and effects.
#### metal {#metal}
##### metal {#metal}
Defines that the surface is of metal. Affects impact sound and effects.
#### glass {#glass}
##### glass {#glass}
Defines that the surface is of glass. Affects impact sound and effects.
#### sand {#sand}
##### sand {#sand}
Defines that the surface is of sand. Affects impact sound and effects.
#### slosh {#slosh}
##### slosh {#slosh}
Defines that the surface is of a liquid. Affects impact sound and
effects.
#### snow {#snow}
##### snow {#snow}
Defines that the surface is of snow. Affects impact sound and effects.
#### tile {#tile}
##### tile {#tile}
Defines that the surface is of kitchen/bathroom tiles. Affects impact
sound and effects.
#### wood {#wood}
##### wood {#wood}
Defines that the surface is of wood. Affects impact sound and effects.
#### concrete {#concrete}
##### concrete {#concrete}
Defines that the surface is of concrete. Affects impact sound and
effects.
effects.

10
Documentation/Materials/commands/vmap_backmaterial.md → Documentation/Materials/ToolCommands/vmap_backmaterial.md
View file

@ -1,10 +1,12 @@
# Materials: VMap Commands {#mat_vmap}
## vmap_backmaterial
### Syntax
# Material Command List {#mat_commands}
### vmap_backmaterial
#### Syntax
**vmap_backMaterial <material>**
### Overview
#### Overview
This allows a brush surface to use a different material when you are
inside it looking out.

9
Documentation/Materials/commands/vmap_backsplash.md → Documentation/Materials/ToolCommands/vmap_backsplash.md
View file

@ -1,10 +1,11 @@
# Materials: VMap Commands {#mat_vmap}
## vmap_backsplash
### Syntax
# Material Command List {#mat_commands}
### vmap_backsplash
#### Syntax
**vmap_backsplash <percent> <distance>**
### Overview
#### Overview
Controls the percentage of [surface
light](vmap_surfaceLight) backsplash (how

9
Documentation/Materials/commands/vmap_basematerial.md → Documentation/Materials/ToolCommands/vmap_basematerial.md
View file

@ -1,10 +1,11 @@
# Materials: VMap Commands {#mat_vmap}
## vmap_basematerial
### Syntax
# Material Command List {#mat_commands}
### vmap_basematerial
#### Syntax
**vmap_baseMaterial <material>**
### Overview
#### Overview
Copies the vmap_/surfaceparm commands from the specified material into
this one.

9
Documentation/Materials/commands/vmap_bounce.md → Documentation/Materials/ToolCommands/vmap_bounce.md
View file

@ -1,10 +1,11 @@
# Materials: VMap Commands {#mat_vmap}
## vmap_bounce
### Syntax
# Material Command List {#mat_commands}
### vmap_bounce
#### Syntax
**vmap_bounce <scale>**
### Overview
#### Overview
Specifies the fraction of light to re-emit during a bounce pass on this
surface.

9
Documentation/Materials/commands/vmap_clonematerial.md → Documentation/Materials/ToolCommands/vmap_clonematerial.md
View file

@ -1,10 +1,11 @@
# Materials: VMap Commands {#mat_vmap}
## vmap_clonematerial
### Syntax
# Material Command List {#mat_commands}
### vmap_clonematerial
#### Syntax
**vmap_cloneMaterial <material>**
### Overview
#### Overview
A material with this directive will inherit the target material's
properties and appearance. **Be careful, this can lead to an infinite

9
Documentation/Materials/commands/vmap_invert.md → Documentation/Materials/ToolCommands/vmap_invert.md
View file

@ -1,10 +1,11 @@
# Materials: VMap Commands {#mat_vmap}
## vmap_invert
### Syntax
# Material Command List {#mat_commands}
### vmap_invert
#### Syntax
**vmap_invert**
### Overview
#### Overview
Inverts a surface normal. Works on brush faces, models and patches. Used
in celshading to achieve the inverted backfacing hull.

9
Documentation/Materials/commands/vmap_lightimage.md → Documentation/Materials/ToolCommands/vmap_lightimage.md
View file

@ -1,10 +1,11 @@
# Materials: VMap Commands {#mat_vmap}
## vmap_lightimage
### Syntax
# Material Command List {#mat_commands}
### vmap_lightimage
#### Syntax
**vmap_lightImage <texturepath>**
### Overview
#### Overview
By default, surface lights use the average color of the source image to
generate the color of the light. vmap_lightImage specifies an alternate

9
Documentation/Materials/commands/vmap_lightmapfilterradius.md → Documentation/Materials/ToolCommands/vmap_lightmapfilterradius.md
View file

@ -1,11 +1,12 @@
# Materials: VMap Commands {#mat_vmap}
## vmap_lightmapfilterradius
### Syntax
# Material Command List {#mat_commands}
### vmap_lightmapfilterradius
#### Syntax
**vmap_lightmapFilterRadius <lightmap filter radius>
<light filter radius>**
### Overview
#### Overview
This is usually used on [light emitting
materials](vmap_surfaceLight) to

9
Documentation/Materials/commands/vmap_lightmapmergable.md → Documentation/Materials/ToolCommands/vmap_lightmapmergable.md
View file

@ -1,10 +1,11 @@
# Materials: VMap Commands {#mat_vmap}
## vmap_lightmapmergable
### Syntax
# Material Command List {#mat_commands}
### vmap_lightmapmergable
#### Syntax
**vmap_lightmapMergable**
### Overview
#### Overview
When specified, the compiler will attempt to merge all surfaces using
this material together onto lightmap sheets. This can drastically reduce

9
Documentation/Materials/commands/vmap_lightmapsampleoffset.md → Documentation/Materials/ToolCommands/vmap_lightmapsampleoffset.md
View file

@ -1,10 +1,11 @@
# Materials: VMap Commands {#mat_vmap}
## vmap_lightmapsampleoffset
### Syntax
# Material Command List {#mat_commands}
### vmap_lightmapsampleoffset
#### Syntax
**vmap_lightmapSampleOffset <float>**
### Overview
#### Overview
Takes a single parameter, defaulting to 1.0, which specifies how many
units off a surface should the compiler sample lighting from. Use larger

9
Documentation/Materials/commands/vmap_lightmapsamplesize.md → Documentation/Materials/ToolCommands/vmap_lightmapsamplesize.md
View file

@ -1,10 +1,11 @@
# Materials: VMap Commands {#mat_vmap}
## vmap_lightmapsamplesize
### Syntax
# Material Command List {#mat_commands}
### vmap_lightmapsamplesize
#### Syntax
**vmap_lightmapSampleSize <int>**
### Overview
#### Overview
Surfaces using a material with this option will have the pixel size of
the lightmaps set to N world grid units. This option can be used to

9
Documentation/Materials/commands/vmap_lightrgb.md → Documentation/Materials/ToolCommands/vmap_lightrgb.md
View file

@ -1,10 +1,11 @@
# Materials: VMap Commands {#mat_vmap}
## vmap_lightrgb
### Syntax
# Material Command List {#mat_commands}
### vmap_lightrgb
#### Syntax
**vmap_lightRGB <red color> <green color> <blue color>**
### Overview
#### Overview
Alternative to [vmap_lightImage (Material
Command)](vmap_lightImage) and the

9
Documentation/Materials/commands/vmap_lightsubdivide.md → Documentation/Materials/ToolCommands/vmap_lightsubdivide.md
View file

@ -1,10 +1,11 @@
# Materials: VMap Commands {#mat_vmap}
## vmap_lightsubdivide
### Syntax
# Material Command List {#mat_commands}
### vmap_lightsubdivide
#### Syntax
**q3map_lightSubdivide <units>**
### Overview
#### Overview
Used on surface lights (see [vmap_surfaceLight (Material
Command)](vmap_surfaceLight)). Controls

9
Documentation/Materials/commands/vmap_nodirty.md → Documentation/Materials/ToolCommands/vmap_nodirty.md
View file

@ -1,10 +1,11 @@
# Materials: VMap Commands {#mat_vmap}
## vmap_nodirty
### Syntax
# Material Command List {#mat_commands}
### vmap_nodirty
#### Syntax
**vmap_nodirty**
### Overview
#### Overview
This surface is not affected by dirt-mapping. The compiler baked variant
of ambient occlusion.

9
Documentation/Materials/commands/vmap_offset.md → Documentation/Materials/ToolCommands/vmap_offset.md
View file

@ -1,10 +1,11 @@
# Materials: VMap Commands {#mat_vmap}
## vmap_offset
### Syntax
# Material Command List {#mat_commands}
### vmap_offset
#### Syntax
**vmap_offset <float>**
### Overview
#### Overview
Offsets a surface along the vertex normals by N.N units. Used in
celshading for those black edges. This is the sort-of the compiler

9
Documentation/Materials/commands/vmap_remapmaterial.md → Documentation/Materials/ToolCommands/vmap_remapmaterial.md
View file

@ -1,10 +1,11 @@
# Materials: VMap Commands {#mat_vmap}
## vmap_remapmaterial
### Syntax
# Material Command List {#mat_commands}
### vmap_remapmaterial
#### Syntax
**vmap_remapMaterial <material>**
### Overview
#### Overview
Allows the material to later become known as the specified material.

9
Documentation/Materials/commands/vmap_shadeangle.md → Documentation/Materials/ToolCommands/vmap_shadeangle.md
View file

@ -1,10 +1,11 @@
# Materials: VMap Commands {#mat_vmap}
## vmap_shadeangle
### Syntax
# Material Command List {#mat_commands}
### vmap_shadeangle
#### Syntax
**vmap_shadeAngle <degrees>**
### Overview
#### Overview
In short: At which angle the phong shading on a material breaks. If you
set it to 0, basically no phong shading will ever be performed. The

9
Documentation/Materials/commands/vmap_surfacelight.md → Documentation/Materials/ToolCommands/vmap_surfacelight.md
View file

@ -1,10 +1,11 @@
# Materials: VMap Commands {#mat_vmap}
## vmap_surfacelight
### Syntax
# Material Command List {#mat_commands}
### vmap_surfacelight
#### Syntax
**vmap_surfacelight <intensity>**
### Overview
#### Overview
The texture gives off light equal to the value set for it. The relative
surface area of the texture in the world affects the actual amount of

9
Documentation/Materials/commands/vmap_surfacelightdistance.md → Documentation/Materials/ToolCommands/vmap_surfacelightdistance.md
View file

@ -1,10 +1,11 @@
# Materials: VMap Commands {#mat_vmap}
## vmap_surfacelightdistance
### Syntax
# Material Command List {#mat_commands}
### vmap_surfacelightdistance
#### Syntax
**vmap_surfaceLightDistance <scale>**
### Overview
#### Overview
Increases the range of a surfacelight. This is different from increasing
the [vmap_surfaceLight (Material

9
Documentation/Materials/commands/vmap_surfacemodel.md → Documentation/Materials/ToolCommands/vmap_surfacemodel.md
View file

@ -1,11 +1,12 @@
# Materials: VMap Commands {#mat_vmap}
## vmap_surfacemodel
### Syntax
# Material Command List {#mat_commands}
### vmap_surfacemodel
#### Syntax
**vmap_surfaceModel <modelpath> <density> <odds> <minscale> <maxscale>
<minangle> <maxangle> <oriented>**
### Overview
#### Overview
A surface with vmap_surfaceModel in its shader will randomly place a
specified model across it's face. This is designed to place grass or

11
Documentation/Materials/commands/vmap_tesssize.md → Documentation/Materials/ToolCommands/vmap_tesssize.md
View file

@ -1,10 +1,11 @@
# Materials: Compiler Commands {#mat_vmap}
## vmap_tesssize
### Syntax
# Material Command List {#mat_commands}
### vmap_tesssize
#### Syntax
**vmap_tessSize <amount>**
### Overview
#### Overview
Formely known as just **tessSize**.
@ -18,7 +19,7 @@ only used on surfaces that are flagged with the
Abuse of this can create a huge number of triangles. This happens during
BSP processing, so maps must be reprocessed for changes to take effect.
### Note {#note}
#### Note {#note}
It can also be used on tesselating surfaces to make sure that
tesselations are large, and thus, less costly in terms of triangles

24
Documentation/Materials/commands/diffusemap.md
View file

@ -1,24 +0,0 @@
# Materials: Commands {#mat_commands}
## diffusemap
### Syntax
**diffusemap <texturepath/texturename>**
### Overview
Specifies the default texture asset to use on the diffuse/albedo pass of
the material. This is the base texture in most cases. Some special
materials used for special effects and the like might not have one.
However surfaces such as floors, walls etc. certainly do. It will affect
which texture is used to get color information from for lighting passes,
etc.
### See also {#see_also}
- [normalmap](Documentation/Materials/commands/normalmap.md)
- [specularmap](Documentation/Materials/commands/specularmap.md)
- [fullbrightmap](Documentation/Materials/commands/fullbrightmap.md)
- [uppermap](Documentation/Materials/commands/uppermap.md)
- [lowermap](Documentation/Materials/commands/lowermap.md)
- [reflectmask](Documentation/Materials/commands/reflectmask.md)
- [reflectcube](Documentation/Materials/commands/reflectcube.md)

25
Documentation/Materials/commands/fullbrightmap.md
View file

@ -1,25 +0,0 @@
# Materials: Commands {#mat_commands}
## fullbrightmap
### Syntax
**fullbrightmap <texturepath/texturename>**
### Overview
The texture is essentially a fullbright overlay on top of the
diffuse/albedomap.
Not all [Shaders](Shaders.md) support them. In some, like the
[unlit](unlit.md) shader, the
[diffusemap](diffusemap.md) is always
fullbright.
### See also {#see_also}
- [diffusemap](diffusemap.md)
- [normalmap](normalmap.md)
- [specularmap](specularmap.md)
- [uppermap](uppermap.md)
- [lowermap](lowermap.md)
- [reflectmask](reflectmask.md)
- [reflectcube](reflectcube.md)

27
Documentation/Materials/commands/normalmap.md
View file

@ -1,27 +0,0 @@
# Materials: Commands {#mat_commands}
## normalmap
### Syntax
**normalmap <texturepath/texturename>**
### Overview
Specifies the default texture to use for any normalmap operations. This
depends heavily on which [GLSL program](Shaders) is used
inside the later stages. The dynamic lights will use this to determine
height information for light and shadows. So sometimes you want to skip
setting this.
### Creating normal maps to use with this command {#creating_normal_maps_to_use_with_this_command}
Check out our [Normal mapping guide](Normal_mapping_guide).
### See also {#see_also}
- [diffusemap](diffusemap.md)
- [specularmap](specularmap.md)
- [fullbrightmap](fullbrightmap.md)
- [uppermap](uppermap.md)
- [lowermap](lowermap.md)
- [reflectmask](reflectmask.md)
- [reflectcube](reflectcube.md)

20
Documentation/Materials/commands/reflectcube.md
View file

@ -1,20 +0,0 @@
# Materials: Commands {#mat_commands}
## reflectcube
### Syntax
**reflectcube <texturepath/cubemapname>**
### Overview
Specifies which cubemap to use on this material. By default, the engine
will pass the nearest in-world cubemap instead.
### See also {#see_also}
- [diffusemap](diffusemap.md)
- [normalmap](normalmap.md)
- [specularmap](specularmap.md)
- [fullbrightmap](fullbrightmap.md)
- [uppermap](uppermap.md)
- [lowermap](lowermap.md)
- [reflectmask](reflectmask.md)

25
Documentation/Materials/commands/reflectmask.md
View file

@ -1,25 +0,0 @@
# Materials: Commands {#mat_commands}
## reflectmask
### Syntax
**reflectmask <texturepath/texturename>**
### Overview
Defines a texture that specifies which parts of a material will reveal a
reflective material, such as a
[cubemap](reflectcube.md). This applies to
standard FTEQW. In Nuclide the reflectmask is currently unused with the
included shaders. If you want to apply reflectivity to your materials,
use the alpha channel of your
[normalmap](normalmap.md) instead.
### See also {#see_also}
- [diffusemap](diffusemap.md)
- [normalmap](normalmap.md)
- [specularmap](specularmap.md)
- [fullbrightmap](fullbrightmap.md)
- [uppermap](uppermap.md)
- [lowermap](lowermap.md)
- [reflectcube](reflectcube.md)

22
Documentation/Materials/commands/specularmap.md
View file

@ -1,22 +0,0 @@
# Materials: Commands {#mat_commands}
## specularmap
### Syntax
**specularmap <texturepath/texturename>**
### Overview
Can set the specularity of the surface in relation to dlights.
Specularity is the intensity of the light reflecting off the surface. In
special cases some [GLSL programs](Shaders) might use the
texture it for other purposes, too.
### See also {#see_also}
- [diffusemap](diffusemap.md)
- [normalmap](normalmap.md)
- [fullbrightmap](fullbrightmap.md)
- [uppermap](uppermap.md)
- [lowermap](lowermap.md)
- [reflectmask](reflectmask.md)
- [reflectcube](reflectcube.md)

30
Documentation/Models.md Normal file
View file

@ -0,0 +1,30 @@
# Model Importing {#models}
The engine handles all the file formats related to model files.
Table of supported model formats:
| File Extension | Type | Description |
|----------------|------|-------------|
| mdl | Animated, Vertex | Quake 'Alias' Model |
| md2 | Animated, Vertex | Quake II Model |
| md3 | Animated, Vertex | Quake III Arena Model |
| mdl | Animated, Skeletal | Half-Life Model |
| iqm | Animated, Skeletal | Inter Quake Model |
| vvm | Animated, Skeletal | Vera Visions Model |
| psk | Animated, Skeletal | Unreal Engine Model |
| zym | Animated, Skeletal | Zymotic Models |
| dpm | Animated, Skeletal | Darkplaces Model |
| gltf | Animated, Skeletal | ??? |
| glb | Animated, Skeletal | ??? |
| spr | Sprite | Quake I variant, Global Palette |
| spr2 | Sprite | Quake II |
| obj | Static | Wavefront OBJ |
| lwo | Static | Lightwave Object |
| ase | Static | Alias Static ??? |
Formats available in plugin-form:
| File Extension | Type | Description |
|----------------|------|-------------|
| mdl | Animated, Skeletal | Source Engine Model |

13
Documentation/Models/VVM.md
View file

@ -1,8 +1,11 @@
# Models: VVM
# Model Importing {#models}
## Vera Visions Models (VVM) {#vvm}
**Vera Visions Model**, also known as **VVM** or **IQM-FTE** is the main
skeletal model format.
## Features {#features}
### Features {#vvm_features}
Features that the original IQM exporter (by Lee Salzman) did not offer:
@ -36,7 +39,7 @@ It also has a re-engineered exporter that takes control files as input,
rather than a giant command-line string. This was done because some
models have hundreds of model parameters in The Wastes.
## History {#history}
### History {#vvm_history}
In 2016 when we had our first prototype of The Wastes, we started out
using DPM for tool-chain related reasons and quickly migrated to IQM.
@ -63,7 +66,7 @@ exposed to the game-logic.
However, the initial extensions to the IQM format in FTE were designed
by us; and this is the exporter that was used to make our game.
## Viewing VVM Models {#viewing_vvm_models}
### Previewing Models {#vvm_viewing}
You can grab a binary build of FTE [1](https://www.fteqw.org/)
(basically a generic, non The Wastes specific version) and use the
@ -73,6 +76,6 @@ Shift+ESC.
If you want to see for example the Winston viewmodel, type *modelviewer
models/weapons/v_winchester.vvm*
## External links {#external_links}
### External links {#vvm_links}
[vvmtool on GitHub](https://github.com/VeraVisions/vvmtool)

19
Documentation/Models/VVM_Tutorial.md
View file

@ -1,5 +1,8 @@
# Models: VVM Tutorial
## Introduction {#introduction}
# Model Importing {#models}
## Tutorial: SMD to VVM {#vvmtut}
### Introduction {#vvmtut_intro}
As you already know, the VVM exporter (vvmtool) takes inspiration from
Valve's **studiomdl** in terms of usage. There are *slight* syntax
@ -9,7 +12,7 @@ differ **drastically**.
For example, **model events** can be stacked and applied to many
animation sequences at once. *There is no way to do so with studiomdl.*
## Input files {#input_files}
### Input files {#vvmtut_input}
Any .vvm consists of multiple input files. These can come in the
following formats:
@ -23,7 +26,7 @@ following formats:
Make sure that when you use animated files, that the bone naming and
bone order is consistent among them.
## Control File {#control_file}
### Control File {#vvmtut_qc}
This file is the head of the format. It specifies how the input files
are loaded in, with additional useful commands on how to manipulate the
@ -117,7 +120,7 @@ upon importing.
`scene` Tells it to load one input file, which is a reference. If it was
an animation it'd specify a framerate via the 'fps X' parameter.
## Compiling {#compiling}
### Compiling {#vvmtut_compiling}
You grab your copy of **vvmtool** and you either drag
and drop your control file onto it, or run it via command-line:
@ -126,11 +129,11 @@ and drop your control file onto it, or run it via command-line:
It should be as simple as that!
## Notes {#notes}
### Notes {#vvmtut_notes}
Some helpful tips for your content creation journey.
### vid_reload {#vid_reload}
#### vid_reload {#vvmtut_reload}
I recommend getting a single reference, plus the animations into your
game first, then adding events and other necessary commands on top.
@ -139,7 +142,7 @@ You can use the console command `vid_reload` to force the engine to
flush the model/texture cache and to reload an updated model from disk.
Really useful when iterating over model exports.
### Blender users {#blender_users}
#### Blender users {#vvmtut_blender}
If you're using the Blender Source Model tools, as of 2021, it still
doesn't down-mix certain animation features into the .smd format.

4
Documentation/Modules.md Normal file
View file

@ -0,0 +1,4 @@
# Modules {#modules}
We offer multiple sub modules the game-logic can load/unload at runtime.
They compliment the server game and are generally optional.

12
Documentation/Modules/.gwdir Normal file
View file

@ -0,0 +1,12 @@
{
"fsn_info_type" = <*I0>;
geometry = "1172 64 600 660 0 0 1920 1080 ";
lastselection = (
"/4TB/VCS/Nuclide-SDK/Documentation/Modules"
);
shelfdicts = (
);
shelfheight = <*R77>;
singlenode = <*BN>;
viewtype = Browser;
}

81
Documentation/Modules/AddonC.md Normal file
View file

@ -0,0 +1,81 @@
# Modules {#modules}
## AddonC
AddonC is the server side module architecture offered by Nuclide. It is inspired by efforts such as [MetaMod](http://metamod.org/).
### Usage
If the file `<game dir>/plugins.txt` exists, it is loaded into memory. It contains a sorted list of QuakeC progs. The order in which the .dat names are listed, also decides the load order:
```
banner
chatfilter
chatsounds
connectsounds
ircbridge
```
Each entry will result in Nuclide attempting to look for `<gamedir>/Addon_<name>.dat`. So `banner` in the list will resolve to `<gamedir>/Addon_banner.dat`.
The first entry takes priority over the ones listed below it.
### Callback List
Here is a list of callbacks your plugin can implement in its source code:
#### bool Addon_Load(void)
Called when the plugin is loaded. Can happen on initialisation, reload and so on.
#### void Addon_UnLoad(void)
Called when the plugin is being unloaded from memory. The chance for the plugin to remove anything it allocated that needs to be removed.
#### void Addon_Pause(void)
Called when plugin operation is halted.
#### void Addon_UnPause(void)
Called when plugin operation is resumed.
#### void Addon_LevelInit(string levelName)
Called upon level init, before entities are allowed to spawn.
#### void Addon_ServerActivate(void)
Called when the level has initialized the level fully. Entities are now able to spawn from here.
#### void Addon_GameFrame(void)
Called every frame on the server. As often as dictated by the server tic rate.
#### void Addon_LevelShutdown(void)
Called when the current level is being unloaded. This can happen during level transitions also.
#### bool Addon_ClientConnect(entity clientEntity)
Called when a client starts connecting to the current game session.
#### void Addon_ClientPutInServer(entity clientEntity)
Called when a client is being spawned into the game.
#### void Addon_ClientActive(entity clientEntity)
Called when a client is fully finished joining the current game session, after the game rules had a chance to work on the player.
#### void Addon_ClientDisconnect(entity clientEntity)
Called when the client disconnects from the server.
#### void Addon_ClientCommand(entity clientEntity, string commandString)
Called when the client enters a command into his console, which is then forwarded to the server. Gives the plugin to evaluate chat commands and more.
### Examples
The Nuclide source tree has some examples under `src/plugins/` if you need some tested, reference examples of AddonC.

16
Documentation/MapC.md → Documentation/Modules/MapC.md
View file

@ -1,4 +1,6 @@
# MapC Scripting
# Modules {#modules}
## MapC Scripting
**Notice: This is an uncomitted document and is subject to change.**
@ -9,7 +11,7 @@ Ritual's ÜberTools for Quake III also had a scripting system for each map, this
If you're curious about use-cases, you should make yourself familar with what those games do.
## MapC versus QuakeC
### MapC versus QuakeC
MapC is basically a superset of QuakeC.
You essentially write valid SSQC, but there's extra helper functions that you can use to communicate with entities from the server-side progs. Concepts that are alien to regular QuakeC code.
@ -47,7 +49,7 @@ You can compile the MapC file with fteqcc (`fteqcc mapscript.mapC`) to receive `
Like with regular QuakeC progs, you only have to include the resulting .dat with your game - although we encourage you to release the sources to all progs for modders and tinkerers to enjoy. It's also a way for users to support the game themselves in case you're no longer able to support it.
## Use cases, benefits
### Use cases, benefits
When it comes to managing the complexity of events in games like the Call of Duty series, this is a desired substitute to hundreds (sometimes thousands) of entities.
@ -55,19 +57,19 @@ Boxing the map-specific logic also aids portability. With less dependence on Nuc
The design has been proven across dozens of games within the Call of Duty series, with little to no changes - serving for both single and multiplayer logic. Managing waves of enemies, or writing entire game-modes using this type of set-up has been proven.
## Extra features over Vanilla SSQC
### Extra features over Vanilla SSQC
These extra functions are available to MapC programs:
### spawnClass(className, desiredPos)
#### spawnClass(className, desiredPos)
Spawns the specified entity class name at the desired position. If the classname does not exist, it will return a new info_notnull type entity with no model or collision for you to modify.
### sendInput(targetEntity, inputName, dataString, targetActivator)
#### sendInput(targetEntity, inputName, dataString, targetActivator)
Sends an input event to an NSEntity and with a specific activator. While that can be __NULL__, this, or world most of the time - some inputs very much depend on the activator being valid within their respective contexts.
## Map-specific entities
### Map-specific entities
You can bundle an [EntityDef](EntityDef.md) file with your level, like with MapC progs they have to have the same filename as the map, but with the extension ending in '**def**' (e.g. `maps/mapscript.def`).

3
Documentation/Multiplayer.md Normal file
View file

@ -0,0 +1,3 @@
# Multiplayer Systems {#mp}
Here you will find integral multiplayer subsystems documented.

43
Documentation/Multiplayer/Punkbusting.md Normal file
View file

@ -0,0 +1,43 @@
# Multiplayer Systems {#mp}
## Punkbusting (Cheaters Lament) System {#lament}
### Preface
Cheating in games is a difficult problem to tackle, as those measures have gotten more sophisticated over the years.
It is now common to deploy more invasive techniques, even going down into the kernel level. It is our belief that automated systems won't work on any scale and that the only reliable mechanism is informing players as to what is going on.
Our proposed solution is dubbed **Cheaters Lament**.
### Analysis of Automated Solutions
Automated systems have, much like humans, high rates of error. Calibration is a necessary, ongoing duty for the vendor. Automated systems have to constantly adjust the changing methods and strategies of detecting unfair behaviour.
Automated systems are judge, jury and executioner. Which means if they misjudge, it hurts players that are innocent, and will make those individuals very unhappy.
And in some games, some players are not given enough tools to make a confident decision. Often automated systems don't detect new, or non-obvious cheats.
### Our Proposal
**Cheaters Lament** is a passive warning system collecting movement information about a player and testing it against their movement tracking capability.
If someone has an insanely rating it will trigger a warning to the console. This system can be elevated so it will notify other players of said warning. Players can then leverage the built-in [voting](@ref voting) system to make a democratic decision over the fate of the player.
### Our Implementation
We accumulate the camera angle deltas over time, tracking the average mouse movement intensity over a short period of time. Waiting a full second will remove a full 360 degrees of delta.
We also accumulate accuracy information by increasing a counter whenever the player is actively firing, while also aiming at an opposing player with a radius of less than 10 degrees (to compensate for projectiles). Whenever the player we're tracking is firing, and not aiming with that consistent level of precision, we decrease the counter.
If the deltas are both very high, that must mean that the player is having frantic mouse movements, coupled with insanely high accuracy.
### Limitations
The system can totally misfire, especially in high latency environments where we cannot get enough movement samples.
Since the system is passive and won't act on its own, it doesn't really have any negative consequences if it does fire a warning.
It is calibrated against a demo of someone most likely cheating in the videogame **Quake**. It might need to be recalibrated to be useful in other types of games.
Currently there is no easy way to calibrate it, or to turn it off.

22
Documentation/Multiplayer/RCon.md Normal file
View file

@ -0,0 +1,22 @@
# Multiplayer Systems {#mp}
## Remote Administration (RCon) System {#rcon}
Not a Nuclide specific feature, but you can make use of **rcon** to control a game-server from within a client or a third-party **rcon** utility.
### Console Variables
#### rcon_password [string]
Sets the **rcon** password to the given string.
#### rcon_address
When empty, will send **rcon** commands to the current server.
Otherwise, commands issued with [rcon](@ref rcon_cmd)
### Console Commands
#### rcon [...] {#rcon_cmd}
Executes a command as the server. Only possible when rcon_password is set to the same value on client & server console.

31
Documentation/Multiplayer/Voting.md Normal file
View file

@ -0,0 +1,31 @@
# Multiplayer Systems {#mp}
## Voting System {#voting}
When the console variable `mp_allowvote` is set to 1, players are allowed access to the `callvote` command.
They have access to the following subcommands:
### callvote map [mapname]
Will request a map change to the proposed map. Will alert when the map does not exist on the server.
### callvote kick [player id]
Requests a player to be kicked.
### callvote timelimit
Requests an adjustment to the timelimit.
### callvote fraglimit
Requests an adjustment to the fraglimit.
### callvote map_restart
Requests the map to restart, without altering the [map cycle](@ref mapcycle).
### callvote nextmap
Requests a change to the next map.

Some files were not shown because too many files have changed in this diff Show more