View source for Server plugins:es

{{lang|Server plugins}}

{{finishtranslation:es}}
El Source Engine implementa un 3rd party plugin API similar a la API proporcionada por MetaMod bajo el motor del HL1. Este documento proporciona una breve descripción del interfaz proporcionado y como usarlo de la mejor manera.

=Includes necesarios para compilar=

De cara a compilar tu plugin necesitarás configurar tu compilador para incluir los siguientes directorios:
<pre>
 * public
 * public/dlls
 * public/engine
 * public/tier0
 * public/tier1
 * public/vstdlib
 * tier1 
</pre>
Para hacer esto debes conseguir los archivos SDK creando un MOD en el Source SDK.

=Compilando el Sample=

El SDK contiene un plugin de muestra que ejerce varias de las capacidades disponibles en un plugin. Puedes encontrar una muestra en <code>src/utils/serverplugin_sample</code>. Bajo Windows carga el proyecto <code>serverplugin_empty.vcproj</code>, bajo Linux, puedes typear:
<pre>
make plugin
</pre>

desde el directorio <code>linux_sdk</code>.

=Ejecutando el Plugin=

El motor cargará los plugins basados en archivos de valores clave en formato especial localizado en la carpeta <code><mod dir>/addons/</code> (debes crear este directorio, un servidor, por defecto, no viene con el). Para cargar tu plugin coloca un archivo en esta carpeta con la extensión *.vdf y con el siguiente formato:
<pre>
"Plugin"
{
        "file"  "serverplugin_empty"
}
</pre>
El parámetro <code>"file"</code> debería apuntar al archivo a cargar. En este ejemplo, el binario creado después de compilar el código debería ser copiado a la carpeta <code>bin/</code> del servidor instalado. La extensión del archivo (.dll para Windows) es añadida automaticamente al nombre de archivo cuando es cargado. El nombre del archivo debería ser relativo a la carpeta base bin/ en el servidor (i.e usarías <code>../cstrike/addons/serverplugin_empty</code> para especificar un archivo en la carpeta de addons del cstrike).

{{note|Para servidores TF2 Linux el la extension de archivo (.so) necesita ser añadida.}}

{{note|"file" define el tipo de plugin a cargar, i.e. le dice al [[Source Engine]] que es un archivo; "serverplugin_empty" es la ruta al archivo.}}
'''Ejemplo:'''

 "Plugin"
 {
         "file"  "../cstrike/addons/serverplugin_empty"
 }

==Versión Simplificada==
*Coloca el archivo compilado dentro de tu directorio <game dir>/bin (archivo .dll para Windows)
*crea el archivo exactamente como en el ejemplo de arriba, y cambia "serverplugin_empty" por tu nombre de archivo (mantén las comillas)
{{note|Para crear un archivo .vdf, solo crea un archivo de texto, botón derecho y cambia la extensión de .txt a .vdf}}

=La interfaz IServerPlugin=

Los plugins trabajan exponiendo una interfaz <code>IServerPluginCallbacks</code> al motor. El motor devuelve la llamada a esta interfaz cuando suceden varios eventos. La definición de esta interfaz puede ser encontrada en <code>public/engine/iserverplugin.h</code>. El tipo de retorno <code> PLUGIN_RESULT </code> de algunas de las funciones permite que el plugin controle si es pasada esta llamada al mod subyacente o no, vea la cabecera para más detalles.

