# 8. Quake-C Built-in functions

These are the built-in functions of Quake C. Since they are hard-coded in C, they cannot be redefined, but they are very fast.

### 8.1 Math functions

#### Function: anglemod

```float anglemod (float angle)
```
returns angle in degree, module 360.

#### Function: rint

```
float rint(float val)
```
Returns val, rounded up to the closest integer value.

#### Function: floor

```
float floor(float val)
```
Returns val, rounded up to the integer below (like the equivalent function in C).

#### Function: ceil

```
float ceil(float val)
```
Returns val, rounded up to the integer above (like the equivalent function in C).

#### Function: fabs

```
float fabs(float val)
```
Returns absolute value of val (like the equivalent function in C).

#### Function: random

Returns a random floating point number between 0.0 and 1.0.

#### Function: ftos

```string ftos(float value)
```
Float to string: converts value to string.

### 8.2 Vector maths

#### Function: normalize

```vector normalize(vector v)
returns a vector of length 1
```
Gives the vector colinear to v, but of length 1. This can be useful for calculation of distance along an axis.

#### Function: vlen

```float vlen(vector v)
```
Returns the length of vector v (never < 0).

#### Function: vectoyaw

```float vectoyaw(vector v)
returns and angle in degree
```
Vector to yaw: calculates the yaw angle (bearing) corresponding to a given 3D direction v.

#### Function: vectoangles

```vector vectoangles(vector v)
returns vector 'pitch  yaw  0 '
```
Vector to angles: calculates the pitch angle (aiming) and yaw angle (bearing) corresponding to a given 3D direction v.

#### Function: vtos

```string vtos(vector v)
```
Vector to String: print a vector, as a string.

#### Function: makevectors

```void makevectors(vector angles)
angle = 'pitch yaw 0'
```
Calculate the vectors pointing forward, right and up, according to the provided angles.
Returns result in the global variables:
```
vector	v_forward;  // points forward
vector  v_up;       // points up
vector  v_right;    // points toward the right
```

### 8.3 Sounds

#### Function: sound

```void sound (entity source, float channel, string sample, float volume, float attenuation)
source = entity emiting the sound (ex: self)
channel = channel to use for sound
sample = name of the sample WAV file (ex: "ogre/ogdrag.wav")
volume = 0.0 for low volume, 1.0 for maximum volume
attenuation= attenuation of sound
```
The entity emits a sound, on one of it's 8 channels.

#### Function: ambientsound

```void ambientsound(vector position, string sample, float volume, float attenuation)
position = position, in 3D space, inside the level
sample = name of the sample WAV file (ex: "ogre/ogdrag.wav")
volume = 0.0 for low volume, 1.0 for maximum volume
attenuation= attenuation of sound
```
An ambient sound is emited, from the given position.

### 8.4 Entity management

#### Function: spawn

```entity spawn ()
returns an empty entity.
```
Create a new entity, totally empty. You can manually set every field, or just set the origin and call one of the existing entity setup functions.

#### Function: remove

```void remove (entity e)
```
Removes entity e from the world (R.I.P.).

#### Function: makestatic

```void makestatic (entity e)
```
Make an entity static to the world, by sending a broadcast message to the network.
The entity is then removed from the list of dynamic entities in the world, and it cannot be deleted (until the level ends).

#### Function: nextent

```entity nextent(entity e)
```
Returns entity that is just after e in the entity list.
Useful to browse the list of entities, because it skips the undefined ones.

#### Function: find

```entity find (entity start, .string field, string match)
start = begining of list to search (world, for the begining of list)
field = entity field that must be examined (ex: targetname)
match = value that must be matched (ex: other.target)
returns the entity found, or world if no entity was found.
```
Searches the server entity list beginning at start, looking for an entity that has entity.field = match.

Example: find the first player entity

``` e = find( world, classname, "player");
```
Take care that field is a name of an entity field, without dot, and without quotes.

```entity findradius (vector origin, float radius)
origin = origin of sphere
```
Returns a chain of entities that have their origins within a spherical area.
The entity returned is e, and the next in the chain is e.chain, until e==FALSE.
Typical usage: find and harm the victims of an explosion.
```  e = findradius( origin, radius)
while(e)
{
T_Damage(e, ... ) // Let God sort his ones!
e = e.chain
}
```

#### Function: setmodel

