-
Notifications
You must be signed in to change notification settings - Fork 8
Server map config features
The following features are supported in cMod to allow customizing the map configuration.
These features should remain supported in future versions of cMod, unless specifically marked as "experimental". If it becomes necessary to make changes to non-experimental features in a way that may break existing scripts, the changes will be documented on this page.
The "sv_mapscript" cvar specifies a console command to be run in place of the "map" command on the server. When sv_mapscript is set to a non-empty value, it overrides the "map" command to run the specified console command instead of the normal map command execution.
Prior to running sv_mapscript, the engine sets the following cvars, which can be utilized by the map script:
"sv_mapscript_mapcmd": This cvar contains the map command entered by the user, which can be run by "vstr sv_mapscript_mapcmd" to launch the map. Note that an extra underscore is added at the beginning of the command, which causes the engine to actually launch the map instead of recursively calling sv_mapscript.
"sv_mapscript_mapname": Contains the name of the map being launched for convenient access in scripts. This is needed instead of "mapname" to get the name of the map, because mapname still refers to the previous map during map script execution until the new map is fully launched.
// Just executes the map normally - has essentially no effect
set sv_mapscript "vstr sv_mapscript_mapcmd"
// Resets the speed to 300 before starting each map
set sv_mapscript "set g_speed 300 ; vstr sv_mapscript_mapcmd"
// Reset entire server configuration and run config before each map
// Note setr command to make sv_mapscript read only so it doesn't reset itself during cvar_restart
setr sv_mapscript "cvar_restart ; exec config ; vstr sv_mapscript_mapcmd"
The setting "sv_mapscript_bsp_check" (default: 1) specifies whether to check if the map exists, like the standard map command, before executing the map script.
Advanced map scripts handling maps located in non-standard paths may disable sv_mapscript_bsp_check and perform their own map validity check. In the case of an invalid map the script is responsible for aborting the map launch before making any changes to the server config, and for printing its own error message e.g. via the echo command.
The map table system provides a way to store configuration data for each map, which can be accessed from server scripts and engine-based voting systems. It does not change any settings directly, but rather provides a way for config scripts to access map-specific data.
A map table file for a particular map uses the following format:
key1=value1
key2=value2
keyn=valuen
Keys and values are separated by the '=' character, and each key-value pair occupies one line in the file. Quotes should not be used. Note that values are allowed to contain '=' characters, as only the first '=' is treated as a separator.
By default, map table files are expected at maps/{mapname}.mt under the virtual filesystem. This means the full path may be for example {sourcedir}/servercfg/maps/{mapname}.mt. Map table files can also be packaged in a pk3 such as {sourcedir}/servercfg/maptables.pk3 where the internal name within the pk3 is maps/{mapname}.mt.
The source directory for map tables is controlled by "sv_maptable_source_dirs", which is "maps" by default. This can be modified or set to include multiple space-separated directories. If multiple tables exist for the same map, they will be merged, and conflicting keys will be resolved to use the value from the earlier directory specified in sv_maptable_source_dirs.
The following commands are supported for accessing map tables from server scripts. Note these commands support the asterisk cvar reference syntax.
-
maptable_load <mapname>: Attempts to load map table for given map. Cvar "sv_maptable_loaded" will be set to true/false depending on whether the map table was successfully loaded. Also "sv_maptable_entry_count" will be set to the number of entries in the map table, or -1 if map table was not loaded.
-
maptable_retrieve <key> <target_cvar>: Copies value for specified key from maptable to target cvar. Writes empty string if key not found.
-
maptable_unload: Unloads map table. Resets "sv_maptable_loaded" to false and "sv_maptable_entry_count" to -1.
-
maptable_status: Debug command to print the keys and values of currently loaded map table.
The following configuration lets a map table specify two commands, one that is always run before the map is loaded, and one that is run only if the gametype is ctf.
file maps/pro_faceoff.mt:
general_command=set g_speed 300 ; set timelimit 10
ctf_command=set timelimit 15
in server config script (executed via sv_mapscript):
// Load the maptable
maptable_load *sv_mapscript_mapname
// Run the general command
maptable_retrieve general_command temp
vstr temp
// Run the ctf command
maptable_retrieve ctf_command temp
if *g_gametype i>= 4 vstr temp
Note that similar functionality can be achieved using the "exec" command with custom scripts for each map. This may be simpler in some cases, however map tables may be better suited for configurations involving engine voting support or when map data needs to be shared across multiple servers. You can select whichever approach works best for your particular configuration.
The following cvars can be used to override certain paths on the server and client. These settings are intended for advanced uses and should be manually cleared or updated by server scripts whenever the map or settings change.
- sv_override_bsp_file: Specifies a virtual path to load the bsp file from (instead of maps/{mapname}.bsp)
- sv_override_aas_file: Specifies a virtual path to load the aas file from (instead of maps/{mapname}.aas)
- sv_override_ent_file: Specifies a virtual path to load map entities from (instead of extracting from bsp)
- sv_override_client_map: Specifies map name to send to client (instead of server map name)
- sv_override_client_mod: Specifies mod name to send to client (instead of server fs_game) (experimental)