This call adds a command to the command buffer i.e. so that the programmer may issue server commands that would normally need to be entered into the console. exec_when takes an element of the cbufExec_t enumeration:
// paramters for command buffer stuffing
typedef enum {
EXEC_NOW, // don't return until completed, a VM should NEVER use this,
// because some commands might cause the VM to be unloaded...
EXEC_INSERT, // insert at current position, but don't run yet
EXEC_APPEND // add to end of the command buffer (normal case)
} cbufExec_t;
The string provided by text is run as if typed as a command into the console. A leading slash (/) is not required.
Description of the EXEC_* values are described in q_shared.h.
In general, EXEC_APPEND is the most common use, simulating the user typing in the command.
The string is stored to a buffer (appended) until a game frame is completed, then the engine will examine the buffered strings to run.
EXEC_NOW is a bad idea, as it can lead to an infinite loop: EXEC_NOW causes an immediate jump into engine space, which then jumps back to QVM/mod space to execute commands, which could lead to an immediate jump right back to engine space, which would lead to... and so on.
Examples
trap_SendConsoleCommand(EXEC_APPEND, "team free");
trap_SendConsoleCommand(EXEC_APPEND, "say Vini vidi vici.; quit");