```void setmodel (entity e, string model)
e = entity whose model is to be set
model = name of the model (ex: "progs/soldier.mdl")
```
Changes the model associated to an entity. This model should also be declared by precache_model. Please set e.movetype and e.solid first.

#### Function: lightstyle

```void lightstyle(float style, string value)
style = index of the light style, from 0 to 63.
value = (ex: "abcdefghijklmlkjihgfedcb")
```
Modifies a given light style. The light style is used to create cyclic lighting effects, like torches or teleporter lighting.
There are 64 light styles, from 0 to 63. If style is not strictly comprised in these values, the game may crash.
styles 32-62 are assigned by the light program for switchable lights.
value is a set of characters, whose ascii value indicates a light level, from "a" (0) to "z" (30).

### 8.5 Entity movements

#### Function: ChangeYaw

```void ChangeYaw()
```
Change the horizontal orientation of self. Turns towards self.ideal_yaw at self.yaw_speed, and sets the global variable current_yaw.
Called every 0.1 sec by monsters

#### Function: walkmove

```float walkmove(float yaw, float dist)
returns TRUE or FALSE
```
Moves self in the given direction.
Returns FALSE if could not move (used to detect blocked monsters).

#### Function: droptofloor

```float droptofloor()
returns TRUE or FALSE
```
Drops self to the floor, if the floor is less than -256 coordinates below.
Returns TRUE if landed on floor.
Mainly used to spawn items or walking monsters on the floor.

#### Function: setorigin

```void setorigin (entity e, vector position)
e = entity to be moved
position = new position for the entity
```
Move an entity to a given location. That function is to be used when spawning an entity or when teleporting it.
This is the only valid way to move an object without using the physics of the world (setting velocity and waiting).
DO NOT change directly e.origin, otherwise internal links would be screwed, and entity clipping would be messed up.

#### Function: setsize

```void setsize (entity e, vector min, vector max)
e = entity whose bounding box is to be set
min = minimum, for bounding box (ex: VEC_HULL2_MIN)
max = maximum, for bounding box (ex: VEC_HULL2_MAX)
```
Set the size of the entity bounding box, relative to the entity origin. The size box is rotated by the current angle.

#### Function: movetogoal

```void movetogoal (float step)
```
Move self toward it's goal.
Used for monsters.

### 8.6 Fighting

#### Function: aim

```vector aim(entity e, float missilespeed)
```
Returns a vector along which the entity e can shoot.
Usually, e is a player, and the vector returned is calculated by auto-aiming to the closest enemy entity.

#### Function: particle

```void particle(vector origin, vector dir, float color, float count)
origin = initial position
dir = initial direction
color = color index (73,75,
count = time to live, in seconds
```
Create a particle effect (small dot that flies away).
```color = 0   for chunk
color = 75  for yellow
color = 73  for blood red
color = 225 for entity damage
```

#### Function: checkclient

```entity checkclient()
```
Returns client (or object that has a client enemy) that would be a valid target.
If there are more than one valid options, they are cycled each frame.
If (self.origin + self.viewofs) is not in the PVS of the target, 0 (false) is returned.

### 8.7 Collision checking

#### Function: traceline

```traceline (vector v1, vector v2, float nomonsters, entity forent)
v1= start of line
v2= end of line
nomonster= if TRUE, then see through other monsters, else FALSE.
forent= ignore this entity, it's owner, and it's owned entities.
if forent = world, then ignore no entity.
```
Trace a line of sight, possibly ignoring monsters, and possibly ignoring the entity forent (usually, forent = self).
This function is used very often, tracing and shot targeting.
Traces are blocked by bounding boxes and exact bsp entities.
Returns the results in the global variables:
```float trace_allsolid;
// never used
float trace_startsolid;
// never used
float trace_fraction;
// fraction (percent) of the line that was traced, before
// an obstacle was hit. Equal to 1 if no obstacle were found.
vector trace_endpos;
// point where line ended or met an obstacle.
vector trace_plane_normal;
// direction vector of trace (?)
float  trace_plane_dist;
// distance to impact along direction vector (?)
entity trace_ent;
// entity hit by the line
float  trace_inopen;
// boolean, true if line went through non-water area.
float  trace_inwater;
// boolean, true if line went through water area.
```

#### Function: checkpos

CURRENTLY DISABLED. DO NOT USE.
```scalar checkpos (entity e, vector position)
```
Returns true if the given entity can move to the given position from it's current position by walking or rolling.