=Explicación de IServerPluginCallbacks=
{| class=standard-table
| <code>Load</code> || Esta función es llamada cuando el plugin es cargado por el motor. Esto puede suceder en la inicialización o cuando se recarga después de ser descargado. Los dos parametros proporcionan la factoria de interfaz que el plugin necesita para operar.
|-
| <code>UnLoad</code> || Llamada cuando un plugin es descargado, usa esto para desactivar cualquier tarea asincrónica y eliminar cualquier callbacks que hayas registrado con el motor (Por ejemplo un listener de eventos de juego).{{Note|Entiendo por listener una "función" o proceso subyacente que permanece a la espera de cualquier evento para capturarlo NdT.}}
|-
| <code>Pause</code> || Called when the operation of the plugin is paused (i.e it will stop receiving callbacks but should not be unloaded).
|-
| <code>UnPause</code> || Called when a plugin is brought out of the paused state. You should re-enable any asynchronous events your plugin uses in this call
|-
| <code>GetPluginDescription</code> || This function should return a friendly string describing your plugin. Typically this would be its name and the author.
|-
| <code>LevelInit</code> || Called on level (map) startup, it is the first function called as a server enters a new level.
|-
| <code>ServerActivate</code> || This is called when the server successfully enters a new level, this will happen after the LevelInit call. This call provides pointers to the list of edicts created on the server and the maxplayer count of the server.
|-
| <code>GameFrame</code> || Called once per server frame (typically 60 times a second). Server performance is very sensitive to the execution time of this function so keep anything you do in this function to a minimum.
|-
| <code>LevelShutdown</code> || Called when a server is changing to a new level or is being shutdown. Remove any map specific allocations in this call. This can be called multiple times during a map change.
|-
| <code>ClientConnect</code> || Called when a client initially connects to a server. Set bAllowConnect to false to stop this user from connecting.
|-
| <code>ClientPutInServer</code> || Called when a client spawns into a server. This is called before the server spawn function.
|-
| <code>ClientActive</code> || Called after a client is fully spawned and configured by the Mod. Use this call to change any player specific settings.
|-
| <code>ClientDisconnect</code> || Called when a client disconnects from the server.
|-
| <code>SetCommandClient</code> || Called by the ConVar code to let you keep track of which client is entering a ConCommand. Use this index in ConCommands if you want to see who is running the command. As ConVar commands don't have an edict associated with them when they run you can use this index to look up the entity that is running the command.  The index is one less than the entity index.
|-
| <code>ClientSettingsChanged</code> || 	
Called when player specific cvars about a player change (for example the users name). Use this function to control what operations a user is allowed to perform to their settings (for example limiting usernames).
|-
| <code>ClientCommand</code> || Called when a remote client enters a command into the console. This should be used to provide commands to clients (and ConCommand used to implement server side only commands).
|-
| <code>NetworkIDValidated</code> || Called when the server retrieves a clients network ID (i.e Steam ID). Note that a clients network ID is not set on connect, you must wait for this callback before a users network ID is valid. The client name is passed into this function, you need to search the currently connected players to find the associated edict pointer. Note that the clients name can change between connect and id validation, you should use the entity index to track specific players.  Note also that this function is NOT called for the local user when running a listen/non-dedicated server.
|}

=Listening to Events=

The <code>IGameEventManager2</code> (<code>IGameEventManager</code> was used previously) interface allows a plugin to listen to game events. Game events are fired by a Mod when things of interest happen, like a player dying or the bomb being planted. <code>IGameEventManager2::AddListener</code> should be called to subscribe to particular game events. It must be called for each event that your listener wishes to be aware of. FireGameEvent is then called in your plugin when an one of the listened for events happen. The data contained in each event is described by event configuration files, in particular:

* <code>hl2/resource/serverevents.res</code>
* <code>hl2/resource/GameEvents.res</code>
* <code><mod dir>/resource/ModEvents.res</code>

=Creating [[ConVar]]s and [[Command]]s=

[[ConVar]]s let you specify variables that users can use to configure the behavior of your plugin. [[ConCommand]]s allow the creation of commands that your plugin provides. Creating both is easy and self contained, the code snippet below creates a new command <code>empty_version</code> and a new variable <code>plugin_empty</code>. These commands can be run from the server or client, you should use the index provided by <code>SetCommandClient</code> to determine the source of the command.
<pre>
CON_COMMAND( empty_version, "prints the version of the empty plugin" )
{
        Msg( "Version:1.0.0.0\n" );
}

static ConVar empty_cvar("plugin_empty", "0", 0, "Example plugin cvar");
</pre>

=Interacting with Clients=

The engine provides the <code>IServerPluginHelpers</code> interface to allow plugins to message clients. This interface provides a single function, <code>CreateMessage</code> that is called with 3 different dialog options to message users in different ways.

# <code>DIALOG_MSG, this prints a simple message to a client.</code>
# <code>DIALOG_MENU, this provides a client with a menu of options.</code>
# <code>DIALOG_TEXT, this shows a user a larger text field.</code>

Examples of how to use this interface are shown in the sample plugin example. Each message will be displayed for 10 seconds in the HUD and for the menu and text option for up to 200 seconds in GameUI. Only 1 message can be displayed at a time, you have to wait for the current one to expire before a new one can be shown. Messages with a lower <code>"level"</code> field can be used to override current messages (the minimum level value is 0). Details of valid message fields can be found in the sample code.

=Debug your plugin=
When add "-allowdebug" to your server startup line

=Release your plugin=
When ready for public consumption or beta testing, announce your server plugin at a community website like [http://www.sourceplugins.com SourcePlugins].

=Console commands=
In the console, you can get a list of available plugin related commands with this command: '''cvarlist plugin_'''

<pre>
cvar list
--------------
plugin_load        : cmd : : plugin_load <filename> : loads a plugin
plugin_pause       : cmd : : plugin_pause <index> : pauses a loaded plugin
plugin_pause_all   : cmd : : pauses all loaded plugins
plugin_print       : cmd : : Prints details about loaded plugins
plugin_unload      : cmd : : plugin_unload <index> : unloads a plugin
plugin_unpause     : cmd : : plugin_unpause <index> : unpauses a disabled plugin
plugin_unpause_all : cmd : : unpauses all disabled plugins
--------------
  7 convars/concommands for [plugin_]
</pre>

[[Category:Programming:es]]