AlliedModders Wiki - User contributions [en]

Natives (SourceMod Development)

2007-06-06T05:19:18Z

CyberMind: Reverted edits by PydPcp (Talk); changed back to last version by Damaged Soul

Natives are functions which are available to plugins via Core itself, or a C++ extension. They are called "natives" because they must be translated via a ''native interface''. This article explains the various parameter passing conventions in SourcePawn, as well as how to use them in your own natives.

To understand the contents of this article, you will need to read [[Writing_Extensions#Creating_Native_Functions|Creating Natives]], the Native section in the introductory article on creating extensions.

In this article, <tt>float</tt> refers to the C/C++ data type, and <tt>Float</tt> (note capital 'F') refers to the SourcePawn [[Tags (Scripting)|tag]].

=By Value versus By Reference=
There are two ways to pass integers/Floats to native implementations. They are ''by value'' (ByVal) and ''by reference'' (ByRef). ByVal means that a copy of the value is passed to the native. This is the default behaviour. ByRef means a ''reference'' is passed to the native, and this reference points to the value. Both will be explained below.

Note that arrays and strings, as will be explained later, are always passed by reference. This is because they are usually larger structures, and passing them ByVal would require copying their data, wasting CPU cycles.

==By Value==
Passing by value is the default behaviour for primitive data types (integers, Floats, or any tag that's cell-based). Data is treated normally as raw, copied input. Observe the following native:

<pawn>/**
* Returns the number decremented by one.
*
* @param num Number to decrement.
* @return Decremented number.
*/
native Decrement(num);</pawn>

How would we use this native? Since <tt>num</tt> is passed as a value, it cannot change in the native code. This means we have to use the return value as such:

<pawn>//Decrements a number 5 times
Example(num)
{
num = Decrement(num);
num = Decrement(num);
num = Decrement(num);
num = Decrement(num);
num = Decrement(num);
return num;
}</pawn>

==By Reference==
Let's reuse the above example to use reference passing. Observe the new native below:

<pawn>/**
* Subtracts one from the given number, by reference.
*
* @param num Number to subtract, by reference.
* @noreturn
*/
native Decrement(&num);</pawn>

Note the ampersand ('&') before the parameter name -- this specifies that it is passed by reference. Now, let's see how this would look in our script:

<pawn>Example(num)
{
Decrement(num);
Decrement(num);
Decrement(num);
Decrement(num);
Decrement(num);
return num;
}</pawn>

In this example, <tt>Decrement</tt> is acting on the <tt>num</tt> variable ''itself'', not a copy of it. Thus, num will decrease 5 times. In fact, scripts can even do this internally. We can shorten the example even more:

<pawn>Example(&num)
{
Decrement(num);
Decrement(num);
Decrement(num);
Decrement(num);
Decrement(num);
}</pawn>

==When to use By Ref==
There is a misconception that passing by reference is always better then by value. After all, copying data sounds excessive. However, by value in SourcePawn only works on 32bit values, and thus copying the value is inherent to the processor, and trivial.

On the other hand, passing by value is slightly more expensive. First, the compiler has to generate a little extra code to compute the local address of the variable. Second, the native code itself has to translate the local address to a ''real virtual address'' (native memory).

It is a good idea to only use by reference when you need it. A common usage is when you need to return more than one piece of data, and you can't fit it into the return value of your native or function. In this case, by reference is ideal.

=Integers/Floats=

==By Value==
Natives based purely on by-value floating point or integer input are generally the easiest to make. Let's take a simple function which takes in a Float and an integer, and returns a Float:
<pawn>/**
* Raises a number to an integer power.
*
* @param fNum Base number (Float).
* @param exp Exponent (integer).
* @return Computed exponent result as a Float.
*/
native FloatIntPower(Float:fNum, exp);</pawn>

An implementation of this native might look like:
<cpp>#include <stdlib.h>

static cell_t sm_FloatIntPower(IPluginContext *pContext, const cell_t *params)
{
float f1 = sp_ctof(params[1]);
int num = params[2];

float result = (float)pow(f1, (double)f2);
return sp_ftoc(result);
}</cpp>

Integers, as we saw in the introduction, are accessed from the parameter stack normally. Floats, however, must be ''reinterpret casted'' from a <tt>cell_t</tt> to <tt>float</tt>. Two inline functions are provided for this:
*<tt>sp_ctof</tt>: Convert a <tt>cell_t</tt> to a <tt>float</tt>.
*<tt>sp_ftoc</tt>: Convert a <tt>float</tt> to a <tt>cell_t</tt>.

==By Reference==
By reference is a little more tricky. Let's first implement our <tt>Decrement</tt> native from earlier. A refresher:
<pawn>native Decrement(&num);</pawn>

If we try to use our above code, <tt>params[1]</tt> will no longer hold a value. Instead, it holds a ''local address'' in the plugin. We must use the <tt>LocalToPhysAddr</tt> function to translate this. It takes in a local address and returns back a physical pointer, which we can then modify. This will modify the value in the script.

<cpp>static cell_t sm_Decrement(IPluginContext *pContext, const cell_t *params)
{
cell_t *addr;

/* Translate the address. */
pContext->LocalToPhysAddr(params[1], &addr);

/* Decrement the number */
*addr -= 1;

/* We have to return something, even if the plugin doesn't the value */
return 1;
}</cpp>
''Note: LocalToPhysAddr can return an error code. For all practical purposes, this will never error, unless there is some memory or corruption issue, so checking it isn't necessary.''

This works the same way for floats. Let's say we change our native to this:
<pawn>/**
* Decrements a Float by an integer, and stores the result by reference.
*
* @param fNum Float number to decrement (by ref).
* @param decamt Amount to decrement by.
* @noreturn
*/
native Decrement(&Float:fNum, decamt);
</pawn>

This example is fairly contrived -- our native simply performs a subtract operation. But let's look at the implementation:

<cpp>static cell_t sm_Decrement(IPluginContext *pContext, const cell_t *params)
{
cell_t *addr;

/* Translate the address. */
pContext->LocalToPhysAddr(params[1], &addr);

/* Get the value */
float val = sp_ctof(*addr);
/* Decrement */
val -= params[2];
/* Store back */
*addr = sp_ftoc(val);

/* We have to return something, even if the plugin doesn't the value */
return 1;
}</cpp>

Note that even though the first parameter was passed by reference, the second was not, and is accessed normally.

=Arrays=

==Basic Arrays==
Arrays are always passed by reference. The first example is an array which contains a list of numbers to sum. Observe the native:
<pawn>/**
* Averages an array of numbers.
*
* @param array Array of numbers to average.
* @param num Number of slots in the array.
* @return Average number as a Float.
*/
native Float:Average(array[], num);</pawn>

Usage might look like:
<pawn>Example()
{
new numbers[5] = {5, 6, 1, 3, 8};
return Average(numbers, 5);
}</pawn>

The implementation, like the by ref examples above, requires <tt>LocalToPhysAddr</tt>:
<cpp>static cell_t sm_Average(IPluginContext *pContext, cell_t *params)
{
cell_t *array;
float sum = 0.0f, average;

if (params[2] < 1)
{
/* 0 works without sp_ftoc() */
return 0;
}

pContext->LocalToPhysAddr(params[1], &array);
for (cell_t i=0; i<params[2]; i++)
{
sum += array[i];
}

average = sum / params[2];

return sp_ftoc(average);
}</cpp>

==Float Arrays==
This works similarly for Float arrays. Let's take Vectors an example, with the following native:
<pawn>/**
* Adds two vectors together.
*
* @param r Array to store the result in.
* @param v1 First vector to add.
* @param v2 Second vector to add.
* @noreturn
*/
native AddVectors(Float:r[3], const Float:v1[3], const Float:v2[3]);</pawn>

The implementation is straightforward:
<cpp>static cell_t sm_AddVectors(IPluginContext *pContext, cell_t *params)
{
cell_t *v1, *v2;
float result[3];

pContext->LocalToPhysAddr(params[2], &v1);
pContext->LocalToPhysAddr(params[3], &v2);

result[0] = sp_ctof(v1[0]) + sp_ctof(v2[0]);
result[1] = sp_ctof(v1[1]) + sp_ctof(v2[1]);
result[2] = sp_ctof(v1[2]) + sp_ctof(v2[2]);

cell_t *r;
pContext->LocalToPhysAddr(params[1], &r);
r[0] = sp_ftoc(result[0]);
r[1] = sp_ftoc(result[1]);
r[2] = sp_ftoc(result[2]);

return 1;
}</cpp>

Note that we only store the result after we have computed the input, rather than store directly. This is a bit more work, but is good practice in case users re-use data inputs, and risk overwriting inputs as they are written. For example:

<pawn>new Float:origin[3];
AddVectors(origin, origin, origin);</pawn>

=Strings=
Strings are just like arrays, in that they are passed by reference. The only difference is that each character is stored in a byte, not a 32bit <tt>cell_t</tt>. However, to make coding a bit easier for you, the coder, there are separate functions.
*<tt>LocalToString</tt>: Converts a local address to a physical string address.
*<tt>StringToLocal</tt>: Copies a physical string into a local address buffer.
*<tt>StringToLocalUTF8</tt>: Same as <tt>StringToLocal</tt>, but only copies the maximum amount possible without cutting off any multi byte characters.

First, let's take an easy example: the infamous strlen.
<pawn>/**
* Returns the length of a string.
*
* @param string String to calculate.
* @return Number of bytes in the string.
*/
native strlen(const String:string[]);</pawn>

Implementation:
<cpp>static cell_t sm_StrLen(IPluginContext *pContext, cell_t *params)
{
char *str;
pContext->LocalToString(params[1], &str);
return strlen(str);
}</cpp>

Now, let's say we want to modify the string. There is an important note here: since the string is passed by reference, when you modify the string, it is also modified in the plugin. This is a huge difference from AMX Mod X, where strings were essentially by value in most cases, and you had to copy results back.

Thus, if we wanted to copy a new result into <tt>str</tt> in the above implementation, it would be very easy. If we were implementing <tt>strcpy()</tt>, we would have to use <tt>memmove()</tt> to make sure there are no overlaps. Let's do this:
<pawn>/**
* Copies one string onto another.
*
* @param dest Destination buffer to copy to.
* @param length Maximum length of the buffer.
* @param source Source to copy from.
* @noreturn
*/
native StringCopy(String:dest[], length, const String:source);</pawn>

Implementation using <tt>memmove</tt> for safety:
<cpp>static cell_t sm_StringCopy(IPluginContext *pContext, cell_t *params)
{
char *dest, *src;
size_t len;

pContext->LocalToString(params[1], &dest);
pContext->LocalToString(params[3], &src);

/* Perform bounds checking */
len = strlen(src);
if (len >= params[2])
{
len = params[2] - 1;
} else {
len = params[2];
}

/* Copy */
memmove(dest, src, len);

dest[len] = '\0';

return 1;
}</cpp>

We can also use <tt>StringToLocal</tt>, which would requires a temporary buffer for the original string:
<cpp>static cell_t sm_StringCopy(IPluginContext *pContext, cell_t *params)
{
char *src;
char buffer[2048];
size_t len;

pContext->LocalToString(params[3], &src);

snprintf(buffer, sizeof(buffer), "%s", src);
pContext->StringToLocal(params[1], params[2], src);

return 1;
}</cpp>

Generally, you will be using <tt>StringToLocal</tt> for setting strings from outside sources, because it calculates addresses and overflows for you. However, you must make sure that you are not overwriting memory as you are reading it, or else programmers who are using certain types of array slicing may find themselves getting unexpected results.

=Advanced=
==Default Arguments==
Any type of parameter can have a default argument. For example, here is a native where every argument has a default parameter:
<pawn>native RandomStuff(a=0, Float:b=1.0f, &c=0, const String:d[]="", e[3] = {0,1,2});</pawn>

Note that even by reference parameters can have default arguments, as shown above. This does not change the code; it just means the address will contain the default value.

Scripts can force default values. Example:
<pawn>native RandomStuff(a, b, c=0, d=0);

Example()
{
RandomStuff(1, 2, _, d);
}</pawn>

The underscore ('_') means "use the default value for this argument."

==Variable Arguments==
Variable arguments means any number of arguments can be passed. An example of this looks like:
<pawn>native FormatText(const String:format[], {Float,String,_}:...);</pawn>

The <tt>{Float,Handle_}:</tt> is a multi-tag specifier that means any extra parameters must be either a <tt>Float</tt>, <tt>String</tt>, or have no tag at all. The <tt>...</tt> characters mean any number of parameters can follow.

'''There is one important note about variable arguments. They are always passed by reference.''' This means if you have a function which supports variable arguments, and an integer is passed, you will need to use <tt>LocalToPhysAddr</tt> as required with by reference parameters.

==Argument Counts/Backwards Compatibility==
In native handlers, the <tt>params</tt> array has a 0th index which stores the number of parameters it contains. This is useful for both Default Arguments and Variable Arguments.

For example, consider the following native:
<pawn>native DoSomething(index);</pawn>

Let's say that this native exists in plugins for six months. After that, you decide to add a new parameter. You want two conditions to be true after you release this update:
*Old plugins in binary form should still work on newer installations.
*Old plugins should still compile fine on the new API.

The second condition is solved by using default arguments. You should choose a value that will mimic the old functionality of the native.
<pawn>native DoSomething(index, newparam = 0);</pawn>

Next, when changing the implementation, you should detect whether <tt>params[0]</tt> contains ''one parameter'' or ''two parameters''. If it only contains one, you know to use the old version. If it contains two, you know to use the later version and accept the second parameter.

Similarly, you can use the <tt>params[0]</tt> count to detect how many arguments were passed to a variable argument native. This is used primarily in [[Format Class Functions (SourceMod Scripting)|Format Class Functions]] for parameter-count validation.

=Throwing Errors/Invoking the Debugger=
Often, you will write a native and realize that you need to tell the plugin that a serious error has occurred. A good example of this is if you are writing a function which requires a player index, but that index is beyond the reasonable bounds for the maximum players in the server.

In this case, it is a good idea to throw a ''runtime error''. This is an error that halts the plugin and invokes a call trace from the debugger. The halt is not permanent, but it does break the execution flow of the current callback.

There are two ways to throw a native error: <tt>ThrowNativeErrorEx()</tt> or <tt>ThrowNativeError()</tt>. The former lets you specify a detailed error code from <tt>sp_vm_types.h</tt>. The latter is a helper function for generic errors, and it returns 0, allowing you to return with the function itself. For example:

<cpp>static cell_t GetPlayerFrags(IPluginContext *pContext, const cell_t *params)
{
if (params[1] < 0 || params[1] > maxplayers)
{
return pContext->ThrowNativeError("Invalid client index: %d", params[1]);
}
/* ... rest of code ... */
}</cpp>

Don't worry about including extra information, such as your native name or the module name. The debugger knows all of this information and will decide what to print to the user.

[[Category:SourceMod Development]]

Handles (SourceMod Scripting)

2007-05-02T01:14:16Z

CyberMind:

Handles are a special data type used in [[SourceMod Scripting]]. They represent a single internal and unique object. For example, there are "File" Handles for files, and "Menu" Handles for menus, but they are both encapsulated under the "Handle" [[Tags (SourceMod Scripting)|tag]].

Handles are more than "pointers" from C or C++ because they have a ''reference count''. This means that the number of copies floating around in memory is tracked. The actual internal object is not destroyed until each copy is also destroyed.

Since SourcePawn does not have [[Garbage Collection]], Handles are a special way of intelligently allowing plugins and SourceMod to manage their own memory.

For more information on using Handles in the SourceMod API, see [[Handle API (SourceMod)]].

=Opening Handles=
Opening a Handle is usually done implicitly by a native function. For example, OpenDirectory opens a new Handle which is used in other Directory natives. This associates a ''type'' with the Handle. Trying to use a Directory Handle with any other non-Directory native will cause an error (HandleError_Type), because Handles are type checked.

<pawn>new Handle:hndl = OpenDirectory("addons/sourcemod/configs");
</pawn>

=Closing Handles=
==Basic operation==
Closing a Handle means seeing if the internal object can be removed from memory. For example, if a plugin creates an SQL connection, closing the Handle means closing and destroying the connection. This is almost always done using the CloseHandle() native function.

==When to close==
When a plugin unloads, all of its Handles are automatically destroyed. This does not mean, however, that closing Handles is optional. Consider the following code:

<pawn>stock bool:IsFileInFolder(const String:path[], const String:file[])
{
new String:path[PLATFORM_MAX_PATH];
new FileType:type;

new Handle:dir = OpenDirectory(path);
if (dir == INVALID_HANDLE)
{
return false;
}

while (ReadDirEntry(dir, path, sizeof(path), type))
{
if (type == FileType_File && StrEqual(path, file))
{
return true;
}
}

CloseHandle(dir);

return false;
}
</pawn>

This function searches a directory for a single file. If this function were to omit the call to CloseHandle, it would [[Memory Leak|leak memory]] every time it was called, and eventually the script would fill up with a large number of lingering Handles that were left open.

So, when do you close Handles? There are generally two rules of thumb to go by:
*If the native uses terminology such as "Opens a [...]" or "Creates a [...]" or gives explicit directions for closing.
*If the Handle represents a temporary object or piece of information, and you will no longer be using it.

Most of the time, you will be closing Handles. Check the Handle Type documentation at the end of this page.

==When you can't close==
There are a few Handle types that cannot be closed. The major one is the Handle which identifies a plugin. Plugins cannot unload themselves, and thus destroying their own Handles is not allowed.

Furthermore, a script cannot close a Handle that is owned by another plugin. This is for protection against API mistakes and accidental errors. For example, if a Handle is shared between two plugins, one accidental free could invalidate a Handle unexpectedly. To allow the sharing of Handles, see [[#Cloning Handles|Cloning Handles]].

==Reference counters==
Closing Handles does not always destroy the internal data. This is the case when Handles are [[#Cloning Handles|cloned]]. Each clone adds a ''reference count'' to the Handle, and closing each clone removes one reference count. The original object is only actually destroyed once the Handle has no more reference counters.

=Cloning Handles=
As briefly described earlier, there is a problem when scripts try to share Handles. Imagine this scenario:
*Plugin 'A' creates a Handle.
*Plugin 'B' received the Handle.
*Plugin 'A' is unloaded, and the Handle is destroyed.
*Plugin 'B' tries to use the Handle.

To prevent this, the CloneHandle native is provided. This function returns a ''new'' Handle that is a "copy" of the original. While their values won't be equal, they contain the same internal data. The data itself will not be destroyed until each copy and the original are closed with CloseHandle. It does not matter what order they are freed in, however, each Handle can only be freed once.

There are two ways of cloning. A plugin can either clone a Handle itself, and become the owner, or it can explicitly set a new owner. The difference is one of API design. Example of the former:
<pawn>new Handle:g_hSQL;
/**
* The other plugin calling this function must pass his ID in,
* but doesn't have to call CloneHandle()
*/
public Handle:GetGlobalSQL(Handle:otherPlugin)
{
return CloneHandle(g_hSQL, otherPlugin);
}

/**
* This code would appear in the other plugin
*/
new Handle:sql = GetGlobalSQL(myself);
/* ... */
CloseHandle(sql);
</pawn>

Example of the latter:
<pawn>new Handle:g_hSQL;
/**
* The calling plugin must call CloneHandle() himself.
*/
public Handle:GetGlobalSQL()
{
return g_hSQL;
}

/**
* This code would appear in the other plugin
*/
new Handle:sql = GetGlobalSQL();
if (sql != INVALID_HANDLE)
{
sql = CloneHandle(sql);
}
CloseHandle(sql);
</pawn>

=Handle Types=
The following is a list of the known Handle types provided by SourceMod and some documentation on each.
==BitBuffers==
{{HandleType|bf_read or bf_write|Only if explicitly stated|Only if it can also be closed|Core|bitbuffer.inc}}

There are four types of BitBuffer Handles. They are separated into ''bf_write'' (writable buffer) and ''bf_read'' (readable buffer). These are directly abstracted from their Half-Life 2 counterpart. Internally, there are separate Handle types for each; certain functions will use BitBuffer handles that cannot be freed.

==ConVars==
{{HandleType|ConVar|No|No|Core|console.inc}}

ConVar Handles are primarily used for getting and setting a console variable's value. They cannot be cloned nor deleted since they exist until SourceMod is shut down.

==Directories==
{{HandleType|Directory|Yes|Yes|Core|files.inc}}

Directory Handles are used for opening and enumerating the contents of a directory (folder) on the filesystem.

==Database Drivers==
{{HandleType|DBDriver|Yes|No|Core|dbi.inc}}

DBDriver Handles contain information about a database driver. They must be closed so your plugin does not have any dependencies lingering on the database driver.

==Database Queries==
{{HandleType|IQuery|Yes|No|Core|dbi.inc}}

Database Queries wrap an <tt>IQuery</tt> pointer for database queries. Closing a query frees its resources, including any prepared statement information and any result sets.

==Databases==
{{HandleType|IDatabase|Yes|Yes|Core|dbi.inc}}

Database Handles wrap an <tt>IDatabase</tt> pointer for database connections. Closing these disconnects the database and frees any related resources.

==Events==
{{HandleType|Event|No|No|Core|events.inc}}

Event Handles are used for getting and setting data in Half-Life 2 game events as well as for firing them. They can only be closed using CancelCreatedEvent() if the event was not fired for some reason.

==Files==
{{HandleType|File|Yes|Yes|Core|files.inc}}

File Handles are used for opening, reading from, writing to, and creating to files on the file system.

==Forwards==
{{HandleType|Forward|Yes|Only if explicitly stated|Core|functions.inc}}

Forward Handles are primarily used when calling functions inside a forward container. There are two types of forwards: global and private. Only private forwards can be cloned.

==KeyValues==
{{HandleType|KeyValues|Yes|No|Core|keyvalues.inc}}

KeyValues Handles abstract the Valve data type <tt>KeyValues</tt>, which are tree-based, recursive key to value mapping structures, often used to enumerate properties or configuration file directives.

==Plugins==
{{HandleType|Plugin|No|No|Core|sourcemod.inc}}

Plugin Handles are used for the unique identification of a Plugin. They are owned by Core and cannot be cloned or closed by any other plugin or extension. However, plugins can use Handles for certain natives which enumerate or retrieve information on plugins.

Plugin Handles should not be cached globally, as plugins can become unloaded, and the Handle will be invalid.

==Plugin Iterators==
{{HandleType|PluginIter|Yes|No|Core|sourcemod.inc}}

Plugin Iterators allow you to walk over a list of plugins. They are intended for temporary use only.

==SMC Parsers==
{{HandleType|SMC Parser|Yes|No|Core|textparse.inc}}

SMC Parsers are Handles which contain a set of functions for hooking parse events in an SMC file. See more in [[SMC Parsing (SourceMod Scripting)]]. Since they directly reference functions in a plugin, they cannot be cloned.

==Timers==
{{HandleType|Timer|Yes|No|Core|timers.inc}}

Timers are temporary Handles which are automatically closed on any of the following events:
*The timer ends (via Plugin_Stop or being a one-time timer that is finished)
*The timer is killed via <tt>KillTimer</tt>
*The timer is closed via <tt>CloseHandle</tt>
*The timer's parent plugin unloads

[[Category:SourceMod Development]][[Category:SourceMod Scripting]]

Timers (SourceMod Scripting)

2007-04-30T04:57:24Z

CyberMind: /* Simple Values */ typo

Timers in [[SourceMod]] are timed events that occur once or repeatedly at a given interval.

=Introduction=
Timers allow you to set an interval, a function to use as the event callback, and an optional Handle to pass through the callback. This is useful for saving data asynchronously.

All timer functions are in <tt>plugins/include/timers.inc</tt>.

=Basic Usage=
==One-Time Timers==
One-time timers are timers that only execute once. An example of a one-time timer might look like:

<pawn>public OnPluginStart()
{
CreateTimer(5.0, LoadStuff)
}

public Action:LoadStuff(Handle:timer)
{
PrintToServer("Loading stuff!")
}</pawn>

This code will print "Loading stuff!" to the server console five seconds after the map loads. The return value has no meaning for one-time timers.

==Repeatable Timers==
Repeatable timers execute infinitely many times, once every interval. Based on the return value, they either continue or cancel.

For example, say you want to display a message five times, once every three seconds:
<pawn>
DoMessage()
{
CreateTimer(3.0, PrintMsg, _, TIMER_REPEAT)
}

public Action:PrintMsg(Handle:timer)
{
static NumPrinted = 0
if (NumPrinted++ >= 5)
{
PrintToServer("Warning! This is a message.")
NumPrinted = 0

return Plugin_Stop
}

return Plugin_Continue
}</pawn>

Note that <tt>Plugin_Stop</tt> stops the timer, and <tt>Plugin_Continue</tt> allows it to continue repeating.

=Passing Data=
==Simple Values==
As mentioned earlier, timers let you pass values on to the callback function. This value can be any type. For example, let's say we want to print a message to a player fifteen seconds after they connect. However, we want to cancel the timer if the player disconnects. Implementing this is very easy:

<pawn>#define MAX_PLAYERS 256

new Handle:WelcomeTimers[MAX_PLAYERS+1]

public OnClientPutInServer(client)
{
WelcomeTimers[client] = CreateTimer(15.0, WelcomePlayer, client)
}

public OnClientDisconnect(client)
{
if (WelcomeTimers[client] != INVALID_HANDLE)
{
KillTimer(WelcomeTimers[client])
WelcomeTimers[client] = INVALID_HANDLE
}
}

public Action:WelcomePlayer(Handle:timer, client)
{
PrintToConsole(client, "Welcome to the server!")
WelcomeTimers[client] = INVALID_HANDLE
}</pawn>

==Handles==
If you want to pass a Handle as a value, you have the option of using <tt>TIMER_HNDL_CLOSE</tt>, which will automatically call <tt>CloseHandle()</tt> for you once the timer dies.

==Data Packs==
Data packs are packable structures that can be used to hold asynchronous data (data that must be saved and unpacked for later). They are especially useful for timers, and thus there exists a helper function, called <tt>CreateDataTimer()</tt>, which creates a timer using a data pack handle. The handle is created and closed automatically for you.

The above example could be rewritten as:
<pawn>#define MAX_PLAYERS 256

new Handle:WelcomeTimers[MAX_PLAYERS+1]

public OnClientPutInServer(client)
{
new Handle:pack
WelcomeTimers[client] = CreateDataTimer(15.0, WelcomePlayer, pack)
WritePackCell(pack, client)
WritePackString(pack, "Welcome to the server!")
}

public OnClientDisconnect(client)
{
if (WelcomeTimers[client] != INVALID_HANDLE)
{
KillTimer(WelcomeTimers[client])
WelcomeTimers[client] = INVALID_HANDLE
}
}

public Action:WelcomePlayer(Handle:timer, Handle:pack)
{
decl String:str[128]
new client

/* Set to the beginning and unpack it */
ResetPack(pack)
client = ReadPackCell(pack)
ReadPackString(pack, str, sizeof(str))

PrintToConsole(client, "%s", str)
WelcomeTimers[client] = INVALID_HANDLE
}</pawn>

=Notes=
==Accuracy==
The smallest possible interval is 0.1 seconds. Timers have high precision (floating point) but low accuracy, as the current time is based on the in-game tick count, not the system clock. This has two implications:
*If the server is paused (not ticking), timers will not run.
*The server will not always tick at an exact interval.

For example, a 1.234 second interval timer starting from time <tt>t</tt> might not tick until <tt>t+1.242</tt> at a tickrate of 66 ticks per second.

==Timer Death==
All timers are guaranteed to die either by:
*<tt>CloseHandle()</tt> being called (or on plugin unload);
*<tt>KillTimer()</tt> being called;
*<tt>Plugin_Stop</tt> being returned from a repeatable timer;
*<tt>TriggerTimer()</tt> being called on a one-time timer;
*Execution of a one-time timer finishes.

When a timer dies, if <tt>TIMER_HNDL_CLOSE</tt> is set, the Handle will always be closed with the permissions that <tt>CloseHandle()</tt> uses by default. Since timers cannot be cloned, there should be no ownership issues.

==Changing Intervals==
The interval of a timer cannot be changed as of this writing. The timer must be killed and a new one created.

==AMX Mod X==
Unlike [[AMX Mod X]]'s <tt>set_task</tt> function, you cannot pass arrays using <tt>CreateTimer</tt>. To accomplish this, you should use the data pack functionality explained above.

Similarly, there are no flags for counted repeats (non-infinite loops) or timers based on the map start or end. These must be done manually.

[[Category:SourceMod Scripting]]
[[Category:SourceMod Development]]

Timers (SourceMod Scripting)

2007-04-30T04:57:16Z

CyberMind: /* Data Packs */ fixed typo in timer function name

Timers in [[SourceMod]] are timed events that occur once or repeatedly at a given interval.

=Introduction=
Timers allow you to set an interval, a function to use as the event callback, and an optional Handle to pass through the callback. This is useful for saving data asynchronously.

All timer functions are in <tt>plugins/include/timers.inc</tt>.

=Basic Usage=
==One-Time Timers==
One-time timers are timers that only execute once. An example of a one-time timer might look like:

<pawn>public OnPluginStart()
{
CreateTimer(5.0, LoadStuff)
}

public Action:LoadStuff(Handle:timer)
{
PrintToServer("Loading stuff!")
}</pawn>

This code will print "Loading stuff!" to the server console five seconds after the map loads. The return value has no meaning for one-time timers.

==Repeatable Timers==
Repeatable timers execute infinitely many times, once every interval. Based on the return value, they either continue or cancel.

For example, say you want to display a message five times, once every three seconds:
<pawn>
DoMessage()
{
CreateTimer(3.0, PrintMsg, _, TIMER_REPEAT)
}

public Action:PrintMsg(Handle:timer)
{
static NumPrinted = 0
if (NumPrinted++ >= 5)
{
PrintToServer("Warning! This is a message.")
NumPrinted = 0

return Plugin_Stop
}

return Plugin_Continue
}</pawn>

Note that <tt>Plugin_Stop</tt> stops the timer, and <tt>Plugin_Continue</tt> allows it to continue repeating.

=Passing Data=
==Simple Values==
As mentioned earlier, timers let you pass values on to the callback function. This value can be any type. For example, let's say we want to print a message to a player fifteen seconds after they connect. However, we want to cancel the timer if the player disconnects. Implementing this is very easy:

<pawn>#define MAX_PLAYERS 256

new Handle:WelcomeTimers[MAX_PLAYERS+1]

public OnClientPutInServer(client)
{
WelcomeTimers[client] = CreateTimer(15.0, WelcomePlayer, client)
}

public OnClientDisconnect(client)
{
if (WelcomeTimers[client] != INVALID_HANDLE)
{
KillTimer(WelcomeTimers[client])
WelcomeTimers[client] = INVALID_HANDLE
}
}

public Action:WelcomeTimer(Handle:timer, client)
{
PrintToConsole(client, "Welcome to the server!")
WelcomeTimers[client] = INVALID_HANDLE
}</pawn>

==Handles==
If you want to pass a Handle as a value, you have the option of using <tt>TIMER_HNDL_CLOSE</tt>, which will automatically call <tt>CloseHandle()</tt> for you once the timer dies.

==Data Packs==
Data packs are packable structures that can be used to hold asynchronous data (data that must be saved and unpacked for later). They are especially useful for timers, and thus there exists a helper function, called <tt>CreateDataTimer()</tt>, which creates a timer using a data pack handle. The handle is created and closed automatically for you.

The above example could be rewritten as:
<pawn>#define MAX_PLAYERS 256

new Handle:WelcomeTimers[MAX_PLAYERS+1]

public OnClientPutInServer(client)
{
new Handle:pack
WelcomeTimers[client] = CreateDataTimer(15.0, WelcomePlayer, pack)
WritePackCell(pack, client)
WritePackString(pack, "Welcome to the server!")
}

public OnClientDisconnect(client)
{
if (WelcomeTimers[client] != INVALID_HANDLE)
{
KillTimer(WelcomeTimers[client])
WelcomeTimers[client] = INVALID_HANDLE
}
}

public Action:WelcomePlayer(Handle:timer, Handle:pack)
{
decl String:str[128]
new client

/* Set to the beginning and unpack it */
ResetPack(pack)
client = ReadPackCell(pack)
ReadPackString(pack, str, sizeof(str))

PrintToConsole(client, "%s", str)
WelcomeTimers[client] = INVALID_HANDLE
}</pawn>

=Notes=
==Accuracy==
The smallest possible interval is 0.1 seconds. Timers have high precision (floating point) but low accuracy, as the current time is based on the in-game tick count, not the system clock. This has two implications:
*If the server is paused (not ticking), timers will not run.
*The server will not always tick at an exact interval.

For example, a 1.234 second interval timer starting from time <tt>t</tt> might not tick until <tt>t+1.242</tt> at a tickrate of 66 ticks per second.

==Timer Death==
All timers are guaranteed to die either by:
*<tt>CloseHandle()</tt> being called (or on plugin unload);
*<tt>KillTimer()</tt> being called;
*<tt>Plugin_Stop</tt> being returned from a repeatable timer;
*<tt>TriggerTimer()</tt> being called on a one-time timer;
*Execution of a one-time timer finishes.

When a timer dies, if <tt>TIMER_HNDL_CLOSE</tt> is set, the Handle will always be closed with the permissions that <tt>CloseHandle()</tt> uses by default. Since timers cannot be cloned, there should be no ownership issues.

==Changing Intervals==
The interval of a timer cannot be changed as of this writing. The timer must be killed and a new one created.

==AMX Mod X==
Unlike [[AMX Mod X]]'s <tt>set_task</tt> function, you cannot pass arrays using <tt>CreateTimer</tt>. To accomplish this, you should use the data pack functionality explained above.

Similarly, there are no flags for counted repeats (non-infinite loops) or timers based on the map start or end. These must be done manually.

[[Category:SourceMod Scripting]]
[[Category:SourceMod Development]]

User:CyberMind

2007-03-02T02:09:39Z

CyberMind: /* WebMod */

=About Me=
I am a [[User:BAILOPAN|BAILOPAN]] groupie. I am on IRC [http://cybermind.user.stfunoob.com/misc/mirctimer.png too much].

=Gaming Projects=
*[http://www.q3mm.org/ QMM] (Quake3 MultiMod) - a Metamod-like system for Quake 3-based games
*[http://qmm.planetquake.gamespy.com/forums/viewtopic.php?t=52 Stripper] QMM plugin - Dynamic map entity addition/removal
*[http://qmm.planetquake.gamespy.com/forums/viewtopic.php?t=53 RocketMod] QMM plugin - Gameplay modification plugin
*[http://www.phpua.com/ phpua_mm] [[Metamod]] plugin (co-author, lead developer) - Provides real-time game information for web-based phpUA software
*[http://logd.sourceforge.net/weaptfc/ WeapTFC] [[Metamod]] plugin - Class-based TFC weapon restrictions

=Other Projects=
*[http://finop.sourceforge.net/ FinOP] IRC Bot - Modular IRC bot that has gone through far too many core rewrites; still not done; very inactive
*[http://quala.sourceforge.net/ Quala] Extension Language - Scripting language based off of the Quake3 Virtual Machine format. Currently undeveloped and inactive.

=Contributions=
I enjoy pointing out answers via pictorial depictions. See [http://www.sourcemod.net/forums/viewtopic.php?p=27600#27600 here], [http://www.amxmodx.org/forums/viewtopic.php?p=182749&#182749 here], and [http://www.amxmodx.org/forums/viewtopic.php?p=204502&#204502 here].

==AMX Mod X==
Since I don't know [[AMX_Mod_X|AMX Mod X]] plugin API to save my life, I typically only help out when questions are related to Pawn programming in general.

==SourceMM==
I know a little bit more in the [[SourceMM]] plugin API department, despite not owning [[Half-Life_2|Half-Life 2]], and sometimes help out on the [[SourceMod]] forums. I also have moderate-to-advanced C/C++ knowledge and minor asm knowledge and sometimes help with general coding questions.

==Pawn/AMX==
A while ago, I set out to get Visual Basic 6 to load and execute AMX files. My goal was to run AdminMod plugins in a pseudo-server environment, and I got as far as properly loading the files and handling natives, but I only coded around 3 or 4 of all of available AdminMod natives. The AMX version has undoubtedly changed by then, but the code is available [http://cybermind.user.stfunoob.com/vbamx/ here] to view. Note the included amx.h file has been changed and must be used in recompiling AdminMod's amx_admin.dll. Yes, I am aware my malloc/free implementation could have been better, but I was not as awesome back then as I am now.

==WebMod==
I [http://secunia.com/advisories/14302/ defeated it] in hand-to-hand combat.
And then I [http://secunia.com/advisories/24346/ judo-chopped] it.

User:CyberMind

2007-03-02T02:07:26Z

CyberMind: /* WebMod */

=About Me=
I am a [[User:BAILOPAN|BAILOPAN]] groupie. I am on IRC [http://cybermind.user.stfunoob.com/misc/mirctimer.png too much].

=Gaming Projects=
*[http://www.q3mm.org/ QMM] (Quake3 MultiMod) - a Metamod-like system for Quake 3-based games
*[http://qmm.planetquake.gamespy.com/forums/viewtopic.php?t=52 Stripper] QMM plugin - Dynamic map entity addition/removal
*[http://qmm.planetquake.gamespy.com/forums/viewtopic.php?t=53 RocketMod] QMM plugin - Gameplay modification plugin
*[http://www.phpua.com/ phpua_mm] [[Metamod]] plugin (co-author, lead developer) - Provides real-time game information for web-based phpUA software
*[http://logd.sourceforge.net/weaptfc/ WeapTFC] [[Metamod]] plugin - Class-based TFC weapon restrictions

=Other Projects=
*[http://finop.sourceforge.net/ FinOP] IRC Bot - Modular IRC bot that has gone through far too many core rewrites; still not done; very inactive
*[http://quala.sourceforge.net/ Quala] Extension Language - Scripting language based off of the Quake3 Virtual Machine format. Currently undeveloped and inactive.

=Contributions=
I enjoy pointing out answers via pictorial depictions. See [http://www.sourcemod.net/forums/viewtopic.php?p=27600#27600 here], [http://www.amxmodx.org/forums/viewtopic.php?p=182749&#182749 here], and [http://www.amxmodx.org/forums/viewtopic.php?p=204502&#204502 here].

==AMX Mod X==
Since I don't know [[AMX_Mod_X|AMX Mod X]] plugin API to save my life, I typically only help out when questions are related to Pawn programming in general.

==SourceMM==
I know a little bit more in the [[SourceMM]] plugin API department, despite not owning [[Half-Life_2|Half-Life 2]], and sometimes help out on the [[SourceMod]] forums. I also have moderate-to-advanced C/C++ knowledge and minor asm knowledge and sometimes help with general coding questions.

==Pawn/AMX==
A while ago, I set out to get Visual Basic 6 to load and execute AMX files. My goal was to run AdminMod plugins in a pseudo-server environment, and I got as far as properly loading the files and handling natives, but I only coded around 3 or 4 of all of available AdminMod natives. The AMX version has undoubtedly changed by then, but the code is available [http://cybermind.user.stfunoob.com/vbamx/ here] to view. Note the included amx.h file has been changed and must be used in recompiling AdminMod's amx_admin.dll. Yes, I am aware my malloc/free implementation could have been better, but I was not as awesome back then as I am now.

==WebMod==
I [http://secunia.com/advisories/14302/ defeated it] in hand-to-hand combat.
And then I [url=http://secunia.com/advisories/24346/]judo-chopped[/url] it.

Ru Using New Menu System

2007-01-23T00:21:55Z

CyberMind: added russian category

[[Category:Russian]]
[[Category:Ru:Scripting (AMX Mod X)]]

= Введение =
Это статья поможет вам разобраться в новой системе меню.

== Урок по созданию меню ==
Давайте попробуем воспользоваться новой системмой меню. Мы пройдем через этоу простую инструкцию и создадим простое голосование смены карты.

=== Заголовочные файлы ===
Как обычно мы начинаем с добавления необходимых заголовочных файлов
<pawn>
#include <amxmodx>
</pawn>

=== Глобальные переменные ===
<pawn>
new g_Menu; // Переменная обработки главного меню
new g_Votes[3]; // Сохраняем голосования Да как 1, No как 2
</pawn>

Тут мы создали 2 глобальные переменные. Одна содержит указатель вашего меню, другая хранит резуьтаты голосования. Голоса 'Да' будут сохранены в g_Votes[1] ,а 'Нет' будет сохранена в g_Votes[2].

=== Регистрируем Плагин и Меню ===
<pawn>
public plugin_init()
{
// Регистрируем ваш плагин
register_plugin("Vote Menu","1.0","Freecode");

// Регистрируем меню смены карты
g_Menu = menu_create("Change Level?","menu_handle");

register_clcmd("amx_startvote","startvote",ADMIN_CFG,"Gaben");

// Теперь нам надо создать наше меню
build_menu();
}
</pawn>

Lets break this down.

*Регистрирует ваш плагин
<pawn>register_plugin("Vote Menu","1.0","Freecode");</pawn>

*g_Menu - Указатель на ваше меню. Это будет установлено после вызова menu_create.
<pawn>g_Menu = menu_create("Change Level?","menu_handle");

//menu_create ( title[], handler[], ml=0 )
//title[] - Заголовок меню
//handler[] - Эта функция будет вызвана когда будет нажата клавиша в вашем меню.
</pawn>

* Мы добавили эту команду. Она начинает ваше голосование.
<pawn>register_clcmd("amx_startvote","startvote",ADMIN_CFG,"Gaben");
</pawn>

* Это вызов функции. build_menu() функция создает ваше меню.
<pawn>build_menu();</pawn>

=== Создение меню ===
Конструирование заключается в добавлении пунктов в ваше меню. Прежде чем начали добавлять пункты, мы должны взглянуть на
menu_additem .
<pawn>menu_additem ( menu, const name[], const command[], paccess=0, callback=-1 )</pawn>
* menu - указатель на меню. Это указывает menu_additem меню к которому нужно добавить пункты.
* const name[] - имя пункта меню. Это то что будет показано в меню.
* const command[] - информация пункта меню.

Теперь давайте приступим к созданию нашего меню. Как уже говорилось, это простое голосование смены карты. Так что нам надо всего 2 пункта меню. А именно "Да" и "Нет".
<pawn>build_menu()
{
menu_additem(g_Menu, "Yes", "1");
menu_additem(g_Menu, "No", "2");

menu_setprop(g_Menu, MPROP_PERPAGE, 0);
}</pawn>
*<tt>Примечание</tt>
** Как вы можете видеть вместо command[] я указал числа. Это необходимо для более простой идентификации пунктов меню.
** Я так-же добавил menu_setprop. Это говорит нашему меню что оно не имеет страниц. Для дополнительной информации смотрите в amxconst.inc

=== Показывает меню голосования ===
Для того что-бы показать меню мы должны использовать menu_display.
<pawn>menu_display ( id, menu, page )</pawn>
* id - id пользователя которому надо показать это меню.
* menu - тут указываем хэндл меню которое показываем пользователю.
* page - какая страница (номер страницы меню) с которой начинаем. Страницы меню начинаются с 0.

Ok теперь посмотрим на наш код.
<pawn>public startvote(id)
{
for(new i = 0; i < 33; i++)
{
if( is_user_alive(i) )
{
menu_display(i, g_Menu, 0);
}
}

return PLUGIN_HANDLED;
}</pawn>
*<tt>Примечание:</tt>
** Используем цыкл для прохождения по всем игрокам и показываем меню тем кто живой.

=== Обработка выборов меню ===
Последний этап заключается в обработке выбора меню. Это делается через функцию обработки.
Она вызывается каждый раз когда пользователь сделал выбор.
Вот 3 переменные которые передаются в функцию.
* id - id пользователя
* menu - открытое меню у пользователя
* item - тут выбор пункта меню пользователем

Далее мы объявляем несколько специальных переменных таких как меню выхода.
<pawn>#define MENU_EXIT -3
#define MENU_BACK -2
#define MENU_MORE -1</pawn>

Теперь нам надо проверить если пункт меню выбран и он не является специальной переменной
<pawn>if( item < 0 ) return PLUGIN_CONTINUE;</pawn>

Следующим шагом мы получаем информацию о выбранном пункте меню. Все что мы ищем это номер пункта меню. (Да = 1, Нет = 2).
Для этого надо использовать menu_item_getinfo.
<pawn>menu_item_getinfo ( menu, item, &access, command[], cmdlen, name[]="", namelen=0, &callback )</pawn>
* menu - меню в котором находится пункт меню.
* item - the item itself
* &access - (edit)
* command[] - (edit)(это то где сохраняются идентификационные номера меню)
* cmdlen - размер command[]
* name[] - имя пункта меню
* namelen - размер name[]
* &callback - (edit)

После того как мы получили информацию о пуектах меню, надо взять из command[] номера выбранных меню(это должно быть 1 или 2).
Теперь надо добавить в g_Votes теми голосами что были сделаны.
Вот как завершонная функция должна выглядеть:
<pawn>public menu_handle(id, menu, item)
{
if( item < 0 ) return PLUGIN_CONTINUE;

// Get item info
new cmd[3];
new access, callback;

menu_item_getinfo(menu, item, access, cmd,2,_,_, callback);

new iChoice = str_to_num(cmd);

g_Votes[iChoice]++;

return PLUGIN_HANDLED;
}
</pawn>

=== Завершение ===
Это конец. Вы завершили Урок по созданию меню. Используя новую систему меню можно создать более удобное управление.
В следующем уроке вы увидите более сложную систему меню которая будет использовать callbacks, уничтожение меню и создание.
Вот код который должен получится посли всех действий.
<pawn>#include <amxmodx>

new g_Menu; // Переменная обработки главного меню
new g_Votes[3]; // Сохраняем голосования Да как 1, No как 2

public plugin_init()
{
// Регистрируем ваш плагин
register_plugin("Vote Menu","1.0","Freecode");

// Регистрируем меню смены карты
g_Menu = menu_create("Change Level?","menu_handle");

register_clcmd("amx_startvote","startvote",ADMIN_CFG,"Gaben");

// Теперь нам надо создать наше меню
build_menu();
}

build_menu()
{
menu_additem(g_Menu, "Yes", "1");
menu_additem(g_Menu, "No", "2");

menu_setprop(g_Menu, MPROP_PERPAGE, 0);
}

public startvote(id)
{
for(new i = 0; i < 33; i++)
{
if( is_user_alive(i) )
{
menu_display(i, g_Menu, 0);
}
}

return PLUGIN_HANDLED;
}

public menu_handle(id, menu, item)
{
if( item < 0 ) return PLUGIN_CONTINUE;

// Получаем информацию о пункте
new cmd[3];
new access, callback;

menu_item_getinfo(menu, item, access, cmd,2,_,_, callback);

new iChoice = str_to_num(cmd);

g_Votes[iChoice]++;

return PLUGIN_HANDLED;
}</pawn>

Ru Commands (AMX Mod X)

2007-01-23T00:21:40Z

CyberMind: added russian category

[[Category:Russian]]
[[Category:Ru:Documentation (AMX Mod X)]]

= Выбор языка =

Смотреть эту страницу на:

* [[Commands_%28AMX_Mod_X%29|English]]
* [[ru:Commands_%28AMX_Mod_X%29|Russian]]

=Введение=
Консольные команды вводятся в консоли как:
<pre>amx_<command> <option1> <option2> [option3]</pre>
Обязательные оции показаны с <>, не обязательные параметры показаны с []. Символы <> и [] в действительности вводить не нужно.

Чтобы увидеть справку во время игры, введите в консоли следующее:
<pre>amx_help</pre>

=Команды админа=
:{|
|- class="t2th"
| Команда
| Формат
| Доступ
| Описание
|- class="t2td"
| amx_kick
| <name или #userid> [причина]A
| ADMIN_KICK
| Кикнуть игрока.
|- class="t2td"
| amx_ban
| <name или #userid> <время> [причина]
| ADMIN_BAN
| Забанить игрока.
|- class="t2td"
| amx_banip
| <authid или ip> <минуты> [причина]
| ADMIN_BAN
| Забанить игрока по IP.
|- class="t2td"
| amx_addban
| <authid или ip> <минуты> [причина]
| ADMIN_BAN
| Добавить бан в бансписок.
|- class="t2td"
| amx_unban
| <authid или ip>
| ADMIN_BAN
| Разбанить игрока.
|- class="t2td"
| amx_slay
| <name или #userid>
| ADMIN_SLAY
| Убивает игрока.
|- class="t2td"
| amx_slap
| <name или #userid> [повреждение]
| ADMIN_SLAY
| Бьет игрока с силой указанной в переменной.
|- class="t2td"
| amx_leave
| <tag> [тег1] [тег2] [тег3]
| ADMIN_KICK
| Кикать всех игроков которые не имеют один из тегов.
|- class="t2td"
| amx_pause
|
| ADMIN_CVAR
| Устанавливает паузу в игре или снимает её.
|- class="t2td"
| amx_who
|
| ADMIN_ADMIN
| Выводит список текущих клиентов сервера, с указанием различных деталей, таких как уровень доступа и др.
|- class="t2td"
| amx_cvar
| <cvar> [value]
| ADMIN_CVAR
| Устанавливает или показывает cvar переменную.
|- class="t2td"
| amx_map
| <имя карты>
| ADMIN_MAP
| Меняет карту.
|- class="t2td"
| amx_nick
| <name or #userid> <новое имя>
| ADMIN_LEVEL_A
| Меняет имя пользователя (на самом деле запускает команду name удаленно на консоли пользователя - не работает если у пользователя прописано alias name)
|- class="t2td"
| amx_cfg
| <имя файла>
| ADMIN_CFG
| Загружает на стороне сервера конфигурационный файл.
|- class="t2td"
| amx_rcon
| <командная строка>
| ADMIN_RCON
| Запускает консольную команду на стороне сервера.
|- class="t2td"
| amx_showrcon
| <командная строка>
| ADMIN_RCON
| Запускает консольную команду на стороне сервера с возвратом ответа от сервера.
|- class="t2td"
| amx_plugins
|
| ADMIN_ADMIN
| Список всех загруженых плагинов.
|- class="t2td"
| amx_modules
|
| ADMIN_ADMIN
| Список всех загруженых модулей.
|}

=Команды чата=
:{|
|- class="t2th"
| Команда
| Формат
| Доступ
| Описание
|- class="t2td"
| amx_say
| <сообщение>
| ADMIN_CHAT
| Посылает сообщение всем игрокам через обычный чат.
|- class="t2td"
| amx_chat
| <сообщение>
| ADMIN_CHAT
| Посылает сообщение всем администраторам через обычный чат.
|- class="t2td"
| amx_psay
| <name или #userid> <сообщение>
| ADMIN_CHAT
| Послать личное сообщение игроку.
|- class="t2td"
| amx_tsay
| <цвет> <сообщение>
| ADMIN_CHAT
| Посылает сообщение всем игрокам. Сообщение показывается слевой стороны в игре.
|- class="t2td"
| amx_csay
| <цвет> <сообщение>
| ADMIN_CHAT
| Посылает сообщение всем игрокам. Сообщение показывается в центре экрана.
|}

=Команды голосования=
:{|
|- class="t2th"
| Команда
| Формат
| Доступ
| Описание
|- class="t2td"
| amx_votemap
| <карта> [карта] [карта] [карта]
| ADMIN_VOTE
| Начинает голосование за карту.
|- class="t2td"
| amx_votekick
| <name или #userid>
| ADMIN_VOTE
| Начинает голосование за то чтобы кикнуть игрока.
|- class="t2td"
| amx_voteban
| <name или #userid>
| ADMIN_VOTE
| Начинает голосование за то чтобы забанить игрока.
|- class="t2td"
| amx_vote
| <Вопрос> <ответ1> <ответ2>
| ADMIN_VOTE
| Начинает произвольное голосование.
|- class="t2td"
| amx_cancelvote
|
| ADMIN_VOTE
| Отменяет последнее голосование которое находится в прогрессе.
|}

=Команды статистики=
:{|
|- class="t2th"
| Команда
| Описание
|- class="t2td"
| say /hp
| Показывает информацию о вашем убийце.
|- class="t2td"
| say /statsme
| Показывает вашу статистику.
|- class="t2td"
| say /stats
| Показывает статистику других игроков.
|- class="t2td"
| say /top15
| Показывает рейтинг лучших 15 игроков.
|- class="t2td"
| say /rank
| Показывает ваш рейтинг на сервере.
|}

=Команды чата=
:{|
|- class="t2th"
| Команда
| Описание
|- class="t2td"
| say nextmap
| Показывает следующую карту в mapcycle.
|- class="t2td"
| say timeleft
| Показывает сколько времени осталось до смены карты.
|- class="t2td"
| say thetime
| Показывает текущее время.
|}

=Команды меню=
{{qnotice|ACCESS_LEVEL_A не является "a", это "m". Смотрите [[Adding Admins (AMX Mod X)#Access Levels|Уровни доступа]].}}

:{|
|- class="t2th"
| Команда
| Доступ
| Описание
|- class="t2td"
| amxmodmenu
| ADMIN_MENU
| Показывает главное AMX Mod X меню.
|- class="t2td"
| amx_cvarmenu
| ADMIN_CVAR
| Показывает CVAR меню.
|- class="t2td"
| amx_mapmenu
| ADMIN_MAP
| Показывает меню смены карт.
|- class="t2td"
| amx_votemapmenu
| ADMIN_MAP
| Показывает меню голосований.
|- class="t2td"
| amx_kickmenu
| ADMIN_KICK
| Показывает kick меню.
|- class="t2td"
| amx_banmenu
| ADMIN_BAN
| Показывает ban меню.
|- class="t2td"
| amx_slapmenu
| ADMIN_SLAY
| Показывает slap/slay меню.
|- class="t2td"
| amx_teammenu
| ADMIN_LEVEL_A
| Показывает меню смены команд.
|- class="t2td"
| amx_clcmdmenu
| ADMIN_LEVEL_A
| Показывает меню клиентских команд.
|- class="t2td"
| amx_restmenu
| ADMIN_CFG
| Показывает меню оружейного огранчения.
|- class="t2td"
| amx_teleportmenu
| ADMIN_CFG
| Показывает меню телепорта.
|- class="t2td"
| amx_pausecfgmenu
| ADMIN_CFG
| Меню установки плагинов в паузу или снятие паузы.
|- class="t2td"
| amx_statscfgmenu
| ADMIN_CFG
| Показывает меню настроек статистики.
|}

=Команда Конфига=
:{|
|-
| class="t2th" | Команда:
| class="t2td" | amx_pausecfg
|-
| class="t2th" | Формат:
| class="t2td" | <команда> [имя]
|-
| class="t2th" | Доступ:
| class="t2td" | ADMIN_CFG
|-
| class="t2th" | Описание:
| class="t2td" | Установить в паузу плагин. 
Список команд: 
*off - Установить паузу на всех плагинах которые не в списке.
*on - Снять паузу со всех плагинов.
*stop <файл> - Остановить плагин.
*pause <файл> - Установть в паузу плагин.
*enable <файл> - Включить плагин.
*save - Сохранить список остановленных плагинов.
*clear - Очистить список остановленных плагинов.
*list [id] - Список плагинов.
*add <заголовок> - Пометить плагин как не устанавливаемый в паузу.
|}

:{|
|-
| class="t2th" | Команда
| class="t2td" | amx_statscfg
|-
| class="t2th" | Формат:
| class="t2td" | <команда> [параметры]
|-
| class="t2th" | Доступ:
| class="t2td" | ADMIN_CFG
|-
| class="t2th" | Описание:
| class="t2td" | Изменение настроек статистики. 
Список команд: 
*on <переменная> - Включить выбранную опцию.
*off <переменная> - Выключить выбранную опцию.
*save - Сохранить конфигурацию статистики.
*load - Загрузить конфигурацию статистики.
*list [id] - Список статусов статистики.
*add <имя> <переменная> - Добавить переменную статистики в список.
|}

=Команды RCON=
:{|
|-
| class="t2th" | Команда:
| class="t2td" | amxx
|-
| class="t2th" | Формат:
| class="t2td" | <команда> [параметры]
|-
| class="t2th" | Доступ:
| class="t2td" |
|-
| class="t2th" | Описание:
| class="t2td" | Список доступных команд: 
*amxx version - Показать версию AMX Mod X;
*amxx modules - Показать список модулей;
*amxx plugins - Показать список плагинов;
*amxx gpl - Показать GNU General Public Лицензию;
*amxx cvars - Показать AMX Mod X зарегистрированные CVARs;
*amxx cmds - Показать AMX Mod X зарегистрированные команды;
*amxx pause <plugin> - Приостановить плагин;
*amxx unpause <plugin> - Возобновить работу приостановленного плагина.
|}

Ru Button constants (AMX Mod X)

2007-01-23T00:21:28Z

CyberMind:

[[Category:Russian]]
[[Category:Ru:Scripting (AMX Mod X)]]
=Кнопочные константы=

Просмотреть оригинал статьи (англ.): [[Button constants (AMX Mod X)]]

=Использование=

Кнопочные константы обычно используются для того, чтобы "поймать" момент, когда игрок пытается совершить какое-либо действие, нажимая на кнопки, "привязанные" к таким командам, как +attack, +use и так далее. Метод используется потому, что HL "движок" не может "поймать" +/-команды стандартным регистрированием, если их реализация выполнена в самом движке.

Например, это будет работать:<pawn>register_concmd("+explode","explode");</pawn>

А это - нет:<pawn>register_concmd("+attack","hook_attack");</pawn>

=Константы=

Полный список всех констант вы можете найти [http://amxmodx.org/funcwiki.php?go=module&id=3#const_buttons здесь].

=Реализация=

Вот, например, один из вариантов, как оперделить, нажимает ли игрок кнопку атаки или нет:<pawn>#include <amxmodx>
#include <engine>

public plugin_init()
{
register_plugin("Attack Test","1.0","Hawk552");
}

public client_PreThink(id)
{
if(entity_get_int(id, EV_INT_BUTTON) & IN_ATTACK)
{
// do something
}
}</pawn>

Обратите внимание, что используется битовый оператор &, в отличии от логического оператора &&. Оператор & проверяет, содержится ли бит после оператора в бите до него, т.е. в данном случае проверяется, есть ли среди нажатых кнопок игрока кнопка IN_ATTACK.

Чтобы заставить игрока эмулировать нажатие кнопки, можно поступить следующим образом:<pawn>#include <amxmodx>
#include <engine>

public plugin_init()
{
register_plugin("Attack Test","1.0","Hawk552");
}

public client_PreThink(id)
{
entity_set_int(id,EV_INT_button,entity_get_int(id,EV_INT_button) | IN_ATTACK);
}</pawn>

Этот пример будет выставлять флаг кнопки "атака" в положение "ВКЛ" каждый раз, когда рендерится entity игрока. Т.е. мы получаем все кнопки, нажатые в данный момент, и как бы прибавляем кнопку атаки.

Чтобы "поймать" кнопки игрока, а потом "вычесть" какую либо кнопку, можно использовать следующий метод:<pawn>#include <amxmodx>
#include <engine>

public plugin_init()
{
register_plugin("Attack Test","1.0","Hawk552");
}

public client_PreThink(id)
{
entity_set_int(id,EV_INT_button,entity_get_int(id,EV_INT_button) & ~IN_ATTACK);
}</pawn>

Например, клиент прыгает (IN_JUMP) и атакует (IN_ATTACK) одновременно, функция entity_get_int(id,EV_INT_button) будет возвращать бит сумму IN_ATTACK и IN_JUMP. Используя конструкцию & ~БИТ мы как бы удаляем конкретное значение бита, в данном случае IN_ATTACK. Таким образом, в итоге получим только IN_JUMP.

=Замечания=

Важно понимать, что нажатие какой-либо кнопки не всегда означает, что в это время происходит конкретное действие. Например, если выстрелить из пистолета и не отпускать кнопку атаки - пуля вылетит, атака закончится и не возобновится, т.к. пистолет не является автоматическим оружием, но, т.к. кнопка все еще будет нажата, то, используя вышеприведенный метод, мы получим активное состояние кнопки IN_ATTACK, хотя атаки как таковой в данный момент не осуществляется.

Более наглядный пример с прыжком. Представьте, что вы прыгнули и, не отпуская кнопки прыжка, опустились на землю. Второго прыжка не произойдет, т.к. для этого нужно отпустить кнопку и нажать ее снова. Таким образом, нажатая кнопка прыжка не говорит о том, что в данный момент вы находитесь в состоянии прыжка. Как уже было отмечено, это относится и к другим кнопкам. Поэтому, в подавляющем большинстве случаев вы не должны делать проверку на наличие нажатой кнопки, если хотите определить, совершает ли игрок соответствующее действие или нет, для этого существуют другие методы.

По большому счету метод, описанный в данной статье, может быть эффективен только для блокировки или эмуляции атаки, хотя для этого есть еще более эффективные методы. Описанный метод не может быть применим к блокировке подавляющего большинства кнопок: для этого существуют другие методы ''(TODO: указать здесь ссылку на эти методы)''.

Ru Configuring AMX Mod X

2007-01-23T00:21:18Z

CyberMind:

[[Category:Russian]]
[[Category:Ru:Documentation (AMX Mod X)]]
Данная статья переведена не полностью.

Просмотреть оригинал статьи (англ.): [[Configuring AMX Mod X]]

=Плагины=
==Установка==
Иногда плагины могут иметь свои собственные инструкции, если они требуют особенной установки. Однако данная статья поможет освоить основы установки плагинов.
#Следуйте всем указаниям, которые дает автор плагина. Если плагин требует дополнительных шагов или специальных файлов, убедитесь, что вы имеете их в правильном месте и порядке.
#Если вам был предоставлен .sma файл вместо .amxx, вам следует откомпилировать плагин самим. Для более детальной информации смотрите [[Ru:Compiling Plugins (AMX Mod X)]].
#Поместите .amxx файл в addons/amxmodx/plugins директорию.
#Добавьте имя плагина в addons\amxmodx\configs\plugins.ini. Например: <pre>myplugin.amxx</pre>
#Смените карту или перезапустите сервер. Если при загрузке сообщается о каких-либо ошибках, смотрите [[Troubleshooting AMX Mod X#Plugins|Troubleshooting AMX Mod X]].

==Удаление==
#Удалите запись из addons\amxmodx\configs\plugins.ini или добавьте в начале строки точку с запятой.
#Также можно удалить все файлы, связанные с отключаемым плагином.

Ru Intro to AMX Mod X Scripting

2007-01-23T00:21:11Z

CyberMind: added russian category

[[Category:Ru:Scripting (AMX Mod X)]]
[[Category:Russian]]
Просмотреть оригинал статьи (англ.): [[Intro to AMX Mod X Scripting]]

=Введение в AMX Mod X скриптинг=
Это руководство позволит разобраться в основах скриптинга [[AMX Mod X]] плагинов.

=Обзор=

Значит, вы хотите создать плагин? Вы должны иметь хорошее представление о том, как работает [[Pawn]], скриптинг язык, который используется для написания [[AMX Mod X]] плагинов. Поэтому в первую очередь настоятельно рекомендуется ознакомиться с фундаментальными основами [[Pawn]] и [[AMX Mod X]] скриптинга: [[Ru:Fundamental Basics of AMX Mod X Scripting]]. Желательно читать данную статью, сидя за компьютером с текстовым редактором и [[Pawn]] компилятором под рукой - хорошее подспорье для эффективного обучения. Конечно же, вы не будете сразу писать большие плагины типа WC3, Matrix Mod и CSDM, но все же статья даст вам "толчок" в мир моддинга [[AMX Mod X]]. Хороший редактор с поддержкой [[Pawn]] - это AMXX-Studio, который можно найти в секции [http://www.amxmodx.org/downloads.php AMX Mod X downloads].

Вам необходимо знать, как компилировать плагины. Обратитесь к секции [[Ru:Compiling Plugins (AMX Mod X)]] для ознакомления. Также, чтобы проверить и отладить ваш плагин, вы должны знать, как устанавливать плагины. Для этого обратитесь к секции [[Ru:Configuring AMX Mod X]].

=Введение=

AMX Mod X плагин может иметь четыре главных типа функций. Первый - "public" функция. Это означает, что функция доступна для AMX Mod X "движка". Второй тип - "native" функция, которая располагается в модуле или в ядре AMX Mod X. Третий тип - обычные пользовательские функции, которые прописываются без каких-либо специальных атрибутов. Четвертый тип - это "forward" функция, которая вызывается каждый раз, когда происходит какое-то определенное событие (forward функция также является и public). AMX Mod X плагин должен начинаться с функции, инициализирующей плагин:

<pawn>//Это делает возможным использование функций AMX Mod X ядра
//Это "влаживает" native "определители"(заголовки) из includes\amxmodx.inc
#include <amxmodx>

//Объявляем три строковых переменных
new PLUGIN[]="AMXX Demo"
new AUTHOR[]="BAILOPAN"
new VERSION[]="1.00"

//Это public функция.
//Необходимо инициализировать ваш скрипт для AMX Mod X.
//Эта функция не содержит параметров, вызывается сразу после загрузки карты.
public plugin_init()
{
//Это функция, которая "берет" три строки.
//Она регистрирует ваш плагин в AMX Mod X и присваивает некоторую основную информацию.
register_plugin(PLUGIN, VERSION, AUTHOR)
}</pawn>

Попробуйте откомпилировать скрипт, приведенный выше. Он будет очень мал, т.к. не делает ничего особенного. Однако, если вы загрузите этот скрипт и напишите "amxx plugins" в серверной консоли, вы должны увидеть новую запись в листе плагинов.

=Создание админ-комманд=

AMX Mod X предоставляет возможность простого добавления консольных админ-команд. Каждая команда "регистрируется" как консольная команда. При регистрировании команды вы должны указать четыре свойства: имя консольной команды; функцию, которая будет вызываться при использовании команды; уровень доступа, необходимый для использования команды; короткое описание команды.

Для демонстрации давайте сделаем плагин, который позволит вам изменить количество жизней игрока на сервере с помощью команды "amx_hp".

Для начала нам понадобится сделать две вещи: первая - нам нужно зарегистрировать команду в консоли. Т.к. мы "привязываем" команду к public функции, мы должны убедиться, что функция существует.

<pawn>#include <amxmodx>
#include <amxmisc> //Это содержит некоторые полезные функции
#include <fun> //Это содержит функцию для изменения жизней

new PLUGIN[]="Change Health"
new AUTHOR[]="BAILOPAN"
new VERSION[]="1.00"

public plugin_init()
{
register_plugin(PLUGIN, VERSION, AUTHOR)
register_concmd("amx_hp", "cmd_hp", ADMIN_SLAY, "<target> ")
}

public cmd_hp(id, level, cid)
{
return PLUGIN_HANDLED
}</pawn>

Первая новая функция - это "register_concmd", которая берет четыре параметра. Первый - название команды, которую необходимо набрать в консоли. Второй - название public функции, которая будет контролировать команду. Третий - уровень доступа, который необходим для вашей команды. И последний - строка, описывающая, как использовать вашу команду.

Далее мы создаем public функцию для контроля amx_hp команды. Обратите внимание, что мы даем ей три параметра. Эти параметры будут содержать специальные данные, когда команду будет использована. id будет содержать индекс(номер) игрока, который запустил команду, level будет содержать уровень доступа команды (вы должны сами осуществить проверку уровня доступа), cid будет содержать внутренний индекс(номер) команды.

Также обратите внимание на PLUGIN_HANDLED. Существует два главных return значения. PLUGIN_CONTINUE как бы означает "продолжить с нормальным выполнением", PLUGIN_HANDLED означает "блокировать дальнейшее выполнение". Разница сложно уловима, но важна. К примеру, если вы делаете "привязку" к своей команде, вы не должны возвращать PLUGIN_CONTINUE. Но если вы возвращаете PLUGIN_HANDLED, при привязанной "say" команде, это полностью заблокирует say-текст. Вы должны быть внимательны с тем, что вы выбираете для возврата в различных ситуациях. Однако, многие вещи "безразличны" к возвращаемому значению. Например, таймеры(tasks), события(events) и другие вещи, с которыми вы встретитесь позже.

Итак, как же мы убедимся, что данный пользователь - это админ, который имеет ADMIN_SLAY уровень доступа?

<pawn>public cmd_hp(id, level, cid)
{
if (!cmd_access(id, level, cid, 3))
return PLUGIN_HANDLED
return PLUGIN_HANDLED
}</pawn>

cmd_access() функция проверит информацию команды (пользователя, уровень доступа и индекс) и проверяет две вещи: что пользователь имеет доступ, и что было дано минимальное количество параметров. Мы указали три, потому что команда будет выглядеть как: amx_hp <target> <amount>, и в действительности сама команда также считается как параметр. Если cmd_access откажет, мы сразу прекращаем выполнение команды.

Следующее, что нужно решить: мы должны взять два параметра и преобразовать их. "amount" параметр прост - мы просто конвертируем его из строки в число. Другой же параметр будет по сложнее, т.к. мы хотим иметь возможность указывать на три различных типа людей:

* @CT или @T - (контр-террористы или террористы)
* @ALL - (все)
* <target> - частичное имя игрока

<pawn>public cmd_hp(id, level, cid)
{
if (!cmd_access(id, level, cid, 3))
return PLUGIN_HANDLED

new Arg1[24]
new Arg2[4]

//Берем аргументы команды из консоли
read_argv(1, Arg1, 23)
read_argv(2, Arg2, 3)

//Конвертируем количество жизней из строки в число
new Health = str_to_num(Arg2)

//Является ли первый символ @ символом?
if (Arg1[0] == '@')
{
new Team = 0
//Проверяем, какая команда была указана.
//Заметьте, что мы начинаем с [1]
// это означает, что @ не входит
if (equali(Arg1[1], "CT"))
{
Team = 2
} else if (equali(Arg1[1], "T")) {
Team = 1
}
new players[32], num
//Эта функция заполнит players[32] переменную
// верными индексами игроков. num будет содержать количество
// игроков, которые действительны.
get_players(players, num)
new i
for (i=0; i<num; i++)
{
if (!Team)
{
//Устанавливаем количество жизней этого игрока
set_user_health(players[i], Health)
} else {
if (get_user_team(players[i]) == Team)
{
set_user_health(players[i], Health)
}
}
}
} else {
//находит индекс игрока, который соответствует части указанного имени
//1 означает, что игрок с "иммунитетом" не будет учтен
new player = cmd_target(id, Arg1, 1)
if (!player)
{
//это напечатает сообщение пользователю, который запускал команду
//Формат для этой команды называется "format()" стиль,
// где первая строка форматирует сообщение соответственно
// любому количеству следующих параметров:
// %s означает строка
// %d или %i означает целое число
// %f означает дробное число
// поэтому "Privet %s, mne %d let" будет требовать
// чтобы следовали параметры строки и целого числа
console_print(id, "Izvinite, igrok %s ne mojet bit naiden ili ispol'zovan v kachestve ob'ekta!", Arg1)
return PLUGIN_HANDLED
} else {
set_user_health(player, Health)
}
}

return PLUGIN_HANDLED
}</pawn>

Таким образом, наша финальная версия amx_hp плагина будет выглядеть следующим образом:

<pawn>#include <amxmodx>
#include <fun>

new PLUGIN[]="Change Health"
new AUTHOR[]="BAILOPAN"
new VERSION[]="1.00"

public plugin_init()
{
register_plugin(PLUGIN, VERSION, AUTHOR)
register_concmd("amx_hp", "cmd_hp", ADMIN_SLAY, "<target> <hp>")
}

public cmd_hp(id, level, cid)
{
if (!cmd_access(id, level, cid, 3))
return PLUGIN_HANDLED

new Arg1[24]
new Arg2[4]

//Берем аргументы команды из консоли
read_argv(1, Arg1, 23)
read_argv(2, Arg2, 3)

//Конвертируем количество жизней из строки в число
new Health = str_to_num(Arg2)

//Является ли первый символ @ символом?
if (Arg1[0] == '@')
{
new Team = 0
if (equali(Arg1[1], "CT"))
{
Team = 2
} else if (equali(Arg1[1], "T")) {
Team = 1
}
new players[32], num
get_players(players, num)
new i
for (i=0; i<num; i++)
{
if (!Team)
{
set_user_health(players[i], Health)
} else {
if (get_user_team(players[i]) == Team)
{
set_user_health(players[i], Health)
}
}
}
} else {
new player = cmd_target(id, Arg1, 1)
if (!player)
{
console_print(id, "Izvinite, igrok %s ne mojet bit naiden ili ispol'zovan v kachestve ob'ekta!", Arg1)
return PLUGIN_HANDLED
} else {
set_user_health(player, Health)
}
}

return PLUGIN_HANDLED
}</pawn>

=Консольные переменные=

CVar - это консольная переменная. Существуют клиентские и серверные CVar'ы. К примеру, "mp_startmoney" - Counter-Strike серверная CVar, содержащая число, указывающее, сколько денег дается игрокам, когда они заходят на сервер. Вы можете создавать свои серверные CVar'ы путем их регистрирования. Давайте создадим свою amx_startmoney CVar.

<pawn>#include <amxmodx>
#include <cstrike>

public plugin_init()
{
register_plugin("CVAR Test", "1.0", "BAILOPAN")
//регистрируем amx_startmoney CVar
// и устанавливаем для нее значение по умолчанию 500
register_cvar("amx_startmoney", "500")
}

//это вызывается, когда клиент заходит непосредственно на сервер
public client_putinserver(id)
{
if (get_cvar_num("amx_startmoney") > 0)
{
cs_set_user_money(id, get_cvar_num("amx_startmoney"))
} else {
cs_set_user_money(id, get_cvar_num("mp_startmoney"))
}
}</pawn>

Вы можете устанавливать дробные, целые или строковые значения как для своих CVar, так и для любых других.

=Дополнительно=

Чтобы узнать больше о скриптинге для AMX Mod X вам следует взглянуть на native прототипы в описаниях функий или в *.inc файлах ("инклудах"). Инклуды по большому счету придерживаются двух форматов. Они имеют название в соответствии с модулем или определенным предназначением. _const добавляется, если они содержат предопределенные числа или списки. _stocks добавляется, если они содержат "помогающие" или полезные "функции-обертки". Помните, что stocks компилируются только, если вы используете их, поэтому без опаски можно "включать" файлы, содержащие большое количество stocks.

Вы также можете посетить [http://amxmodx.ucoz.ru/forum/ Форум] и задать вопросы или найти больше информации.

Ru:Fundamental Basics of AMX Mod X Scripting

2007-01-23T00:20:43Z

CyberMind: added russian category

[[Category:Russian]]
[[Category:Ru:Scripting (AMX Mod X)]]
=Фундаментальные основы AMX Mod X скриптинга=

Данная статья не дает готовых "рецептов" по [[AMX Mod X]] скриптингу, но раскрывает его фундаментальные основы. Это и типы данных, и прототипы функций и многое другое, без знания чего невозможно писать AMX Mod X плагины.

=Введение=

Прежде чем начинать писать AMX Mod X плагины, в первую очередь необходимо разобраться в основах [[Pawn]].
 Pawn – это скриптовый язык, созданный компанией ITB CompuPhase. Ранее Pawn назывался Small, но с версии 3.0 языку было решено дать более характерное название. Т.к. "pawn" в переводе с английского языка означает "пешка", можно догадаться, что основной характерной чертой данного языка является простота.
 Если вы владеете английским языком, рекомендуется ознакомиться с полным руководством по Pawn - [http://www.compuphase.com/pawn/pawn-lang.pdf Pawn The Language].
 Код плагина представляет собой текст (как правило, заключенный в файл типа *.sma), включающий множество элементов языка: комментарии, переменные, функции и др. Поэтому для оформления кода потребуется текстовый редактор. Из простейших можно выделить, например, Microsoft Notepad. Также существует AMXX-Studio – специализированый редактор для AMX Mod X плагинов, позволяющий максимально эффективно работать в соответствующей среде. Последняя версия данного редактора может быть найдена в секции [http://www.amxmodx.org/downloads.php downloads] официального сайта AMX Mod X.
 Чтобы позволить AMX Mod X выполнять код, файл с кодом необходимо откомпилировать с помощью компилятора AMXXPC (AMX Mod X Pawn Compiler). Операция компилирования преобразовывает набор текстовых инструкций в последовательность инструкций абстрактной машины (от англ. abstract machine), она же AMX, а также интерпретатор (от англ. interpreter).
 Откомпилированый код обычно помещается в файл типа *.amxx, имеющий двоичный формат. Такой файл называют AMX Mod X плагином (от англ. plugin).
 Для ознакомления с инструкциями по компилированию и установке плагинов смотрите [[Ru:Compiling Plugins (AMX Mod X)]] и [[Ru:Configuring AMX Mod X]].

=Pawn=

==Уровни кода==

В основе любого кода лежит уровневая структура. Причиной этому является нелинейность инструкций.
 Т.н. "нулевой уровень" или "глобальное пространство" является неотъемлемой частью любого кода. Как только вы приступаете к написанию нового кода, вы оказываетесь в его глобальном пространстве. Оно же в свою очередь будет включать в себя пространства с более низкими уровнями.
 Обычно глобальное пространство содержит всю общую информацию, которая может потребоваться в ходе выполнения кода пространствам более низкого уровня. Примером такой информации могут служить общие константы, переменные, списки, макросы.

==Комментарии==

Комментарий – это, как правило, текст информативного характера. Например, чтобы дать описание плагину можно использовать многострочный комментарий:<pawn>/* здесь вы помещаете
необходимую информацию */</pawn>Как видно из примера, многострочный комментарий ограничивается символами /* и */, отмечающими начало и конец комментария соответственно. Недопустимо открывать последующий комментарий, не закрыв при этом предыдущий.
 Примером однострочного комментария может быть:<pawn>/* ваш комментарий */</pawn>Хотя, можно упростить конструкцию:<pawn>// ваш комментарий</pawn>
 Как видно из последнего примера, комментарий начинается с двойного симовола обратного слеша //. Заканчивается такой комментарий вместе с концом текущей строки, поэтому не требует закрывающих символов. Такие комментарии могут быть только однострочными. Не обязательно комментарий должен начинаться с новой строки. Например, /* ... */ комментарий может быть расположен непосредственно в самом коде.
 Т.к. комментарии не считаются кодом, они исключаются из обработки. Данная особенность позволяет при необходимости исключать части кода путем комментирования, что может быть использовано, например, при отладке кода.

==Типы данных==

Технически основой всех типов данных в Pawn является т.н. "cell" – ячейка памяти, состоящая из последовательности определенного количества бит. Количество бит в такой ячейке постоянно для определенной платформы. Так для 32х битной платформы оно будет составлять 32, а для 64х битной – 64.
 Т.к. технически все данные не имеют отличия, для обозначения их типа применяются т.н. "тэги". Если при создании переменной тэг не указан, то переменная является целым числом:<pawn>new ivar // создана целочисленная переменная с именем "ivar"</pawn>
 Если при создании переменной ей не присваивается какое-либо конкретное значение, то переменная будет равна нулю. Таким образом, вышеприведенный пример технически соответствует:<pawn>new ivar = 0</pawn>
 Чтобы создать дробную переменную, необходимо использовать тэг "Float":<pawn>new Float:fvar</pawn>Переменная fvar также будет равна нулю, но ввиду соответствия типу данных это будет 0.0, т.е. технический аналог примера будет:<pawn>new Float:fvar = 0.0</pawn>Таким образом, мы обеспечиваем типовое соответствие "левой" и "правой" части.
 Одним из особых типов данных является т.н. "булевые" переменные, которые технически могут иметь только два значение, логически интерпретируемые как "истина" и "ложь" (true и false). Чтобы создать булевую переменную, необходимо использовать тэг "bool":<pawn>new bool:bvar</pawn>Т.к. численно false является нулем, то технический аналог примера будет выглядеть как:<pawn>new bool:bvar = false</pawn>
 Примечание: чтобы запретить изменение значения переменной, необходимо использовать атрибут const, например:<pawn>new const var = 1</pawn>
 Pawn также позволяет создавать массивы данных, представляющие собой набор значений определенного типа. Так примером простого массива, содержащего два целочисленных значения будет:<pawn>new array[2]</pawn>Технически данный пример выглядит следующим образом:<pawn>new array[2] = {0, 0}</pawn>Технические аналоги для Float и bool массивов выглядят как:<pawn>new Float:farray[2] = {0.0, 0.0}
new bool:barray[2] = {false, false}</pawn>
 Также существует особый тип данных, называемый "строка", технически являющийся массивом целых чисел. Каждое целое число в строковом массиве соответствует числовому ASCII коду символа. Например, код 32 соответствует пробелу. Таким образом,<pawn>new string[3] = {'h', 'i', '^0'}</pawn>является символьным представлением строкового массива<pawn>new string[3] = "hi"</pawn>Обратите внимание на наличие специального символа '^0'. Это обязательный элемент строки, указывающий на ее окончание (численно равен нулю).
 Также Pawn поддерживает многоуровневые массивы, например:<pawn>new multiarray[2][2]</pawn>Технически такой массив равен:<pawn>new multiarray[2][2] = {{0, 0}, {0, 0}}</pawn>Максимальное количество уровней массива равно 3.
 Для любого явно заданного массива его размер может не указываться, например:<pawn>new array[] = {1, 2, 3} // размер массива равен 3
new string[] = "hello" // размер массива равен 6, т.к. помимо 5 символов также включает в себя символ окончания строки '^0'</pawn>
 Чтобы инициализировать все элементы массива каким-либо конкретным значением, можно использовать символ троеточия ..., например:<pawn>new bool:is_active[16] = {true, ...}</pawn>

==Прекомпиляция==

На начальной стадии компилирования Pawn компилятор обрабатывает т.н. "статическую" часть кода. К ней можно отнести директивы, глобальные константы, списки и др.
 Директивы являются специальными инструкциями компилятора. Одна из самых широко используемых директив – это "include". Пример ее использования может быть следующим:<pawn>#include <amxmodx></pawn>Директива как бы "влаживает" содержимое указанного файла в текущую позицию. В данном случае указывается файл amxmodx.inc, который обычно расположен в amxmodx\scripting\include директории, и декларирует основные AMX Mod X функции.
 Другая директива, позволяющая конструировать т.н. "макросы", имеет название "define". Макрос удобен тем, что способен заменять простые блоки кода. Один из простейших макросов – это т.н. "макроконстанта", например:<pawn>#define VALUE 1</pawn>В названиях макросов принято использовать буквы только верхнего регистра.
 Нетехническим аналогом вышеприведенной макроконстанты является т.н. "глобальная константа":<pawn>stock const value = 1</pawn>stock атрибут позволяет не включать константу в плагин, если она не используется в коде.
 Т.н. "список" – это набор нумерованных элементов определенного типа. Например:<pawn>enum {zero, one, two} // соответствует 0, 1, 2
enum {elem1 = 1, elem2, elem3} // соответствует 1, 2, 3
enum steeps {steep1 = 10, steep2 = 20} // соответствует 10, 20</pawn>Тип списка (в вышеприведенном примере типом списка является steeps) – необязательный атрибут, по сути является тэгом, указывающим тип элементов, поэтому следующий пример является верным:<pawn>new steeps:steep = steep2</pawn>

==Функции==

Существует несколько типов функций.
 Т.н. "обычная" – обычно т.н. "вспомогательная" функция; может быть вызвана непосредственно только другими функциями данного плагина; не может быть вызвана непосредственно AMX Mod X либо его модулями.
 public – обычно функция, вызываемая непосредственно AMX Mod X либо его модулями; может быть также вызвана непосредственно другими функциями данного плагина.
 native – функция, имеющая т.н. "глобальный" характер; может быть вызвана AMX Mod X плагинами.
 forward - функция, имеющая т.н. "глобальный" характер; при наличии в плагине public функции с соответствующим именем функция будет вызываться AMX Mod X или его модулями.
 stock – обычно функция, состоящая в т.н. "библиотеке" функций; не включается в плагин, если не используется в коде.
 В общем виде заголовок, а также прототип любой функции условно выглядит следующим образом (символами треуголных скобок <> ограничены обязательные элементы, символами квадратных скобок [] ограничены необязательные элементы, которые могут быть опущены в определенных случаях):<pawn>[type] [tag]:<name>([[param1], [param2], ..., [paramN]])</pawn>, где
[type] – соответствует типу функции (для обычной функции тип не указывается).
 [tag] – соответствует типу данных возвращаемого результата функции.
 <name> - соответствует имени функции
 ([...]) – соответствует набору параметров функции; количество параметров может быть от нуля (параметры отсутствуют) до N, где N – целое положительное число.
 За заголовком функции следует т.н. "тело" функции, ограниченное символами фигурных скобок {}. Таким образом, примером простейшей функции является:<pawn>function()
{
// это пустое тело функции, имеющей имя "function"
}</pawn>Технически данная функция не выполняет никаких действий, т.к. в своем теле содержит только комментарий. Обратите внимание, что комментарий как бы сдвинут вправо относительно заголовка функции. В данном случае функция инициализирует новый уровень кода. Каждый уровень кода в целях удобочитаемости принято оформлять с соответствующим отступом. Чем более низкий уровень кода, тем больший отступ он будет иметь. Обычно в качестве отступа принято использовать символ табуляции, т.к. многие редакторы позволяют задавать видимую ширину табулированого отступа.
 Существует два способа передачи параметров функции. Т.н. "основной" способ заключается в том, что при передаче данные дублируются путем создания соответствующих копий в памяти. Т.н. способ передачи параметров "по ссылке" (от англ. by reference) состоит в том, что данные передаются "как есть", т.е. их дублирования не осуществляется, что позволяет функции изменять оригинальные данные непосредственно.
 Для параметров функции все типы массивов, в том числе и строковые, могут передаваться исключительно по ссылке. Передача остальных данных по умолчанию осуществляется основным способом. Чтобы произвести передачу параметра функции по ссылке, в заголовке функции перед параметром необходимо добавлять символ амперсанда &, например:<pawn>function(&Float:fparam)</pawn>
 Параметры функции могут иметь значения по умолчанию, например:<pawn>function(param = 1)</pawn>Таким образом, чтобы вызвать данную функцию с параметром по умолчанию, параметр можно не указывать:<pawn>function()</pawn>Также в таких случаях можно использовать символ подчеркивания _:<pawn>function(_)</pawn>
 Чтобы запретить функции изменение передаваемых данных, необходимо использовать атрибут const, например:<pawn>function(const array[])</pawn>Таким образом, можно утверждать, что в данном случае целью функции не является изменение данных массива, чего нельзя утверждать о следующей функции:<pawn>swaparray(array[2])</pawn>Исходя из названия функции, типа параметра, его размера и отсутствия запрета на изменение, можно сделать предположение о том, что данная функция меняет элементы массива местами.
 Важным свойством функции является способность возвращать результат, значение которого имеет определенный тип, например:<pawn>bool:is_true()
{
return true
}</pawn>
 Чтобы указать допустимые типы параметра функции, в заголовке функции перед параметром необходимо добавлять конструкцию, которая условно выглядит как {tag1, tag2, ..., tagN}:, т.е. представляет собой набор тэгов, количество которых может быть от одного до N, где N – целое положительное число, например:<pawn>get_integer({bool, _}:value)
{
return _:value // возвращается значение типа "целое число"
}</pawn>Смысл вышеприведенной функции заключается в том, что она принимает параметр как типа "целое число", так и булевого типа, в результате возвращая значение параметра в числовой форме.

=AMX Mod X=

==Функции==

При написании AMX Mod X плагинов важно уметь понимать назначение и принцип действия AMX Mod X функций.
 Прототипы функций, а также используемые ими константы и списки заключены в файлы типа *.inc, т.н. "инклуды" (от англ. include), которые обычно расположены в amxmodx\scripting\include директории.
 Иногда одни инклуды включают в себя другие. Так основные AMX Mod X функции (т.н. функции AMX Mod X "ядра") продекларированы в файле amxmodx.inc, который также включает векторные и другие инклуды, декларирующие функции, константы и списки, также имеющие непосредственное отношение к AMX Mod X ядру.
 Одной из основных функций AMX Mod X является forward функция plugin_init. Если в коде плагина имеется public функция plugin_init, она будет вызвана AMX Mod X после загрузки карты на сервере. Обычно в plugin_init регистрируют сам плагин, его команды, переменные и т.п.
 Плагин регистрируют с помощью native функции register_plugin. Т.к. прототип register_plugin соответствует:<pawn>native register_plugin(const plugin_name[], const version[], const author[])</pawn>, можно понять, что в качестве параметров функция принимает три строковых массива, соответствующих названию плагина, номеру его версии и автору плагина.
 Итак, примером простого AMX Mod X плагина является:<pawn>#include <amxmodx>
public plugin_init()
{
register_plugin("Test", "0.1", "VEN")
}</pawn>По сути данный плагин не выполняет каких-либо действий, но регистрирует себя в AMX Mod X с указанными данными.

==Системы функционирования==

AMX Mod X предоставляет большое количество определенных систем функционирования. Так одна из основных систем – это система контроля уровней доступа. Здесь имеют место соответствующие функции, например get_user_flags, а также константы стандартных уровней доступа типа ADMIN_*.
 Система регистрирования и контроля консольных команд также "пересекается" с системой контроля уровней доступа и использует такие функции, как например register_concmd и cmd_access.
 Также существует множество других систем, среди которых имеется система регистрирования и контроля серверных консольных переменных (англ.: Server CVars), клиентских меню и др.
 Как правило, системы регистрирования используют т.н. "handle" (или "hook") функции, которые вызываются системой в необходимый момент.
 Так после регистрирования консольной команды "action":<pawn>register_concmd("action", "action_handler")</pawn>при исполнении данной команды из консоли сервера или клиента система попытается найти и выполнить public функцию action_handler.

==Система строкового форматирования==

Многие AMX Mod X функции используют систему строкового форматирования. Например, это все *_print функции.
 Такие функции принимают практически неограниченное количество параметров, которые используются при форматировании соответствующей строковой конструкции. Для наглядности рассмотрим пример:<pawn>server_print("Formatted string: %d %f %s %c", 1, 1.234567, "hello", '!')</pawn>Функция server_print отформатирует строковую конструкцию "Formatted string: %d %f %s %c", используя переданные параметры, и выведет в серверной консоли строку:<pawn>Formatted string: 1 1.234567 hello !</pawn>Таким образом, %d, %f, %s, %c – специальные элементы, используемые для форматирования целого числа, дробного числа, строки и символа соответственно.
 Опасно при использовании функций, поддерживающих форматирование, передавать строковую переменную непосредственно в параметр строковой конструкции, например:<pawn>server_print(string)</pawn>Безопасный вариант выглядит, следующим образом:<pawn>server_print("%s", string)</pawn>
 Т.к. символ процента % является, т.н. "специальным символом", для его форматирования в строковой конструкции необходимо использовать двойной символ процента %%, например:<pawn> server_print("This is a single symbol of percent: %%")</pawn>выведет в серверной консоли:<pawn> This is a single symbol of percent: %</pawn>
 Также существует т.н. "контрольный символ" (от англ. control character), позволяющий использовать т.н. "специальные символы форматирования". Контрольным символом по умолчанию является символ ^, который может быть изменен директивой pragma ctrlchar, например:<pawn>#pragma ctrlchar '\'</pawn>изменит контрольный символ на \.
 Примеры некоторых специальных символов форматирования приведены ниже:
 ^t – табуляция
 ^n – новая строка
 ^xHH – символ, представленный в шестнадцатиричном формате, где HH – двойное число, представленное в шестнадцатиричном формате

Ru Compiling Plugins (AMX Mod X)

2007-01-23T00:20:32Z

CyberMind: added russian category

[[Category:Russian]]
[[Category:Ru:Scripting (AMX Mod X)]]
Просмотреть оригинал статьи (англ.): [[Compiling Plugins (AMX Mod X)]]

=Компилирование плагинов=

Эта статья описывает, как компилировать [[AMX Mod X]] плагины из [[Ru:source code|исходного кода]] (.sma).

Для всех случаев вы должны поместить .sma файл в директорию addons/amxmodx/scripting.

=Windows=

==Метод перетаскивания==
#Перетащите .sma файл на "compile.exe".
#Откомпилированный .amxx файл будет находиться в директории compiled.

==Компилирование всех плагинов==
#Дважды щелкните на compile.exe, чтобы откомпилировать все плагины и поместить их в директорию compiled.
==Командная строка==
#Зайдите в "Пуск", "Выполнить", введите "cmd", нажмите Ok.
#Используйте cd, чтобы сменить директорию, например: <pre>cd c:\hlserver\cstrike\addons\amxmodx\scripting</pre>
#Используйте amxxpc, чтобы откомпилировать плагин: <pre>amxxpc.exe myplugin.sma</pre>
#Откомпилированный плагин будет в этой же директории.

=Linux=

Сперва перейдите в scripting директорию в вашей оболочке следующим образом: <pre>cd addons/amxmodx/scripting</pre>

==Компилирование всех плагинов==
#Запустите скрипт compile.sh одним из способов: <pre>sh compile.sh</pre> or <pre>chmod +x compile.sh
./compile.sh</pre>

==Компилирование одиночного плагина==
#Запустите amxxpc, например: <pre>./amxxpc myplugin.sma</pre>
#Откомпилированный плагин будет в этой же директории.

Talk:Alternative Language

2007-01-22T22:43:01Z

CyberMind:

I want to translate into Norwegian, how can I add the language to the LanguageSwitch template?
:The language template needs to be redone, it doesn't work when you use it on a foreign page, only on English. --[[User:CyberMind|cybermind]] 12:10, 22 January 2007 (CST)
::AMWiki needs to have an "Ru" namespace added (and perhaps an "No" namespace) in order for Template:LangaugeSwitch to work as desired. [http://meta.wikimedia.org/wiki/Help:Custom_namespaces Here] are MediaWiki instructions for how to add it. Also all the old Talk:Ru:blah pages will have to be moved over to Ru_talk if you decide to use that for the Ru namespace talk pages. --[[User:CyberMind|cybermind]] 12:15, 22 January 2007 (CST)
:::I've renamed all the Ru: pages so that when the namespace is added, the pages will not become inaccessible (I will move them to the new namespace once it is created). I also added a new template, LanguageHelpSwitch which will be used where the namespace for the English version of the page is Help: but the Russian is just Ru: (like Help:Editing vs Ru:Editing). --[[User:CyberMind|cybermind]] 12:27, 22 January 2007 (CST)

----
[http://wiki.amxmodx.org/index.php/Category:Ru:Scripting_%28AMX_Mod_X%29 Category:Ru:Scripting (AMX Mod X)] contain broken links. What is the best to do here? Should i create Category:Ru Scripting (AMX Mod X) and relink related articles here?
:They should all work now. The Category names can stay Ru: since you can't have any other category namespaces other than Category, so Category:Ru: would be like a sub-namespace sort of. Also, once the Ru namespace is made, the Ru articles will be moved back to Ru:Whatever which will make them active in the Ru namespace (right now, there is no Ru namespace, that was just a part of those articles' titles). Once that happens, the LanguageSwitch (and LanguageHelpSwitch) templates will work perfectly. For now, nothing else should be modified and we should wait for the namespaces to be created before we figure out what else needs to be changed. --[[User:CyberMind|cybermind]] 16:42, 22 January 2007 (CST)

Talk:Alternative Language

2007-01-22T22:42:10Z

CyberMind:

I want to translate into Norwegian, how can I add the language to the LanguageSwitch template?
:The language template needs to be redone, it doesn't work when you use it on a foreign page, only on English. --[[User:CyberMind|cybermind]] 12:10, 22 January 2007 (CST)
::AMWiki needs to have an "Ru" namespace added (and perhaps an "No" namespace) in order for Template:LangaugeSwitch to work as desired. [http://meta.wikimedia.org/wiki/Help:Custom_namespaces Here] are MediaWiki instructions for how to add it. Also all the old Talk:Ru:blah pages will have to be moved over to Ru_talk if you decide to use that for the Ru namespace talk pages. --[[User:CyberMind|cybermind]] 12:15, 22 January 2007 (CST)
:::I've renamed all the Ru: pages so that when the namespace is added, the pages will not become inaccessible (I will move them to the new namespace once it is created). I also added a new template, LanguageHelpSwitch which will be used where the namespace for the English version of the page is Help: but the Russian is just Ru: (like Help:Editing vs Ru:Editing). --[[User:CyberMind|cybermind]] 12:27, 22 January 2007 (CST)

----
[http://wiki.amxmodx.org/index.php/Category:Ru:Scripting_%28AMX_Mod_X%29 Category:Ru:Scripting (AMX Mod X)] contain broken links. What is the best to do here? Should i create Category:Ru Scripting (AMX Mod X) and relink related articles here?
:They should all work now. The Category names can stay Ru: since you can't have any other category namespaces other than Category, so Category:Ru: would be like a sub-namespace sort of. Also, once the Ru namespace is made, the Ru articles will be moved back to Ru:Whatever which will make them active in the Ru namespace (right now, there is no Ru namespace, that was just a part of those articles' titles). Once that happens, the LanguageSwitch (and LanguageHelpSwitch) templates will work perfectly. --[[User:CyberMind|cybermind]] 16:42, 22 January 2007 (CST)

Talk:Alternative Language

2007-01-22T18:29:36Z

CyberMind:

Talk:Alternative Language

2007-01-22T18:27:13Z

CyberMind:

Template:LanguageHelpSwitch

2007-01-22T18:25:18Z

CyberMind:

<table width="100%" style="border: 1px solid #AAAAAA; background-color: #EEEEEE">
<tr><td width="80%">
'''View this page in:'''
 [[Help:{{PAGENAME}}|English]]
 [[Ru:{{PAGENAME}}|Russian]]
</td><td width="20%" align="right">
</td></tr>
</table>

Help:Editing

2007-01-22T18:25:03Z

CyberMind:

{{LanguageHelpSwitch}}
To read more about editing a wiki, see the MediaWiki editing documentation here: [http://meta.wikimedia.org/wiki/Help:Editing MediaWiki Editing]

Ru Configuring AMX Mod X

2007-01-22T18:21:27Z

CyberMind: Ru:Configuring AMX Mod X moved to Ru Configuring AMX Mod X

[[Category:Ru:Documentation (AMX Mod X)]]
Данная статья переведена не полностью.

Просмотреть оригинал статьи (англ.): [[Configuring AMX Mod X]]

=Плагины=
==Установка==
Иногда плагины могут иметь свои собственные инструкции, если они требуют особенной установки. Однако данная статья поможет освоить основы установки плагинов.
#Следуйте всем указаниям, которые дает автор плагина. Если плагин требует дополнительных шагов или специальных файлов, убедитесь, что вы имеете их в правильном месте и порядке.
#Если вам был предоставлен .sma файл вместо .amxx, вам следует откомпилировать плагин самим. Для более детальной информации смотрите [[Ru:Compiling Plugins (AMX Mod X)]].
#Поместите .amxx файл в addons/amxmodx/plugins директорию.
#Добавьте имя плагина в addons\amxmodx\configs\plugins.ini. Например: <pre>myplugin.amxx</pre>
#Смените карту или перезапустите сервер. Если при загрузке сообщается о каких-либо ошибках, смотрите [[Troubleshooting AMX Mod X#Plugins|Troubleshooting AMX Mod X]].

==Удаление==
#Удалите запись из addons\amxmodx\configs\plugins.ini или добавьте в начале строки точку с запятой.
#Также можно удалить все файлы, связанные с отключаемым плагином.

Ru Scripting (AMX Mod X)

2007-01-22T18:20:57Z

CyberMind: Ru:Scripting (AMX Mod X) moved to Ru Scripting (AMX Mod X)

[[Category:Russian]]
[[AMX Mod X]] позволяет расширить функциональность игры с помощью плагинов. Перейдите в категорию [http://wiki.amxmodx.org/index.php/Category:Ru:Scripting_%28AMX_Mod_X%29 Ru:Scripting (AMX Mod X)], чтобы просмотреть список некторых статей, которые помогут вам разработать свои (или доработать чужие) плагины, используя язык [[Pawn]] (известный ранее как [[Small]]).

Ru Editing

2007-01-22T18:20:50Z

CyberMind: Ru:Editing moved to Ru Editing

[[Category:Russian]]
Чтобы узнать больше о том, как редактировать wiki-страницы, посетите страницу Википедии [http://ru.wikipedia.org/wiki/Википедия:Как_править_статьи Как править статьи].

Ru Commands (AMX Mod X)

2007-01-22T18:20:43Z

CyberMind: Ru:Commands (AMX Mod X) moved to Ru Commands (AMX Mod X)

[[Category:Ru:Documentation (AMX Mod X)]]

= Выбор языка =

Смотреть эту страницу на:

* [[Commands_%28AMX_Mod_X%29|English]]
* [[ru:Commands_%28AMX_Mod_X%29|Russian]]

=Введение=
Консольные команды вводятся в консоли как:
<pre>amx_<command> <option1> <option2> [option3]</pre>
Обязательные оции показаны с <>, не обязательные параметры показаны с []. Символы <> и [] в действительности вводить не нужно.

Чтобы увидеть справку во время игры, введите в консоли следующее:
<pre>amx_help</pre>

=Команды админа=
:{|
|- class="t2th"
| Команда
| Формат
| Доступ
| Описание
|- class="t2td"
| amx_kick
| <name или #userid> [причина]A
| ADMIN_KICK
| Кикнуть игрока.
|- class="t2td"
| amx_ban
| <name или #userid> <время> [причина]
| ADMIN_BAN
| Забанить игрока.
|- class="t2td"
| amx_banip
| <authid или ip> <минуты> [причина]
| ADMIN_BAN
| Забанить игрока по IP.
|- class="t2td"
| amx_addban
| <authid или ip> <минуты> [причина]
| ADMIN_BAN
| Добавить бан в бансписок.
|- class="t2td"
| amx_unban
| <authid или ip>
| ADMIN_BAN
| Разбанить игрока.
|- class="t2td"
| amx_slay
| <name или #userid>
| ADMIN_SLAY
| Убивает игрока.
|- class="t2td"
| amx_slap
| <name или #userid> [повреждение]
| ADMIN_SLAY
| Бьет игрока с силой указанной в переменной.
|- class="t2td"
| amx_leave
| <tag> [тег1] [тег2] [тег3]
| ADMIN_KICK
| Кикать всех игроков которые не имеют один из тегов.
|- class="t2td"
| amx_pause
|
| ADMIN_CVAR
| Устанавливает паузу в игре или снимает её.
|- class="t2td"
| amx_who
|
| ADMIN_ADMIN
| Выводит список текущих клиентов сервера, с указанием различных деталей, таких как уровень доступа и др.
|- class="t2td"
| amx_cvar
| <cvar> [value]
| ADMIN_CVAR
| Устанавливает или показывает cvar переменную.
|- class="t2td"
| amx_map
| <имя карты>
| ADMIN_MAP
| Меняет карту.
|- class="t2td"
| amx_nick
| <name or #userid> <новое имя>
| ADMIN_LEVEL_A
| Меняет имя пользователя (на самом деле запускает команду name удаленно на консоли пользователя - не работает если у пользователя прописано alias name)
|- class="t2td"
| amx_cfg
| <имя файла>
| ADMIN_CFG
| Загружает на стороне сервера конфигурационный файл.
|- class="t2td"
| amx_rcon
| <командная строка>
| ADMIN_RCON
| Запускает консольную команду на стороне сервера.
|- class="t2td"
| amx_showrcon
| <командная строка>
| ADMIN_RCON
| Запускает консольную команду на стороне сервера с возвратом ответа от сервера.
|- class="t2td"
| amx_plugins
|
| ADMIN_ADMIN
| Список всех загруженых плагинов.
|- class="t2td"
| amx_modules
|
| ADMIN_ADMIN
| Список всех загруженых модулей.
|}

=Команды чата=
:{|
|- class="t2th"
| Команда
| Формат
| Доступ
| Описание
|- class="t2td"
| amx_say
| <сообщение>
| ADMIN_CHAT
| Посылает сообщение всем игрокам через обычный чат.
|- class="t2td"
| amx_chat
| <сообщение>
| ADMIN_CHAT
| Посылает сообщение всем администраторам через обычный чат.
|- class="t2td"
| amx_psay
| <name или #userid> <сообщение>
| ADMIN_CHAT
| Послать личное сообщение игроку.
|- class="t2td"
| amx_tsay
| <цвет> <сообщение>
| ADMIN_CHAT
| Посылает сообщение всем игрокам. Сообщение показывается слевой стороны в игре.
|- class="t2td"
| amx_csay
| <цвет> <сообщение>
| ADMIN_CHAT
| Посылает сообщение всем игрокам. Сообщение показывается в центре экрана.
|}

=Команды голосования=
:{|
|- class="t2th"
| Команда
| Формат
| Доступ
| Описание
|- class="t2td"
| amx_votemap
| <карта> [карта] [карта] [карта]
| ADMIN_VOTE
| Начинает голосование за карту.
|- class="t2td"
| amx_votekick
| <name или #userid>
| ADMIN_VOTE
| Начинает голосование за то чтобы кикнуть игрока.
|- class="t2td"
| amx_voteban
| <name или #userid>
| ADMIN_VOTE
| Начинает голосование за то чтобы забанить игрока.
|- class="t2td"
| amx_vote
| <Вопрос> <ответ1> <ответ2>
| ADMIN_VOTE
| Начинает произвольное голосование.
|- class="t2td"
| amx_cancelvote
|
| ADMIN_VOTE
| Отменяет последнее голосование которое находится в прогрессе.
|}

=Команды статистики=
:{|
|- class="t2th"
| Команда
| Описание
|- class="t2td"
| say /hp
| Показывает информацию о вашем убийце.
|- class="t2td"
| say /statsme
| Показывает вашу статистику.
|- class="t2td"
| say /stats
| Показывает статистику других игроков.
|- class="t2td"
| say /top15
| Показывает рейтинг лучших 15 игроков.
|- class="t2td"
| say /rank
| Показывает ваш рейтинг на сервере.
|}

=Команды чата=
:{|
|- class="t2th"
| Команда
| Описание
|- class="t2td"
| say nextmap
| Показывает следующую карту в mapcycle.
|- class="t2td"
| say timeleft
| Показывает сколько времени осталось до смены карты.
|- class="t2td"
| say thetime
| Показывает текущее время.
|}

=Команды меню=
{{qnotice|ACCESS_LEVEL_A не является "a", это "m". Смотрите [[Adding Admins (AMX Mod X)#Access Levels|Уровни доступа]].}}

:{|
|- class="t2th"
| Команда
| Доступ
| Описание
|- class="t2td"
| amxmodmenu
| ADMIN_MENU
| Показывает главное AMX Mod X меню.
|- class="t2td"
| amx_cvarmenu
| ADMIN_CVAR
| Показывает CVAR меню.
|- class="t2td"
| amx_mapmenu
| ADMIN_MAP
| Показывает меню смены карт.
|- class="t2td"
| amx_votemapmenu
| ADMIN_MAP
| Показывает меню голосований.
|- class="t2td"
| amx_kickmenu
| ADMIN_KICK
| Показывает kick меню.
|- class="t2td"
| amx_banmenu
| ADMIN_BAN
| Показывает ban меню.
|- class="t2td"
| amx_slapmenu
| ADMIN_SLAY
| Показывает slap/slay меню.
|- class="t2td"
| amx_teammenu
| ADMIN_LEVEL_A
| Показывает меню смены команд.
|- class="t2td"
| amx_clcmdmenu
| ADMIN_LEVEL_A
| Показывает меню клиентских команд.
|- class="t2td"
| amx_restmenu
| ADMIN_CFG
| Показывает меню оружейного огранчения.
|- class="t2td"
| amx_teleportmenu
| ADMIN_CFG
| Показывает меню телепорта.
|- class="t2td"
| amx_pausecfgmenu
| ADMIN_CFG
| Меню установки плагинов в паузу или снятие паузы.
|- class="t2td"
| amx_statscfgmenu
| ADMIN_CFG
| Показывает меню настроек статистики.
|}

=Команда Конфига=
:{|
|-
| class="t2th" | Команда:
| class="t2td" | amx_pausecfg
|-
| class="t2th" | Формат:
| class="t2td" | <команда> [имя]
|-
| class="t2th" | Доступ:
| class="t2td" | ADMIN_CFG
|-
| class="t2th" | Описание:
| class="t2td" | Установить в паузу плагин. 
Список команд: 
*off - Установить паузу на всех плагинах которые не в списке.
*on - Снять паузу со всех плагинов.
*stop <файл> - Остановить плагин.
*pause <файл> - Установть в паузу плагин.
*enable <файл> - Включить плагин.
*save - Сохранить список остановленных плагинов.
*clear - Очистить список остановленных плагинов.
*list [id] - Список плагинов.
*add <заголовок> - Пометить плагин как не устанавливаемый в паузу.
|}

:{|
|-
| class="t2th" | Команда
| class="t2td" | amx_statscfg
|-
| class="t2th" | Формат:
| class="t2td" | <команда> [параметры]
|-
| class="t2th" | Доступ:
| class="t2td" | ADMIN_CFG
|-
| class="t2th" | Описание:
| class="t2td" | Изменение настроек статистики. 
Список команд: 
*on <переменная> - Включить выбранную опцию.
*off <переменная> - Выключить выбранную опцию.
*save - Сохранить конфигурацию статистики.
*load - Загрузить конфигурацию статистики.
*list [id] - Список статусов статистики.
*add <имя> <переменная> - Добавить переменную статистики в список.
|}

=Команды RCON=
:{|
|-
| class="t2th" | Команда:
| class="t2td" | amxx
|-
| class="t2th" | Формат:
| class="t2td" | <команда> [параметры]
|-
| class="t2th" | Доступ:
| class="t2td" |
|-
| class="t2th" | Описание:
| class="t2td" | Список доступных команд: 
*amxx version - Показать версию AMX Mod X;
*amxx modules - Показать список модулей;
*amxx plugins - Показать список плагинов;
*amxx gpl - Показать GNU General Public Лицензию;
*amxx cvars - Показать AMX Mod X зарегистрированные CVARs;
*amxx cmds - Показать AMX Mod X зарегистрированные команды;
*amxx pause <plugin> - Приостановить плагин;
*amxx unpause <plugin> - Возобновить работу приостановленного плагина.
|}

Ru Intro to AMX Mod X Scripting

2007-01-22T18:20:33Z

CyberMind: Ru:Intro to AMX Mod X Scripting moved to Ru Intro to AMX Mod X Scripting

[[Category:Ru:Scripting (AMX Mod X)]]
Просмотреть оригинал статьи (англ.): [[Intro to AMX Mod X Scripting]]

=Введение в AMX Mod X скриптинг=
Это руководство позволит разобраться в основах скриптинга [[AMX Mod X]] плагинов.

=Обзор=

Значит, вы хотите создать плагин? Вы должны иметь хорошее представление о том, как работает [[Pawn]], скриптинг язык, который используется для написания [[AMX Mod X]] плагинов. Поэтому в первую очередь настоятельно рекомендуется ознакомиться с фундаментальными основами [[Pawn]] и [[AMX Mod X]] скриптинга: [[Ru:Fundamental Basics of AMX Mod X Scripting]]. Желательно читать данную статью, сидя за компьютером с текстовым редактором и [[Pawn]] компилятором под рукой - хорошее подспорье для эффективного обучения. Конечно же, вы не будете сразу писать большие плагины типа WC3, Matrix Mod и CSDM, но все же статья даст вам "толчок" в мир моддинга [[AMX Mod X]]. Хороший редактор с поддержкой [[Pawn]] - это AMXX-Studio, который можно найти в секции [http://www.amxmodx.org/downloads.php AMX Mod X downloads].

Вам необходимо знать, как компилировать плагины. Обратитесь к секции [[Ru:Compiling Plugins (AMX Mod X)]] для ознакомления. Также, чтобы проверить и отладить ваш плагин, вы должны знать, как устанавливать плагины. Для этого обратитесь к секции [[Ru:Configuring AMX Mod X]].

=Введение=

AMX Mod X плагин может иметь четыре главных типа функций. Первый - "public" функция. Это означает, что функция доступна для AMX Mod X "движка". Второй тип - "native" функция, которая располагается в модуле или в ядре AMX Mod X. Третий тип - обычные пользовательские функции, которые прописываются без каких-либо специальных атрибутов. Четвертый тип - это "forward" функция, которая вызывается каждый раз, когда происходит какое-то определенное событие (forward функция также является и public). AMX Mod X плагин должен начинаться с функции, инициализирующей плагин:

<pawn>//Это делает возможным использование функций AMX Mod X ядра
//Это "влаживает" native "определители"(заголовки) из includes\amxmodx.inc
#include <amxmodx>

//Объявляем три строковых переменных
new PLUGIN[]="AMXX Demo"
new AUTHOR[]="BAILOPAN"
new VERSION[]="1.00"

//Это public функция.
//Необходимо инициализировать ваш скрипт для AMX Mod X.
//Эта функция не содержит параметров, вызывается сразу после загрузки карты.
public plugin_init()
{
//Это функция, которая "берет" три строки.
//Она регистрирует ваш плагин в AMX Mod X и присваивает некоторую основную информацию.
register_plugin(PLUGIN, VERSION, AUTHOR)
}</pawn>

Попробуйте откомпилировать скрипт, приведенный выше. Он будет очень мал, т.к. не делает ничего особенного. Однако, если вы загрузите этот скрипт и напишите "amxx plugins" в серверной консоли, вы должны увидеть новую запись в листе плагинов.

=Создание админ-комманд=

AMX Mod X предоставляет возможность простого добавления консольных админ-команд. Каждая команда "регистрируется" как консольная команда. При регистрировании команды вы должны указать четыре свойства: имя консольной команды; функцию, которая будет вызываться при использовании команды; уровень доступа, необходимый для использования команды; короткое описание команды.

Для демонстрации давайте сделаем плагин, который позволит вам изменить количество жизней игрока на сервере с помощью команды "amx_hp".

Для начала нам понадобится сделать две вещи: первая - нам нужно зарегистрировать команду в консоли. Т.к. мы "привязываем" команду к public функции, мы должны убедиться, что функция существует.

<pawn>#include <amxmodx>
#include <amxmisc> //Это содержит некоторые полезные функции
#include <fun> //Это содержит функцию для изменения жизней

new PLUGIN[]="Change Health"
new AUTHOR[]="BAILOPAN"
new VERSION[]="1.00"

public plugin_init()
{
register_plugin(PLUGIN, VERSION, AUTHOR)
register_concmd("amx_hp", "cmd_hp", ADMIN_SLAY, "<target> ")
}

public cmd_hp(id, level, cid)
{
return PLUGIN_HANDLED
}</pawn>

Первая новая функция - это "register_concmd", которая берет четыре параметра. Первый - название команды, которую необходимо набрать в консоли. Второй - название public функции, которая будет контролировать команду. Третий - уровень доступа, который необходим для вашей команды. И последний - строка, описывающая, как использовать вашу команду.

Далее мы создаем public функцию для контроля amx_hp команды. Обратите внимание, что мы даем ей три параметра. Эти параметры будут содержать специальные данные, когда команду будет использована. id будет содержать индекс(номер) игрока, который запустил команду, level будет содержать уровень доступа команды (вы должны сами осуществить проверку уровня доступа), cid будет содержать внутренний индекс(номер) команды.

Также обратите внимание на PLUGIN_HANDLED. Существует два главных return значения. PLUGIN_CONTINUE как бы означает "продолжить с нормальным выполнением", PLUGIN_HANDLED означает "блокировать дальнейшее выполнение". Разница сложно уловима, но важна. К примеру, если вы делаете "привязку" к своей команде, вы не должны возвращать PLUGIN_CONTINUE. Но если вы возвращаете PLUGIN_HANDLED, при привязанной "say" команде, это полностью заблокирует say-текст. Вы должны быть внимательны с тем, что вы выбираете для возврата в различных ситуациях. Однако, многие вещи "безразличны" к возвращаемому значению. Например, таймеры(tasks), события(events) и другие вещи, с которыми вы встретитесь позже.

Итак, как же мы убедимся, что данный пользователь - это админ, который имеет ADMIN_SLAY уровень доступа?

<pawn>public cmd_hp(id, level, cid)
{
if (!cmd_access(id, level, cid, 3))
return PLUGIN_HANDLED
return PLUGIN_HANDLED
}</pawn>

cmd_access() функция проверит информацию команды (пользователя, уровень доступа и индекс) и проверяет две вещи: что пользователь имеет доступ, и что было дано минимальное количество параметров. Мы указали три, потому что команда будет выглядеть как: amx_hp <target> <amount>, и в действительности сама команда также считается как параметр. Если cmd_access откажет, мы сразу прекращаем выполнение команды.

Следующее, что нужно решить: мы должны взять два параметра и преобразовать их. "amount" параметр прост - мы просто конвертируем его из строки в число. Другой же параметр будет по сложнее, т.к. мы хотим иметь возможность указывать на три различных типа людей:

* @CT или @T - (контр-террористы или террористы)
* @ALL - (все)
* <target> - частичное имя игрока

<pawn>public cmd_hp(id, level, cid)
{
if (!cmd_access(id, level, cid, 3))
return PLUGIN_HANDLED

new Arg1[24]
new Arg2[4]

//Берем аргументы команды из консоли
read_argv(1, Arg1, 23)
read_argv(2, Arg2, 3)

//Конвертируем количество жизней из строки в число
new Health = str_to_num(Arg2)

//Является ли первый символ @ символом?
if (Arg1[0] == '@')
{
new Team = 0
//Проверяем, какая команда была указана.
//Заметьте, что мы начинаем с [1]
// это означает, что @ не входит
if (equali(Arg1[1], "CT"))
{
Team = 2
} else if (equali(Arg1[1], "T")) {
Team = 1
}
new players[32], num
//Эта функция заполнит players[32] переменную
// верными индексами игроков. num будет содержать количество
// игроков, которые действительны.
get_players(players, num)
new i
for (i=0; i<num; i++)
{
if (!Team)
{
//Устанавливаем количество жизней этого игрока
set_user_health(players[i], Health)
} else {
if (get_user_team(players[i]) == Team)
{
set_user_health(players[i], Health)
}
}
}
} else {
//находит индекс игрока, который соответствует части указанного имени
//1 означает, что игрок с "иммунитетом" не будет учтен
new player = cmd_target(id, Arg1, 1)
if (!player)
{
//это напечатает сообщение пользователю, который запускал команду
//Формат для этой команды называется "format()" стиль,
// где первая строка форматирует сообщение соответственно
// любому количеству следующих параметров:
// %s означает строка
// %d или %i означает целое число
// %f означает дробное число
// поэтому "Privet %s, mne %d let" будет требовать
// чтобы следовали параметры строки и целого числа
console_print(id, "Izvinite, igrok %s ne mojet bit naiden ili ispol'zovan v kachestve ob'ekta!", Arg1)
return PLUGIN_HANDLED
} else {
set_user_health(player, Health)
}
}

return PLUGIN_HANDLED
}</pawn>

Таким образом, наша финальная версия amx_hp плагина будет выглядеть следующим образом:

<pawn>#include <amxmodx>
#include <fun>

new PLUGIN[]="Change Health"
new AUTHOR[]="BAILOPAN"
new VERSION[]="1.00"

public plugin_init()
{
register_plugin(PLUGIN, VERSION, AUTHOR)
register_concmd("amx_hp", "cmd_hp", ADMIN_SLAY, "<target> <hp>")
}

public cmd_hp(id, level, cid)
{
if (!cmd_access(id, level, cid, 3))
return PLUGIN_HANDLED

new Arg1[24]
new Arg2[4]

//Берем аргументы команды из консоли
read_argv(1, Arg1, 23)
read_argv(2, Arg2, 3)

//Конвертируем количество жизней из строки в число
new Health = str_to_num(Arg2)

//Является ли первый символ @ символом?
if (Arg1[0] == '@')
{
new Team = 0
if (equali(Arg1[1], "CT"))
{
Team = 2
} else if (equali(Arg1[1], "T")) {
Team = 1
}
new players[32], num
get_players(players, num)
new i
for (i=0; i<num; i++)
{
if (!Team)
{
set_user_health(players[i], Health)
} else {
if (get_user_team(players[i]) == Team)
{
set_user_health(players[i], Health)
}
}
}
} else {
new player = cmd_target(id, Arg1, 1)
if (!player)
{
console_print(id, "Izvinite, igrok %s ne mojet bit naiden ili ispol'zovan v kachestve ob'ekta!", Arg1)
return PLUGIN_HANDLED
} else {
set_user_health(player, Health)
}
}

return PLUGIN_HANDLED
}</pawn>

=Консольные переменные=

CVar - это консольная переменная. Существуют клиентские и серверные CVar'ы. К примеру, "mp_startmoney" - Counter-Strike серверная CVar, содержащая число, указывающее, сколько денег дается игрокам, когда они заходят на сервер. Вы можете создавать свои серверные CVar'ы путем их регистрирования. Давайте создадим свою amx_startmoney CVar.

<pawn>#include <amxmodx>
#include <cstrike>

public plugin_init()
{
register_plugin("CVAR Test", "1.0", "BAILOPAN")
//регистрируем amx_startmoney CVar
// и устанавливаем для нее значение по умолчанию 500
register_cvar("amx_startmoney", "500")
}

//это вызывается, когда клиент заходит непосредственно на сервер
public client_putinserver(id)
{
if (get_cvar_num("amx_startmoney") > 0)
{
cs_set_user_money(id, get_cvar_num("amx_startmoney"))
} else {
cs_set_user_money(id, get_cvar_num("mp_startmoney"))
}
}</pawn>

Вы можете устанавливать дробные, целые или строковые значения как для своих CVar, так и для любых других.

=Дополнительно=

Чтобы узнать больше о скриптинге для AMX Mod X вам следует взглянуть на native прототипы в описаниях функий или в *.inc файлах ("инклудах"). Инклуды по большому счету придерживаются двух форматов. Они имеют название в соответствии с модулем или определенным предназначением. _const добавляется, если они содержат предопределенные числа или списки. _stocks добавляется, если они содержат "помогающие" или полезные "функции-обертки". Помните, что stocks компилируются только, если вы используете их, поэтому без опаски можно "включать" файлы, содержащие большое количество stocks.

Вы также можете посетить [http://amxmodx.ucoz.ru/forum/ Форум] и задать вопросы или найти больше информации.

Talk:Ru Button constants (AMX Mod X)

2007-01-22T18:19:22Z

CyberMind: Talk:Ru:Button constants (AMX Mod X) moved to Talk:Ru Button constants (AMX Mod X)

[[User:Slogic|Slogic]]: Теперь понятно, почему я +use не мог поймать =)

== reply ==

Сам момент исполнения +use с помощью описанного метода "поймать" можно, но нельзя "поймать" т.н. момент самого использования (pfnUse) --[[User:VEN|VEN]] 10:30, 12 December 2006 (CST)

Ru Button constants (AMX Mod X)

2007-01-22T18:19:21Z

CyberMind: Ru:Button constants (AMX Mod X) moved to Ru Button constants (AMX Mod X)

[[Category:Ru:Scripting (AMX Mod X)]]
=Кнопочные константы=

Просмотреть оригинал статьи (англ.): [[Button constants (AMX Mod X)]]

=Использование=

Кнопочные константы обычно используются для того, чтобы "поймать" момент, когда игрок пытается совершить какое-либо действие, нажимая на кнопки, "привязанные" к таким командам, как +attack, +use и так далее. Метод используется потому, что HL "движок" не может "поймать" +/-команды стандартным регистрированием, если их реализация выполнена в самом движке.

Например, это будет работать:<pawn>register_concmd("+explode","explode");</pawn>

А это - нет:<pawn>register_concmd("+attack","hook_attack");</pawn>

=Константы=

Полный список всех констант вы можете найти [http://amxmodx.org/funcwiki.php?go=module&id=3#const_buttons здесь].

=Реализация=

Вот, например, один из вариантов, как оперделить, нажимает ли игрок кнопку атаки или нет:<pawn>#include <amxmodx>
#include <engine>

public plugin_init()
{
register_plugin("Attack Test","1.0","Hawk552");
}

public client_PreThink(id)
{
if(entity_get_int(id, EV_INT_BUTTON) & IN_ATTACK)
{
// do something
}
}</pawn>

Обратите внимание, что используется битовый оператор &, в отличии от логического оператора &&. Оператор & проверяет, содержится ли бит после оператора в бите до него, т.е. в данном случае проверяется, есть ли среди нажатых кнопок игрока кнопка IN_ATTACK.

Чтобы заставить игрока эмулировать нажатие кнопки, можно поступить следующим образом:<pawn>#include <amxmodx>
#include <engine>

public plugin_init()
{
register_plugin("Attack Test","1.0","Hawk552");
}

public client_PreThink(id)
{
entity_set_int(id,EV_INT_button,entity_get_int(id,EV_INT_button) | IN_ATTACK);
}</pawn>

Этот пример будет выставлять флаг кнопки "атака" в положение "ВКЛ" каждый раз, когда рендерится entity игрока. Т.е. мы получаем все кнопки, нажатые в данный момент, и как бы прибавляем кнопку атаки.

Чтобы "поймать" кнопки игрока, а потом "вычесть" какую либо кнопку, можно использовать следующий метод:<pawn>#include <amxmodx>
#include <engine>

public plugin_init()
{
register_plugin("Attack Test","1.0","Hawk552");
}

public client_PreThink(id)
{
entity_set_int(id,EV_INT_button,entity_get_int(id,EV_INT_button) & ~IN_ATTACK);
}</pawn>

Например, клиент прыгает (IN_JUMP) и атакует (IN_ATTACK) одновременно, функция entity_get_int(id,EV_INT_button) будет возвращать бит сумму IN_ATTACK и IN_JUMP. Используя конструкцию & ~БИТ мы как бы удаляем конкретное значение бита, в данном случае IN_ATTACK. Таким образом, в итоге получим только IN_JUMP.

=Замечания=

Важно понимать, что нажатие какой-либо кнопки не всегда означает, что в это время происходит конкретное действие. Например, если выстрелить из пистолета и не отпускать кнопку атаки - пуля вылетит, атака закончится и не возобновится, т.к. пистолет не является автоматическим оружием, но, т.к. кнопка все еще будет нажата, то, используя вышеприведенный метод, мы получим активное состояние кнопки IN_ATTACK, хотя атаки как таковой в данный момент не осуществляется.

Более наглядный пример с прыжком. Представьте, что вы прыгнули и, не отпуская кнопки прыжка, опустились на землю. Второго прыжка не произойдет, т.к. для этого нужно отпустить кнопку и нажать ее снова. Таким образом, нажатая кнопка прыжка не говорит о том, что в данный момент вы находитесь в состоянии прыжка. Как уже было отмечено, это относится и к другим кнопкам. Поэтому, в подавляющем большинстве случаев вы не должны делать проверку на наличие нажатой кнопки, если хотите определить, совершает ли игрок соответствующее действие или нет, для этого существуют другие методы.

По большому счету метод, описанный в данной статье, может быть эффективен только для блокировки или эмуляции атаки, хотя для этого есть еще более эффективные методы. Описанный метод не может быть применим к блокировке подавляющего большинства кнопок: для этого существуют другие методы ''(TODO: указать здесь ссылку на эти методы)''.

Ru Using New Menu System

2007-01-22T18:19:02Z

CyberMind: Ru:Using New Menu System moved to Ru Using New Menu System

[[Category:Ru:Scripting (AMX Mod X)]]

= Введение =
Это статья поможет вам разобраться в новой системе меню.

== Урок по созданию меню ==
Давайте попробуем воспользоваться новой системмой меню. Мы пройдем через этоу простую инструкцию и создадим простое голосование смены карты.

=== Заголовочные файлы ===
Как обычно мы начинаем с добавления необходимых заголовочных файлов
<pawn>
#include <amxmodx>
</pawn>

=== Глобальные переменные ===
<pawn>
new g_Menu; // Переменная обработки главного меню
new g_Votes[3]; // Сохраняем голосования Да как 1, No как 2
</pawn>

Тут мы создали 2 глобальные переменные. Одна содержит указатель вашего меню, другая хранит резуьтаты голосования. Голоса 'Да' будут сохранены в g_Votes[1] ,а 'Нет' будет сохранена в g_Votes[2].

=== Регистрируем Плагин и Меню ===
<pawn>
public plugin_init()
{
// Регистрируем ваш плагин
register_plugin("Vote Menu","1.0","Freecode");

// Регистрируем меню смены карты
g_Menu = menu_create("Change Level?","menu_handle");

register_clcmd("amx_startvote","startvote",ADMIN_CFG,"Gaben");

// Теперь нам надо создать наше меню
build_menu();
}
</pawn>

Lets break this down.

*Регистрирует ваш плагин
<pawn>register_plugin("Vote Menu","1.0","Freecode");</pawn>

*g_Menu - Указатель на ваше меню. Это будет установлено после вызова menu_create.
<pawn>g_Menu = menu_create("Change Level?","menu_handle");

//menu_create ( title[], handler[], ml=0 )
//title[] - Заголовок меню
//handler[] - Эта функция будет вызвана когда будет нажата клавиша в вашем меню.
</pawn>

* Мы добавили эту команду. Она начинает ваше голосование.
<pawn>register_clcmd("amx_startvote","startvote",ADMIN_CFG,"Gaben");
</pawn>

* Это вызов функции. build_menu() функция создает ваше меню.
<pawn>build_menu();</pawn>

=== Создение меню ===
Конструирование заключается в добавлении пунктов в ваше меню. Прежде чем начали добавлять пункты, мы должны взглянуть на
menu_additem .
<pawn>menu_additem ( menu, const name[], const command[], paccess=0, callback=-1 )</pawn>
* menu - указатель на меню. Это указывает menu_additem меню к которому нужно добавить пункты.
* const name[] - имя пункта меню. Это то что будет показано в меню.
* const command[] - информация пункта меню.

Теперь давайте приступим к созданию нашего меню. Как уже говорилось, это простое голосование смены карты. Так что нам надо всего 2 пункта меню. А именно "Да" и "Нет".
<pawn>build_menu()
{
menu_additem(g_Menu, "Yes", "1");
menu_additem(g_Menu, "No", "2");

menu_setprop(g_Menu, MPROP_PERPAGE, 0);
}</pawn>
*<tt>Примечание</tt>
** Как вы можете видеть вместо command[] я указал числа. Это необходимо для более простой идентификации пунктов меню.
** Я так-же добавил menu_setprop. Это говорит нашему меню что оно не имеет страниц. Для дополнительной информации смотрите в amxconst.inc

=== Показывает меню голосования ===
Для того что-бы показать меню мы должны использовать menu_display.
<pawn>menu_display ( id, menu, page )</pawn>
* id - id пользователя которому надо показать это меню.
* menu - тут указываем хэндл меню которое показываем пользователю.
* page - какая страница (номер страницы меню) с которой начинаем. Страницы меню начинаются с 0.

Ok теперь посмотрим на наш код.
<pawn>public startvote(id)
{
for(new i = 0; i < 33; i++)
{
if( is_user_alive(i) )
{
menu_display(i, g_Menu, 0);
}
}

return PLUGIN_HANDLED;
}</pawn>
*<tt>Примечание:</tt>
** Используем цыкл для прохождения по всем игрокам и показываем меню тем кто живой.

=== Обработка выборов меню ===
Последний этап заключается в обработке выбора меню. Это делается через функцию обработки.
Она вызывается каждый раз когда пользователь сделал выбор.
Вот 3 переменные которые передаются в функцию.
* id - id пользователя
* menu - открытое меню у пользователя
* item - тут выбор пункта меню пользователем

Далее мы объявляем несколько специальных переменных таких как меню выхода.
<pawn>#define MENU_EXIT -3
#define MENU_BACK -2
#define MENU_MORE -1</pawn>

Теперь нам надо проверить если пункт меню выбран и он не является специальной переменной
<pawn>if( item < 0 ) return PLUGIN_CONTINUE;</pawn>

Следующим шагом мы получаем информацию о выбранном пункте меню. Все что мы ищем это номер пункта меню. (Да = 1, Нет = 2).
Для этого надо использовать menu_item_getinfo.
<pawn>menu_item_getinfo ( menu, item, &access, command[], cmdlen, name[]="", namelen=0, &callback )</pawn>
* menu - меню в котором находится пункт меню.
* item - the item itself
* &access - (edit)
* command[] - (edit)(это то где сохраняются идентификационные номера меню)
* cmdlen - размер command[]
* name[] - имя пункта меню
* namelen - размер name[]
* &callback - (edit)

После того как мы получили информацию о пуектах меню, надо взять из command[] номера выбранных меню(это должно быть 1 или 2).
Теперь надо добавить в g_Votes теми голосами что были сделаны.
Вот как завершонная функция должна выглядеть:
<pawn>public menu_handle(id, menu, item)
{
if( item < 0 ) return PLUGIN_CONTINUE;

// Get item info
new cmd[3];
new access, callback;

menu_item_getinfo(menu, item, access, cmd,2,_,_, callback);

new iChoice = str_to_num(cmd);

g_Votes[iChoice]++;

return PLUGIN_HANDLED;
}
</pawn>

=== Завершение ===
Это конец. Вы завершили Урок по созданию меню. Используя новую систему меню можно создать более удобное управление.
В следующем уроке вы увидите более сложную систему меню которая будет использовать callbacks, уничтожение меню и создание.
Вот код который должен получится посли всех действий.
<pawn>#include <amxmodx>

new g_Menu; // Переменная обработки главного меню
new g_Votes[3]; // Сохраняем голосования Да как 1, No как 2

public plugin_init()
{
// Регистрируем ваш плагин
register_plugin("Vote Menu","1.0","Freecode");

// Регистрируем меню смены карты
g_Menu = menu_create("Change Level?","menu_handle");

register_clcmd("amx_startvote","startvote",ADMIN_CFG,"Gaben");

// Теперь нам надо создать наше меню
build_menu();
}

build_menu()
{
menu_additem(g_Menu, "Yes", "1");
menu_additem(g_Menu, "No", "2");

menu_setprop(g_Menu, MPROP_PERPAGE, 0);
}

public startvote(id)
{
for(new i = 0; i < 33; i++)
{
if( is_user_alive(i) )
{
menu_display(i, g_Menu, 0);
}
}

return PLUGIN_HANDLED;
}

public menu_handle(id, menu, item)
{
if( item < 0 ) return PLUGIN_CONTINUE;

// Получаем информацию о пункте
new cmd[3];
new access, callback;

menu_item_getinfo(menu, item, access, cmd,2,_,_, callback);

new iChoice = str_to_num(cmd);

g_Votes[iChoice]++;

return PLUGIN_HANDLED;
}</pawn>

Ru Main Page

2007-01-22T18:18:03Z

CyberMind: Ru:Main Page moved to Ru Main Page

[[Category:Russian]]

__NOTOC__
Добро пожаловать в AMWiki, объединенный и совместный проект документации проектов [[AMX Mod X]], [[Metamod:Source]], и [[SourceMod]].

С чего вам начать? Проверьте [[AMWiki:Community Portal|Страницу проекта]], чтобы увидеть краткий обзор. Прочитайте [[Help:Contents|Помощь]] для понимания основных принципов и правил wiki. Или если вы что-то ищите, можете воспользоваться поиском с левой стороны!

=Основные статьи=

==Оптимизация Плагинов==
[[Optimizing Plugins|Данная статья]] описывает много важных моментов, трюков и советов, а также рассказывает о том, как сделать ваши плагины более быстрыми. Пользователи, следующие этим инструкциям, получат существенный прирост производительности в своих плагинах. Для продолжения чтения статьи нажмите [[Optimizing Plugins|здесь]].

==Изменения в скриптах AMX Mod X 1.70==
В [[AMX Mod X]] 1.70 были сделаны важные изменения. Авторам серьезных плагинов рекомендуется как можно быстрее ознакомиться с изменениями и новыми возможностями: [[AMX Mod X 1.70 Scripting Changes]].

{| cellspacing="0" style="border:0px; margin-right:10%;"
|- valign="top"
|
{| width="100%"
|-
|

=Проекты=
{| width="100%" cellpadding="5"
|- class="t2th"
| '''AMX Mod X'''
|- class="t2td"
|[[Image:Amxxsmall.gif|left]] [[AMX Mod X]] - мощная, расширяемая скриптами среда для [[Half-Life 1]].
* [[:Category:Ru:Documentation (AMX Mod X)|Документация]]
* [[:Category:Ru:Scripting (AMX Mod X)|Скриптинг]]
* [http://amxmodx.ucoz.ru Русский сайт AMX Mod X]
|}

{| width="100%" cellpadding="5"
|- class="t2th"
| '''Metamod:Source'''
|- class="t2td"
|[[Image:Mms.jpg|left]][[Metamod:Source]], мощный plugin API для [[Half-Life 2]], функции перехвата интерфейсов и универсальный plugin API.
* [[:Category:Documentation (SourceMM)|Документация]]
* [[Introduction_to_SourceMM_Coding|Разработка]]
|}
|}
|
{| width="100%"
|-
|

=Новости=
{| cellpadding="6"
|- class="t2th"
| AMX Mod X 1.70
|- class="t2td"
| ''2006-03-04'': Новая версия [[AMX Mod X]] выпущена в свет. Список изменений смотрите на [http://www.amxmodx.org/ домашней странице]. Разработчикам стоит взглянуть на новые темы, [[Optimizing Plugins|статью]] по оптимизации плагинов и [[AMX Mod X 1.70 Scripting Changes|изменения]] в AMX Mod X 1.70.
|}

{| cellpadding="6"
|- class="t2th"
| Metamod:Source 1.2.1
|- class="t2td"
| ''2006-02-15'': Выпущена новая версия [[Metamod:Source|SourceMM]]. Список изменений смотрите на [http://www.sourcemm.net/ домашней странице].
|}

{| cellpadding="6"
|- class="t2th"
| Wiki Запущен!
|- class="t2td"
| ''2006-01-17'': Запущен AMWiki проект! Пожалуйста, пишите любые предложения в разделе обсуждений [[Talk:Main_Page|Main Page]].
|}

|}

Ru:Fundamental Basics of AMX Mod X Scripting

2007-01-22T18:17:55Z

CyberMind: Ru:Fundamental Basics of AMX Mod X Scripting moved to Ru Fundamental Basics of AMX Mod X Scripting

[[Category:Ru:Scripting (AMX Mod X)]]
=Фундаментальные основы AMX Mod X скриптинга=

Данная статья не дает готовых "рецептов" по [[AMX Mod X]] скриптингу, но раскрывает его фундаментальные основы. Это и типы данных, и прототипы функций и многое другое, без знания чего невозможно писать AMX Mod X плагины.

=Введение=

Прежде чем начинать писать AMX Mod X плагины, в первую очередь необходимо разобраться в основах [[Pawn]].
 Pawn – это скриптовый язык, созданный компанией ITB CompuPhase. Ранее Pawn назывался Small, но с версии 3.0 языку было решено дать более характерное название. Т.к. "pawn" в переводе с английского языка означает "пешка", можно догадаться, что основной характерной чертой данного языка является простота.
 Если вы владеете английским языком, рекомендуется ознакомиться с полным руководством по Pawn - [http://www.compuphase.com/pawn/pawn-lang.pdf Pawn The Language].
 Код плагина представляет собой текст (как правило, заключенный в файл типа *.sma), включающий множество элементов языка: комментарии, переменные, функции и др. Поэтому для оформления кода потребуется текстовый редактор. Из простейших можно выделить, например, Microsoft Notepad. Также существует AMXX-Studio – специализированый редактор для AMX Mod X плагинов, позволяющий максимально эффективно работать в соответствующей среде. Последняя версия данного редактора может быть найдена в секции [http://www.amxmodx.org/downloads.php downloads] официального сайта AMX Mod X.
 Чтобы позволить AMX Mod X выполнять код, файл с кодом необходимо откомпилировать с помощью компилятора AMXXPC (AMX Mod X Pawn Compiler). Операция компилирования преобразовывает набор текстовых инструкций в последовательность инструкций абстрактной машины (от англ. abstract machine), она же AMX, а также интерпретатор (от англ. interpreter).
 Откомпилированый код обычно помещается в файл типа *.amxx, имеющий двоичный формат. Такой файл называют AMX Mod X плагином (от англ. plugin).
 Для ознакомления с инструкциями по компилированию и установке плагинов смотрите [[Ru:Compiling Plugins (AMX Mod X)]] и [[Ru:Configuring AMX Mod X]].

=Pawn=

==Уровни кода==

В основе любого кода лежит уровневая структура. Причиной этому является нелинейность инструкций.
 Т.н. "нулевой уровень" или "глобальное пространство" является неотъемлемой частью любого кода. Как только вы приступаете к написанию нового кода, вы оказываетесь в его глобальном пространстве. Оно же в свою очередь будет включать в себя пространства с более низкими уровнями.
 Обычно глобальное пространство содержит всю общую информацию, которая может потребоваться в ходе выполнения кода пространствам более низкого уровня. Примером такой информации могут служить общие константы, переменные, списки, макросы.

==Комментарии==

Комментарий – это, как правило, текст информативного характера. Например, чтобы дать описание плагину можно использовать многострочный комментарий:<pawn>/* здесь вы помещаете
необходимую информацию */</pawn>Как видно из примера, многострочный комментарий ограничивается символами /* и */, отмечающими начало и конец комментария соответственно. Недопустимо открывать последующий комментарий, не закрыв при этом предыдущий.
 Примером однострочного комментария может быть:<pawn>/* ваш комментарий */</pawn>Хотя, можно упростить конструкцию:<pawn>// ваш комментарий</pawn>
 Как видно из последнего примера, комментарий начинается с двойного симовола обратного слеша //. Заканчивается такой комментарий вместе с концом текущей строки, поэтому не требует закрывающих символов. Такие комментарии могут быть только однострочными. Не обязательно комментарий должен начинаться с новой строки. Например, /* ... */ комментарий может быть расположен непосредственно в самом коде.
 Т.к. комментарии не считаются кодом, они исключаются из обработки. Данная особенность позволяет при необходимости исключать части кода путем комментирования, что может быть использовано, например, при отладке кода.

==Типы данных==

Технически основой всех типов данных в Pawn является т.н. "cell" – ячейка памяти, состоящая из последовательности определенного количества бит. Количество бит в такой ячейке постоянно для определенной платформы. Так для 32х битной платформы оно будет составлять 32, а для 64х битной – 64.
 Т.к. технически все данные не имеют отличия, для обозначения их типа применяются т.н. "тэги". Если при создании переменной тэг не указан, то переменная является целым числом:<pawn>new ivar // создана целочисленная переменная с именем "ivar"</pawn>
 Если при создании переменной ей не присваивается какое-либо конкретное значение, то переменная будет равна нулю. Таким образом, вышеприведенный пример технически соответствует:<pawn>new ivar = 0</pawn>
 Чтобы создать дробную переменную, необходимо использовать тэг "Float":<pawn>new Float:fvar</pawn>Переменная fvar также будет равна нулю, но ввиду соответствия типу данных это будет 0.0, т.е. технический аналог примера будет:<pawn>new Float:fvar = 0.0</pawn>Таким образом, мы обеспечиваем типовое соответствие "левой" и "правой" части.
 Одним из особых типов данных является т.н. "булевые" переменные, которые технически могут иметь только два значение, логически интерпретируемые как "истина" и "ложь" (true и false). Чтобы создать булевую переменную, необходимо использовать тэг "bool":<pawn>new bool:bvar</pawn>Т.к. численно false является нулем, то технический аналог примера будет выглядеть как:<pawn>new bool:bvar = false</pawn>
 Примечание: чтобы запретить изменение значения переменной, необходимо использовать атрибут const, например:<pawn>new const var = 1</pawn>
 Pawn также позволяет создавать массивы данных, представляющие собой набор значений определенного типа. Так примером простого массива, содержащего два целочисленных значения будет:<pawn>new array[2]</pawn>Технически данный пример выглядит следующим образом:<pawn>new array[2] = {0, 0}</pawn>Технические аналоги для Float и bool массивов выглядят как:<pawn>new Float:farray[2] = {0.0, 0.0}
new bool:barray[2] = {false, false}</pawn>
 Также существует особый тип данных, называемый "строка", технически являющийся массивом целых чисел. Каждое целое число в строковом массиве соответствует числовому ASCII коду символа. Например, код 32 соответствует пробелу. Таким образом,<pawn>new string[3] = {'h', 'i', '^0'}</pawn>является символьным представлением строкового массива<pawn>new string[3] = "hi"</pawn>Обратите внимание на наличие специального символа '^0'. Это обязательный элемент строки, указывающий на ее окончание (численно равен нулю).
 Также Pawn поддерживает многоуровневые массивы, например:<pawn>new multiarray[2][2]</pawn>Технически такой массив равен:<pawn>new multiarray[2][2] = {{0, 0}, {0, 0}}</pawn>Максимальное количество уровней массива равно 3.
 Для любого явно заданного массива его размер может не указываться, например:<pawn>new array[] = {1, 2, 3} // размер массива равен 3
new string[] = "hello" // размер массива равен 6, т.к. помимо 5 символов также включает в себя символ окончания строки '^0'</pawn>
 Чтобы инициализировать все элементы массива каким-либо конкретным значением, можно использовать символ троеточия ..., например:<pawn>new bool:is_active[16] = {true, ...}</pawn>

==Прекомпиляция==

На начальной стадии компилирования Pawn компилятор обрабатывает т.н. "статическую" часть кода. К ней можно отнести директивы, глобальные константы, списки и др.
 Директивы являются специальными инструкциями компилятора. Одна из самых широко используемых директив – это "include". Пример ее использования может быть следующим:<pawn>#include <amxmodx></pawn>Директива как бы "влаживает" содержимое указанного файла в текущую позицию. В данном случае указывается файл amxmodx.inc, который обычно расположен в amxmodx\scripting\include директории, и декларирует основные AMX Mod X функции.
 Другая директива, позволяющая конструировать т.н. "макросы", имеет название "define". Макрос удобен тем, что способен заменять простые блоки кода. Один из простейших макросов – это т.н. "макроконстанта", например:<pawn>#define VALUE 1</pawn>В названиях макросов принято использовать буквы только верхнего регистра.
 Нетехническим аналогом вышеприведенной макроконстанты является т.н. "глобальная константа":<pawn>stock const value = 1</pawn>stock атрибут позволяет не включать константу в плагин, если она не используется в коде.
 Т.н. "список" – это набор нумерованных элементов определенного типа. Например:<pawn>enum {zero, one, two} // соответствует 0, 1, 2
enum {elem1 = 1, elem2, elem3} // соответствует 1, 2, 3
enum steeps {steep1 = 10, steep2 = 20} // соответствует 10, 20</pawn>Тип списка (в вышеприведенном примере типом списка является steeps) – необязательный атрибут, по сути является тэгом, указывающим тип элементов, поэтому следующий пример является верным:<pawn>new steeps:steep = steep2</pawn>

==Функции==

Существует несколько типов функций.
 Т.н. "обычная" – обычно т.н. "вспомогательная" функция; может быть вызвана непосредственно только другими функциями данного плагина; не может быть вызвана непосредственно AMX Mod X либо его модулями.
 public – обычно функция, вызываемая непосредственно AMX Mod X либо его модулями; может быть также вызвана непосредственно другими функциями данного плагина.
 native – функция, имеющая т.н. "глобальный" характер; может быть вызвана AMX Mod X плагинами.
 forward - функция, имеющая т.н. "глобальный" характер; при наличии в плагине public функции с соответствующим именем функция будет вызываться AMX Mod X или его модулями.
 stock – обычно функция, состоящая в т.н. "библиотеке" функций; не включается в плагин, если не используется в коде.
 В общем виде заголовок, а также прототип любой функции условно выглядит следующим образом (символами треуголных скобок <> ограничены обязательные элементы, символами квадратных скобок [] ограничены необязательные элементы, которые могут быть опущены в определенных случаях):<pawn>[type] [tag]:<name>([[param1], [param2], ..., [paramN]])</pawn>, где
[type] – соответствует типу функции (для обычной функции тип не указывается).
 [tag] – соответствует типу данных возвращаемого результата функции.
 <name> - соответствует имени функции
 ([...]) – соответствует набору параметров функции; количество параметров может быть от нуля (параметры отсутствуют) до N, где N – целое положительное число.
 За заголовком функции следует т.н. "тело" функции, ограниченное символами фигурных скобок {}. Таким образом, примером простейшей функции является:<pawn>function()
{
// это пустое тело функции, имеющей имя "function"
}</pawn>Технически данная функция не выполняет никаких действий, т.к. в своем теле содержит только комментарий. Обратите внимание, что комментарий как бы сдвинут вправо относительно заголовка функции. В данном случае функция инициализирует новый уровень кода. Каждый уровень кода в целях удобочитаемости принято оформлять с соответствующим отступом. Чем более низкий уровень кода, тем больший отступ он будет иметь. Обычно в качестве отступа принято использовать символ табуляции, т.к. многие редакторы позволяют задавать видимую ширину табулированого отступа.
 Существует два способа передачи параметров функции. Т.н. "основной" способ заключается в том, что при передаче данные дублируются путем создания соответствующих копий в памяти. Т.н. способ передачи параметров "по ссылке" (от англ. by reference) состоит в том, что данные передаются "как есть", т.е. их дублирования не осуществляется, что позволяет функции изменять оригинальные данные непосредственно.
 Для параметров функции все типы массивов, в том числе и строковые, могут передаваться исключительно по ссылке. Передача остальных данных по умолчанию осуществляется основным способом. Чтобы произвести передачу параметра функции по ссылке, в заголовке функции перед параметром необходимо добавлять символ амперсанда &, например:<pawn>function(&Float:fparam)</pawn>
 Параметры функции могут иметь значения по умолчанию, например:<pawn>function(param = 1)</pawn>Таким образом, чтобы вызвать данную функцию с параметром по умолчанию, параметр можно не указывать:<pawn>function()</pawn>Также в таких случаях можно использовать символ подчеркивания _:<pawn>function(_)</pawn>
 Чтобы запретить функции изменение передаваемых данных, необходимо использовать атрибут const, например:<pawn>function(const array[])</pawn>Таким образом, можно утверждать, что в данном случае целью функции не является изменение данных массива, чего нельзя утверждать о следующей функции:<pawn>swaparray(array[2])</pawn>Исходя из названия функции, типа параметра, его размера и отсутствия запрета на изменение, можно сделать предположение о том, что данная функция меняет элементы массива местами.
 Важным свойством функции является способность возвращать результат, значение которого имеет определенный тип, например:<pawn>bool:is_true()
{
return true
}</pawn>
 Чтобы указать допустимые типы параметра функции, в заголовке функции перед параметром необходимо добавлять конструкцию, которая условно выглядит как {tag1, tag2, ..., tagN}:, т.е. представляет собой набор тэгов, количество которых может быть от одного до N, где N – целое положительное число, например:<pawn>get_integer({bool, _}:value)
{
return _:value // возвращается значение типа "целое число"
}</pawn>Смысл вышеприведенной функции заключается в том, что она принимает параметр как типа "целое число", так и булевого типа, в результате возвращая значение параметра в числовой форме.

=AMX Mod X=

==Функции==

При написании AMX Mod X плагинов важно уметь понимать назначение и принцип действия AMX Mod X функций.
 Прототипы функций, а также используемые ими константы и списки заключены в файлы типа *.inc, т.н. "инклуды" (от англ. include), которые обычно расположены в amxmodx\scripting\include директории.
 Иногда одни инклуды включают в себя другие. Так основные AMX Mod X функции (т.н. функции AMX Mod X "ядра") продекларированы в файле amxmodx.inc, который также включает векторные и другие инклуды, декларирующие функции, константы и списки, также имеющие непосредственное отношение к AMX Mod X ядру.
 Одной из основных функций AMX Mod X является forward функция plugin_init. Если в коде плагина имеется public функция plugin_init, она будет вызвана AMX Mod X после загрузки карты на сервере. Обычно в plugin_init регистрируют сам плагин, его команды, переменные и т.п.
 Плагин регистрируют с помощью native функции register_plugin. Т.к. прототип register_plugin соответствует:<pawn>native register_plugin(const plugin_name[], const version[], const author[])</pawn>, можно понять, что в качестве параметров функция принимает три строковых массива, соответствующих названию плагина, номеру его версии и автору плагина.
 Итак, примером простого AMX Mod X плагина является:<pawn>#include <amxmodx>
public plugin_init()
{
register_plugin("Test", "0.1", "VEN")
}</pawn>По сути данный плагин не выполняет каких-либо действий, но регистрирует себя в AMX Mod X с указанными данными.

==Системы функционирования==

AMX Mod X предоставляет большое количество определенных систем функционирования. Так одна из основных систем – это система контроля уровней доступа. Здесь имеют место соответствующие функции, например get_user_flags, а также константы стандартных уровней доступа типа ADMIN_*.
 Система регистрирования и контроля консольных команд также "пересекается" с системой контроля уровней доступа и использует такие функции, как например register_concmd и cmd_access.
 Также существует множество других систем, среди которых имеется система регистрирования и контроля серверных консольных переменных (англ.: Server CVars), клиентских меню и др.
 Как правило, системы регистрирования используют т.н. "handle" (или "hook") функции, которые вызываются системой в необходимый момент.
 Так после регистрирования консольной команды "action":<pawn>register_concmd("action", "action_handler")</pawn>при исполнении данной команды из консоли сервера или клиента система попытается найти и выполнить public функцию action_handler.

==Система строкового форматирования==

Многие AMX Mod X функции используют систему строкового форматирования. Например, это все *_print функции.
 Такие функции принимают практически неограниченное количество параметров, которые используются при форматировании соответствующей строковой конструкции. Для наглядности рассмотрим пример:<pawn>server_print("Formatted string: %d %f %s %c", 1, 1.234567, "hello", '!')</pawn>Функция server_print отформатирует строковую конструкцию "Formatted string: %d %f %s %c", используя переданные параметры, и выведет в серверной консоли строку:<pawn>Formatted string: 1 1.234567 hello !</pawn>Таким образом, %d, %f, %s, %c – специальные элементы, используемые для форматирования целого числа, дробного числа, строки и символа соответственно.
 Опасно при использовании функций, поддерживающих форматирование, передавать строковую переменную непосредственно в параметр строковой конструкции, например:<pawn>server_print(string)</pawn>Безопасный вариант выглядит, следующим образом:<pawn>server_print("%s", string)</pawn>
 Т.к. символ процента % является, т.н. "специальным символом", для его форматирования в строковой конструкции необходимо использовать двойной символ процента %%, например:<pawn> server_print("This is a single symbol of percent: %%")</pawn>выведет в серверной консоли:<pawn> This is a single symbol of percent: %</pawn>
 Также существует т.н. "контрольный символ" (от англ. control character), позволяющий использовать т.н. "специальные символы форматирования". Контрольным символом по умолчанию является символ ^, который может быть изменен директивой pragma ctrlchar, например:<pawn>#pragma ctrlchar '\'</pawn>изменит контрольный символ на \.
 Примеры некоторых специальных символов форматирования приведены ниже:
 ^t – табуляция
 ^n – новая строка
 ^xHH – символ, представленный в шестнадцатиричном формате, где HH – двойное число, представленное в шестнадцатиричном формате

Ru Compiling Plugins (AMX Mod X)

2007-01-22T18:17:37Z

CyberMind: Ru:Compiling Plugins (AMX Mod X) moved to Ru Compiling Plugins (AMX Mod X)

[[Category:Ru:Scripting (AMX Mod X)]]
Просмотреть оригинал статьи (англ.): [[Compiling Plugins (AMX Mod X)]]

=Компилирование плагинов=

Эта статья описывает, как компилировать [[AMX Mod X]] плагины из [[Ru:source code|исходного кода]] (.sma).

Для всех случаев вы должны поместить .sma файл в директорию addons/amxmodx/scripting.

=Windows=

==Метод перетаскивания==
#Перетащите .sma файл на "compile.exe".
#Откомпилированный .amxx файл будет находиться в директории compiled.

==Компилирование всех плагинов==
#Дважды щелкните на compile.exe, чтобы откомпилировать все плагины и поместить их в директорию compiled.
==Командная строка==
#Зайдите в "Пуск", "Выполнить", введите "cmd", нажмите Ok.
#Используйте cd, чтобы сменить директорию, например: <pre>cd c:\hlserver\cstrike\addons\amxmodx\scripting</pre>
#Используйте amxxpc, чтобы откомпилировать плагин: <pre>amxxpc.exe myplugin.sma</pre>
#Откомпилированный плагин будет в этой же директории.

=Linux=

Сперва перейдите в scripting директорию в вашей оболочке следующим образом: <pre>cd addons/amxmodx/scripting</pre>

==Компилирование всех плагинов==
#Запустите скрипт compile.sh одним из способов: <pre>sh compile.sh</pre> or <pre>chmod +x compile.sh
./compile.sh</pre>

==Компилирование одиночного плагина==
#Запустите amxxpc, например: <pre>./amxxpc myplugin.sma</pre>
#Откомпилированный плагин будет в этой же директории.

Ru Alternative Language

2007-01-22T18:17:14Z

CyberMind: Ru:Alternative Language moved to Ru Alternative Language

[[Category:Russian]]

Если вы желаете составить документацию на языке отличном от английского, пожалуйста, начните отсюда. Приветствуется содержимое на любом языке.

Другие языки не обязательно должны быть "зеркалом" английской документации.
Приветствуется не только перевод документации с английского языка, но и дополнения к ней.

= Выбор языка =

Переключение осуществляется подстановкой префикс-кода языка.

* [[Alternative_Language|English]]
* [[ru:Alternative_Language|Russian]]

Быстрый и эффективный способ добавления переключателя нового языка - это использование шаблона
<nowiki>{{LanguageSwitch}}</nowiki>
где-либо в статье (рекомендуется добавлять вверху, либо в самом низу). Данный код добавит маленькое меню, которое выглядит следующим образом:
{{LanguageSwitch}}

После того, как новый язык добавлен в wiki, данный темплейт будет изменен автоматически. Таким образом, все страницы, которые его используют, будут также автоматически обновлены.

= Как перевести страницу =

1) Перейдите на страницу, которую вы желаете перевести.

2) Вверху страницы выберите "edit"(править), затем сверху добавьте переключатель языка, если такового не существует.

3) Скопируйте весь текст темплейта страницы.

4) Сохраните (чтобы сохранился переключатель языка).

5) Теперь вверху страницы должен появиться переключатель языка, как на этой странице.

6) Выберите нажатием язык, на который вы желаете осуществить перевод.

7) Вставьте текст, который вы скопировали, в текстовую область.

8) Осуществите перевод, после чего сохраните его.

Вышеприведенные инструкции позволят создать версию текущего документа на вашем языке. Существует возможность перевода любых страниц.

'''Ресурсы:'''

* Список 2х-буквенных кодов языков можно найти тут: http://www.w3.org/WAI/ER/IG/ert/iso639.htm

Talk:Ru Alternative Language

2007-01-22T18:17:14Z

CyberMind: Talk:Ru:Alternative Language moved to Talk:Ru Alternative Language

[[User:Slogic|Slogic]]: Если вставить шаблон на русской странце, то шаблон не понимает, что мы создали его на русской странице и не правильно создает ссылки: должен на английскую версию, а создает опять на русскую.
:Да, замечал, есть такая вещь. Выход: помещать ссылку на оригинал, не используя шаблон, например:
:* [[Something|Просмотреть оригинал]]
:--[[User:VEN|VEN]] 05:52, 19 January 2007 (CST)

Talk:Alternative Language

2007-01-22T18:15:41Z

CyberMind:

Talk:Alternative Language

2007-01-22T18:13:37Z

CyberMind:

Talk:Alternative Language

2007-01-22T18:10:09Z

CyberMind:

Writing Extensions

2007-01-19T21:07:20Z

CyberMind: /* Visual Studio Users */

SourceMod's Extension System is a powerful way to greatly enhance the flexibility of your SourceMod plugins. You can take full advantage of SourceMod's Core, using the interfaces it provides, to create C++ plugins, plugin events, plugin native functions, and shared interfaces. Extensions can also hook into Metamod:Source.

This article goes into the details of creating a SourceMod Extension. Knowledge of C++ is required.

=SDK Structure=
First, download the [[SourceMod SDK]] from the [[SourceMod]] website. The directory structure looks like this:
*<tt>extensions</tt>
**<tt>geoip/</tt> - Source code to the GeoIP extension
**<tt>mysql/</tt> - Source code to the MySQL extension
**<tt>threader/</tt> - Source code to the Threader extension
*<tt>plugins/</tt> - Source code to all of SourceMod's plugins
**<tt>include/</tt> - The include files which document plugin API
*<tt>public/</tt> - Interface files for SourceMod's Core Interfaces
**<tt>extensions/</tt> - Interfaces that are provided by extensions
**<tt>sample_ext/</tt> - The Sample Extension SDK
**<tt>sourcepawn</tt> - The include/interface files for SourcePawn
*<tt>sourcepawn/</tt>
**<tt>compiler/</tt> - The SourcePawn Compiler

=Starting an Extension=
For simplicity, this article will assume you are using the SDK base files. These are:
*<tt>smsdk_config.h</tt> - Configuration settings (we will be editing this)
*<tt>smsdk_ext.h</tt> - Header for SDK wrappers (usually never needs to be edited)
**''Note: Sometimes, this may be updated by the SourceMod Dev Team. Using a newest version is recommended.'
*<tt>smsdk_ext.cpp</tt> - Source for SDK wrappers (usually never needs to be edited)
**''Note: Sometimes, this may be updated by the SourceMod Dev Team. Using a newest version is recommended.'
*<tt>extension.h</tt> - User file for main extension header
*<tt>extension.cpp</tt> - User file for main extension code

''The <tt>extension.*</tt> files are not technically part of the SDK. However, they are provided to give users a starting point and some documentation.''

'''Note:''' For help setting up Visual Studio, please see [[#Setting up Visual Studio|Setting up Visual Studio]].

The first step of creating your extension is to configure it. Open the <tt>smsdk_config.h</tt> file and edit each of the following defines. Use the information below to guide you.
*<tt>SMEXT_CONF_NAME</tt> - The general name for your Extension (should be short).
*<tt>SMEXT_CONF_DESCRIPTION</tt> - A short description of what your extension does.
*<tt>SMEXT_CONF_VERSION</tt> - A version number string. By convention, SourceMod uses the four set build number notation. I.e. for 1.2.3.4:
**<tt>1</tt> is the "Major" release version.
**<tt>2</tt> is the "Minor" release version.
**<tt>3</tt> is the "Maintenance" or "Revision" version.
**<tt>4</tt> is the "Build," usually an internal source control number.
*<tt>SMEXT_CONF_AUTHOR</tt> - Your name (or whoever/whatever authored the plugin).
*<tt>SMEXT_CONF_URL</tt> - The URL/homepage of this extension.
*<tt>SMEXT_CONF_LOGTAG</tt> - The logtag your extension will use for SourceMod logging. By convention, try to keep this under ten characters or so, and to make it all caps.
*<tt>SMEXT_CONF_LICENSE</tt> - Right now, the SourceMod Dev Team mandates that 3rd party extensions must be under an Open Source license. Putting a license abbreviation or very short message here is appropriate. For more information, see [[SourceMod License]].
*<tt>SMEXT_CONF_DATESTRING</tt> - You do not need to modify this.
*<tt>SMEXT_CONF_METAMOD</tt> - If your plugin requires using SourceHook or Metamod:Source, uncomment this line.

Next, you may want to change the name of the default class that <tt>extension.h</tt> declares. To do this...
<ul><li>Open <tt>extension.h</tt> and change "Sample" in this line:
<cpp>class Sample : public SDKExtension</cpp></li>
<li>Open <tt>extension.cpp</tt> and change the two lines to correspond to your new class name. You can also change the global singleton that's declared, although you cannot remove the <tt>SMEXT_LINK</tt> line (this lets SourceMod load your extension).</li>
</ul>

==Visual Studio Users==
Make sure you change the name of your <tt>.dll</tt> file. The naming convention for SourceMod extensions is <tt>name.ext.dll</tt>, where <tt>name</tt> is a short name for your extension. You are free to change this, but it is highly recommended that you keep the <tt>.ext.dll</tt> intact.

You can do this by going to <tt>Project</tt> -> <tt>Properties</tt> -> <tt>Configuration Properties</tt> -> <tt>Linker</tt> -> <tt>General</tt>. Set the <tt>Output File</tt> option appropriately.

==Linux Users==
Simply edit the <tt>Makefile</tt> and change the <tt>BINARY</tt> line near the top. Make sure you do not add any trailing spaces at the end of the name, or the build won't come out right.

You should now be able to compile a blank extension!

=Creating Native Functions=
Most of the time, an extension exists to add "native functions" to the plugin system. Native functions are simply the functions that plugins can use in SourceMod. They are coded in C++ and have a short prototype declaration in an include file.

==Prototyping==
The first step to creating a native is to <tt>spec it</tt>, or <tt>prototype</tt> it. This is a simple but often time consuming process, but if you get in the habit of it, your documentation will be much better. Let's first create a very simply native. Here is a prototype for it, which we will place in <tt>sample.inc</tt>:
<pawn>/**
* Returns the square of a number.
*
* @param num Number to square.
* @return The square of num.
*/
native SquareNumber(num);</pawn>

The <tt>native</tt> keyword tells the compiler that this function exists in an outside source. The comment style is similar to [http://www.stack.nl/~dimitri/doxygen/ doxygen] or [http://java.sun.com/j2se/javadoc/ Javadoc], and is preferred by the SourceMod Development Team.

==Implementing==
Now that our function is documented, it's time to create it! Each native function is bound to a C++ function. The prototype for this function looks lile:
<cpp>cell_t Function(IPluginContext *pContext, const cell_t *params);</cpp>

A quick explanation of these types:
*<tt>cell_t</tt> - This is a 32bit signed integer, the generic data type for Pawn.
*<tt>IPluginContext</tt> - This interface provides Virtual Machine functions for retrieving or modifying memory in the plugin.
*<tt>params</tt> - This is the "stack" of parameters that the plugin passed. It is an array from [0..N] where 0 contains N.
**For example, if one parameter was passed, and the parameter is 25:
***<tt>params[0]</tt> == 1
***<tt>params[1]</tt> == 25
**Even though it tells you how many parameters are passed, you do not need to verify this number. The compiler will always pass the correct number of parameters in. The only time you need to verify it is for backwards compatibility or variable parameter lists, which will be discussed later.

Now, let's write our native function:
<cpp>cell_t SquareNumber(IPluginContext *pContext, const cell_t *params)
{
cell_t number = params[1];
return number * number;
}</cpp>

==Binding==
Now, the final step is to bind our native. Natives are bound in ''native lists''. Each list must be terminated by a <tt>NULL</tt> bind. Example:
<cpp>const sp_nativeinfo_t MyNatives[] =
{
{"SquareNumber", SquareNumber},
{NULL, NULL},
};</cpp>

The first column/member is a string containing the name you've assigned to the native. The second column/member is the C++ function you're binding to. Here, both contain the same name, but it is certainly possible to bind a function to any valid Pawn function name, and likewise, you can bind one function to more than one name.

Lastly, you must tell Core about your native list. There are two places that are good to do this. Whichever you choose, you must uncomment the function in <tt>extension.h</tt> and implement it in <tt>extension.cpp</tt>.
*<tt>SDK_OnLoad</tt> - This is called when your extension is first loaded. If you do not require any outside interfaces, it is safe to add natives here.
*<tt>SDK_OnAllLoaded</tt> - This is called when all extensions have been loaded. This is generally a better place to add natives.

Let's say we choose <tt>SDK_OnAllLoaded</tt>, we'd then have code like this:
<cpp>void Sample::SDK_OnAllLoaded()
{
g_pShareSys->AddNatives(myself, MyNatives);
}</cpp>
''Note: <tt>myself</tt> is a global variable declared in the SDK. It is a pointer that identifies your extension.''

For more information on writing natives, see [[Natives (SourceMod Development)]].

=Creating Events/Forwards=
Events are an integral part to SourceMod. An Event is formally called a ''Forward''. Forwards are functions inside a plugin which are not called by the plugin itself, but are triggered from an external source. For example, <tt>OnClientConnect</tt> is a forward which is triggered when a player connects to a server.

There are two major types of forwards:
*'''Managed''': This forward is global and has a name. To use this forward, the function must be declared as <tt>public</tt> inside the user's script. Any plugin having this public function will receive the event.
*'''Unmanaged''': This forward is private in nature. For example, the <tt>HookUserMessage</tt> native lets users specify a function to be called when a specific user message is sent. This is done with an unmanaged forward, and adding functions to this forward is not automatic. In general, function calls for unmanaged forwards are not public, although they can be.

==Managed Forwards==
Let's say we want to create a forward that will be called when a player uses say chat. For simplicity, let's assume you already have a function that tells you when a player says say chat. We will just be creating the forward for it.

As we did before, first let's prototype our global forward. In our include file, we add this:
<pawn>/**
* @brief Called whenever a client says somethign in chat.
*
* @param client Index of the client.
* @param text String containing the say text.
* @return Pl_Handled to block text from printing, Pl_Continue otherwise.
*/
forward ResultType:OnPlayerSayChat(client, const String:text[]);</pawn>

The <tt>forward</tt> keyword tells the compiler that any function having this name must be declared exactly the same. In a plugin, this would

The next step is to declare your forward somewhere at the top of your <tt>extension.cpp</tt> file. This will look like:
<cpp>IForward *g_pSayChat = NULL</cpp>

Next, re-using our code from above, let's create this forward in <tt>SDK_OnAllLoaded</tt>:
<cpp>void Sample::SDK_OnAllLoaded()
{
g_pShareSys->AddNatives(myself, MyNatives);
g_pSayChat = g_pForwards->CreateForward(ET_Event, 2, NULL, Param_Cell, Param_String);
}</cpp>

Explanation of parameters:
*<tt>ET_Event</tt> - Since forwards can execute multiple functions in multiple scripts, this is one of the ways of specifying what to do with the return value of each function. <tt>ET_Event</tt> means "return the highest value, do not allow stops." A stop refers to <tt>Pl_Stop</tt>, which lets a plugin block the rest of the event chain.
*<tt>2</tt> - This is the number of parameters our forward will have.
*<tt>NULL</tt> - Not used in our example. This lets you pass parameters by array rather than variable arguments.
*<tt>Param_Cell</tt> - The first parameter is a cell (integer).
*<tt>Param_String</tt> - The second parameter is a string.

Now, we write a quick function in our module to call this forward:
<cpp>/** Fires the say chat event in plugins. Returns true to allow the text, false to block. */
bool FireChatEvent(int client, const char *text)
{
if (!g_pSayChat)
{
return true;
}

cell_t result = 0;
g_pSayChat->PushCell(client);
g_pSayChat->PushString(text);
g_pSayChat->Execute(&result);

if (result == Pl_Handled)
{
return false;
}

return true;
}</cpp>

As you can see, this was pretty simple. Each parameter is "pushed" one at a time, in ascending order. First we push the client index as a cell, then the text as a string. Once done, we execute, and the value will be returned by reference.

Lastly, there is a caveat. Unlike natives, SourceMod does not automatically clean up forwards for us when are done. We have to make sure we destroy them. Uncomment <tt>SDK_OnUnload</tt> from <tt>extension.h</tt> and implement it like so:
<cpp>void Sample::SDK_OnUnload()
{
g_pForwards->ReleaseForward(g_pSayChat);
}</cpp>

==Unmanaged Forwards==
Now things get a bit more complicated. However, unmanaged forwards are essentially the same -- they just give you more flexibility. Let's consider the managed example with a new twisty. We want to let users add and remove hooks from their plugins, rather than having one global forward. The standard way to do this is with ''function IDs''.

Example prototype:
<pawn>funcenum SayChatHook
{
forward(client, const String:text[]);
}

native AddSayChatHook(SayChatHook:hook);
native RemoveSayChatHook(SayChatHook:hook);</pawn>

The <tt>funcenum</tt> syntax lets you define all the valid prototypes for your hook. In this example, the only valid method is a function declared like this (only MyHook can be changed):
<pawn>MyHook(client, const String:text[])</pawn>

How do we make such a beast? The first step is setting up our forward.
<cpp>IChangeableForward *g_pSayChat = NULL;
/* ... */
void Sample::SDK_OnAllLoaded()
{
g_pSayChat = g_pForwards->CreateForwardEx(NULL, ET_Hook, 2, NULL, Param_Cell, Param_String);
}</cpp>

Notice two big difference. We now use <tt>IChangeableForward</tt> instead of <tt>IForward</tt>, and we use <tt>CreateForwardEx</tt> instead. The initial first parameter specifies a name for our forward - we're going to ignore this.

Now, we need to create our natives. These will be fairly simple:
<cpp>cell_t AddSayChatHook(IPluginContext *pContext, const cell_t *params)
{
g_pSayChat->AddFunction(pContext, static_cast<funcid_t>(params[1]));
return 1;
}

cell_t RemoveSayChatHook(IPluginContext *pContext, const cell_t *params)
{
IPluginFunction *pFunction = pContext->GetFunctionById(static_cast<funcid_t>(params[1]));
g_pSayChat->RemoveFunction(pFunction);
return 1;
}</cpp>
''Note: These natives must be added -- that step is removed here and explained earlier.''

You do not need to worry about a plugin unloading - Core will automatically remove the functions for you. Since an <tt>IChangeableForward</tt> is also an <tt>IForward</tt>, the <tt>FireChatEvent</tt> function from earlier does not need to change. We're done!

==Creating Interfaces==
Do you want your extension to share an interface? If so, first you should create an ''interface file''. This file should contain everything your interface needs - this way other authors can easily reference it. Your interface must inherit the <tt>SMInterface</tt> class. It must also declare two global macros that uniquely identify your interface. It must also implement two functions: <tt>GetInterfaceName</tt> and <tt>GetInterfaceVersion</tt>.

The two defines must start with <tt>SMINTERFACE_</tt> and end with <tt>_NAME</tt> and <tt>_VERSION</tt> respectively. The first must be a string and the second must be an unsigned integer. This integer represents your interface's version number. While you are free to use it however you please, by default it should be linearly increased. If you make breaking changes or change the versioning scheme, you must overload the <tt>IsVersionCompat</tt> function in <tt>SMInterface</tt>.

Example:
<cpp>#ifndef _INCLUDE_MYINTERFACE_FILE_H_
#define _INCLUDE_MYINTERFACE_FILE_H_

#include <IShareSys.h>

#define SMINTERFACE_MYINTERFACE_NAME "IMyInterface"
#define SMINTERFACE_MYINTERFACE_VERSION 1

class IMyInterface : public SourceMod::SMInterface
{
public:
virtual const char *GetInterfaceName()
{
return SMINTERFACE_MYINTERFACE_NAME;
}
virtual unsigned int GetInterfaceVersion()
{
return SMINTERFACE_MYINTERFACE_VERSION;
}
public:
/**
* @brief This function does nothing.
*/
virtual void DoNothingAtAll() =0;
};

#endif //_INCLUDE_MYINTERFACE_FILE_H_</cpp>

Notice, of course, that our interface is ''pure virtual''. This means it must be implemented in the extension. Assuming you know C++, this should be fairly straight forward, so let's skip right to how to add this interface to the SourceMod shared system:
<cpp>bool Sample::SDK_OnLoad(char *error, size_t err_max, bool late)
{
g_pShareSys->AddInterface(myself, &g_MyInterface);
return true;
}</cpp>
''Note: We do this in <tt>SDK_OnLoad()</tT> instead of <tt>SDK_OnAllLoaded()</tt>. Otherwise, an extension might try to search for your interface during <tt>SDK_OnAllLoaded()</tt>, and it might fail depending on the load order.''

That simple? Yup! Now other extensions can use your interface.

=Using Interfaces/Other Extensions=
There are a variety of interfaces that are available, but not loaded by default in the Extension SDK. These interfaces can be retrieved and used in your extension.

==Core Interfaces==
If they are provided by Core, getting them is very simple. Most of the <tt>.h</tt> interface files in the root of the <tt>public</tt> folder in the SDK are Core interfaces. For example, code to use the IPluginManager interface might look like this:
<cpp>#include <IPluginSys.h>

IPluginManager *g_pPlugins = NULL;

bool Sample::SDK_OnLoad(char *error, size_t err_max, bool late)
{
SM_GET_IFACE(PLUGINSYSTEM, g_pPlugins);
return true;
}</cpp>

Where did we get <tt>PLUGINSYSTEM</tt> from? Observe the two lines in <tt>IPluginSys.h</tt>:
<cpp>#define SMINTERFACE_PLUGINSYSTEM_NAME "IPluginManager"
#define SMINTERFACE_PLUGINSYSTEM_VERSION 1</cpp>

The <tt>SM_GET_IFACE</tt> macro uses the text in between the <tt>SMINTERFACE_</tt> and the <tt>_NAME</tt> characters. It also uses the version for compatibility checking. If it can't find the interface, it automatically prints to the error buffer and returns false.

===Default Interfaces===
There are interfaces which are grabbed by the Extension SDK by default. You do not need to query for them on load, or even check if they are valid or not. They are:
*<tt>IShareSys</tt> - Exposed as <tt>g_pShareSys</tt>, found in <tt>IShareSys.h</tt>
*<tt>HANDLESYSTEM</tt> - Exposed as <tt>g_pHandleSys</tt>, found in <tt>IHandleSys.h</tt>
*<tt>SOURCEMOD</tt> - Exposed as <tt>g_pSM</tt>, found in <tt>ISourceMod.h</tt>
*<tt>FORWARDMANAGER</tt> - Exposed as <tt>g_pForwards</tt>, found in <tt>IForwardSys.h</tt>

==External Interfaces==
The situation changes if your extension requires ''another extension'', since extensions may load in a completely random order. The first step is to mark the other extension as a dependency. Let's say you want to use the <tt>IThreader.h</tt> interfaces from <tt>threader.ext.dll</tt>. First, we declare it as such:

<cpp>bool Sample::SDK_OnLoad(char *error, size_t err_max, bool late)
{
g_pShareSys->AddDependency(myself, "thread.ext", true, true);
return true;
}</cpp>

The two boolean parameters to <tt>AddDependency</tt> mean, respectively: "try to automatically load this extension" and "this extension cannot work without the dependency."

Second, we query for the interface in <tt>SDK_OnAllLoaded</tt>. Since we don't know when <tt>thread.ext</tt> will actually be loaded, we have to wait until everything is definitely loaded.
<cpp>IThreader *g_pThreader = NULL;
/* ... */
void Sample::SDK_OnAllLoaded()
{
SM_GET_IFACE(THREADER, g_pThreader);
}</cpp>

Third, we need to find a way to fail if this interface was never found. The way to do this is by uncommenting <tt>QueryRunning</tt> from <tt>extension.h</tt> and implementing it:
<cpp>bool Sample::QueryRunning(char *error, size_t err_max)
{
SM_CHECK_IFACE(THREADER, g_pThreader);
return false;
}</cpp>

When SourceMod queries your extension, the macro above will either vaildate the pointer or return false. If it returns false, SourceMod marks your extension as failed.

==Caveats==
===NULL Interfaces===
There are a few ways that external interfaces can make your code complicated. The first is simple but a common oversight. Don't assume interfaces will be okay. For example, say we want to create a thread once we get the <tt>IThreader</tt> interface. Our code should something like this:

<cpp>void Sample::SDK_OnAllLoaded()
{
SM_GET_IFACE(THREADER, g_pThreader);

if (QueryRunning(NULL, 0))
{
g_pThreader->MakeThread(/* stuff */);
}
}</cpp>

Note that we ''query ourself'' in order to find if it's safe to continue executing code. We could also have simply checked if <tt>g_pThreader</tt> is <tt>NULL</tt>, but self-querying has a bonus: if your extension continues to do things like hook events or add listeners, you will be preventing your extension from entirely initializing itself while one interface is bad. Always make sure you have sanity checks like this where needed.

===Dynamic Unloading===
The second major caveat is that extensions can be dynamically unloaded. If you specified yourself as having a dependency and that each dependency is required, you will have no problem. Your extension will be unloaded before the interface is removed, and you can clean up memory/hooks in your <tt>SDK_OnUnload()</tt> code. There are two situations where this is a different story.

====Optional Interfaces====
The first situation is if you are not requiring an extension that contains an interface. Now, when the extension unloads, your extension will not be unloaded first. This creates a small problem, as you must clean up without being unloaded. There are two functions you can implement in your extension class to resolve this, both documented in <tt>IExtensionSys.h</tt>:
*<tt>QueryInterfaceDrop</tt> - Allows you to request unloading when a specific interface is unloaded. This is the default behaviour for all interfaces. If you want to block this functionality, continue reading.
*<tt>NotifyInterfaceDrop</tt> - This is called when an interface is dropped. If your plugin will not be unloaded, you can use this to clean up any resources on a specific inteface being removed.

====Circular Dependencies====
The second situation is a bit more complicated. It is possible for two extensions to have circular dependencies. For example:
*Extension "A" requires extension "B."
*Extension "B" requires extension "A."

If either extension is unloaded, the opposite extension is unloaded normally. The first extension then receives the interface drop callbacks. In this situation, it is essential that the <tt>NotifyInterfaceDrop</tt> function be implemented and used with the circular interface. Otherwise, you risk crashing when your extension unloads (or at the very least, leaking memory). Since the actual drop order is undefined, it means both extensions must implement this function to be safe.

=Setting up Visual Studio=
==Paths==
'''Visual Studio 2003''': Tools -> Options -> Projects, VC++ Directories

'''Visual Studio 2005''': Tools -> Options -> Projects and Solutions -> VC++ Directories

===Include Paths===
*SourceMod only:
**sdk\public\extensions
**sdk\public\sourcepawn
**sdk\public
*SourceMM (Note that sourcemm might be 'trunk' for you):
**sourcemm\sourcemm
**sourcemm\sourcehook
**sourcemm
*HL2SDK:
**game_shared
**public\vstdlib
**public\tier1
**public\tier0
**public\engine
**public\dlls
**public
**dlls

===Link Paths===
*HL2SDK:
**lib\public
**lib\public\msvc8 for version 2005
**lib\public\msvc7 for version 2003

==Compiler Options==
Note: These options are set by default in the sample Extension SDK. 
Note: These options should be set for every build (Release/Debug/others).

*General
**<tt>Character Set</tt>: '''Use Multi-Byte Character Set'''
*C/C++
**General
***<tt>Detect 64-bit Portability Issues</tt>: '''No'''
**Preprocessor
***<tt>Preprocessor Defines</tt>: Add <tt>_CRT_SECURE_NO_DEPRECATE</tt> and <tt>_CRT_NONSTDC_NO_DEPRECATE</tt>
**Code Generation
***<tt>Runtime Library</tt>: Multi-threaded or /MT (for Release), Multi-threaded Debug or /MTd (for Debug)
*Linker
**General
***<tt>Output File</tt>: Change <tt>$(ProjectName)</tt> to <tt>$(ProjectName).ext</tt>, or use your own custom string.
**Input
***<tt>Additional Dependencies</tt>: <tt>tier0.lib tier1.lib vstdlib.lib</tt> (for SourceMM attached extensions only)

[[Category:SourceMod]]
[[Category:SourceMod Development]]

Talk:Optimizing Plugins (AMX Mod X Scripting)

2007-01-18T23:42:55Z

CyberMind: Reverted edit of Qqqqqqq, changed back to last version by BAILOPAN

Let's say i have Float:{233.594378, 345.634256, 1234.756464} array and i need reindex it two times. Two example:
<pawn>if (array[0] > some_float_variable)
x = 1.2 + array[0]</pawn>
or
<pawn>y = array[1] * array[1]</pawn>
Would it be more efficient (in fact)?
<pawn>new Float:temp = array[0]
if (temp > some_float_variable)
x = 1.2 + temp</pawn>
or
<pawn>new Float:temp = array[1]
y = temp * temp</pawn>--[[User:VEN|VEN]] 08:32, 3 March 2006 (EST)
:The bottom two are more efficient. However, it only really matters if you're repeating this computation a lot. If this is a one-time computation it won't make a difference. -- [[User:BAILOPAN|BAILOPAN]] 18:25, 3 March 2006 (EST)
----
Regarding [[User:NiLuJe|NiLuJe]]'s change of '\0' to 0: while they are both the same, keeping the syntax in terms of characters would probably be better for people to understand when dealing with strings, so I reverted the changes back.
:Perhaps it should be changed to '^0'... by default we don't use \ for a backtick. This is probably what he meant to correct. -- [[User:BAILOPAN|BAILOPAN]] 18:55, 1 March 2006 (EST)
::Ah, indeed, fixing that now --[[User:CyberMind|cybermind]] 02:39, 2 March 2006 (EST)
----

Is there evidence that when something is const it's faster? I think this might be to the contrary, as the compiler has to copy it into the heap first to ensure that it isn't modified. -- [[User:BAILOPAN|BAILOPAN]] 00:54, 1 February 2006 (EST)

:Whether or not const variables/arrays are copied to the heap depends on the situation:

:<tt>For a function that has an array argument with a default value, the compiler allocates space for
:the default array value on the heap. However, if the array argument (with a default value) is
:also const, the pawn compiler passes the default array directly (there is no need to make a copy
:on the heap here, as the function will not attempt to change the array argument and, thereby,
:overwrite the default value).

:The arguments of a function that has "variable arguments" (denoted with the ... operator, see
:the pawn booklet "The Language") are always passed by reference. For constants and expressions
:that are not lvalues, the compiler copies the values to a cell that is allocated from the heap,
:and it passes the address of the cell to the function.</tt>
:-Page 106 (PDF page 108) of "The Implentor's Guide"

:<tt>Function insert copies in the other direction and it does not change its function argument item.
:In such a case, it is advised to mark the function argument as "const". This helps the pawn parser
:to both check for errors and to generate better (more compact, quicker) code.</tt>
:-Page 21 (PDF page 23) of "The Language Guide"
:--[[User:CyberMind|cybermind]] 01:24, 1 February 2006 (EST)
 
::I see, thanks for the clarification. Twilight, I'd amend your part somewhat to mirror that. -- [[User:BAILOPAN|BAILOPAN]] 02:54, 1 February 2006 (EST)

AlliedModders Wiki:Site support

2007-01-12T10:39:25Z

CyberMind: Reverted edit of Avol, changed back to last version by Googol

Currently a central hub in between projects is in the works.
In the meantime, you should use the donations link from the [http://www.sourcemod.net/ SourceMod] website.

Optimizing Plugins (AMX Mod X Scripting)

2006-10-24T17:55:53Z

CyberMind: Reverted edit of Reiko, changed back to last version by UserError

==Introduction==
[[Admin-Mod]] and [[AMX Mod X]] became very popular because of their easy to use scripting language. However, the words "scripting language" come with a lot of loaded preconceptions. Most people assume that because it's scripted:
*You can't possibly make it any faster
*It's pre-compiled, so it's already quite fast
*Details don't matter, as it's only "scripting" anyway

Especially, with [[Pawn]] (formerly Small), none of these are true. The compiler, in fact, is very poor at optimizing, and you can '''greatly''' increase the speed and efficiency of your plugins by keeping a few rules in mind. Remember - it's more important to minimize instructions than it is to minimize lines of code.

===Terms===
To read this document, you will need to understand a few concepts beforehand:
*<tt>BRANCHING</tt> - When the processor takes a different path of code. For example, to call a function or to use an if statement, the processor will "branch". Modern processors attempt to predict pathways with "branch prediction", but it's best to avoid branching a lot if possible.
*<tt>STACK ALLOCATION</tt> - In Pawn, all local data is stored on the stack, a big chunk of continuous memory. Whenever you create a variable on the stack, it is automatically written with zeroes.
*<tt>HEAP ALLOCATION</tt> - In Pawn, temporary data that needs to be referenced by a native is stored on the heap, another area of contiguous, but less restrictive memory.
*<tt>DATA SECTION</tt> - This is an area of memory built into your .amxx file. In fact, it "becomes" the heap at load time. All your strings and arrays are hardcoded into this area.
*<tt>EXPENSIVENESS</tt> - To be "expensive" in computer science means an operation requires a lot of CPU processing. It usually does not refer to memory size, only to processing cycles and time. Addition is inexpensive, floating power operations are expensive. However, both are inexpensive in comparison to writing a file. An inexpensive operation can also be called "cheap".
*<tt>BIG-OH NOTATION</tt> - O(*) notation refers to the expensiveness of an algorithm. If something is O(n), it occurs in linear time -- meaning that for N items, it will complete relative to N. O(N^2) means with N items, it will complete relative to N^2. O(1) means "constant time" - no matter what N is, it will run in the same amount of time.

==Compiler Optimizations==
These optimizations have to do with changing how your code is compiled. While the syntax may remain the same, you are not only increasing compile time, but increasing your plugin's efficiency and speed at run time.

===Always Save Results===
Observe the example code snippet below:
<pawn>if (get_user_team(player) == TEAM_T)
{
//...code
} else if (get_user_team(player) == TEAM_CT) {
//...code
} else if (get_user_team(player) == TEAM_SPECTATOR) {
//...code
}</pawn>
This is a mild example of "cache your results". When the compiler generates assembly for this code, it will (in pseudo code) generate:
<pre>
CALL get_user_team
COMPARE+BRANCH
CALL get_user_team
COMPARE+BRANCH
CALL get_user_team
COMPARE+BRANCH
</pre>
Notice the problem? We have called <tt>get_user_team</tt> an extra two times than necessary. The result doesn't change, so we can save it. Observe:
<pawn>new team = get_user_team(player)
if (team == TEAM_T)
{
//...code
} else if (team == TEAM_CT) {
//...code
} else if (team == TEAM_SPECTATOR) {
//...code
}</pawn>
Now, the compiler will only generate this:
<pre>
CALL get_user_team
COMPARE+BRANCH
COMPARE+BRANCH
COMPARE+BRANCH
</pre>
If <tt>get_user_team</tt> were an expensive operation (it's relatively cheap), we would have recalculated the entire result each branch of the <tt>if</tt> case.

===Switch instead of If===
If you can, you should use <tt>switch</tt> cases instead of <tt>if</tt>. This is because for an if statement, the compiler must branch to each consecutive <tt>if</tt> case. Using the example from above, observe the switch version:
<pawn>new team = get_user_team(player)
switch (team)
{
case TEAM_T:
//code...
case TEAM_CT:
//code...
case TEAM_SPECTATOR:
//code...
}</pawn>
This will generate what's called a "case table". Rather than worm through displaced <tt>if</tt> tests, the compiler generates a table of possible values, which the virtual machine knows to browse through:
<pre>
CALL get_user_team
COMPARE
COMPARE
COMPARE
</pre>

===Don't Re-index Arrays===
A common practice in Small is to "save space" by re-indexing arrays. There are a few myths behind this, such as saving memory, assuming the compiler does it for you, or readability. Fact: none of these are true. Observe the code below:
<pawn>new players[32], num, team
get_players(players, num)
for (new i=0; i<num; i++)
{
if (!is_user_connected(players[i]))
continue;
team = get_user_team(players[i])
set_user_frags(players[i], 0)
}</pawn>
For this, the compiler generates code similar to:
<pre>
:LOOP_BEGIN
LOAD i
LOAD players
CALC
LOAD players[i]
CALL is_user_connected
LOAD i
LOAD players
CALC
LOAD players[i]
CALL get_user_team
LOAD i
LOAD players
CALC
LOAD players[i]
CALL set_user_frags
</pre>
See what happened? The compiler does not cache array indexing. Because we've used <tt>players[i]</tt> each time, every instance generates 4-6 (or more) instructions which load <tt>i</tt>, the address of <tt>players</tt>, computes the final location, and then grabs the data out of memory. It is much faster to do:
<pawn>new player
for (new i=0; i<num; i++)
{
player = players[i]
if (!is_user_connected(player))
continue;
team = get_user_team(player)
}</pawn>
Not only is this more readable, but look at how much cruft we've shaved off the compiler's generated code:
<pre>
:LOOP_BEGIN
LOAD i
LOAD players
CALC
LOAD players[i]
STORE player
CALL is_user_connected
LOAD player
CALL get_user_team
LOAD player
CALL set_user_frags
</pre>
In a large loop you can drastically reduce codesize in this manner.

===Global vs Local and Variables in Loops===
It is important to realize that every variable in [[Pawn]] is automatically zeroed. For global variables, they are static and permanent, thus they are zeroed when your plugin is loaded. Variables in functions, however, must be zeroed dynamically. This is a slow and tedious operation, and you should not only avoid relying on it when necessary, but you should keep that fact in mind when using arrays.

[[Arrays]] in [[Pawn]] are "cells" of data. Each cell is four or eight bytes, depending on whether your processor is 32bit or 64bit. To create an array of 4096 cells, for example:
<pawn>new array[4096]</pawn>
The compiler generates code to manually zero every single one of the 16,384 bytes in that location. Normally, this isn't too bad -- but it can be absolutely deadly in a function which is called quite often. For example, <tt>server_frame</tt> is called on every [[server tick]] in [[AMX Mod X]]. To declare an array of that size in <tt>server_frame</tt> is highly unnecessary. Instead, you can take advantage of the fact that not only are globals free of charge, but <tt>server_frame</tt> does not need to be re-entrant. That is, you will never call <tt>server_frame</tt> inside of <tt>server_frame</tt>, so making the variable global will not bring up the problem of one instance of the function overwriting data from another instance of the same function. Observe:
<pawn>new g_serverframe_array[4096]
public server_frame()
{
//...code that uses g_serverframe_array
}</pawn>
This will execute conseridably faster. You can do this with smaller arrays too.

Likewise, it is equally important to avoid declaring arrays inside of loops. Consider the following block of code:
<pawn>for (new i=0; i<num; i++)
{
new message[255], name[32], player
player = players[i]
get_user_name(player, name, 31)
format(message, 254, "Hello, %s", name)
}</pawn>
If there are 32 players, this loop will actually resize and zero out over 1K of memory thirty two times in a row. Not good! However, on the other hand, it's nice that the message is zeroed out for us each time. <tt>Tip:</tt> you often only need to zero out the first character of a string. This will make the entire string empty. The code below is much more efficient:
<pawn>new message[255], name[32], player
for (new i=0; i<num; i++)
{
player = players[i]
name[0] = '^0'
message[0] = '^0'
get_user_name(player, name, 31)
format(message, 254, "Hello, %s", name)
}</pawn>
This has the effect of safely making the string empty beforehand, as well as largely reducing a lot of run-time overhead.

===Static vs Global===
An alternative to global variables is static variables, which are internally the same but easier to work with for programming.

A variable declared with the keyword "static" instead of "new" operates in the same way a global does (it is created only once) but the variable is local to the function; this means the code is much easier to read, while drastically improving speed just like a global variable. Example:
<pawn>stock SomeBigFunction()
{
static gaben[255];
format(gaben, "%L", LANG_SERVER, "STUFF");
}</pawn>

This has the same effect as declaring <tt>gaben</tt> as global, except only <tt>SomeBigFunction</tt> can use it.

{{qnotice|Be careful of re-entrancy!}}
When a variable is static, it has the same re-entrancy problems of a global variable. That means, if your function might be called recursively, or twice in the same stack frame, you should not use static variables. This is most often the case for API provided to other plugins or helper functions. Triggered events are usually never called twice on the same execution chain.

===Constant variables===
You can declare a variable "constant" by adding the "const" keyword before the variable name:

<pawn>new const AMX_GABEN[] = "amx_gaben"</pawn>

What this does is prevents the variable from being changed; essentially, you've locked the variable to a certain value. In this way, a constant can offer a type safe method of simplifying code, unlike a define, which is not type safe.

In addition, constant variables are often optimized out, resulting in quicker and smaller code.

===For Loop Comparisons===
A common mistake is to write code like this:
<pawn>new string[256] = "something long"
for (new i=0; i<strlen(string); i++)
//...code</pawn>
This plays off a similar principle from before: cache results. The compiler will actually recompute your string length on each iteration of the loop. This will have even worse effects if your string changes mid-loop. A more sensible method is:
<pawn>new string[256] = "something long"
new len = strlen(string)
for (new i=0; i<len; i++)
//...code</pawn>

==Tips and Tricks==
===Lookup Tables===
Precompute what can be precomputed. For example, say you have a mapping of weapon indices to names:
<pawn>if (weapon == CSW_AK47)
copy(name, len, "weapon_ak47")</pawn>
Ignoring the fact that we have <tt>get_weapon_name</tt> in [[AMX Mod X]], this is inefficient. We could precompute this result in a table:
<pawn>new g_WeaponNamesTable[TOTAL_WEAPONS][] = {
//..0 to CSW_AK47-1
"weapon_ak47",
//..CSW_AK47+1 to TOTAL_WEAPONS-1
};</pawn>

===Perfect Hashing===
:TODO: explain this

===Local Strings===
The [[Pawn]] compiler does not optimize the DATA section, which stores all hardcoded strings and global arrays. If you reference the same hardcoded string 500 times in your plugin, it will appear 500 different times. If this seems bad enough, it actually does this with all strings. For example, the empty string ("") appears everywhere in the include files, usually used as a default parameter to many natives. This too is copied into the data section for each unique reference.

For example:
<pawn>set_cvar_string("amx_gaben", get_cvar_string("amx_gaben") + 1)</pawn>
This will create two copies of "amx_gaben" in the DATA section. While this doesn't really hurt, it does increase the size of your plugin.

Similarly, this has the same problem:
<pawn>#define AMX_GABEN "amx_gaben"
set_cvar_string(AMX_GABEN, get_cvar_string(AMX_GABEN) + 1)</pawn>
The only way to avoid this mess is to use global variables. As stated earlier, they're basically free storage.
<pawn>new AMX_GABEN[] = "amx_gaben"
set_cvar_string(AMX_GABEN, get_cvar_string(AMX_GABEN) + 1)</pawn>

Again, while not necessary, this will reduce your plugin's size in memory and on disk. If you're already using defines, you can make this switch easily.

In order to prevent this from changing, you may want to declare it constant:

<pawn>new const AMX_GABEN[] = "amx_gaben"
set_cvar_string(AMX_GABEN, get_cvar_string(AMX_GABEN) + 1)</pawn>

Now it is a perfectly safe method of storage.

==Faster Natives==
AMX Mod X replaces many of the old AMX Mod natives with faster versions. Read below to discover them.

===Cvar Pointers===
As of AMX Mod X 1.70, you can cache "cvar pointers". These are direct accesses to cvars, rather than named access. This is a critical optimization which is dozens of times faster. For example:
<pawn>new g_enabled = register_cvar("csdm_enabled", "1")
//OR
new g_enabled = get_cvar_pointer("csdm_enabled")

stock SetCSDM(num)
set_pcvar_num(g_enabled, num)

stock GetCSDM()
return get_pcvar_num(g_enabled)
</pawn>
All of the cvar* functions (except for set_cvar_string) are mapped to [get|set]_pcvar_*. You can get a cached cvar pointer with get_cvar_pointer() or register_cvar().

===FormatEX===
As of AMX Mod X 1.70, there is an ultra high-speed version of format() called formatex(). It skips copy-back checking, unlike format(). formatex() cannot be used if a source input is the same as the output buffer. For example, these are invalid:
<pawn>new buffer[255]
formatex(buffer, 254, "%s", buffer);
formatex(buffer, 254, buffer);
formatex(buffer, 254, "%d %s", buffer[2]);</pawn>

It should be noted that format() will behave the same as formatex() if it detects that there will be no copy-back needed. However, formatex() does not check this, and thus is slightly faster for situations where the coder is sure of its usage.

===File Writing===
As of AMX Mod X 1.70, there are new natives for file writing. Read_file and write_file are O(n^2) functions for consecutive read/writes. fopen(), fgets(), fputs(), and fclose() are O(n) (or better) depending on how you use them.

[[Category:Scripting (AMX Mod X)]]

GNU General Public License

2006-10-24T17:55:50Z

CyberMind: Reverted edit of Blackgizmo, changed back to last version by BAILOPAN

==Overview==
Perhaps the most well known of stock licenses, the GPL is a viral license because of how it controls copying. A common misconception about the GPL is how it "makes things open source". The GPL only affects the act of copying or distributing a piece of work. It simply mandates that for each person you distribute or copy the software to, that person must have the same freedoms as enumerated in the license. The essential freedom is GPL'd access to the source code and the ability to freely modify and redistribute the source code.

==License Text==
<pre>
GNU GENERAL PUBLIC LICENSE

Version 2, June 1991

Copyright (C) 1989, 1991 Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
</pre>

===Preamble===

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Lesser General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.
===TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION===

*0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

*1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

*2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:
**a) You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.
**b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
**c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

*3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:
**a) Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
**b) Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
**c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

*4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

*5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

*6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

*7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

*8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.

*9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

*10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

NO WARRANTY

*11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

*12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

===How to Apply These Terms to Your New Programs===

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

<pre>
one line to give the program's name and an idea of what it does.
Copyright (C) yyyy name of author

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
</pre>

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in an interactive mode:

<pre>
Gnomovision version 69, Copyright (C) year name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'. This is free software, and you are welcome
to redistribute it under certain conditions; type `show c'
for details.
</pre>

The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here is a sample; alter the names:

<pre>
Yoyodyne, Inc., hereby disclaims all copyright
interest in the program `Gnomovision'
(which makes passes at compilers) written
by James Hacker.

signature of Ty Coon, 1 April 1989
Ty Coon, President of Vice
</pre>

This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the [[GNU Lesser General Public License]] instead of this License.

==Projects==
*[[Metamod]]
*[[AMX Mod X]]

==External Links==
*[http://www.gnu.org/copyleft/gpl.html GNU GPL Site]
*[http://www.fsf.org/ Free Software Foundation]
*[http://www.opensource.org/licenses/gpl-license.php OSI GPL Site]
*[http://www.opensource.org Open Source Initiative]

[[Category:Copyright]]

Help:Editing

2006-10-21T12:12:46Z

CyberMind: Reverted edit of Tictac, changed back to last version by Twilight Suzuka

To read more about editing a wiki, see the MediaWiki editing documentation here: [http://meta.wikimedia.org/wiki/Help:Editing MediaWiki Editing]

User:Twistedeuphoria

2006-10-21T12:10:13Z

CyberMind: Reverted edit of Cl flushentity, changed back to last version by Twilight Suzuka

== TwistedEuphoria==
Euphoria, known as "Twisty" or "The twisted one" by his firneds (of whom you are NOT a part of), is an insane but quite lazy and lethargic man, who is also a basement dweller. He is the only person to date to have communicated over IRC without moving.

=== Childhood ===
From the moment he was born, Twisty's parents knew he would be a failure of epic proportions.
This story is, remarkably, about Twisty's birth:
<pre>
euphoriasai once the doctor hit me and i didnt move
euphoriasai then i was like oh hey i should move
euphoriasai then i did
euphoriasai true story
BAILOPAN then you collapsed from exhaustion
euphoriasai yeah that moving thing is overrated
</pre>

From that moment on, not much changed.

Twisty didn't move more than an inch until his tenth birthday, when he was plyed with alcohol to move towards a large peice of cake. This is also the day that Twisty became an orphan, as his parents were caught plying many young girls with alcohol, along with Twisty. In a feat of untold horror, the police uncovered an amount of child pornography that made the great egyptian pyramids look like mole hills.

At this point, Twisty was over 500 pounds, and used a computer with OSX on it.

Currently, Twisty is at a much more acceptable weight, and uses a PC, but unfortunately, he still doesn't move much. In a feat of untold will, he has managed to link with IRC telepathically, so that he can sleep and chat with friends. Well, not really "friends", more like people...that work and talk with other people....that they hate.

Twisty has a great deal of telekenetic skill, as he refuses to move very much. Unfortunately, he is also very lazy, and telekenesis takes a lot of energy and concentration.

Twisty also has the innate ability to see ghosts. At some point, he had orange hair, and was actually muscular, as his fat imploded into him due to the immense tidal forces, forming muscle somehow, and met some girl, stole her virginity and powerz, and got a kickass sword. Luckily for all humanity, some homeless guy named Aizen managed to steal the sword from him. In a fit of rage, Twisty locked himself in his basement. He has not come out since.

For a detailed analysis of these events in Twisty's life, read the manga "Bleach". While slightly exaggerated for marketing purpose, it is Twisty's teenage years. More or less.

=== A average day with the Twisted One ===
All he does is sleep, masturbate, and communicate online. Thats it. Stop reading. Theres no more to tell! I'm serious!

=== Twisty on virginity ===
Twisty will take your virginity. If you think this is impossible, because you've already lost yours, you are wrong.

<tt> Dead wrong </tt>

Talk:Installing Metamod:Source

2006-10-04T05:33:06Z

CyberMind: Reverted edit of Hpc1ne2006, changed back to last version by Cybot

I had a problem while installing SourceMM to Source Dedicated Server (STEAM version, not independent, windows). My gameinfo.txt ShearchPaths changed after server load to this:
<pre>
SearchPaths
{
Game |gameinfo_path|.
Game cstrike
Game hl2
}
}
}

Game cstrike
Game hl2
}
}
}
</pre>
and plugin didn't work. I solve this by putting "Read Only" flag to gameinfo.txt file.

== Where 'before'? ==

GameBin |gameinfo_path|addons/metamod/bin
SearchPaths
{
Game |gameinfo_path|.
Game cstrike
Game hl2
}

or

SearchPaths
{
GameBin |gameinfo_path|addons/metamod/bin
Game |gameinfo_path|.
Game cstrike
Game hl2
}

???

Metamod

2006-07-16T06:59:00Z

CyberMind:

== About Metamod ==
[[Category:Half-Life_1]]
Metamod is a plugin/DLL manager that sits between the [[Half-Life_1|Half-Life]] Engine and an HL Game mod, allowing the dynamic loading/unloading of mod-like DLL plugins to add functionality to the HL server or game mod.

[[AMX_Mod_X|AMX Mod X]] is a Metamod plugin.

{{Stub}}

Talk:FTP

2006-05-31T17:31:49Z

CyberMind:

"how do i find out FTP information?"

Get it from your server provider.

Metamod:Source Development

2006-04-26T09:02:48Z

CyberMind: Reverted edit of Cpufreak04, changed back to last version by CyberMind

This article is an introduction to [[SourceMM]] coding.

{{qnotice|The majority of this documentation should be merged or moved into an article about [[SourceHook]].}}

{{qnotice|This article probably needs some better formatting.}}

=Requirements=
You must have the Valve [[HL2SDK]], available from your [[Steam]] Menu. For Windows, you must have [[Microsoft Visual Studio]] 7.0 or 7.1 (we have not tried 6.0). For [[Linux]], Valve requires you use at least [[GCC]] 3.4.1. You should also have a copy of the [[Metamod:Source]] source code, available [http://www.sourcemm.net/ here] (sourcemm/sourcehook and sourcemm/sourcemm).

For [[Microsoft Visual Studio]], you should make sure that you have the following HL2SDK paths in your include settings (Tools -> Options -> Projects, VC++ Directories, Include Files), as well as the "sourcehook" and "sourcemm" folders:
*dlls
*public
*public\vstdlib
*public\tier1
*public\tier0
*public\engine
*public\dlls
*tier1
*lib\public (this should be in your Library Paths!)

=Plugin API=
In order to write a plugin, you must implement the ISmmPlugin interface, similar to IServerPluginCallbacks. Each Metamod:Source release has a minimum required interface version and a current version. The minimum version is guaranteed to be upward compatible to the current, however, it may be lacking some features.

Once you've implemented the interface, you must also have a global singleton of your plugin available. There are a few macros to assist you in properly exposing the interface as a DLL and setting up the API states.

*{{bcode|PLUGIN_GLOBALVARS}}() - Place in header. Declares the global variables that some API calls require (such as g_SHPtr and g_PLAPI).
*{{bcode|PLUGIN_EXPOSE}}(class, singleton) - Place in .cpp file. Declares the external CreateInterface function which exposes the API.
*{{bcode|PLUGIN_SAVEVARS}}() - Use first thing in ISmmPlugin::Load(), saves the global variables sent from SourceMM.

The actual plugin API you must implement as of this writing is version 004. To see a description of each of the functions, you can view the doxygen information here. Note that the Load, Unload, Pause, and Unpause functions allow you to refuse the action and copy an error message (you should check to make sure error is not NULL - it can be).

=SourceHook (Hooking)=
SourceHook is the engine used to intercept function calls, much like Metamod. The difference with SourceHook is that it can intercept any virtual function in any class that, at compile time, you have the header for. SourceHook has the following steps of operation:

* Declare the prototype of the function you are going to hook. This generates compile-time code that is able to pinpoint exactly how to go about hooking the function.
* Hook the function - as a member function of another class or a regular static function.
* Before the hooked function is called, all of the "pre" hook handlers attached to it are called. Each hook can set a special flag, the highest of which is chosen as a final operation. This flag specifies whether the original function should be called or not.
* Once all the hooks have been called, SourceHook decides whether to call the original function. Another set of hooks are called directly after, called "post" hook handlers. You can specify whether each hook is a post or pre hook - it simply changes whether it's called before or after the original call is made.
* After you are done using a hook, you can safely remove it.

For example, let's say you wanted to intercept log messages in VEngineServer. Observe the prototype:
<pre>
virtual void LogPrint( const char *msg ) = 0;
</pre>
This is a virtual, public function of a class we have an instance of (let's say in IVEngineServer *m_Engine) and that we have the header for. It can be intercepted.

The first step is to figure out how to declare its prototype to SourceHook. This function is void, and has one parameter. The declaration macro follows these formats:

*{{bcode|SH_DECL_HOOK}}n - n is the number of parameters
**The parameters are: Class name, member function name, attributes, overloaded?, the return type, and a list of the parameter types.
*{{bcode|SH_DECL_HOOKn_void}} - n is the number of parameters
**_void specifies that the function does not return a value. The format is the same as above except the "return type" parameter is missing.
*'''Note:''' Not covered here are the SH_DECL_HOOKn[_void]_vafmt hooks. These can hook string-formattable variable argument lists. You do not pass the string format or ellipses parameter. SourceHook will automatically format the string for your hook.

Our macro will look like this:
<pre>
SH_DECL_HOOK1_void(IVEngineServer, LogPrint, SH_NOATTRIB, 0, const char *);
</pre>
This line must appear outside of a function. It means "Declare a hook prototype for LogPrint in IVEngineServer, which is a void function that has one parameter, which is a const char *".

Next we must actually hook the function. You can do this wherever you want to begin the interception. The two macros for hooking look like this:

*{{bcode|SH_ADD_HOOK_STATICFUNC}}(class, memberfunction, instance_pointer, handler, post) Hooks a virtual function to a static/global function.
**class - The name of the class
**memberfunction - The name of the member function
**instance - A pointer to an instance of the class
**handler - Your function that will be called on hooking
**post - true for post operation, false for pre operation
*{{bcode|SH_ADD_HOOK_MEMFUNC}}(class, memberfunction, instance, myinstance, myfunction, post) Hooks a virtual function to a member function of another class.
**class - The name of the class
**memberfunction - The name of the member function
**instance - An pointer to an instance of the class
**myinstance - A pointer to an instance of the class that has the handler member function
**myfunction - The name of the handler member function in your class
**post - true for post operation, false for pre-operation

Let's continue with the example. To hook LogPrint to a function in your class, CMetaHooks (instance, g_MetaHooks), you would use:
<pre>
SH_ADD_HOOK_MEMFUNC(IVEngineServer, LogPrint, m_Engine, &g_MetaHooks, &CMetaHooks::LogPrint, false);
</pre>
To remove the hook (either once it will no longer be unused, or at unload time):
<pre>
SH_REMOVE_HOOK_MEMFUNC(IVEngineServer, LogPrint, m_Engine &g_MetaHooks, &CMetaHooks::LogPrint, false);
</pre>
Now, your function contents will look something like this:
<pre>
void CMetaHooks::LogPrint(const char *msg)
{
//Code here
RETURN_META(MRES_IGNORED);
}
</pre>
Note this return statement. This style of returning is similar to Metamod's, where you can set four different flags to indicate how you would like SourceHook to proceed. In Metamod, this return statement was required. In SourceMM, it is only required if you wish to set a return state other than MRES_IGNORED.

*{{bcode|MRES_IGNORED}} - No states were changed, act as though nothing happened. Original function is still called.
*{{bcode|MRES_HANDLED}} - Something changed, but the original function was still called. This can be used to tell another plugin that you did something.
*{{bcode|MRES_OVERRIDE}} - The original function will still be called, but your return value will override whatever it returns.
*{{bcode|MRES_SUPERCEDE}} - The original function is not called, and your return value will be what is returned to the caller.

Note, that if you need to return a value, there is another macro. For example:
<pre>
RETURN_META_VALUE(MRES_SUPERCEDE, value);
</pre>
This is required for non-void functions, athough the return value is ignored using MRES_IGNORED or MRES_HANDLED.

Alternatively, you can hook to static member functions which has a slightly easier syntax. The DECL_HOOK line does not change. To add the hook:
<pre>
SH_ADD_HOOK_STATICFUNC(IVEngineServer, LogPrint, m_Engine, LogPrint_handler, false);
</pre>
Removing the hook:
<pre>
SH_REMOVE_HOOK_STATICFUNC(IVEngineServer, LogPrint, m_Engine, LogPrint_handler, false);
</pre>
Declaring the handler:
<pre>
void LogPrint_handler(const char *msg)
{
//Code here
RETURN_META(MRES_IGNORED);
}
</pre>
Note that vafmt functions hooked with SourceHook assume that the vafmt is for a printf style string, and that the vafmt occurs at the end. When setting the parameters, you do not include the '...' notation, and SourceHook will vafmt the input string for you (meaning you also don't specify ... in your hooked function).

=Calling Original Functions=
Often it will be necessary for you to call a function that's hooked, however, you don't want the hooks to be included in the calling. For example, if you want to entirely supercede a function and call it yourself from within a hook. To do this, you must request a call class. This is similar to MDLL_x() from Metamod for Half-Life 1.

Continuing with the above example, let's say we want to supercede the original call and log a different message. Assume we also have the pointer m_Engine which is a <tt>IVEngineServer *</tt>.
<cpp>
SourceHook::CallClass<IVEngineServer> *Engine_CC = SH_GET_CALLCLASS(m_Engine);

SH_CALL(Engine_CC, &IVEngineServer::LogPrint)("This is a log message!\n");

//When you are done with the pointer..
SH_RELEASE_CALLCLASS(Engine_CC);
</cpp>

Because of the complex nature of inheritance, instance pointers, and vtables, this syntax can be quite daunting. You may wish to make macros for specific functions or classes you use quite often, to reduce the amount of typing. For example:
<cpp>
//Assuming you have a global pointer g_Engine...
#define ENGCALL(func) SH_CALL(g_Engine, &IVEngineServer::func)

//Then you can do:
ENGCALL(LogPrint)("This is a test!");
</cpp>

The syntax of calling class construction is:
*<tt>SourceHook::CallClass<class> *ptr = SH_GET_CALLCLASS(instance);</tt>
**Returns an object which allows you to call the original function. Class is the name of the class which is the target, instance is an instance of that class.
*<tt>SH_CALL(cc_ptr, &class::func)([params])</tt>
**Pass the pointer returned from SH_GET_CALLCLASS as cc_ptr. The target function you call must be passed as a pointer-to-member-function, which takes the form &Class::Function as seen in previous examples. You must then complete the function call by adding a parenthetical parameter expression, even for void functions, which would be ().

=Other Macros=
All of the macros take g_PLAPI as the first parameter. For more information on this, see the global variables section.

*{{bcode|META_CONPRINT}}(const char *msg)
*{{bcode|META_CONPRINTF}}(const char *fmt, ...)
**These two functions are recommended over Msg() for printing to the server console. Msg() does not relay commands back through rcon, and as of this writing Valve does not expose the function which does. To be able to display text through the rcon console (much like HL1), you should use these functions. If SourceMM is unable to extract the function properly, it will automatically default to Msg.
*{{bcode|META_LOG}}(g_PLAPI, const char *msg, ...)
**Logs a message through IVEngineServer::LogPrint(). A newline is automatically added, and msg is formatted as a sprintf() style string.
*{{bcode|META_REGCVAR}}(var)
**Registers a ConCommandBase pointer through SourceMM. The correct way to use this is to create an IConCommandBaseAccessor, and inside RegisterConCommandBase, call the macro on the given ConComandBase. This will ensure that SourceMM correctly detects and unloads your cvars and concommands at the appopriate time. Otherwise, unloading your plugin will cause a crash.
*{{bcode|META_UNREGCVAR}}(var)
**Unregisters a ConCommandBase pointer. This is not needed if you have set up your IConCommandBaseAccessor correctly (and called ConCommandBaseMngr::OneTimeInit()).

=Events System=
The Events System is based on IMetamodListener. By implementing the IMetamodListener class and using g_SMAPI->AddListener, you can watch for certain, low-traffic events. These events are split into three categories:

*Plugin Events let you listen for plugin pauses and unloads. This is important if you're relying on information from another plugin, as you can handle cases where a live plugin has become invalid.
*Game Events are simple events that SourceMM is already hooking and makes available. These are LevelShutdown and LevelInit right now.
*Query Events occur when a factory is used. The four main factories (Engine, GameDLL, FileSystem, and Physics) are all overridable. You should simply return a non-NULL result to override, and fill the return code with IFACE_OK if available. There is no way to handle the case of two plugins overriding right now. The final factory is the Metamod Factory, which is the factory that Metamod:Source adds to the runtime space for plugins. By default, it only contains the interfaces for the PluginManager and SourceHook. Plugins can use this to add new interfaces. Other plugins request these interfaces through g_SMAPI->MetaFactory().

=Global Variables=
These global variables are saved by PLUGIN_EXPOSE and PLUGIN_SAVEVARS. They are declared with PLUGIN_GLOBALVARS.

*{{bcode|g_PLAPI}}
**ISmmPlugin * pointer to your global class singleton.
*{{bcode|g_PLID}}
**The internal PluginId of your plugin.
*{{bcode|g_SHPtr}}
**The SourceHook::ISourceHook * pointer to SourceHook's interface.
*{{bcode|g_SMAPI}}
**The ISmmAPI * pointer to SourceMM's interface.

=Compiling=
To see more about compiling, see the Sample Plugin Compiling section.

Modifying the default Makefiles for your own projects:

*<tt>OPT_FLAGS</tt> - Optimization flags
*<tt>DEBUG_FLAGS</tt> - Debug flags
*<tt>CPP</tt> - C++ Compiler
*<tt>OBJECTS</tt> - List of C++ files to compile
*<tt>LINK</tt> - Linker Options
*<tt>CFLAGS</tt> - Base Compiler Flags
*<tt>BINARY</tt> - Output Binary Name

Makefile commands:

*clean - Cleans all build files
*debug - Builds debug version

=1.1 Changes - Late Loading, Events=
SourceMM 1.1 changed quite a few things internally, and externally made many breaking changes. These include:

*ISmmPlugin::Load() has removed the factory list parameter (the factory system was replaced with the event system). Also, a boolean parameter was added, specifying whether the plugin was loaded late or not.
*ISmmPlugin::Load() is now called BEFORE DLLInit(), rather than after. This means it might not have all information it needs -- for example, IGameEvents won't be parsed yet. You will need to do things like this in ISmmPlugin:AllPluginsLoaded() instead, as it is guaranteed to occur when all DLLs are initialized.
*ISmmPlugin now has default functions -- you don't have to implement all of them.
*SourceHook was modified to use interfaces rather than straight struct pointers. This breaking changes will ensure that future SourceHook modifications do not break older plugins.
*SourceHook was modified to be re-entrant.
*SourceHook now has a tiny template library with it. This removes the necessity to link against libstdc++.so.*, which harms binary compatibility across linux distributions.
*SourceMM's GameDLL code was completely rewritten. It will now work with newer mods much easier, and issues like the DoD:S release will be much easier to deal with (if at all). It also removes a few important speed bottlenecks.
*An events system was added.

=1.2 Changes - Changing Parameters, Manual Hooking=
SourceMM 1.2 now supports changing the parameters in a hook chain. For example, say the GameDLL has a function called IGameDLL::PrintString(const char *str). You can hook this, let it continue, but change the "str" parameter passed in to the rest of the hooks and the GameDLL. To do this, use the following macros:

*<tt>RETURN_META_NEWPARAMS</tt>
*<tt>RETURN_META_VALUE_NEWPARAMS</tt>

Example:
<cpp>
class ISomething
{
virtual void Function1(int num) =0;
virtual bool Function2(bool what, int hi) =0;
}

void MyHook1(int num)
{
//if num is 0,
// we will change the num parameter in the rest of the hooks, and the gamedll, to be 1.
if (num == 0)
RETURN_META_NEWPARAMS(MRES_IGNORED, &ISomething::Function1, (1))
RETURN_META(MRES_SUPERCEDE);
}

bool MyHook2(bool what, int hi)
{
//change the "what" and "hi" parameters to be false and 3 respectively
//also, return true, but specify that the value is ignored
RETURN_META_VALUE_NEWPARAMS(MRES_IGNORED, true, &ISomething::Function2, (false, 3));
}
</cpp>
SourceHook also supports manual hooking of functions. This means you must know the virtual table index, the virtual table offset (for polymorphism), and the "this" pointer offset. Luckily, the polymorphic offsets are usually zero. This type of hook is ideal when supporting different ABI, for example, across different gamedlls. The API is almost identical:

*<tt>SH_DECL_MANUALHOOKn[_void|_vafamt]</tt> -
**Declares the manual hook. A unique name must be given to each manual hook.
*<tt>SH_[ADD|REMOVE]_MANUALHOOK_[STATIC|MEM]FUNC</tt> -
**Adds or removes a static or member function hook on a manually declared hook.
*<tt>SH_MANUALHOOK_RECONFIGURE</tt> -
**Reconfigures the indexes and offsets of a manual hook.

An example is below, using the ISomething class from above.

<cpp>
SH_DECL_MANUALHOOK2(_M_Function1, 1, 0, 0, bool, bool, int);

void OnLoad(ISomething *pSomething)
{
//we reference the static function by its unique handle we gave it
//the parameters are otherwise the same - this pointer, hook handler, and post/non-post
SH_ADD_MANUALHOOK_STATICFUNC(_M_Function1, pSomething, MyHook1, false);
}

void OnUnload(ISomething *pSomething)
{
SH_REMOVE_MANUALHOOK_STATICFUNC(_M_Function1, pSomething, MyHook1, false);
}
</cpp>

For more examples of the above features, you can look in SourceHook CVS's [http://www.tcwonline.org/cgi-bin/viewcvs.cgi/sourcemm/sourcehook/test/ test suite], which demonstrates a variety of hooking scenarios.

[[Category:SourceHook]]
[[Category:Documentation (SourceMM)]]

Metamod:Source Development

2006-04-17T19:37:10Z

CyberMind: Reverted edit of Eldron, changed back to last version by Belsebub

Category:Translations

2006-04-04T21:21:18Z

CyberMind:

Translations of pages and related information.

Category:Russian

2006-04-04T21:20:53Z

CyberMind:

Russian translations of pages

Ru Alternative Language

2006-04-04T21:20:22Z

CyberMind:

[[Category:Translations]]
[[Category:Russian]]

Если вы хотите писать документацию на другом языке, отличном от Английского. Пожалуйста, начните отсюда. Любое содержимое на любом языке приветствуется.

Другие языки не обязаны быть '''зеркалом''' английской документации. Перевод всегда приветствуется, но и новое содержимое приветствуется тоже.

= Выбор языка =

Переключение осуществляется подставлением кода прификса языка.

* [[Alternative_Language|English]]
* [[ru:Alternative_Language|Russian]]

Быстрый и эффективный путь добавления переключателя нового языка это использование
<nowiki>{{LanguageSwitch}}</nowiki>
где-нибудь в темплейте. Рекомендуется вверху или в самом низу. Этот код добавит маленькое меню, которое выглядит как это:
{{LanguageSwitch}}

Когда новый язык добавлен в wiki, данный темплейт будет изменен автоматически. Таким образом, все страницы использующие его. Автоматически будут обновлены.

= Как перевести страницу =

1) Идите на ту страницу, которую хотите перевести.

2) Выберите править (вверху страницы) и добавьте переключатель языка наверху, если его еще нет.

3) Скопируйте весь текст темплейта страницы.

4) Сохраните (чтобы сохранился переключатель языка)

5) Теперь вверху страницы должен появиться переключатель языка, как на этой странице.

6) Выберите(нажмите) на язык, который вы хотите перевести.

7) Вставьте текст, который вы скопировали в текстовую область

8) Начинайте перевод. Затем как закончите нужно сохранить, что вы перевели.

Данные манипуляции дадут вам полную версию текущего документа на вашем языке. И вы можете переводить любую страницу, какую захотите.

'''Ресурсы:'''

* Список 2'х буквенных кодов языков можно посмотреть тут http://www.w3.org/WAI/ER/IG/ert/iso639.htm