#### Function: checkbottom

```float checkbottom(entity e)
e = entity that is to be checked
return TRUE or FALSE
```
Returns TRUE if on the ground.
Used only for jumping monster, that need to jump randomly not to get hung up (or whatever it actually means).

#### Function: pointcontents

```float pointcontents(vector pos)
```
Returns the contents of the area situated at position pos.
Used to know if an area is in water, in slime or in lava.
Makes use of the BSP tree, and is supposed to be very fast.

### 8.8 Server managment

#### Function: changelevel

```void changelevel (string mapname)
```
Warp to the game map named mapname. Actually executes the console command "changelevel" + mapname, so if you want to alias it...

#### Function: setspawnparms

```void setspawnparms (entity client)
```
Restore the original spawn parameters of a client entity.
Doesn't work if client is not a player.

#### Function: stuffcmd

```stuffcmd (entity client, string text)
client = player that is to receive the command
text = text of the command, ended by \n (newline).
```
Send a command to a given player, as if it had been typed on the player's console.

Don't forget the \n (newline) at the end, otherwise your command will not be executed, and will stand still on the console window.

Examples:

```   stuffcmd(self, "bf\n");         // create a flash of light on the screen
stuffcmd(self, "name Buddy\n"); // name the player Buddy
```

Mostly used to send the command bf, that creates a flash of light on the client's screen.

### 8.9 Print messages

#### Function: bprint

```void bprint (string text)
text = text of the message
```
Broadcast a message to all players on the current server.

#### Function: centerprint

```void centerprint( entity client, string text)
client = player that is to receive the message
text = text of the message
```
Sends a message to a specific player, and print it centered.

#### Function: sprint

```void sprint (entity client, string text)
client = player that is to receive the message
text = text of the message
```
Sends a message to a player.

### 8.10 Console

#### Function: localcmd

```void localcmd (string text)
text = text of the command, ended by \n (newline).
```
Execute a command on the server, as if it had been typed on the server's console.

Examples:

```   localcmd("restart\n");      // restart the level
localcmd("teamplay 1\n");   // set deathmatch mode to teamplay
localcmd("killserver\n");   // poor server...
```

#### Function: dprint

```void dprint (string text)
text = text of the message
```
Prints a message to the server console.

#### Function: cvar

```float cvar (string variable)
variable = see console variables
```
returns the value of a console variable.

#### Function: cvar_set

```float cvar_set (string variable, string value)
variable = see console variables
```
sets the value of a console variable.

### 8.11 Debugging

#### Function: eprint

```void eprint (entity e)
e = entity to print
```
Print details about a given entity (for debug purposes).

#### Function: coredump

```void coredump()
```
Print all entities

#### Function: traceon

```void traceon()
```
Start tracing functions, end them with traceoff()

#### Function: traceoff

```void traceoff()
```
End traces started by traceon()

#### Function: break

```void break()
```
Exit the programs. Never used?

#### Function: error

```void error (string text)
```
Print an error message.

#### Function: objerror

```void objerror (string text)
```
Print an error message related to object self.

### 8.12 Precaching files

Those functions are used to declare models, sounds and stuff, before the PAK file is built.

Just follow this rule: whenever one of your functions makes use of a file that's not defined in Quake, precache this file in a function that will be called by worldspawn().

Then, the QCC compiler can automatically include in the PAK file all the files that you really need to run your programs.

And when the level starts running, those precache orders will be executed, so as to attribute a fixed table index to all those files.

DO NOT USE those functions in code that will be called after worldspawn() was called. As a matter of fact, that could bomb Quake (restarting the level, without crashing the game).

Files can only be precached in spawn functions.

#### Function: precache_file

```void precache_file(string file)
file = name of the file to include in PAK file.
```
Does nothing during game play.
Use precache_file2 for registered Quake.

#### Function: precache_model

```void precache_model(string file)
file = name of the MDL or BSP file to include in PAK file.
```
Does nothing during game play.
Must be used in a model's spawn function, to declare the model file.
Use precache_model2 for registered Quake.

#### Function: precache_sound

```void precache_sound(string file)
file = name of the WAV file to include in PAK file.
```
Does nothing during game play.
Must be used in a model's spawn function, to declare the sound files.
Use precache_sound2 for registered Quake.