diff --git a/.gitignore b/.gitignore index eafb8909..fbb895bf 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ *~ +Documentation/html/ darkstar/ noffice/ pvk/ diff --git a/Documentation/Building.md b/Documentation/Building.md new file mode 100644 index 00000000..623e040f --- /dev/null +++ b/Documentation/Building.md @@ -0,0 +1,58 @@ +# Building + +## 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. + +### Dependencies +* subversion +* gmake +* gcc +* mesa-libGL-devel +* libgnutls-devel +* libopenal-devel +* libX11-devel +* libXcursor-devel +* libXrandr-devel +* libSDL2-devel (only if you pass BUILD_SDL2=1 in build.cfg) + +## Building the Level Editor {#editor} +Handled by **build_editor.sh**. + +### Dependencies +* gcc-c++ +* gtk2-devel +* gtkglext-devel +* libxml2-devel +* libjpeg8-devel +* minizip-devel + +## 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. diff --git a/Documentation/Contributing.md b/Documentation/Contributing.md new file mode 100644 index 00000000..e062c1b7 --- /dev/null +++ b/Documentation/Contributing.md @@ -0,0 +1,36 @@ +# Contributing + +If you'd like to contribute code: Awesome. +There's just 2 very short requirements. + +## Rule #1 + +The code must be yours. + +It's simple: +* Do not take code that is by anyone else that is not you. + + +## Rule #2 +No submission or decompilation of third-party code. This is important if you want to recreate behaviour from another game. + +* We do not decompile - we reverse-engineer by trial and error. + +This is generally referred to as 'clean-room engineering'. +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. + +# Other notes +Game specific features need to be put into game-specific directories. + +Unless other games benefit from this, keep it seperate to one of the game +sub-directories. This usually means it'll be part of another git repository too. + +That's about it! + +# Saying Thanks +If you want to solely say thanks, the main developer of Nuclide **loves** receiving E-Mail. You can contact him at and let him know your thoughts. + +If you'd like to donate to him via [PayPal](https://paypal.me/eukara) or [Patreon](https://www.patreon.com/eukara) you can do that too. That money pays for a lot of free services he provides that come with both [FTEQW](https://www.fteqw.org/) and **Nuclide**. \ No newline at end of file diff --git a/Documentation/Filesystem.md b/Documentation/Filesystem.md new file mode 100644 index 00000000..64e5b79e --- /dev/null +++ b/Documentation/Filesystem.md @@ -0,0 +1,69 @@ +# Filesystem + +## Launching + +The `nuclide` shell script is the launcher. + +It sets **$PATH** to include the directory `bin/` which contains the engine that +you've built with `build_engine.sh`. + +When nuclide is run and executes the engine, it'll first read `default.fmf` which +is a manifest file the engine reads. It is updated occasionally. + +It defines which directories to mount in the virtual filesystem of the engine +and has a document entirely dedicated to itself. For that please read: +``` + src/engine/specs/fte_manifests.txt +``` + +## Loading Games + +On its own, Nuclide launches the game directory `base/`, unless you tell it otherwise: +``` +./nuclide -game mygame +``` + +Will load `mygame/` instead of `base/`. + +You can also load multiple additional directories in a specific order by specifying +multiple `-game` command-line arguments. + +It will still load the other `BASEGAME` entries listed in the default.fmf. +You can even load your own manifest file over default.fmf, by passing + +``` + ./nuclide -manifest mymanifest.fmf +``` + +## Virtual-Filesystem + +When a game is mounted, we're either looking for **loose files** (loaded last), or +**archives** the engine supports. + +The Quake .pak archive format, or zip archives with the pk3 and pk4 extensions are supported. +Upon initializing the filesystem they are enumerated alphabetically and then loaded in order. + +Directories with the .pk3dir extensions are treated as if they were .pk3 archives. +The editor also supports .pk3dir directories. + +Once the game has loaded a game directory, it'll load the persistent menu.dat into our QuakeC +virtual machine. + +It' always running, you can make your own by modifying `src/menu-fn/`, `src/menu-vgui/` +or writing your own module. + +## Archives + +Protected archives always start have the prefix **pak**[...] and cannot be downloaded by connecting +to a server that has them. +**Use this for any copyrighted data.** + +When you spawn a map, you create a server which will distribute its own client-side game-logic. + +It's advised that you do not pack **csprogs.dat** and **progs.dat** into a protected archive. + + +## Nuclide specific formats +Nuclide contains many custom definition files that are not engine specific. +`.efx`, `.font`, `.sndshd` and `.way` to name a few. +The game-logic mostly handles them and can thus be, in theory, extended by you. \ No newline at end of file diff --git a/doc/history b/Documentation/History.md similarity index 99% rename from doc/history rename to Documentation/History.md index cb6558a2..76cac88f 100644 --- a/doc/history +++ b/Documentation/History.md @@ -1,4 +1,4 @@ -NUCLIDE PROJECT HISTORY +# History In November 2016 eukara started work on 'OpenCS', a project which focused solely on creating a clean-room implementation of Counter-Strike 1.5 in QuakeC diff --git a/Documentation/Main.md b/Documentation/Main.md new file mode 100644 index 00000000..7985f2ec --- /dev/null +++ b/Documentation/Main.md @@ -0,0 +1,68 @@ +# Overview + +Welcome to the documentation for Nuclide. + +This is a software development kit and development environment created by [Vera Visions, L.L.C.](https://www.vera-visions.com/) + +## What this project is {#what} + +The Nuclide project produces a freely available game-logic component and +development platform on top of FTEQW; which is the engine we happen to use. +The goal is to create a modern research base for new advancements, as well +as to have a stable base with a decent API for making games. + +- Client-side predicted movement and inputs for things like weapons-systems +- Lots of well documented objects to use in level formats supported by FTEQW +- Reference implementations for a lot of features exlusive to FTEQW compared + to other idTech engines +- Designed to be familar to developers who're used to GoldSrc and Source engine + projects + +### 1. Why might I want to use it? {#why} + +You want to develop a game using a lot of complex and well-tested objects +which might be tedious to implement on your own. + +You want to run or make modifications for a game using Nuclide and need full +control over what you can do. + +### 2. How free is Nuclide? {#license} + +Everything in Nuclide is **free software**. The copyright terms for the game-logic are +very permitting. Nuclide does not use the GPL as a point of reference, it +instead uses a ISC-like license. This means you can use, copy, modify and +distribute the code and work resulting from it for any purpose. + +Please read the very short 'LICENSE' document for details. + +### 3. What are the alternatives? {#alternatives} + +Implementing systems such as prediction, complex map objects and entities on +your own or licensing another engine such as [Source](https://partner.steamgames.com/doc/sdk/uploading/distributing_source_engine) that ships with its own **Source SDK Base**. + +## Getting started {#prerequisites} + +First of all, you want to be sure this is what you want to get into. +If you do posess a basic knowledge of the following: + +- The C programming language +- Debugging a native application +- Makefiles +- Compiling your own binaries +- Concept of public and private APIs + +Then you will have a good time. +We strive to keep the codebase portable and conform to open standards wherever possible. +This means that if you develop on Windows, you probably want to install something like [Cygwin](https://www.cygwin.com/) to make this bearable. + +Please don't ask us how to learn UNIX/Cygwin. + +**This is a development kit and a development environment. This is not a game.** + +## Actually getting started {#how} + +You clone the Nuclide git repository first. There's multiple places to get it, one such place may be GitHub: + +`git clone https://github.com/veravisions/nuclide` + +And then you can [get started on building the engine and the rest of the toolchain](Building.md). \ No newline at end of file diff --git a/Documentation/Materials/MatCommands.md b/Documentation/Materials/MatCommands.md new file mode 100644 index 00000000..67f49092 --- /dev/null +++ b/Documentation/Materials/MatCommands.md @@ -0,0 +1,4 @@ +# 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.](MatVMap.md) \ No newline at end of file diff --git a/Documentation/Materials/MatGoldSrc.md b/Documentation/Materials/MatGoldSrc.md new file mode 100644 index 00000000..dda53ad3 --- /dev/null +++ b/Documentation/Materials/MatGoldSrc.md @@ -0,0 +1,258 @@ +# Materials: GoldSrc +Material definitions handle what footsteps and what impact effects are played against each texture in the game-world. +So when you walk on dirt, you can hear the difference; or when you shoot wood with a gun it will have splinters spawn instead of black bits and smoke. + +*Note:* While Nuclide supports this for legacy BSP files, you are encouraged to define the material of a texture via the [surfaceparm](MatCommands.md) command in a **Material** instead. + +## 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. + +For example: + +``` +C CONCRETEWALL +``` + +Will make any surface **concrete** that starts with the name `CONCRETEWALL`. In vanilla Half-Life, the second argument (name) can only be 12 characters long. + +It will also only compare the length of characters of the name above. So for example if you were to define: + +``` +C CONC +``` + +Then `CONCRETEWALL` would still be marked as concrete, and any other texture that starts with `CONC[...]`. + +## Community Changes and Additions + +In stock GoldSrc, the **materials.txt** can be overwritten by a modification, and users could customize the file on the client-side only for themselves. This means there was no 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 texture sounds. + +A few mods tried to remedy this problem, the following below is methods +documented so far: + +* maps/MAPNAME.mat +> Introduced in The Wastes (2003) + +* maps/MAPNAME_materials.txt +> Convention by Andrew Lucas, creator of Trinity SDK, modeled after +> MAPNAME_details.txt + +* materials_file `PATH/FILE.txt` via the `worldspawn` entity +> Introduced in Sven Co-op 5.0 + +All these methods are supported by Nuclide, as one goal is to implement +conventions by not only Valve but the community as well. + +In addition Nuclide has also implemented a way of giving modifications +their own inheritable materials file: + +``` +sounds/materials_UNIQUENAME.txt +``` + +The idea here is that any mod or even map pack can include ONLY the textures +used, and no longer will anyone have to manage a near-clone of materials.txt + +For repackaging or modding purposes, if you desire to give your map custom +sound definitions, we recommend **The Wastes** its method for individual maps, while +the Nuclide method should be used for Mods or Map Packs. We find these to be +the most clean and efficient way. + +**NOTE**: We recommend only using materials text files for GoldSrc related modding +purposes. It is inefficient for modern projects as there are much better +standards already supported in Nuclide. Keep in mind, it takes memory to load +big text files, and lots of text files adds up over play sessions. + +# Material List +In Nuclide, this is the currently supported list of material IDs: + +| Material ID | Material Name | +|-------------|---------------| +| B | Bloody Flesh | +| C | Concrete | +| D | Dirt | +| F | Flesh | +| G | Grate | +| H | Alien | +| K | Snow | +| M | Metal | +| N | Sand | +| O | Foliage | +| P | Computer | +| S | Slosh | +| T | Tile | +| V | Vent | +| W | Wood | +| Y | Glass | + + +## Game differences +Listed below are definitions for various games and mods. Only the changes and additions are listed since the rest are identical. + +The * indicates these definitions are not implemented in Nuclide + +## GoldSrc +### Arrangement +| **Material ID** | **Material Name** | +|-------------------|---------------------| +| B | Blue Texture | +| N | Snow | +| R | Red Texture | +| U | Slime | +| X | Yellow Texture | +| Z | Black Texture | + +### Counter-Strike +| **Material ID** | **Material Name** | +|-------------------|---------------------| +| N | Snow | +| X | Grass | +*Afraid of Monsters: DC, Natural Selection, and Snow War uses the same definitions.* + +### Cry of Fear +| **Material ID** | **Material Name** | +|-------------------|---------------------| +| B | Random Twig Snap | +| H | Paper | +| I | Mud | +| O | Sand | +| P | Snow | +| R | Gravel | +| U | Grass | +| Y | Broken Glass | +| Z | Carpet | + +### Gunman Chronicles +| **Material ID** | **Material Name** | +|-------------------|---------------------| +| G | Wood | +| T | Rock | +| V | Sand | +| W | Unknown/Unused? | + +### Firearms +| **Material ID** | **Material Name** | +|-------------------|-----------------------------------------| +| B | Sandbag | +| N | Snow | +| U | No impact or decals, just smoke effects | + +### Heart of Evil +| **Material ID** | **Material Name** | +|-------------------|---------------------| +| U | Mud | + +### Hostile Intent +| **Material ID** | **Material Name** | +|-------------------|---------------------| +| A | Sand | +| E | Foliage | +| N | Snow | +| R | Carpet | +| U | Mud | +| Z | Grass | + +### Household DEATH! +| **Material ID** | **Material Name** | +|-------------------|---------------------| +| H | Wood (Creaky) | +| I | Grass | + +### Night at the Office +| **Material ID** | **Material Name** | +|-------------------|---------------------| +| T | Carpet | + +### Opposing Force +| **Material ID** | **Material Name** | +|-------------------|---------------------| +| O | Snow | +*Science and Industry uses the same definitions as Opposing Force.* + +### Poke646 +| **Material ID** | **Material Name** | +|-------------------|---------------------| +| M | Metal/Grate | +| T | Wood/Tile | +| G | Carpet/Grass | + +### Wasteland Half-Life +| **Material ID** | **Material Name** | +|-------------------|---------------------| +| B | Barrel | +| I | Sand | +| N | Tinroof | +| R | Rust | +| U | Drywall | +*The Wastes uses the same definitions.* + +## Source +While Source has materials describing a surface with its **$surfaceprop** command, the GoldSrc way of describing materials with a 1-character symbol is still used to define which impact effect to use. + +So 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 +| **Material ID** | **Material Name** | +|-------------------|---------------------| +| 11 | Steam Pipe | + +Alien Swarm: Reactive Drop uses the same definitions. + +### Counter-Strike: Global Offensive +| **Material ID** | **Material Name** | +|-------------------|---------------------------| +| 11 | Mud | +| 12 | Sand Barrel | +| 13 | Sand Barrel (Penetration) | +| 14 | Metal Shield | + +### Half-Life 2 +| **Material ID** | **Material Name** | +|-------------------|---------------------| +| A | Antlion | +| B | Flesh (Bloody) | +| H | Flesh (Antlion) | +| K | Snow | +| L | Plastic | +| N | Sand | +| I | Clip | +| O | Foliage | +| X | Fake | +| - | No Decal | + +### Half-Life 2: Episode 2 +| **Material ID** | **Material Name** | +|-------------------|---------------------| +| E | Antlion Egg Sacks | +| Z | Adviser Shield | + +### Insurgency +| **Material ID** | **Material Name** | +|-------------------|---------------------| +| A | Fruit | + +*Day of Infamy uses the same definitions.* + +### Left 4 Dead +| **Material ID** | **Material Name** | +|-------------------|---------------------| +| J | Grass | +| K | Mud | +| Q | Asphalt | +| R | Brick | +| U | Cardboard | +| 1 | Clay | +| 2 | Plaster | +| 3 | Rock | +| 4 | Rubber | +| 5 | Sheetrock | +| 6 | Cloth | +| 7 | Carpet | +| 8 | Paper | +| 9 | Upholstery | +| 10 | Puddle | + +### Portal 2 +| **Material ID** | **Material Name** | +|-------------------|---------------------| +| R | Reflective | diff --git a/Documentation/Materials/MatOverview.md b/Documentation/Materials/MatOverview.md new file mode 100644 index 00000000..bf8fd288 --- /dev/null +++ b/Documentation/Materials/MatOverview.md @@ -0,0 +1,80 @@ +# Materials + +**Materials**, also formerly known **Q3 shaders** or wrongly referred to as just **shaders** are scripts that define texture and surface properties. + +## History + +In the idTech 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. + +They effectively merged the Quake texture-prefix 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. + +FTE has since coupled the old 'shader' syntax with proper GPU shaders using the [program](MatCommands.md) material command. + +## What is a Material? +Materials are short text scripts that define the properties of a surface as it appears and functions in a game world (or compatible editing tool). By convention, the documents that contain these scripts usually has the same name as the texture set which contains the textures being modified (e.g; base, hell, castle, etc,). Several specific materials have also been created to handle special cases, like liquids, sky and special effects. + +## Usage + +When the engine looks for a texture, it will look for a material file in the file-tree first, then 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. + +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 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': + +``` + // Vera Visions Material + { + diffusemap textures/common/lava.tga + vmap_tessSize 64 + { + program unlit + blendFunc add + } + } +``` + +The first line is a simple comment. All the official textures are marked that way. + +`diffusemap` defines a texture sampler to associate with the material, it'll also be used by the real-time lights to render an impacted surface, hence why it's defined at a global scope. Other materials may need to be aware of it. The compiler also uses it to compute radiosity. + +`vmap_tessSize` will tell the BSP compiler to tesselate the surface in a specific way. This affects the entire surface and not just a single rendering stage, hence why it's defined at a global scope. + +We then follow into the territory of defining specific rendering instructions within braces ("{" and "}"), most of the time that's not needed if we're defining a simple, opaque material. However in this case we want to make sure that we have 1 rendering stage that blends additively. Things such as real-time lights and the BSP compiler ignore these additional stages entirely. + +`program unlit` will tell it not to be affected by lighting and just use a simple fullbright shader. + +`blendFunc add` will now tell the renderer that this surface is no longer opaque and will be blended with whatever equation will result in an additive blend. + +[You can read more about those commands in detail right here.](MatCommands.md) + +## Engine generated materials +If no material definition for a surface is present, the engine will create an internal one. +It's generally a primitive material using the internal **defaultwall** shader if it's a world texture, the **defaultskin** texture if it's a model, or a **default2d** if it's a HUD element. + +## Legacy materials + +You can support old-style Q3A materials alongside modern shader oriented ones. +``` + { + if $programs + program vertexlit + diffusemap "models/weapons/handcannon/w_handcannon.dds" + normalmap "models/weapons/handcannon/w_handcannon_normal.dds" + else + { + map "models/weapons/handcannon/w_handcannon.tga" + rgbGen lightingDiffuse + } + endif + } +``` +Here everything inside the **if $programs** block will only ever load if it's capable of handling the GLSL. +So if you have a card only performing well under the GL 1.X pipeline, the **else** path will take priority. +This means less graphical fidelity, but generally better performance on those old chipsets. + +All of Quake III's shading language is supported in the else block. diff --git a/Documentation/Materials/MatShaders.md b/Documentation/Materials/MatShaders.md new file mode 100644 index 00000000..5105d1cb --- /dev/null +++ b/Documentation/Materials/MatShaders.md @@ -0,0 +1,55 @@ +# Materials: Shaders +Shaders are referring to GPU-oriented pieces of a program, performing shading and rendering related functions instead of letting the engine handle it. + +In **FTEQW** you can specify a custom GLSL or HLSL shader using the [program](MatCommands.md) command inside a [Material](MatOverview.md). + +## Example Shader +This is a primitive shader file. It includes the vertex and fragment program. + +It will respond to the [diffusemap](MatCommands.md) only, which is loaded +into the **d_f** variable. It can be modified from that point onwards. +The commented out line will turn all of the output red. + +Give it a try, or something! + +``` +//======= Copyright (c) 2015-2020 Vera Visions LLC. All rights reserved. ======= +// +// Purpose: +// +// Example surface +//============================================================================== + +!!ver 110 +!!samps diffuse + +#include "sys/defs.h" + +varying vec2 tex_c; + +#ifdef VERTEX_SHADER +void main () +{ + tex_c = v_texcoord; /* get our texture coordinates, which we'll use for the texture2D command */ + gl_Position = ftetransform(); /* place vertex into the place FTE wants us to put them at */ +} +#endif + +#ifdef FRAGMENT_SHADER +void main () +{ + vec4 d_f = texture2D(s_diffuse, tex_c); /* load the fragment from our diffusemap sample */ + // d_f.rgb = vec3(1.0, 0.0, 0.0); /* turns out fragment (aka pixel) red */ + gl_FragColor = d_f; /* final pixel output is that of d_f */ +} +#endif +``` + +## Dissecting GLSL shaders +When we pass `program ` in our [Material](MatOverview.md), the engine will load `glsl/.glsl` to handle the material for us. + +The shader in question needs to define a `main` function for both a vertex and a fragment shader. That's what the **ifdef**s are for in the above example. + +You can not have separate files handle vertex/fragment programs, unlike in **id Tech 4/Doom III**. + +At some point in the `main` function, we do have to set `gl_Position` and `gl_FragColor` respectively. Those can not be undefined. diff --git a/Documentation/Materials/MatVMap.md b/Documentation/Materials/MatVMap.md new file mode 100644 index 00000000..4a2f9237 --- /dev/null +++ b/Documentation/Materials/MatVMap.md @@ -0,0 +1,4 @@ +# 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. \ No newline at end of file diff --git a/Documentation/Materials/commands/alphafunc.md b/Documentation/Materials/commands/alphafunc.md new file mode 100644 index 00000000..f276c9c6 --- /dev/null +++ b/Documentation/Materials/commands/alphafunc.md @@ -0,0 +1,30 @@ +# Materials: Commands {#mat_commands} +## alphafunc +### Syntax {#syntax} + +**alphaFunc ** + +### Overview {#overview} + +Determines the alpha test function used when rendering this surface. + +Valid values are **GT0**, **LT128**, and **GE128**. These correspond to +**"GREATER THAN 0"**, **"LESS THAN 128"**, and **"GREATER THAN OR EQUAL +TO 128"**. + +This function is used when determining if a pixel should be written to +the frame-buffer. For example, if **GT0** is specified, the only the +portions of the texture map with corresponding alpha values greater than +zero will be written to the framebuffer. **By default alpha testing is +disabled.** + +Both alpha testing and normal [alpha +blending](blendFunc) can be used to get +textures that have see-through parts. The difference is that +**alphaFunc** is an all-or-nothing test, while blending smoothly blends +between opaque and translucent at pixel edges. + +Alpha test can also be used with +[depthWrite](depthWrite), allowing other +effects to be conditionally layered on top of just the opaque pixels by +setting [depthFunc](depthFunc) to equal. \ No newline at end of file diff --git a/Documentation/Materials/commands/alphagen.md b/Documentation/Materials/commands/alphagen.md new file mode 100644 index 00000000..8f671a93 --- /dev/null +++ b/Documentation/Materials/commands/alphagen.md @@ -0,0 +1,23 @@ +# Materials: Commands {#mat_commands} +## alphagen +### Syntax {#syntax} + +**alphaGen ** + +### Overview {#overview} + +The alpha channel can be specified like the [rgb +channels](rgbGen). If not specified, it +defaults to 1.0. + +### Functions {#functions} + +#### portal {#portal} + +This rendering stage keyword is used in conjunction with the +[surfaceparm](surfaceparm) keyword +portal. The function accomplishes the "fade" that causes the scene in +the portal to fade from view. Specifically, it means "Generate alpha +values based on the distance from the viewer to the portal." + +Use `alphaGen portal` on the last rendering pass. \ No newline at end of file diff --git a/Documentation/Materials/commands/blendfunc.md b/Documentation/Materials/commands/blendfunc.md new file mode 100644 index 00000000..4cb317ad --- /dev/null +++ b/Documentation/Materials/commands/blendfunc.md @@ -0,0 +1,142 @@ +# Materials: Commands {#mat_commands} +## blendfunc +![OpenGL blending cheat-sheet](gl_blendmodes.jpg "from zanir.wz.cz/?p=60") + +### Syntax {#syntax} + +**blendFunc ** + +**blendFunc ** + +### 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} + +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} + +This is a shorthand command for `blendFunc GL_ONE GL_ONE`. Effects like +fire and energy are additive. + +##### 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} + +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} + +Getting a handle on this concept is absolutely key to understanding all +shader manipulation of graphics. + +BlendFunc or "Blend Function" is the equation at the core of processing +shader graphics. The formula reads as follows: + +` [Source *``] + [Destination * ``]` + +**Source** is usually the RGB color data in a texture file. + +**Destination** is the color data currently existing in the frame +buffer. + +Rather than think of the entire texture as a whole, it maybe easier to +think of the number values that correspond to a single pixel, because +that is essentially what the computer is processing: One pixel of the +bitmap at a time. + +The process for calculating the final look of a texture in place in the +game world begins with the pre-calculated lightmap for the area where +the texture will be located. This data is in the frame buffer. That is +to say, it is the initial data in the Destination. In an unmanipulated +texture (i.e. one without a special shader script), color information +from the texture is combined with the lightmap. In a shader-modified +texture, the $lightmap stage must be present for the lightmap to be +included in the calculation of the final texture appearance. + +Each pass or "stage" of blending is combined (in a cumulative manner) +with the color data passed onto it by the previous stage. How that data +combines together depends on the values chosen for the Source Blends and +Destination Blends at each stage. Remember it's numbers that are being +mathematically combined together that are ultimately interpreted as +colors. + +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 {#source_blend} + +The following values are valid for the Source Blend part of the +equation. + +- **GL_ONE** This is the value 1. When multiplied by the Source, the + value stays the same the value of the color information does not + change. +- **GL_ZERO** This is the value 0. When multiplied by the Source, all + RGB data in the Source becomes Zero (essentially black). +- **GL_DST_COLOR** This is the value of color data currently in the + Destination (frame buffer). The value of that information depends on + the information supplied by previous stages. +- **GL_ONE_MINUS_DST_COLOR** This is nearly the same as + **GL_DST_COLOR** except that the value for each component color is + inverted by subtracting it from one. (,i.e. R = 1.0 - DST.R, G = + 1.0 - DST.G, B = 1.0 - DST.B, etc.) +- **GL_SRC_ALPHA** The TGA file being used for the Source data must + have an alpha channel in addition to its RGB channels (for a total + of four channels). The alpha channel is an 8-bit black and white + only channel. An entirely white alpha channel will not darken the + Source. +- **GL_ONE_MINUS_SRC_ALPHA** This is the same as **GL_SRC_ALPHA** + except that the value in the alpha channel is inverted by + subtracting it from one.(i.e. A=1.0 - SRC.A) + +##### Destination Blend {#destination_blend} + +The following values are valid for the Destination Blend part of the +equation. + +- **GL_ONE** This is the value 1. When multiplied by the Destination, + the value stays the same the value of the color information does not + change. +- **GL_ZERO** This is the value 0. When multiplied by the Destination, + all RGB data in the Destination becomes Zero (essentially black). +- **GL_SRC_COLOR** This is the value of color data currently in the + Source (which is the texture being manipulated here). +- **GL_ONE_MINUS_SRC_COLOR** This is the value of color data currently + in Source, but subtracted from one(i.e. inverted). +- **GL_SRC_ALPHA The TGA** file being used for the Source data must + have an alpha channel in addition to its RGB channels (four a total + of four channels). The alpha channel is an 8-bit black and white + only channel. An entirely white alpha channel will not darken the + Source. +- **GL_ONE_MINUS_SRC_ALPHA** This is the same as **GL_SRC_ALPHA** + 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} + +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 +frame buffer to become the Destination information for the next stage. +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} + +If no blendFunc is specified then no blending will take place. That's +just a fact of life. \ No newline at end of file diff --git a/Documentation/Materials/commands/cull.md b/Documentation/Materials/commands/cull.md new file mode 100644 index 00000000..b5c33550 --- /dev/null +++ b/Documentation/Materials/commands/cull.md @@ -0,0 +1,45 @@ +# Materials: Commands {#mat_commands} +## cull +### Syntax {#syntax} + +**cull ** + +### 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 +show the front side. In many applications we see both. For example, in +water, you can see both front and a back. The same is true for things +like grates and screens. + +To "cull" means to remove. The value parameter determines the type of +face culling to apply. The default value is cull front if this keyword +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} + +#### front {#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 value or if the keyword cull +does not appear at all in the shader. + +#### back {#back} + +Cull back removes the back or "inside" of a polygon from being drawn in +the world. + +#### none {#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 +as grates, screens, metal wire fences and so on and for liquid volumes +that the player can see from within. Also used for energy fields, +sprites, and weapon effects (e.g. plasma). + +**Design Notes:** For things like grates and screens, put the texture +with the cull none property on one face only. On the other faces, use a +non-drawing texture. \ No newline at end of file diff --git a/Documentation/Materials/commands/deformvertexes.md b/Documentation/Materials/commands/deformvertexes.md new file mode 100644 index 00000000..e760b532 --- /dev/null +++ b/Documentation/Materials/commands/deformvertexes.md @@ -0,0 +1,140 @@ +# Materials: Commands {#mat_commands} +## deformvertexes +### Syntax {#syntax} + +**deformVertexes ** + +### Overview {#overview} + +This command performs a general deformation on the surface's vertexes, +changing the actual shape of the surface before drawing the shader +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} + +#### wave {#wave} + +Designed for water surfaces, modifying the values differently at each +point. + +It accepts the standard **wave** functions of the type: **sin**, +**triangle**, **square**, **sawtooth** or **inversesawtooth**. + +The "div" parameter is used to control the wave "spread" - a value equal +to the [tessSize](vmap_tessSize) of the +surface is a good default value. + +#### normal <amplitude ~0.1-~0.5> <frequency ~1.0-~4.0> {#normal_amplitude_0.1_0.5_frequency_1.0_4.0} + +This deformation affects the normals of a vertex without actually moving +it, which will effect later material options like lighting and +especially environment mapping. If the material stages don't use normals +in any of their calculations, there will be no visible effect. + +**Design Notes:** Putting values of 0.1 to 0.5 in Amplitude and 1.0 to +4.0 in the Frequency can produce some satisfying results. Some things +that have been done with it: A small fluttering bat, falling leaves, +rain, flags. + +#### bulge {#bulge} + +This forces a bulge to move along the given s and t directions. Designed +for use on curved pipes. + +#### move {#move} + +This keyword is used to make a brush, curve patch or model appear to +move together as a unit. The **** **** and **** values are the +distance and direction in game units the object appears to move relative +to it's point of origin in the map. + +The ** ** and **** values are the +same as found in other wave form manipulations. + +The product of the function modifies the values x, y, and z.Therefore, +if you have an amplitude of 5 and an x value of 2, the object will +travel 10 units from its point of origin along the x axis. This results +in a total of 20 units of motion along the x axis, since the amplitude +is the variation both above and below the base. + +It must be noted that an object made with this material does not +actually change position, it only appears to. + +**Design Note**: If an object is made up of surfaces with different +materials, all must have matching deformVertexes move values or **the +object will appear to tear itself apart!** + +#### 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 +sprite without having to make it a separate entity. + +This means that the "sprite" on which the texture is placed will rotate +to always appear at right angles to the player's view as a sprite would. +Any four-sided brush side, flat patch, or pair of triangles in a model +can have the autosprite effect on it. The brush face containing a +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} + +Is a slightly modified "sprite" that only rotates around the middle of +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} + +Specific parameter definitions for deform keywords: + +#### {#section} + +This is roughly defined as the size of the waves that occur. It is +measured in game units. Smaller values create agreater density of +smaller wave forms occurring in a given area. Larger values create a +lesser density of waves, or otherwise put, the appearance of larger +waves. To look correct this value should closely correspond to the value +(in pixels) set for +[tessSize](vmap_tessSize) of the texture. +A value of 100.0 is a good default value (which means your +[tessSize](vmap_tessSize) should be close +to that for things tolook "wavelike"). + +#### {#section_1} + +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 +sharp ascent and a sharp decay. It will make a choppy looking wave +forms. A **square** wave is simply on or off for the period of the +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. + +#### {#section_2} + +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. + +#### {#section_3} + +The distance that the deformation moves away from the base value. See +Wave Forms in the introduction for a description of amplitude. +SeeWave Forms in the introduction for a description of phase) + +#### {#section_4} + +See Wave Forms in the introduction for a description of frequency) + +Design Note: The siv and amplitude parameters, when used in conjunction +with liquid volumes like water should take into consideration how much +the water will be moving. A large ocean area would have have massive +swells (big siv values) that rose and fell dramatically (big amplitude +values). While a small, quiet pool may move very little. \ No newline at end of file diff --git a/Documentation/Materials/commands/depthfunc.md b/Documentation/Materials/commands/depthfunc.md new file mode 100644 index 00000000..3cda0765 --- /dev/null +++ b/Documentation/Materials/commands/depthfunc.md @@ -0,0 +1,15 @@ +# Materials: Commands {#mat_commands} +## depthfunc +### Syntax {#syntax} + +**depthFunc ** + +### Overview {#overview} + +This controls the depth comparison function used while rendering. + +The default is **lequal** (Less than or equal to) where any surface that +is at the same depth or closer of an existing surface is drawn. This is +used for textures with transparency or translucency. Under some +circumstances you may wish to use **equal**, e.g. for light-mapped +grates that are alpha tested (it is also used for mirrors). \ No newline at end of file diff --git a/Documentation/Materials/commands/depthwrite.md b/Documentation/Materials/commands/depthwrite.md new file mode 100644 index 00000000..afa1d6fb --- /dev/null +++ b/Documentation/Materials/commands/depthwrite.md @@ -0,0 +1,13 @@ +# Materials: Commands {#mat_commands} +## depthwrite +### Syntax {#syntax} + +**depthWrite** + +### Overview {#overview} + +By default, writes to the depth buffer when +[depthFunc](depthFunc) passes will happen +for opaque surfaces and not for translucent surfaces. + +Blended surfaces can have the depth writes forced with this function. \ No newline at end of file diff --git a/Documentation/Materials/commands/diffusemap.md b/Documentation/Materials/commands/diffusemap.md new file mode 100644 index 00000000..02b96a5e --- /dev/null +++ b/Documentation/Materials/commands/diffusemap.md @@ -0,0 +1,24 @@ +# Materials: Commands {#mat_commands} +## diffusemap +### Syntax {#syntax} + +**diffusemap ** + +### Overview {#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](normalmap) +- [specularmap](specularmap) +- [fullbrightmap](fullbrightmap) +- [uppermap](uppermap) +- [lowermap](lowermap) +- [reflectmask](reflectmask) +- [reflectcube](reflectcube) \ No newline at end of file diff --git a/Documentation/Materials/commands/fogparms.md b/Documentation/Materials/commands/fogparms.md new file mode 100644 index 00000000..ec6fe4f6 --- /dev/null +++ b/Documentation/Materials/commands/fogparms.md @@ -0,0 +1,42 @@ +# Materials: Commands {#mat_commands} +## fogparms +### Syntax {#syntax} + +**fogParms ** + +### Overview {#overview} + +**Note**: you must also specify "surfaceparm fog" to cause +[vmap](vmap) to identify the surfaces inside the volume. +Fogparms only describes how to render the fog on the surfaces. + +** ** These are normalized values. +To obtain the values that define fog color divide the desired color's +Red, Green and Blue values by 255 to obtain three normalized numbers +within the 0.0 to 1.0 range. + +**** This is the distance, in game units, until the +fog becomes totally opaque, as measured from the point of view of the +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} + +- The fog volume can only have one surface visible (from outside the + fog). +- Fog must be made of one brush. It cannot be made of adjacent + brushes. +- Fog brushes must be axial. This means that only square or + rectangular brushes may contain fog, and those must have their edges + drawn along the axes of the map grid (all 90 degree angles). + +**Design Notes:** + +- If a water texture contains a fog parameter, it must be treated as + if it were a fog texture when in use. +- If a room is to be filled completely with a fog volume,it can only + be entered through one surface (and still have the fog function + correctly). +- Additional shader passes may be placed on a fog brush, as with other + brushes. \ No newline at end of file diff --git a/Documentation/Materials/commands/fte_clutter.md b/Documentation/Materials/commands/fte_clutter.md new file mode 100644 index 00000000..bcf0664b --- /dev/null +++ b/Documentation/Materials/commands/fte_clutter.md @@ -0,0 +1,13 @@ +# Materials: Commands {#mat_commands} +## fte_clutter +### Syntax {#syntax} + +**fte_clutter + ** + +### Overview {#overview} + +Similar to [vmap_surfaceModel (Material +Command)](vmap_surfaceModel), however +it'll place models at runtime. The density can be controlled via the +cvar `r_clutter_density`. \ No newline at end of file diff --git a/Documentation/Materials/commands/fullbrightmap.md b/Documentation/Materials/commands/fullbrightmap.md new file mode 100644 index 00000000..92a435e3 --- /dev/null +++ b/Documentation/Materials/commands/fullbrightmap.md @@ -0,0 +1,25 @@ +# Materials: Commands {#mat_commands} +## fullbrightmap +### Syntax {#syntax} + +**fullbrightmap ** + +### Overview {#overview} + +The texture is essentially a fullbright overlay on top of the +diffuse/albedomap. + +Not all [Shaders](Shaders) support them. In some, like the +[unlit](unlit_(Shader)) shader, the +[diffusemap](diffusemap) is always +fullbright. + +### See also {#see_also} + +- [diffusemap](diffusemap) +- [normalmap](normalmap) +- [specularmap](specularmap) +- [uppermap](uppermap) +- [lowermap](lowermap) +- [reflectmask](reflectmask) +- [reflectcube](reflectcube) \ No newline at end of file diff --git a/Documentation/Materials/commands/gl_blendmodes.jpg b/Documentation/Materials/commands/gl_blendmodes.jpg new file mode 100644 index 00000000..b2e4c394 Binary files /dev/null and b/Documentation/Materials/commands/gl_blendmodes.jpg differ diff --git a/Documentation/Materials/commands/nomipmaps.md b/Documentation/Materials/commands/nomipmaps.md new file mode 100644 index 00000000..779f8bb3 --- /dev/null +++ b/Documentation/Materials/commands/nomipmaps.md @@ -0,0 +1,15 @@ +# Materials: Commands {#mat_commands} +## nomipmaps +### Syntax {#syntax} + +**noMipmaps** + +### Overview {#overview} + +This implies [noPicMip](noPicMip), but +also prevents the generation of any lower resolution mipmaps for use by +the 3d card. This will cause the texture to alias when it gets smaller, +but there are some cases where you would rather have this than a blurry +image. Sometimes thin slivers of triangles force things to very low +mipmap levels, which leave a few constant pixels on otherwise scrolling +special effects. \ No newline at end of file diff --git a/Documentation/Materials/commands/nopicmip.md b/Documentation/Materials/commands/nopicmip.md new file mode 100644 index 00000000..d02475fa --- /dev/null +++ b/Documentation/Materials/commands/nopicmip.md @@ -0,0 +1,12 @@ +# Materials: Commands {#mat_commands} +## nopicmip +### Syntax {#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 +images and text in the heads up display from blurring when user +optimizes the game graphics. \ No newline at end of file diff --git a/Documentation/Materials/commands/normalmap.md b/Documentation/Materials/commands/normalmap.md new file mode 100644 index 00000000..ed6e0b2e --- /dev/null +++ b/Documentation/Materials/commands/normalmap.md @@ -0,0 +1,27 @@ +# Materials: Commands {#mat_commands} +## normalmap +### Syntax {#syntax} + +**normalmap ** + +### Overview {#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) +- [specularmap](specularmap) +- [fullbrightmap](fullbrightmap) +- [uppermap](uppermap) +- [lowermap](lowermap) +- [reflectmask](reflectmask) +- [reflectcube](reflectcube) \ No newline at end of file diff --git a/Documentation/Materials/commands/polygonoffset.md b/Documentation/Materials/commands/polygonoffset.md new file mode 100644 index 00000000..028879de --- /dev/null +++ b/Documentation/Materials/commands/polygonoffset.md @@ -0,0 +1,15 @@ +# Materials: Commands {#mat_commands} +## polygonoffset +### Syntax {#syntax} + +**polygonOffset ** + +### Overview {#overview} + +Surfaces rendered with the polygonOffset keyword are rendered slightly +off the polygon's surface. This is typically used for wall markings and +"decals." The distance between the offset and the polygon is variable. +If no value is supplied a distance of 1 is assumed, however this is +meant for backwards compatibility. Being explicit will help grepping +values later in case you need to find all surfaces with just a +polygonOffset of 1. \ No newline at end of file diff --git a/Documentation/Materials/commands/portal.md b/Documentation/Materials/commands/portal.md new file mode 100644 index 00000000..ca449a64 --- /dev/null +++ b/Documentation/Materials/commands/portal.md @@ -0,0 +1,12 @@ +# Materials: Commands {#mat_commands} +## portal +### Syntax {#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 +texture (within 64 game units). All this does is set "sort portal", so +it isn't needed if you specify that explicitly. \ No newline at end of file diff --git a/Documentation/Materials/commands/program.md b/Documentation/Materials/commands/program.md new file mode 100644 index 00000000..352273a5 --- /dev/null +++ b/Documentation/Materials/commands/program.md @@ -0,0 +1,14 @@ +# Materials: Commands {#mat_commands} +## 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, + +Starting in [The Wastes](The_Wastes) 1.2, there are the +following shader programs available to you: + +- program [unlit](unlit_(Shader)) +- program [lightmapped](lightmapped_(Shader)) +- program [vertexlit](vertexlit_(Shader)) +- program [water](water_(Shader)) +- program [refract](refract_(Shader)) \ No newline at end of file diff --git a/Documentation/Materials/commands/reflectcube.md b/Documentation/Materials/commands/reflectcube.md new file mode 100644 index 00000000..78c6a36d --- /dev/null +++ b/Documentation/Materials/commands/reflectcube.md @@ -0,0 +1,20 @@ +# Materials: Commands {#mat_commands} +## reflectcube +### Syntax {#syntax} + +**reflectcube ** + +### Overview {#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) +- [normalmap](normalmap) +- [specularmap](specularmap) +- [fullbrightmap](fullbrightmap) +- [uppermap](uppermap) +- [lowermap](lowermap) +- [reflectmask](reflectmask) \ No newline at end of file diff --git a/Documentation/Materials/commands/reflectmask.md b/Documentation/Materials/commands/reflectmask.md new file mode 100644 index 00000000..e987a5d6 --- /dev/null +++ b/Documentation/Materials/commands/reflectmask.md @@ -0,0 +1,25 @@ +# Materials: Commands {#mat_commands} +## reflectmask +### Syntax {#syntax} + +**reflectmask ** + +### Overview {#overview} + +Defines a texture that specifies which parts of a material will reveal a +reflective material, such as a +[cubemap](reflectcube). 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) instead. + +### See also {#see_also} + +- [diffusemap](diffusemap) +- [normalmap](normalmap) +- [specularmap](specularmap) +- [fullbrightmap](fullbrightmap) +- [uppermap](uppermap) +- [lowermap](lowermap) +- [reflectcube](reflectcube) \ No newline at end of file diff --git a/Documentation/Materials/commands/rgbgen.md b/Documentation/Materials/commands/rgbgen.md new file mode 100644 index 00000000..b6788a91 --- /dev/null +++ b/Documentation/Materials/commands/rgbgen.md @@ -0,0 +1,117 @@ +# Materials: Commands {#mat_commands} +## rgbgen +### Syntax {#syntax} + +**rgbGen ** + +**rgbGen wave ** + +### Overview {#overview} + +Defines what vertex colors are set to for any given surface. + +If no rgbGen is specified, either "identityLighting" or"identity" will +be selected, depending on which blend modes are used. + +Valid parameters are const, wave, identity, identityLighting, +entity, oneMinusEntity, fromVertex, and lightingDiffuse. + +### Functions {#functions} + +#### 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: + +` rgbGen const 0.0 1.0 0.0` + +#### 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} + +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} + +Colors are grabbed from the entity's .colormod field. + +#### oneMinusEntity {#oneminusentity} + +Colors are grabbed from 1.0 minus the entity's .colormod field. + +#### entityLighting {#entitylighting} + +Introduced by [FTE](FTE), same as entity, but will receive +lighting similar to identityLighting on top of it. + +#### 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} + +As rgbGen vertex, but inverted. + +Design Note: This keyword would probably not be used by a level designer + +#### lightingDiffuse {#lightingdiffuse} + +Colors are computed using a standard diffuse lighting equation. It uses +the vertex normals to illuminate the object correctly. + +Design Note: -rgbGen lightingDiffuse is used when you want the RGB +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 {#wave} + +Colors are generated using the specified waveform. An affected texture +with become darker and lighter, but will not change hue. Hue stays +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**. + +##### {#section} + +- **Sin**: color flows smoothly through changes. +- **Triangle**: color changes at a constant rate and spends no + appreciable time at peaks and valleys. +- **Square**: color alternates instantly between its peak and valley + values. +- **Sawtooth**: With a positive frequency value, the color changes at + a constant rate to the peak then instantly drops to its valley + value. +- **Inversesawtooth**: An inverse sawtooth wave will reverse this, + making the ascent immediate (like a square wave) and the decay fall + off like a triangle wave. + +##### {#section_1} + +Baseline value. The initial RGB formula of a color (normalized). + +##### {#section_2} + +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. + +##### {#section_3} + +See the explanation for phase under the waveforms heading of Key +Concepts. + +##### {#section_4} + +Frequency. This is a value (NOT normalized) that indicates peaks per +second. \ No newline at end of file diff --git a/Documentation/Materials/commands/skyparms.md b/Documentation/Materials/commands/skyparms.md new file mode 100644 index 00000000..d84893b8 --- /dev/null +++ b/Documentation/Materials/commands/skyparms.md @@ -0,0 +1,52 @@ +# Materials: Commands {#mat_commands} +## skyparms +### Overview {#overview} + +**skyParms ** + +Specifies how to use the surface as a sky, including an optional far box +(stars, moon, etc), optional cloud layers with any shader attributes, +and an optional near box (mountains in front of the clouds, etc). Some +of the VMAP specific commands use this as a reference as to what skybox +to use for color, intensity etc. + +The renderer will take it into account only if you do not supply any +Stages in the material. + +**** Specifies a set of files to use as an environment box +behind all cloudlayers. Specify "-" for no farbox, or a file base name. +A base name of "env/test" would look for files "env/test_rt.tga", +"env/test_lf.tga", "env/test_ft.tga", "env/test_bk.tga", +"env/test_up.tga", "env/test_dn.tga" to use as the right / left / front +/ back / up / down sides. + +**** controls apparent curvature of the cloud layers - +lower numbers mean more curvature (and thus more distortion at the +horizons). Higher height values create "flatter" skies with less horizon +distortion. Think of height as the radius of a sphere on which the +clouds are mapped. Good ranges are 64 to 256. The default value is 128. + +**** Specified as farbox, to be alpha blended ontop of the +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} + +`   // Vera Visions Material` +`   {` +`       qer_editorImage textures/skies/dune.tga` +`       skyParms textures/skies/dune/bg 256 -` +`       noPicMip` +`       noMipmaps` +`       ` +`       surfaceParm sky` +`       surfaceParm noimpact` +`       surfaceParm nolightmap` +`       surfaceParm nodlight` +`       {` +`           program skybox` +`           map $cube:textures/skies/dune/bg` +`           map textures/skies/clouds/dunecloud.tga` +`           map textures/skies/clouds/dunecloud_layer.tga` +`       }` +`   }` \ No newline at end of file diff --git a/Documentation/Materials/commands/sort.md b/Documentation/Materials/commands/sort.md new file mode 100644 index 00000000..283d13af --- /dev/null +++ b/Documentation/Materials/commands/sort.md @@ -0,0 +1,53 @@ +# Materials: Commands {#mat_commands} +## sort +### Syntax {#syntax} + +**sort ** + +### 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 +that if there is a question or a problem with materials drawing in the +wrong order against each other, this allows the designer to create a +hierarchy of which materials draws in what order. + +The default behavior is to put all blended materials in sort "additive" +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} + +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): + +- **ripple**: Meant for surfaces blending below water surfaces I + guess. +- **eferredlight**: Blend at the same order as deferred lighting. So + before diffuse mapping usually takes place. +- **portal**: This surface is a portal, it draws over every other + shader seen inside the portal, but before anything in the main view. +- **sky**: Typically, the sky is the farthest surface in the game + world. Drawing this after other opaque surfaces can be an + optimization on some cards. This currently has the wrong value for + this purpose, so it doesn't do much of anything. +- **opaque**: This surface is opaque (rarely needed since this is the + default with noblendfunc) +- **decal**: Blend it like a decal. Ones affected by light, or + something. +- **seethrough**: Not sure what to call this, beyond repeating its + name and it being between decal and unlitdecal. +- **unlitdecal**: Blend it like an unlit decal, this most commonly is + bullet impacts. +- **banner**: Transparent, but very close to walls. +- **underwater**: Draw behind normal transparent surfaces. +- **blend**: Draw like a blendFunc blend transparent surface. +- **additive**: normal transparent surface (default for shaders with + blendfuncs) +- **nearest**: this shader should always sort closest to the viewer, + e.g. muzzle flashes and blend blobs + +It is generally recommended you stick to the keywords. The engine may +introduce new ones and you will benefit from internal sorting parameters +not clashing with yours whenever the engine may update them. \ No newline at end of file diff --git a/Documentation/Materials/commands/specularmap.md b/Documentation/Materials/commands/specularmap.md new file mode 100644 index 00000000..9502654f --- /dev/null +++ b/Documentation/Materials/commands/specularmap.md @@ -0,0 +1,22 @@ +# Materials: Commands {#mat_commands} +## specularmap +### Syntax {#syntax} + +**specularmap ** + +### Overview {#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) +- [normalmap](normalmap) +- [fullbrightmap](fullbrightmap) +- [uppermap](uppermap) +- [lowermap](lowermap) +- [reflectmask](reflectmask) +- [reflectcube](reflectcube) \ No newline at end of file diff --git a/Documentation/Materials/commands/surfaceparm.md b/Documentation/Materials/commands/surfaceparm.md new file mode 100644 index 00000000..e2c3bb60 --- /dev/null +++ b/Documentation/Materials/commands/surfaceparm.md @@ -0,0 +1,296 @@ +# Materials: Commands {#mat_commands} +## surfaceparm +### Overview {#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. + +All surfaceparm keywords are preceded by the word surfaceparm as +follows: + +: + + : surfaceparm **fog** + +### 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} + +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 +a door entity (but is not a part of that entity). The intent is to block +the game from processing surface triangles located behind it when the +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} + +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 +in locations that are natural breaks in a map, such a sentrances to +halls, doors, tunnels, etc. The intent is keep the bot from having to +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} + +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} + +Assigns to the texture the game properties set for lava. This affects +both the surface and the content of a brush. + +#### nodamage {#nodamage} + +The player takes no damage if he falls onto a texture with this +surfaceparm + +#### nosteps {#nosteps} + +The player makes no sound when walking on this texture. + +#### 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} + +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} + +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} + +This surfaceparm included in a texture should give it significantly +reduced friction. + +#### slime {#slime} + +Assigns to the texture the game properties for slime. This affects both +the surface and the content of a brush. + +#### 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 +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} + +Assigns to the texture the game properties for water. + +#### climb {#climb} + +Marks the desired surface as a climbable surface. This currently affects +the entire volume. + +#### vehicleclip {#vehicleclip} + +Blocks all movement of vehicle entities through this surface. + +#### leakssteam {#leakssteam} + +When this surface is impacted, steam will leak out temporarily. Specific +to The Wastes 1.3. + +#### leakswater {#leakswater} + +When this surface is impacted, water will leak out temporarily. Specific +to The Wastes 1.3. + +#### fl_r1 {#fl_r1} + +Reserved for custom games. This can be anything. + +#### fl_r2 {#fl_r2} + +Reserved for custom games. This can be anything. + +#### fl_r3 {#fl_r3} + +Reserved for custom games. This can be anything. + +#### fl_r4 {#fl_r4} + +Reserved for custom games. This can be anything. + +#### fl_r5 {#fl_r5} + +Reserved for custom games. This can be anything. + +#### fl_r6 {#fl_r6} + +Reserved for custom games. This can be anything. + +#### fl_r7 {#fl_r7} + +Reserved for custom games. This can be anything. + +### 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} + +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 +channel as a mask for casting static shadows in the game world. + +Design Note: Alphashadow does not work well with fine line detail on a +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 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} + +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 +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} + +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} + +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} + +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} + +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} + +Projectiles will explode upon contact with this surface, but will not +leave marks. Blood will also not mark this surface. This is useful to +keep lights from being temporarily obscured by battle damage. + +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} + +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} + +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} + +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} + +Defines that the surface is of an 'alien' material. Affects impact sound +and effects. + +#### flesh {#flesh} + +Defines that the surface is of flesh. Affects impact sound and effects. + +#### foliage {#foliage} + +Defines that the surface is foliage. Affects impact sound and effects. + +#### computer {#computer} + +Defines that the surface is of computer parts. Affects impact sound and +effects. + +#### dirt {#dirt} + +Defines that the surface is of dirt. Affects impact sound and effects. + +#### vent {#vent} + +Defines that the surface is a vent. Affects impact sound and effects. + +#### grate {#grate} + +Defines that the surface is a grate. Affects impact sound and effects. + +#### metal {#metal} + +Defines that the surface is of metal. Affects impact sound and effects. + +#### glass {#glass} + +Defines that the surface is of glass. Affects impact sound and effects. + +#### sand {#sand} + +Defines that the surface is of sand. Affects impact sound and effects. + +#### slosh {#slosh} + +Defines that the surface is of a liquid. Affects impact sound and +effects. + +#### snow {#snow} + +Defines that the surface is of snow. Affects impact sound and effects. + +#### tile {#tile} + +Defines that the surface is of kitchen/bathroom tiles. Affects impact +sound and effects. + +#### wood {#wood} + +Defines that the surface is of wood. Affects impact sound and effects. + +#### concrete {#concrete} + +Defines that the surface is of concrete. Affects impact sound and +effects. \ No newline at end of file diff --git a/Documentation/Materials/commands/tcgen.md b/Documentation/Materials/commands/tcgen.md new file mode 100644 index 00000000..fe656f75 --- /dev/null +++ b/Documentation/Materials/commands/tcgen.md @@ -0,0 +1,24 @@ +# Materials: Commands {#mat_commands} +## tcgen +### Syntax {#syntax} + +**tcGen ** + +### Overview {#overview} + +Specifies how texture coordinates are generated and where they come +from. Valid functions are **base**, **lightmap** and **environment**. + +### Sources {#sources} + +#### base {#base} + +Base texture coordinates from the original art. + +#### lightmap {#lightmap} + +Lightmap texture coordinates. + +#### environment {#environment} + +Make this object environment mapped. \ No newline at end of file diff --git a/Documentation/Materials/commands/tcmod.md b/Documentation/Materials/commands/tcmod.md new file mode 100644 index 00000000..51761908 --- /dev/null +++ b/Documentation/Materials/commands/tcmod.md @@ -0,0 +1,132 @@ +# Materials: Commands {#mat_commands} +## tcmod +### Syntax {#syntax} + +**tcMod <…>** + +### Overview {#overview} + +Specifies how texture coordinates are modified after they are generated. + +The valid functions for tcMod are **rotate**, **scale**, **scroll**, +**stretch** and **transform**. + +**Transform** is a function generally reserved for use by programmers +who suggest that designers leave it alone. + +When using multiple **tcMod** functions during a stage, place the scroll +command last in order, because it performs a mod operation to save +precision, and that can disturb other operations. + +Texture coordinates are modified in the order in which **tcMods** are +specified. In otherwords, if you see: + +` tcMod scale 0.5 0.5` +` tcMod scroll 1 1` + +Then the texture coordinates will be **scaled then**scrolled'''. + +### Functions {#functions} + +#### rotate {#rotate} + +This keyword causes the texture coordinates to rotate. The value is +expressed in degrees rotated each second. A positive value means +clockwise rotation. A negative value means counterclockwise rotation. +For example "tcMod rotate 5" would rotate texture coordinates 5 degrees +each second in a clockwise direction. The texture rotates around the +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 {#scale} + +Resizes (enlarges or shrinks) the texture coordinates by multiplying +them against the given factors of and <tScale). The values +"s" and "t" conform to the "x" and "y" values (respectively) as they are +found in the original texture. The values for sScale and tScale are +**NOT** normalized. This means that a value greater than 1.0 will +increase the size of the texture. A positive value less than one will +reduce the texture to a fraction of its size and cause it to repeat +within the same area as the original texture (Note: see +[clampmap](clampmap) for ways to control +this). + +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 {#scroll} + +Scrolls the texture coordinates with the given speeds. The values "s" +and "t" conform to the "x" and "y" values (respectively) as they are +found in the original texture. The scroll speed is measured in +"textures" per second. A "texture" is the dimension of the texture being +modified and includes any previous material modifications to the +original texture). A negative s value would scroll the texture to the +left. A negative t value would scroll the texture down. + +Example: tcMod scroll 0.5 -0.5 moves the texture down and right +(relative to the texture's original coordinates) at the rate of a half +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 {#stretch} + +Stretches the texture coordinates with the given function. Stretching is +defined as stretching the texture coordinate away from the center of the +polygon and then compressing it towards the center of the polygon. + +****: A base value of one is the original dimension of the texture +when it reaches the stretch stage. Inserting other '''values positive or +negative in this variable will produce unknown effects. + +****: This is the measurement of distance the texture will +stretch from the base size. It is measured, like scroll, in textures. A +value of 1 here will double the size of the texture at its peak. + +****: See the explanation for phase under the deform vertexes +keyword. + +****: this is wave peaks per second. + +****: + +- **Sin**: the texture expands smoothly to its peak dimension and then + shrinks smoothly to its valley dimension in a flowing manner. +- **Triangle**: The textures stretch at a constant rate and spend no + appreciable time at the peak or valley points. +- **Square**: The texture is shown at its peak for the duration of the + frequency and then at its valley for the duration of the frequency. +- **Sawtooth**: the texture stretches like a triangle wave until it + reaches a peak, then instantly drops to the valley, as in a square + wave. +- **Inversesawtooth**: this is the reverse of the sawtooth wave. + +#### transform {#transform} + +Transforms each texture coordinate as follows: + +S' = s \* m00 + t \* m10 + t0 T' = s \* m01 + t \* m11 + t1 + +This is for use by programmers. + +#### turb {#turb} + +Applies turbulence to the texture coordinate. Turbulence is a back and +forth churning and swirling effect on the texture. + +The parameters for this are defined as follows: + +- ****: Currently undefined. +- ****: This is essentially the intensity of the + disturbance or twisting and squiggling of the texture. +- ****: See the explanation for phase under the + [deformvertexes](DeformVertexes) + keyword. +- ****: 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. \ No newline at end of file diff --git a/Documentation/Materials/commands/vmap_backmaterial.md b/Documentation/Materials/commands/vmap_backmaterial.md new file mode 100644 index 00000000..ec3f5f1d --- /dev/null +++ b/Documentation/Materials/commands/vmap_backmaterial.md @@ -0,0 +1,21 @@ +# Materials: VMap Commands {#mat_vmap} +## vmap_backmaterial +### Syntax {#syntax} + +**vmap_backMaterial ** + +### Overview {#overview} + +This allows a brush surface to use a different material when you are +inside it looking out. + +By way of example, this would allow a water brush (or other) surfaces to +have a different sort order or appearance when seen from the inside. + +**vmap_backMaterial** only works on brush faces. For this reason, it is +often deprecated in favor of using +[vmap_cloneMaterial](vmap_cloneMaterial) +where the target material contains +[vmap_invert](vmap_invert). + +It can still be useful as a kind of shorthand. \ No newline at end of file diff --git a/Documentation/Materials/commands/vmap_backsplash.md b/Documentation/Materials/commands/vmap_backsplash.md new file mode 100644 index 00000000..890bcb53 --- /dev/null +++ b/Documentation/Materials/commands/vmap_backsplash.md @@ -0,0 +1,16 @@ +# Materials: VMap Commands {#mat_vmap} +## vmap_backsplash +### Syntax {#syntax} + +**vmap_backsplash ** + +### Overview {#overview} + +Controls the percentage of [surface +light](vmap_surfaceLight) backsplash (how +much light the emitting surface hits), as well as the distant away from +the surface of which it is cast. This is really tricky to get right in +tight areas, so put time aside to experiment. + +**The default backsplash amount is 5%, and the default distance is about +16 units.** \ No newline at end of file diff --git a/Documentation/Materials/commands/vmap_basematerial.md b/Documentation/Materials/commands/vmap_basematerial.md new file mode 100644 index 00000000..de11f350 --- /dev/null +++ b/Documentation/Materials/commands/vmap_basematerial.md @@ -0,0 +1,14 @@ +# Materials: VMap Commands {#mat_vmap} +## vmap_basematerial +### Syntax {#syntax} + +**vmap_baseMaterial ** + +### Overview {#overview} + +Copies the vmap_/surfaceparm commands from the specified material into +this one. + +However, if you want to copy the appearance and only specify +compiler-specific modifications, use +[vmap_remapMaterial](vmap_remapMaterial). \ No newline at end of file diff --git a/Documentation/Materials/commands/vmap_bounce.md b/Documentation/Materials/commands/vmap_bounce.md new file mode 100644 index 00000000..87eafd7c --- /dev/null +++ b/Documentation/Materials/commands/vmap_bounce.md @@ -0,0 +1,10 @@ +# Materials: VMap Commands {#mat_vmap} +## vmap_bounce +### Syntax {#syntax} + +**vmap_bounce ** + +### Overview {#overview} + +Specifies the fraction of light to re-emit during a bounce pass on this +surface. \ No newline at end of file diff --git a/Documentation/Materials/commands/vmap_clonematerial.md b/Documentation/Materials/commands/vmap_clonematerial.md new file mode 100644 index 00000000..ef0a1fcf --- /dev/null +++ b/Documentation/Materials/commands/vmap_clonematerial.md @@ -0,0 +1,12 @@ +# Materials: VMap Commands {#mat_vmap} +## vmap_clonematerial +### Syntax {#syntax} + +**vmap_cloneMaterial ** + +### Overview {#overview} + +A material with this directive will inherit the target material's +properties and appearance. **Be careful, this can lead to an infinite +loop if a cloning material references another cloning material or +itself.** \ No newline at end of file diff --git a/Documentation/Materials/commands/vmap_invert.md b/Documentation/Materials/commands/vmap_invert.md new file mode 100644 index 00000000..dddef4f3 --- /dev/null +++ b/Documentation/Materials/commands/vmap_invert.md @@ -0,0 +1,15 @@ +# Materials: VMap Commands {#mat_vmap} +## vmap_invert +### Syntax {#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. + +Can be used with a material that is targeted by +[vmap_cloneMaterial](vmap_cloneMaterial) +for something similar to +[vmap_backMaterial](vmap_backMaterial). \ No newline at end of file diff --git a/Documentation/Materials/commands/vmap_lightimage.md b/Documentation/Materials/commands/vmap_lightimage.md new file mode 100644 index 00000000..7f028a04 --- /dev/null +++ b/Documentation/Materials/commands/vmap_lightimage.md @@ -0,0 +1,16 @@ +# Materials: VMap Commands {#mat_vmap} +## vmap_lightimage +### Syntax {#syntax} + +**vmap_lightImage ** + +### 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 +image to be used for light color emission, radiosity color emission, +light filtering and alpha shadows. You can even use a light image with a +different alpha channel for blurrier alpha shadows. The light color is +averaged from the referenced texture. The texture must be the same size +as the base image map. vmap_lightImage should appear before +qer_editorImage. \ No newline at end of file diff --git a/Documentation/Materials/commands/vmap_lightmapfilterradius.md b/Documentation/Materials/commands/vmap_lightmapfilterradius.md new file mode 100644 index 00000000..ab15280d --- /dev/null +++ b/Documentation/Materials/commands/vmap_lightmapfilterradius.md @@ -0,0 +1,33 @@ +# Materials: VMap Commands {#mat_vmap} +## vmap_lightmapfilterradius +### Syntax {#syntax} + +**vmap_lightmapFilterRadius +** + +### Overview {#overview} + +This is usually used on [light emitting +materials](vmap_surfaceLight) to +approximate finer subdivided lighting. It adds a gaussian blur effect to +the lightmaps of either the material itself, or the surfaces affected by +the material, or both. The values for **** and +**** are measured in world units of filtering +(blurring) of lightmap data cast by any light sources. + +**** Amount of blur set for the material itself +to approximate for the [surface +light's](vmap_surfaceLight) finer +subdivided lighting. It should be set to 0 for sky materials since they +don't have lightmaps. + +****: Amount of blur set for other surfaces +affected by this material's emitted light. It should be set just high +enough to eliminate the "stadium shadow" effect sometimes produced by +[light_environment](light_environment) or to smooth out the +lighting on [surface +lights](vmap_surfaceLight). + +[vmap_lightmapFilterRadius](vmap_lightmapFilterRadius) +should be placed before any light related material directives that you +want it to affect. \ No newline at end of file diff --git a/Documentation/Materials/commands/vmap_lightmapmergable.md b/Documentation/Materials/commands/vmap_lightmapmergable.md new file mode 100644 index 00000000..1c20d573 --- /dev/null +++ b/Documentation/Materials/commands/vmap_lightmapmergable.md @@ -0,0 +1,14 @@ +# Materials: VMap Commands {#mat_vmap} +## vmap_lightmapmergable +### Syntax {#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 +the artifacts occuring on surfaces like terrain where precision issues +might get you black spots along the lightmap seams. Definitely use this +across large collections of surfaces on which you expect smooth +transitions. \ No newline at end of file diff --git a/Documentation/Materials/commands/vmap_lightmapsampleoffset.md b/Documentation/Materials/commands/vmap_lightmapsampleoffset.md new file mode 100644 index 00000000..2635537d --- /dev/null +++ b/Documentation/Materials/commands/vmap_lightmapsampleoffset.md @@ -0,0 +1,13 @@ +# Materials: VMap Commands {#mat_vmap} +## vmap_lightmapsampleoffset +### Syntax {#syntax} + +**vmap_lightmapSampleOffset ** + +### 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 +values (2.0-8.0) if you're getting ugly splotches on lightmapped +terrain. Try to use filtering to solve splotches if possible, leaving +vmap_lightmapSampleOffset as a last resort. \ No newline at end of file diff --git a/Documentation/Materials/commands/vmap_lightmapsamplesize.md b/Documentation/Materials/commands/vmap_lightmapsamplesize.md new file mode 100644 index 00000000..df2691f4 --- /dev/null +++ b/Documentation/Materials/commands/vmap_lightmapsamplesize.md @@ -0,0 +1,15 @@ +# Materials: VMap Commands {#mat_vmap} +## vmap_lightmapsamplesize +### Syntax {#syntax} + +**vmap_lightmapSampleSize ** + +### 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 +produce high-resolution shadows on certain surfaces. In addition, it can +be used to reduce the size of lightmap data, where high-resolution +shadows are not required, gaining memory and performance benefits. The +default sample size is 8, smaller numbers increases lightmap resolution. +In general, you should stick with power of 2 values. \ No newline at end of file diff --git a/Documentation/Materials/commands/vmap_lightrgb.md b/Documentation/Materials/commands/vmap_lightrgb.md new file mode 100644 index 00000000..6b230d8b --- /dev/null +++ b/Documentation/Materials/commands/vmap_lightrgb.md @@ -0,0 +1,12 @@ +# Materials: VMap Commands {#mat_vmap} +## vmap_lightrgb +### Syntax {#syntax} + +**vmap_lightRGB ** + +### Overview {#overview} + +Alternative to [vmap_lightImage (Material +Command)](vmap_lightImage) and the +automatic way of figuring out which light color a specified surface +emits. \ No newline at end of file diff --git a/Documentation/Materials/commands/vmap_lightsubdivide.md b/Documentation/Materials/commands/vmap_lightsubdivide.md new file mode 100644 index 00000000..f876b4d7 --- /dev/null +++ b/Documentation/Materials/commands/vmap_lightsubdivide.md @@ -0,0 +1,15 @@ +# Materials: VMap Commands {#mat_vmap} +## vmap_lightsubdivide +### Syntax {#syntax} + +**q3map_lightSubdivide ** + +### Overview {#overview} + +Used on surface lights (see [vmap_surfaceLight (Material +Command)](vmap_surfaceLight)). Controls +the distance between surface generated light sources for uniform +lighting. It defaults to 120 game units, but can be made larger or +smaller as needed (for light surfaces at the bottom of cracks, for +example). This can be a dominant factor in processing time for lightmap +generation. \ No newline at end of file diff --git a/Documentation/Materials/commands/vmap_nodirty.md b/Documentation/Materials/commands/vmap_nodirty.md new file mode 100644 index 00000000..34989660 --- /dev/null +++ b/Documentation/Materials/commands/vmap_nodirty.md @@ -0,0 +1,10 @@ +# Materials: VMap Commands {#mat_vmap} +## vmap_nodirty +### Syntax {#syntax} + +**vmap_nodirty** + +### Overview {#overview} + +This surface is not affected by dirt-mapping. The compiler baked variant +of ambient occlusion. \ No newline at end of file diff --git a/Documentation/Materials/commands/vmap_offset.md b/Documentation/Materials/commands/vmap_offset.md new file mode 100644 index 00000000..d8dc2fc8 --- /dev/null +++ b/Documentation/Materials/commands/vmap_offset.md @@ -0,0 +1,11 @@ +# Materials: VMap Commands {#mat_vmap} +## vmap_offset +### Syntax {#syntax} + +**vmap_offset ** + +### 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 +version of [polygonOffset](polygonOffset) \ No newline at end of file diff --git a/Documentation/Materials/commands/vmap_remapmaterial.md b/Documentation/Materials/commands/vmap_remapmaterial.md new file mode 100644 index 00000000..7095e21f --- /dev/null +++ b/Documentation/Materials/commands/vmap_remapmaterial.md @@ -0,0 +1,20 @@ +# Materials: VMap Commands {#mat_vmap} +## vmap_remapmaterial +### Syntax {#syntax} + +**vmap_remapMaterial ** + +### Overview {#overview} + +Allows the material to later become known as the specified material. + +These materials should not contain anything but compiler-specific +keywords. + +For example, if you want a material that is **exactly like'' the +specified**vmap_remapMaterial**in appearance, but with a +specific**vmap_''' or surfaceparm characteristics, use this command. + +However, if you want want just a material's vmap_/surfaceparm +properties, use +[vmap_baseMaterial](vmap_baseMaterial). \ No newline at end of file diff --git a/Documentation/Materials/commands/vmap_shadeangle.md b/Documentation/Materials/commands/vmap_shadeangle.md new file mode 100644 index 00000000..9c853eed --- /dev/null +++ b/Documentation/Materials/commands/vmap_shadeangle.md @@ -0,0 +1,11 @@ +# Materials: VMap Commands {#mat_vmap} +## vmap_shadeangle +### Syntax {#syntax} + +**vmap_shadeAngle ** + +### 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 +default shade angle in [VMAP](VMAP) is 40 degrees. \ No newline at end of file diff --git a/Documentation/Materials/commands/vmap_surfacelight.md b/Documentation/Materials/commands/vmap_surfacelight.md new file mode 100644 index 00000000..a56dad75 --- /dev/null +++ b/Documentation/Materials/commands/vmap_surfacelight.md @@ -0,0 +1,24 @@ +# Materials: VMap Commands {#mat_vmap} +## vmap_surfacelight +### Syntax {#syntax} + +**vmap_surfacelight ** + +### 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 +light that appears to be radiated. + +To give off what appears to be the same amount of light, a smaller +texture must be significantly brighter than a larger texture. + +Unless the +[vmap_lightImage](vmap_lightImage) or +[vmap_lightRGB](vmap_lightRGB) directive +is used to select a different source for the texture's light color +information, the color of the light will be the averaged color of the +texture. + +If you want to change the distance/range of the surfacelight, use +[vmap_surfacelightDistance](vmap_surfaceLightDistance). \ No newline at end of file diff --git a/Documentation/Materials/commands/vmap_surfacelightdistance.md b/Documentation/Materials/commands/vmap_surfacelightdistance.md new file mode 100644 index 00000000..eda1c8ca --- /dev/null +++ b/Documentation/Materials/commands/vmap_surfacelightdistance.md @@ -0,0 +1,13 @@ +# Materials: VMap Commands {#mat_vmap} +## vmap_surfacelightdistance +### Syntax {#syntax} + +**vmap_surfaceLightDistance ** + +### Overview {#overview} + +Increases the range of a surfacelight. This is different from increasing +the [vmap_surfaceLight (Material +Command)](vmap_surfaceLight) value, as +it'll travel much wider without affecting the total intensity of the +light. \ No newline at end of file diff --git a/Documentation/Materials/commands/vmap_surfacemodel.md b/Documentation/Materials/commands/vmap_surfacemodel.md new file mode 100644 index 00000000..c1212aa4 --- /dev/null +++ b/Documentation/Materials/commands/vmap_surfacemodel.md @@ -0,0 +1,16 @@ +# Materials: VMap Commands {#mat_vmap} +## vmap_surfacemodel +### Syntax {#syntax} + +**vmap_surfaceModel + ** + +### 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 +tree models over terrain. + +This will bake the models into the .bsp itself, creating an +unnecessarily inflated map. Use [fte_clutter (Material +Command)](fte_clutter) instead. \ No newline at end of file diff --git a/Documentation/Materials/commands/vmap_tesssize.md b/Documentation/Materials/commands/vmap_tesssize.md new file mode 100644 index 00000000..a64afd15 --- /dev/null +++ b/Documentation/Materials/commands/vmap_tesssize.md @@ -0,0 +1,25 @@ +# Materials: Compiler Commands {#mat_vmap} +## vmap_tesssize +### Syntax {#syntax} + +**vmap_tessSize ** + +### Overview {#overview} + +Formely known as just **tessSize**. + +The command controls the tessellation size (how finely a surface is +chopped up in to triangles), in game units, of the surface. + +This is only applicable to solid brushes, not curves, and is generally +only used on surfaces that are flagged with the +[deformVertexes](deformVertexes) keyword. + +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} + +It can also be used on tesselating surfaces to make sure that +tesselations are large, and thus, less costly in terms of triangles +created. \ No newline at end of file diff --git a/Documentation/Models/VVM.md b/Documentation/Models/VVM.md new file mode 100644 index 00000000..dcb56184 --- /dev/null +++ b/Documentation/Models/VVM.md @@ -0,0 +1,79 @@ +# Models: VVM +**Vera Visions Model**, also known as **VVM** or **IQM-FTE** is the main +skeletal model format. + +## Features {#features} + +Features that the original IQM exporter (by Lee Salzman) did not offer: + +- Support for external configuration files for IQM generation (ala + studiomdl) +- Pre-processor for rotating single or all input files +- Pre-processor for translating/repositioning single or all input + files +- Pre-processor for renaming bones inside a single or all input files +- Pre-processor for material prefixes inside a single or all input + files + +Some features that our extended specification (VVM) has to offer: + +- Support for hitmeshes for faster, content-aware collision detection +- Automatic hitmesh generation +- Submodels that allow showing/hiding specific groups of the model via + the game-logic +- Support for frame triggered events that can be read by the + game-logic (model-events) +- Level-of-detail range flag for references/sub-models +- User-defined surface and contentflags per reference/sub-model + +**NOTE: Using any of the VVM features is not supported in any engine +other than FTEQW** + +The tool's output will let you know if you're outputting an IQM +compatible file or not. + +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} + +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. +However we needed a better system for handling reproducible output +files. The original tool only handled compilation via plain command-line +parameters which was not good enough. + +The input command file (.qc) syntax is obviously inspired by qdata and +other tools such as studiomdl. So if you're familiar with those tools +you know exactly what to expect. + +We then went on and designed extensions that we needed to make the game +work, for example a generic model-events system that'd call events in +the game-logic when a certain key-frame in the model is displayed. + +More complicated things were hit-meshes, for more accurate hit detection +of body parts as well as sub-models that made the action of shooting +body-parts off possible. + +We developed this together with David of FTEQW, since this had to be +developed in conjunction with the FTEQW built-ins that'd later be +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} + +You can grab a binary build of FTE [1](https://www.fteqw.org/) +(basically a generic, non The Wastes specific version) and use the +'modelviewer' command in the console. The console can be opened via +Shift+ESC. + +If you want to see for example the Winston viewmodel, type *modelviewer +models/weapons/v_winchester.vvm* + +## External links {#external_links} + +[ vvmtool on +GitHub](https://github.com/VeraVisions/vvmtool) \ No newline at end of file diff --git a/Documentation/Models/VVM_Tutorial.md b/Documentation/Models/VVM_Tutorial.md new file mode 100644 index 00000000..2dcc7580 --- /dev/null +++ b/Documentation/Models/VVM_Tutorial.md @@ -0,0 +1,150 @@ +# Models: VVM Tutorial +## Introduction {#introduction} + +As you already know, the VVM exporter (vvmtool) takes inspiration from +Valve's **studiomdl** in terms of usage. There are *slight* syntax +differences, primarily because the way some features are implemented +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} + +Any .vvm consists of multiple input files. These can come in the +following formats: + +- SMD (GoldSrc & Source) +- MD5MESH and MD5ANIM (idTech 4) +- FBX +- IQE +- OBJ (no animations) + +Make sure that when you use animated files, that the bone naming and +bone order is consistent among them. + +## Control File {#control_file} + +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 +input data. Many of these features would **not be possible** with an +internal, modeling program specific exporter for VVM. + +Here's an EXCERPT of a control file from **The Wastes*: + + output tommygun.vvm + materialprefix models/weapons/tommygun/ + + bone "Bone55" rename "Muzzleflash" + + scene ref/tommygun.smd + rotate 0 -90 0 + + scene seq/idle.smd fps 20.0 + scene seq/idle_empty.smd fps 20.0 + + event 0 1004 "weapons/tommygun/draw.wav 1" + scene seq/draw.smd fps 25.0 + + event reset + event 0 1004 "weapons/tommygun/draw.wav 1" + scene seq/draw_empty.smd fps 25.0 + + event reset + event 0 1004 "weapons/tommygun/holster.wav 1" + scene seq/holster.smd fps 30.0 + + event reset + event 0 1004 "weapons/tommygun/holster.wav 1" + scene seq/holster_empty.smd fps 30.0 + + origin 0 -32 0 + + event reset + event 14 1004 "weapons/tommygun/clipout.wav 1" + event 48 1004 "weapons/tommygun/clipin.wav 1" + scene seq/reload_not_empty.smd fps 22.0 + event 64 1004 "weapons/tommygun/bolt.wav 1" + scene seq/reload.smd fps 22.0 + + origin 0 0 0 + + event reset + event 0 1001 "33 models/effects/muzzleflash/muzzleflash2.vvm" + event 0 1002 "3 40 0 70" + event 0 1005 "33 1" + scene seq/shoot.smd fps 30.0 + scene seq/shoot_last.smd fps 30.0 + ... + +That's a really complicated control file, but it highlights a few +things: + +- You can specify as many events as you like... +- and apply them to as many scenes as you want. +- Creating an interface for a dedicated, in-modeling-program exporter + would be unfeasible. +- You can run commands to fix existing model input files after the + fact, like bone renaming... +- ... and even rotation, scaling and origin re-adjusting (on a + per-input-file basis!) +- The **origin** command is absolute, so set it to '0 0 0' to reset + +However, a model control file doesn't need to be this complicated: + + output terminal01.vvm + materialprefix models/props/computers/ + rotate 0 -90 0 + scene ref/terminal01.smd + +This is `models/props/computers/terminal01.qc` from The Wastes. + +What each line means: + +`output` specifies the resulting final output file name and location +relative to the control file. + +`materialprefix` just appends this string to any referenced material. +Ideally it's the location where the .vvm itself is stored in your game +filesystem. + +`rotate` Simply rotates all input files by 90 degrees on the Y/Yaw axis +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} + +You grab your copy of **vvmtool** and you either drag +and drop your control file onto it, or run it via command-line: + +`vvmtool.exe foobar.qc` + +It should be as simple as that! + +## Notes {#notes} + +Some helpful tips for your content creation journey. + +### vid_reload {#vid_reload} + +I recommend getting a single reference, plus the animations into your +game first, then adding events and other necessary commands on top. + +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} + +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. + +**This is a problem with the Blender exporter, not vvmtool (as it also +won't work in studiomdl).** + +So if your bones seem completely messed up, try .fbx instead. + +If you absolutely need to use .smd, export it as .fbx in Blender, import +said output back into Blender and then export as .fbx. \ No newline at end of file diff --git a/doc/mods b/Documentation/Mods.md similarity index 83% rename from doc/mods rename to Documentation/Mods.md index edabc6cd..be755bc1 100644 --- a/doc/mods +++ b/Documentation/Mods.md @@ -1,5 +1,4 @@ -Mod loading and setting up games -================================ +# Mod/Game Setup For mods to show up in the "Custom Game" menu, we have to either find a manifest file, or a liblist.gam, or a gameinfo.txt inside the respective mod directory. @@ -11,10 +10,12 @@ restricting that. A liblist.gam file can look something like this: -game "My Cool Mod" -version "1.0" -startmap "e1m1" -trainingmap "traininglevel" +``` + game "My Cool Mod" + version "1.0" + startmap "e1m1" + trainingmap "traininglevel" +``` But more definitions are available. Check src/menu-fn/m_customgame.qc's customgame_liblist_parse() function to stay @@ -31,10 +32,12 @@ If you need more control, you can use manifest files. Similar to the default.fmf that's in the root Nuclide source tree. You can set liblist entries like this inside of them: --set gameinfo_game "My Cool Mod" --set gameinfo_version "1.0" --set gameinfo_startmap "e1m1" --set gameinfo_trainingmap "traininglevel" +``` + -set gameinfo_game "My Cool Mod" + -set gameinfo_version "1.0" + -set gameinfo_startmap "e1m1" + -set gameinfo_trainingmap "traininglevel" +``` Please name the manifest the same as the mod/game dir. For example if your game its directory is named "foobar" name your manifest "foobar.fmf". diff --git a/Documentation/Sound/EAX.md b/Documentation/Sound/EAX.md new file mode 100644 index 00000000..20447bb3 --- /dev/null +++ b/Documentation/Sound/EAX.md @@ -0,0 +1,12 @@ +# Sound: 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. + + +Due to the release of Windows Vista which deprecated the DirectSound3D API EAX was based on in 2007, Creative discouraged EAX implementation in favor of its [OpenAL](OpenAL.md)-based EFX equivalent. + + +EFX is fully supported in **FTEQW** and exposed via user-friendly entities and scripting language in **Nuclide**. + +## See also +* [EFX](EFX.md) +* [OpenAL](OpenAL.md) diff --git a/Documentation/Sound/EFX.md b/Documentation/Sound/EFX.md new file mode 100644 index 00000000..3bcf66d6 --- /dev/null +++ b/Documentation/Sound/EFX.md @@ -0,0 +1,87 @@ +# Sound: EFX + +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). + +**Nuclide** offers abstraction for new and old entities relying on **digital signal processing**. + +## Entities + +**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 file in the filesystem. + +## EFX files + +Entities that specify a EFX type, usually want to load one from a file. + +Here's an example one, `efx/city.efx`: + +``` + density "1.000000" + diffusion "0.500000" + gain "0.316200" + gain_hf "0.398100" + gain_lf "1.000000" + decay_time "1.490000" + decay_hf_ratio "0.670000" + decay_lf_ratio "1.000000" + reflections_gain "0.073000" + reflections_delay "0.007000" + reflections_pan "0 0 0" + late_reverb_gain "0.142700" + late_reverb_delay "0.011000" + late_reverb_pan "0 0 0" + echo_time "0.250000" + echo_depth "0.000000" + modulation_time "0.250000" + modulation_depth "0.000000" + air_absorbtion_hf "0.994300" + hf_reference "5000.000000" + lf_reference "250.000000" + room_rolloff_factor "0.000000" + decay_limit "1" +``` + +Most of the parameters are self explanatory. + +## Debug cvars + +With the cvar `>s_al_debug` 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 simple map restart. + + +## Legacy translation table +Here you can see which **.efx file** is responsible for handling a legacy **env_sound** room-type. + +**roomtype ID**|**EFX file** +:-----:|:-----: +0|efx/default.efx +1|efx/gs\_generic.efx +2|efx/gs\_metal\_s.efx +3|efx/gs\_metal\_m.efx +4|efx/gs\_metal\_l.efx +5|efx/gs\_tunnel\_s.efx +6|efx/gs\_tunnel\_m.efx +7|efx/gs\_tunnel\_l.efx +8|efx/gs\_chamber\_s.efx +9|efx/gs\_chamber\_m.efx +10|efx/gs\_chamber\_l.efx +11|efx/gs\_bright\_s.efx +12|efx/gs\_bright\_m.efx +13|efx/gs\_bright\_l.efx +14|efx/gs\_water1.efx +15|efx/gs\_water2.efx +16|efx/gs\_water3.efx +17|efx/gs\_concrete\_s.efx +18|efx/gs\_concrete\_m.efx +19|efx/gs\_concrete\_l.efx +20|efx/gs\_big1.efx +21|efx/gs\_big2.efx +22|efx/gs\_big3.efx +23|efx/gs\_cavern\_s.efx +24|efx/gs\_cavern\_m.efx +25|efx/gs\_cavern\_l.efx +26|efx/gs\_weirdo1.efx +27|efx/gs\_weirdo2.efx +28|efx/gs\_weirdo3.efx \ No newline at end of file diff --git a/Documentation/Sound/SoundDefs.md b/Documentation/Sound/SoundDefs.md new file mode 100644 index 00000000..e09d4988 --- /dev/null +++ b/Documentation/Sound/SoundDefs.md @@ -0,0 +1,86 @@ +# Sound: soundDef +Nuclide mimics the sound defintion spec from **idTech 4** somewhat, albeit +with some changes/enhancements. We call them **soundDefs**. + +**The elevator pitch**: To allow for more control over the sounds than what was previously +allowed in idTech engines we also allow designers to drop sounds into +the game without having to set some common parameters every time. + +Instead of directly calling which .wav or .ogg file to play, we tell it +to play the single name of a sound def. For example: +*c1_sentry_loader_in* which can be located in **any** text file ending +with the **.sndshd** file extension inside the `sound/` directory. + +``` + c1_sentry_loader_in + { + dist_min 10 + dist_max 25 + + no_occlusion + volume 0.25 + + sample sound/movers/comm1/sentry_loader_in.wav + } +``` + +![Attenuation Visualisation](sounds_attenuation.png "Attenuation") +- dist_min / dist_max sets the radius where the sound fades out. The + sound is at maximum volume inside 'dist_min' radius, and it + completely silent after 'dist_max' radius. +- The no_occlusion key tells the engine not to take level geometry in + to account when calculating volume. +- 'volume' is the volume inside the inner radius of the sound. +- The last line sets the actual sound file to play. + +Let's take a look at another one: + +``` + emetal_impacts + { + dist_min 5 + dist_max 45 + volume 0.5 + + sample sound/impact/ambient_impacts/emetal_01.wav + sample sound/impact/ambient_impacts/emetal_02.wav + sample sound/impact/ambient_impacts/emetal_03.wav + sample sound/impact/ambient_impacts/emetal_04.wav + sample sound/impact/ambient_impacts/emetal_05.wav + } +``` + +This one has multiple sound files specified, which means that **Nuclide** will randomly choose one to play. + +## Commands {#commands} + +| | | | +|-----------------|-------------------------|-------------------------------------------------------------------------------------------------------------| +| **Key** | **Value** | **Description** | +| attenuation | idle/static/none/normal | Changes the sound's attenuation, aka playback radius/distance. This essentially just changes **dist_max**. | +| dist_min | | Sets the minimum playback distance in quake units. | +| dist_max | | Sets the maximum playback distance in quake units. | +| volume | | Sets the playback volume. 0.0 - 1.0 range. | +| shakes | | Will shake the screen with an intensity specified. Play around with this, 256 is a good starting value. | +| pitch | | Will set a specific pitch change. 0.0 - 2.0 range most commonly, but there's wiggle room. | +| pitch_min | | Will set a minimum pitch instead of an exact one. This means it'll play a random pitch between min and max. | +| pitch_max | | Will set a maximum pitch instead of an exact one. This means it'll play a random pitch between min and max. | +| offset | | Sound sample offset in seconds. | +| looping | none | Sound set to force loop, regardless of sound markers in file. | +| nodups | none | Don't play duplicate samples in sequence. | +| global | none | Play samples everywhere. | +| private | none | Play samples privately onto the entity that it gets played on. | +| no_reverb | none | Disable any [EAX](/EAX "wikilink") on samples in this def. | +| omnidirectional | none | Samples won't play from any particular direction. | +| follow | none | Samples will move alongside the entity it's being played on | +| footstep | none | Determines sample volume based upon the speed of the entity. | +| distshader | | Which sound def to play to everyone who is out of playback reach of this one. | +| sample | | Adds a sample to play to the list. Will only play one at a time. | + +## Power to the developer {#power_to_the_developer} + +Unlike the implementation in **idTech 4**, all of the sound defs handling +is done in the game-logic and is therefore exposed to all developers. +Some mods may want to hook AI callbacks into the system, or create +visual effects when commands are called by a sound def. The +possibilities are endless! \ No newline at end of file diff --git a/Documentation/Sound/sounds_attenuation.png b/Documentation/Sound/sounds_attenuation.png new file mode 100644 index 00000000..cb8a9235 Binary files /dev/null and b/Documentation/Sound/sounds_attenuation.png differ diff --git a/Documentation/Support.md b/Documentation/Support.md new file mode 100644 index 00000000..ba2de40f --- /dev/null +++ b/Documentation/Support.md @@ -0,0 +1,18 @@ +# Support + +If you require assistance that involves the internals of Nuclide itself (as in, you have already gotten it running) and need someone to talk to about it - there's a few places where we all gather and talk about this project as well as sub-projects and related projects. + +## Matrix +This is the default for us. [You can find a dedicated **Space** right here.](https://matrix.to/#/#nuclide:matrix.org) + +## Internet Relay Chat +This is our fallback. It is also bridged with the general room on Matrix. + +You can connect to irc.libera.chat and join #nuclide. + +## Commercial Support + +While the code is free - both in price and in license, our time is not. +If you require support that involves more than what the documentation here offers, reach out over at . + +While we are a tiny team, and need to be compensated, keep your expectations reasonable as to the level of support we can provide - especially with only one programmer. \ No newline at end of file diff --git a/doc/fte.svg b/Documentation/fte.svg similarity index 100% rename from doc/fte.svg rename to Documentation/fte.svg diff --git a/doc/idtech.svg b/Documentation/idtech.svg similarity index 100% rename from doc/idtech.svg rename to Documentation/idtech.svg diff --git a/Documentation/openal.svg b/Documentation/openal.svg new file mode 100644 index 00000000..8553eb03 --- /dev/null +++ b/Documentation/openal.svg @@ -0,0 +1,85 @@ + + + image/svg+xml diff --git a/Documentation/opengl.svg b/Documentation/opengl.svg new file mode 100644 index 00000000..43b80a76 --- /dev/null +++ b/Documentation/opengl.svg @@ -0,0 +1,85 @@ + + + image/svg+xml diff --git a/doc/release-readme b/Documentation/release-readme.txt similarity index 91% rename from doc/release-readme rename to Documentation/release-readme.txt index 8ed527ec..1239595b 100644 --- a/doc/release-readme +++ b/Documentation/release-readme.txt @@ -19,7 +19,7 @@ Make sure you're running the latest version of FTEQW. If your entire engine/binary crashes to desktop or whatever, it's an FTE bug. Contact #fte at irc.quakenet.org -If you crash to console, contact #freecs at irc.freenode.net +If you crash to console, contact #freecs at irc.libera.chat Notes ======================================= diff --git a/Documentation/vulkan.svg b/Documentation/vulkan.svg new file mode 100644 index 00000000..21aed0d7 --- /dev/null +++ b/Documentation/vulkan.svg @@ -0,0 +1,116 @@ + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + diff --git a/Doxyfile b/Doxyfile index 5a6fcd99..cbdac6d6 100644 --- a/Doxyfile +++ b/Doxyfile @@ -32,7 +32,7 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = "Nuclide" +PROJECT_NAME = Nuclide # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version @@ -44,7 +44,7 @@ PROJECT_NUMBER = # for a project that appears at the top of each page and should give viewer a # quick idea about the purpose of the project. Keep the description short. -PROJECT_BRIEF = +PROJECT_BRIEF = "Software Development Kit for id Tech" # With the PROJECT_LOGO tag one can specify a logo or an icon that is included # in the documentation. The maximum height of the logo should not exceed 55 @@ -58,7 +58,7 @@ PROJECT_LOGO = # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = ./doc +OUTPUT_DIRECTORY = ./Documentation # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and @@ -68,7 +68,7 @@ OUTPUT_DIRECTORY = ./doc # performance problems for the file system. # The default value is: NO. -CREATE_SUBDIRS = NO +CREATE_SUBDIRS = YES # If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII # characters to appear in the names of generated files. If set to NO, non-ASCII @@ -244,7 +244,7 @@ SEPARATE_MEMBER_PAGES = NO # uses this value to replace tabs by spaces in code fragments. # Minimum value: 1, maximum value: 16, default value: 4. -TAB_SIZE = 4 +TAB_SIZE = 8 # This tag can be used to specify a number of aliases that act as commands in # the documentation. An alias has the form: @@ -463,7 +463,7 @@ LOOKUP_CACHE_SIZE = 0 # DOT_NUM_THREADS setting. # Minimum value: 0, maximum value: 32, default value: 1. -NUM_PROC_THREADS = 1 +NUM_PROC_THREADS = 4 #--------------------------------------------------------------------------- # Build related configuration options @@ -489,7 +489,7 @@ EXTRACT_PRIVATE = YES # methods of a class will be included in the documentation. # The default value is: NO. -EXTRACT_PRIV_VIRTUAL = NO +EXTRACT_PRIV_VIRTUAL = YES # If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal # scope will be included in the documentation. @@ -874,7 +874,22 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = src/ +INPUT = src/ \ + Documentation/Main.md \ + Documentation/Building.md \ + Documentation/Filesystem.md \ + Documentation/Mods.md \ + Documentation/Materials/mat_overview.md \ + Documentation/Materials/mat_commands.md \ + Documentation/Materials/mat_vmap.md \ + Documentation/Materials/commands/ \ + Documentation/Materials/mat_shaders.md \ + Documentation/Materials/mat_legacy.md \ + Documentation/Sound/ \ + Documentation/Models/ \ + Documentation/History.md \ + Documentation/Contributing.md \ + Documentation/Support.md # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -903,7 +918,9 @@ INPUT_ENCODING = UTF-8 # comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd, # *.vhdl, *.ucf, *.qsf and *.ice. -FILE_PATTERNS = *.qc *.h +FILE_PATTERNS = *.qc \ + *.h \ + *.md # The RECURSIVE tag can be used to specify whether or not subdirectories should # be searched for input files as well. @@ -918,7 +935,12 @@ RECURSIVE = YES # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE = src/engine src/worldspawn src/vvmtool +EXCLUDE = src/engine \ + src/worldspawn \ + src/vvmtool \ + src/menu-vgui \ + src/menu-fn \ + src/plugins # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded @@ -934,7 +956,12 @@ EXCLUDE_SYMLINKS = NO # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories for example use the pattern */test/* -EXCLUDE_PATTERNS = */src/engine/* */src/worldspawn/* */src/vvmtool/* +EXCLUDE_PATTERNS = */src/engine/* \ + */src/worldspawn/* \ + */src/vvmtool/* \ + */src/menu-fn/* \ + */src/menu-vgui/* \ + */src/plugins/* # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the @@ -971,7 +998,8 @@ EXAMPLE_RECURSIVE = NO # that contain images that are to be included in the documentation (see the # \image command). -IMAGE_PATH = +IMAGE_PATH = Documentation/Materials/ \ + Documentation/Sound/ \ # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program @@ -1027,7 +1055,7 @@ FILTER_SOURCE_PATTERNS = # (index.html). This can be useful if you have a project on for instance GitHub # and want to reuse the introduction page also for the doxygen output. -USE_MDFILE_AS_MAINPAGE = +USE_MDFILE_AS_MAINPAGE = Main.md #--------------------------------------------------------------------------- # Configuration options related to source browsing @@ -1521,7 +1549,7 @@ DISABLE_INDEX = NO # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. -GENERATE_TREEVIEW = NO +GENERATE_TREEVIEW = YES # When both GENERATE_TREEVIEW and DISABLE_INDEX are set to YES, then the # FULL_SIDEBAR option determines if the side bar is limited to only the treeview @@ -2240,7 +2268,9 @@ INCLUDE_FILE_PATTERNS = # recursively expanded use the := operator instead of the = operator. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -PREDEFINED = SERVER CLIENT MENU +PREDEFINED = SERVER \ + CLIENT \ + MENU # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The diff --git a/README.md b/README.md index f7b89dcc..43e20b04 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# ![FTE Logo](doc/fte.svg) Nuclide - Software Development Kit +# ![FTE Logo](Documentation/fte.svg) Nuclide - Software Development Kit Software Development Kit, built around idTech with focus on advanced features and clean-room implementations of true-and-tested game-logic frameworks. @@ -101,7 +101,7 @@ David Walton for **FTEQW** and the **FTEQCC** compiler, which is the brain of th Timothee Besset and the **GtkRadiant** contributors, as well as the NetRadiant team for giving us a base for our editor **WorldSpawn**. -![idTech Logo](doc/idtech.svg) +![idTech Logo](Documentation/idtech.svg) ## License Copyright (c) 2016-2022 Vera Visions L.L.C. diff --git a/doc/about b/doc/about deleted file mode 100644 index 46044562..00000000 --- a/doc/about +++ /dev/null @@ -1,34 +0,0 @@ -About Nuclide - -The Nuclide project produces a freely available game-logic component and -development platform on top of FTEQW; which is the engine we use. -Our goals is to create a modern research base for new advancements, as well -as to have a stable base with a good API for games. - -- Client-side predicted movement and inputs for things like weapons-systems -- Lots of well documented objects to use in level formats supported by FTEQW -- Reference implementations for a lot of features exlusive to FTEQW compared - to other idTech engines -- Designed to be familar to developers who're used to GoldSrc and Source engine - projects - -1. Why might I want to use it? - -You want to develop a game using a lot of complex and well-tested objects -which might be tedious to implement on your own. -You want to run or make modifications for a game using Nuclide and need full -control over what you can do. - -2. How free is Nuclide? - -Everything in Nuclide is free. The copyright terms for the game-logic are -very permitting. Nuclide does not use the GPL as a point of reference, it -instead uses a ISC-like license. This means you can use, copy, modify and -distribute the code and work resulting from it for any purpose. -Please read the very short 'license' document for details. - -3. What are the alternatives? - -Implementing systems such as prediction, complex map objects and entities on -your own or licensing another engine such as Source that ships with its own -Source SDK Base. diff --git a/doc/building b/doc/building deleted file mode 100644 index c8bab155..00000000 --- a/doc/building +++ /dev/null @@ -1,48 +0,0 @@ -Building the engine and toolchain: -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, make and the X/SDL -headers for your operating system. - -Building the editor: -Handled by build_editor.sh. -GTK2, Pango, GTKGLEXT and MiniZip are one of a few other main dependencies. - -Building the game-logic: -Once build_engine.sh has been executed, you can now build the source tree with -build_game.sh. It'll use the fteqcc binary that's in the ./bin/ directory. - -Old, manual build instructions: -================================================================================ - -1. Building all of the game-logic - -To build the game-logic for all games, issue 'make' inside the src/ -directory of the repository. This requires you to have the latest -fteqcc installed. - -2. Building a specific game or mod - -For that you'll have to navigate into the client and server directory -of the game you want to compile. For example if you're only wanting to -build the Half-Life game-logic, navigate into src/client/valve, issue -'make' there, then do the same inside src/server/valve. - -3. Building the engine - -The engine is not part of this project. -However, as of this writing, building the engine is simple. -Checkout/Clone the FTEQW engine repository, then navigate into the -engine/ sub-directory and issue 'make m-rel' there. -This will generate a 'fteqw' binary for your platform in the sub-directory -titled 'release'. - -3. Building fteqcc - -Issue 'make qcc-rel' in the FTEQW repository folder 'engine', like in 3. -It will generate an fteqcc binary inside the sub-directory 'release'. - -4. Misc notes - -To those not in the know, 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 result will be identical. diff --git a/doc/contributing b/doc/contributing deleted file mode 100644 index b65930f1..00000000 --- a/doc/contributing +++ /dev/null @@ -1,17 +0,0 @@ -NUCLIDE CODEBASE CONTRIBUTING RULES - -1. The code must be yours. - -It's simple: Do not take GPL code. Do not take Half-Life SDK code. -We do not decompile, we reverse-engineer by trial and error. -Also referred to as 'clean-room engineering'. -Most of the behaviour is rather predictable, other is not. - -2. Game specific features need to be put into game-specific directories. - -Unless other games benefit from this, keep it seperate to one of the game -sub-directories. - -That's about it. - -Join us on #nuclide at irc.libera.chat diff --git a/doc/filesystem b/doc/filesystem deleted file mode 100644 index 8c946c3c..00000000 --- a/doc/filesystem +++ /dev/null @@ -1,36 +0,0 @@ -NUCLIDE FILESYSTEM DOCUMENTATION - -The 'nuclide' shell script is the launcher. -It sets PATH to include the directory 'bin' which contains the engine that -you've built with build_engine.sh. - -When nuclide is run and executes the engine, it'll first read default.fmf which -is a manifest file the engine reads. It is updated occasionally. -It defines which folders to mount in the virtual filesystem of the engine -and has a document entirely dedicated to itself. For that please read: - src/engine/specs/fte_manifests.txt - -On its own, Nuclide launches the game 'base', unless you tell it otherwise: -./nuclide -game mygame -You can also load multiple additional folders in a specific order by specifying -multiple '-game' arguments. - -Will load 'mygame' instead of base. -It will still load the other 'BASEGAME' entries listed in the default.fmf. -You can even load your own manifest file over default.fmf, by passing - ./nuclide -manifest mymanifest.fmf - -Once the game has loaded, it'll load the persistent menu.dat into our QuakeC -progs VM. -It' always running, you can make your own by forking src/menu-fn, src/menu-vgui -or write something from scratch. - -When a game is mounted, we're either looking for loose files (loaded last), or -pak archives the engine supports. Plain .pak, or zip archives with the pk3 or -pk4 extensions are supported. -Folders with the .pk3dir extensions are treated as if they were .pk3 files. -The editor also supports .pk3dir folders. - -Nuclide contains many custom definition files that are not engine specific. -.efx, .font, .sndshd and .way to name a few. -The engine doesn't really read them, the game-logic mostly handles them. diff --git a/doc/hlmaterials b/doc/hlmaterials deleted file mode 100644 index 2a720be7..00000000 --- a/doc/hlmaterials +++ /dev/null @@ -1,57 +0,0 @@ -hlmaterials - Nuclide Documentation -Written by Gethyn ThomasQuail, 6th April 2021 - -This document gives a general overview of what the materials.txt files is, -and how it's used in Nuclide, and why the decisions were chosen for the -current implementation. It is not an in-depth explanation of the format -itself. - -The materials.txt is how the GoldSrc engine defined sounds for various -textures throughout the game. For example, crates make "wood" sounds, -vents produce metallic feedback, etc. It is an analogue to surfaceparms -for those familiar with idTech engines, this was just Valve Software's -way of doing it before adopting standards. - -In stock Half-Life, this file is located at: - -sounds/materials.txt - -It is allowed to be overwritten by a modification, and users could customize -the file on the client-side only for themselves. This means there was no -map specific materials, and mods could not inherit HL's materials, so -mods would always have to manage a nearly duplicate file if they desired -custom texture sounds. - -A few mods tried to remedy this problem, the following below is methods -documented so far: - -- maps/MAPNAME.mat -Introduced in The Wastes. - -- maps/MAPNAME_materials.txt -Convention by Andrew Lucas, creator of Trinity SDK, modeled after -MAPNAME_details.txt - -- materials_file "PATH/FILE.txt" via "worldspawn" entity -Introduced in Sven Co-op 5.0 - -All these methods are supported by Nuclide, as one goal is to implement -conventions by not only Valve but the community as well. - -In addition Nuclide has also implemented a way of giving modifications -their own inheritable materials file: - -sounds/materials_UNIQUENAME.txt - -The idea here is that any mod or even map pack can include ONLY the textures -used, and no longer will anyone have to manage a near-clone of materials.txt - -For repackaging or modding purposes, if you desire to give your map custom -sound definitions, we recommend The Wastes method for individual maps, while -the Nuclide method should be used for Mods or Map Packs. We find these to be -the most clean and efficient way. - -NOTE: We recommend only using materials text files for GoldSrc related modding -purposes. It is inefficient for modern projects as there are much better -standards already supported in Nuclide. Keep in mind, it takes memory to load -big text files, and lots of text files adds up over play sessions.