Add some markdown docs i wrote (#350)

Author: erysdren

specs/changelevels.md

@@ -0,0 +1,120 @@
+
+The FTEQW engine offers many improvements in changelevel functionality over the
+original Quake engine from 1996. In the original engine, your only way to send
+player data across a level transition was through the `parm` globals in the
+QuakeC server code, which meant you had exactly 16 floating-point numbers to
+use to store any data the players needed to remember across a level change.
+Everything else about the player's state was dropped. This worked well enough
+for Quake, but is severely limiting if you need to send anything that couldn't
+fit into a `float`.
+
+Not only does FTEQW offer 64 `parm` globals instead of 16 (for DarkPlaces
+compatibility), it also has a `parm_string` global which can store a
+theoretically unlimited amount of string or buffer data. In this document I'll
+show you how I decided to use it for my projects.
+
+When the player spawns in a level for the first time, the function
+`SetNewParms()` is called in the SSQC progs. This is where you set the default
+`parm` values for every player that spawns in a level. For example, let's say
+that `parm1` is going to store the player's health value across a level change.
+You would set the default health value like so:
+
+```c
+void() SetNewParms =
+{
+	parm1 = 100;
+};
+```
+
+When the engine is sending the players through a level transition, it calls the
+function `SetChangeParms()` for each player entity in sequence. For storing the
+player's health, you would do it like so:
+
+```c
+void() SetChangeParms =
+{
+	parm1 = self.health;
+};
+```
+
+But, as stated before, this can get rather limiting if the player has data that
+doesn't fit into a floating point number, such as a dynamic inventory of items
+and weapons or an stats tree or something. This is where `parm_string` comes
+in. If you're using a modern version of FTEQW and the FTEQCC compiler, you also
+have access to several JSON parsing builtins. We will be using these to make
+the usage of `parm_string` easier.
+
+If we wanted to store more complex data in `parm_string`, the default value for
+it should be a valid empty JSON node, like so:
+
+```c
+void() SetNewParms =
+{
+	parm1 = 100;
+	parm_string = "{}";
+};
+```
+
+And when `SetChangeParms()` is called, you will write your extended data as
+valid JSON entries in `parm_string`, like so:
+
+```c
+void() SetChangeParms =
+{
+	parm1 = self.health;
+	parm_string = strcat(
+		"{\"some_extended_field_string\":\"",
+		self.some_extended_field_string,
+		"\"}"
+	);
+};
+```
+
+Note we are using the `strcat()` builtin to construct our JSON string rather
+than `sprintf()`, because `sprintf()` seems to have some difficulties with very
+long strings.
+
+The above code will store a per-player string value called
+`some_extended_field_string` into `parm_string` for storage across the level
+transition. Ideally you'd wanna make some helper functions to easily write and
+format your JSON, but this is just a basic example that constructs it directly.
+
+Now the interesting part comes when it's time to read the data back. You'd want
+to do this in the function `PutClientInServer()` after setting up your
+fundamental player class, like so:
+
+```c
+void() PutClientInServer =
+{
+	// setup fundamental player state
+	self.takedamage = DAMAGE_YES;
+	self.solid = SOLID_SLIDEBOX;
+	self.movetype = MOVETYPE_WALK;
+	self.fixangle = TRUE;
+	setsize(self, [-16, -16, -36], [16, 16, 36]);
+	self.flags |= FL_CLIENT;
+	self.view_ofs = [0, 0, 28];
+	self.classname = "player";
+
+	// load health value from parm1
+	self.health = parm1;
+
+	// parse parm_string as json
+	jsonnode root = json_parse(parm_string);
+	if (!root)
+		error("couldn't decode parm_string as JSON!");
+
+	// check if we have the field
+	// if so, copy it out as a string
+	if (root["some_extended_field_string"])
+		self.some_extended_field_string = root["some_extended_field_string"].s;
+
+	// clean up
+	json_free(root);
+};
+```
+
+You don't have to use `parm_string` as JSON, though. You could just print the
+values as space-separated tokens and use the `tokenize()` or
+`tokenize_console()` builtins to read them back. Either way, it's a good method
+for storing lots of custom data across level transitions. Enjoy!

specs/glsl.md

@@ -0,0 +1,99 @@
+
+FTEQW uses [GLSL](https://www.khronos.org/opengl/wiki/Core_Language_%28GLSL%29)
+for all of its shaders, with the legacy
+[Quake 3 shader format](https://graphics.stanford.edu/courses/cs448-00-spring/q3ashader_manual.pdf)
+acting as the glue between the raw textures and the GLSL.
+
+A standard "wall" Q3 shader in FTEQW might be located at
+`mygame/scripts/brick.shader` and might look like this:
+
+```glsl
+// material name used in level file
+brick/wall001a
+{
+	// glsl program to use
+	program defaultwall
+
+	// diffuse texture file path, relative to gamedir
+	diffusemap textures/brick/wall001a.tga
+}
+```
+
+`defaultwall` is the embedded GLSL shader in FTEQW for anything that is not
+water, sky, sprites, or models. These shader files are present in
+[FTEQW's source code](https://github.com/fte-team/fteqw/tree/master/engine/shaders/glsl),
+but you can also dump them with the console command `r_dumpshaders`. `diffusemap`
+is an FTEQW-specific shortcut that passes the texture name into the GLSL shader
+as the diffuse sampler.
+
+Here is an incomplete list of the FTEQW shortcuts for passing samplers to GLSL
+shaders:
+
+- `diffusemap`: Used for the base texture.
+- `fullbrightmap`: Used for glowing pixels.
+- `specularmap`: Used for specular reflections.
+- `normalmap`: Used for bump mapping.
+- `lightmap`: Used for adding baked lighting to a surface.
+
+Here is an incomplete list of the default shaders, and their uses:
+
+- `defaultskin.glsl`: Used for models and their skins.
+- `defaultsky.glsl`: Used for Quake's scrolling skies.
+- `defaultskybox.glsl`: Used for Quake II and Half-Life's skyboxes.
+- `defaultsprite.glsl`: Used for particles and sprites.
+- `defaultwall.glsl`: Used for most level geometry.
+- `defaultwarp.glsl`: Used for Quake's turbulent water surfaces.
+
+These can be used in any Q3 shader with `program <name>`. Any Q3 shader file
+with the extension `.shader` in the `scripts` folder of your game or mod will be
+automatically loaded by the engine.
+
+## Example Code
+
+Here is an example of a very simple `defaultwall.glsl` replacement. It only takes
+a diffuse sampler, an optional fullbrightmap, and a lightmap:
+
+```glsl
+!!ver 130 460
+!!permu FULLBRIGHT
+!!permu FOG
+!!permu LIGHTSTYLED
+!!samps diffuse lightmap fullbright
+
+varying vec2 txc;
+varying vec2 lmc;
+
+#include "sys/defs.h"
+#include "sys/fog.h"
+
+#ifdef VERTEX_SHADER
+	void main()
+	{
+		txc = v_texcoord;
+		lmc = v_lmcoord;
+
+		gl_Position = ftetransform();
+	}
+#endif
+
+#ifdef FRAGMENT_SHADER
+	void main()
+	{
+		// diffuse sampler
+		vec4 diffuse = texture2D(s_diffuse, txc);
+
+		// apply lightmap
+		vec3 lightmaps = (texture2D(s_lightmap, lmc) * e_lmscale).rgb;
+		diffuse.rgb *= lightmaps.rgb;
+
+		// apply brightmap
+		#if defined(FULLBRIGHT)
+			vec4 brightmap = texture2D(s_fullbright, txc);
+			diffuse = brightmap * brightmap.a + diffuse * (1.0 - brightmap.a);
+		#endif
+
+		// final color
+		gl_FragColor = fog4(diffuse * e_colourident);
+	}
+#endif
+```

specs/images/func_rotate.png

@@ -0,0 +1,60 @@
+
+With the `DP_SV_ROTATINGBMODEL` QuakeC extension, brush entities can be made to
+rotate using the `.avelocity` field. The brush entity must have an "origin brush"
+or else it will rotate around the map origin.
+
+![func_rotate example in TrenchBroom](./images/func_rotate.png)
+
+To create an origin brush, create another brush in your level editor of choice
+and make it a part of the entity. The center of the new brush should be where
+you want the entity to rotate from. The new brush should also have an "ORIGIN"
+texture on it, so the map compiler can properly mark it as the center of that
+entity. In Q1-based games, this is usually just a texture named "ORIGIN" with no
+other special properties. In Q2-based games, it will be a texture with the "ORIGIN"
+contents flag set.
+
+Finally, it needs some extra additions in QuakeC. In your entities `.think`
+function, assign the `.avelocity` field to a vector representing the rotation,
+in degrees per second.
+
+**NOTE**: If you're having issues getting this to work, try using the
+`checkextension` builtin to query the `DP_SV_ROTATINGBMODEL` extension before
+using it.
+
+## Example Code
+
+Here is an extremely basic `func_rotate` implementation in QuakeC for FTE:
+
+```c
+enumflags {
+	FUNC_ROTATE_X_AXIS,
+	FUNC_ROTATE_Y_AXIS,
+	FUNC_ROTATE_Z_AXIS
+};
+
+void func_rotate_think()
+{
+	// do rotations
+	if (self.spawnflags & FUNC_ROTATE_X_AXIS)
+		self.avelocity.x = self.speed;
+	if (self.spawnflags & FUNC_ROTATE_Y_AXIS)
+		self.avelocity.y = self.speed;
+	if (self.spawnflags & FUNC_ROTATE_Z_AXIS)
+		self.avelocity.z = self.speed;
+
+	self.nextthink = self.ltime + 0.1;
+}
+
+void func_rotate()
+{
+	// setup brush model
+	setorigin(self, self.origin);
+	setmodel(self, self.model);
+	self.movetype = MOVETYPE_PUSH;
+	self.solid = SOLID_BSP;
+
+	// start thinking
+	self.think = func_rotate_think;
+	self.nextthink = self.ltime + 0.1;
+}
+```

specs/rotating-brushes.md

@@ -0,0 +1,45 @@
+
+One way to have prefab elements in the FTEQW engine is to use separate BSP or
+MAP files that contain their own lighting, geometry and entities. These are
+called bmodels, or brush models. By default, FTEQW does not handle the spawning
+of entities from these files, and will ignore them. But with the
+`FTE_TERRAIN_MAP` extension, you can spawn them in QuakeC.
+
+## Example Code
+
+```c
+// spawn all child entities inside brush model
+// NOTE: this must be called as self! it uses self.modelindex to get the bmodel
+void spawn_child_entities()
+{
+	// get number of child entities
+	int num_entities = (int)terrain_edit(TEREDIT_ENT_COUNT);
+
+	// start at 1 so we don't create another worldspawn
+	for (int entity_id = 1i; entity_id < num_entities; entity_id++)
+	{
+		// spawn child entity
+		entity ent = spawn();
+
+		// get entity data
+		string entdata = (string)terrain_edit(TEREDIT_ENT_GET, entity_id);
+		entdata = strcat("{", entdata, "}");
+
+		// parse it into the entity we spawned
+		parseentitydata(ent, entdata);
+
+		// fix up origin and angles
+		setorigin(ent, ent.origin + self.origin);
+		ent.angles += self.angles;
+
+		// get spawn function
+		var void() spawnfunc = externvalue(0, ent.classname);
+
+		// run spawnfunc as self
+		entity oself = self;
+		self = ent;
+		spawnfunc();
+		self = oself;
+	}
+}
+```

specs/spawning-entities-from-external-bsps.md

@@ -0,0 +1,66 @@
+
+In FTEQW, you can use CSQC to give you more control over weapon viewmodels.
+
+Here is a chunk of code showing how to spawn a viewmodel entity in CSQC, with
+the appropriate flags set.
+
+```c
+static entity viewmodel;
+
+void CSQC_Init(float apilevel, string enginename, float engineversion)
+{
+	viewmodel = spawn();
+	viewmodel.drawmask = MASK_VIEWMODEL;
+	viewmodel.renderflags |= RF_VIEWMODEL;
+	viewmodel.effects |= EF_NOSHADOW;
+	// you may have to rotate the viewmodel angles depending on how you
+	// exported it from your modeling software
+	viewmodel.angles = [0, 0, 0];
+	setorigin(viewmodel, [0, 0, 0]);
+	setsize(viewmodel, [0, 0, 0], [0, 0, 0]);
+}
+```
+
+...and if your model is skeletally animated, you would do this in
+`CSQC_UpdateView`:
+
+```c
+void CSQC_UpdateView(float vwidth, float vheight, float notmenu)
+{
+	// push viewmodel animation at constant framerate
+	// note the use of frametime rather than clframetime, you probably don't
+	// want the viewmodel animating while the game is paused
+	viewmodel.frame1time += frametime;
+
+	// other stuff down here...
+}
+```
+
+Note that we have not set a model on it yet, so it will not yet be visible. To
+do that, we should first figure out what weapon the player is holding. There's
+a few different ways you could do this, but I'm gonna show you the Quake-y way.
+To get the modelindex of the player's viewmodel, you could do this:
+
+```c
+setmodelindex(viewmodel, getstatf(STAT_WEAPONMODELI));
+```
+
+`STAT_WEAPONMODELI` is a networked player stat that corresponds to the
+modelindex of the model specified by `self.weaponmodel` in the SSQC module. You
+should probably call the above code only if you detect that the player has
+switched weapons, or if the viewmodel's current modelindex is different from
+the value read from `STAT_WEAPONMODELI`. You can also read the player's current
+weapon index by reading the stat `STAT_ACTIVEWEAPON`, though you must set this
+yourself in the SSQC module with the `self.weapon` field, otherwise it will
+mean nothing.
+
+To set the weapon's animation, you could set `self.weaponframe` in SSQC and
+then read it from CSQC with the `STAT_WEAPONFRAME` stat. In the CSQC module
+you'd then do:
+
+```c
+viewmodel.frame = getstatf(STAT_WEAPONFRAME);
+```
+
+Note that whenever a new animation starts on the viewmodel, you should set
+`viewmodel.frame1time` back to 0. This will reset the animation time.