[RSX]

This is a specification, made so that different scripts can handle things in a common yet simple way.
[Spec] is tag for specifications.

This specification will also available on sa-mp wiki.

General data :
Version : 0.1 Alpha
Status : Unaccepted
Target : Codes that are incorporated (Although it may be expanded)
Current developers : RSX
Current usage : <None>


1. Purpose and history
2. General description
3. Definition
4. Examples and defaults
5. Changes and suggestions

Purpose and history

There isn't much of history yet, but purpose is to define basic handling of common tasks in servers. Such as adding information to log or creating a connection between different parts of code.

General description

All codes in future should support certain functionality generally used and needed. Main functions are making logs, reporting errors and communication between scripts (for example, Anti Cheats and RP). The way it's intended is that there are a set of functions - given here, that every script should have. They would be made by script author and had some basic templates. Then, as they are always there, they would be the way of replacing basic output such as printf() and others, which would be controlled by the script author's made functions. So when there's a code, which for example has debug mode (for example - testing code) the code writer would be recommended to use controlled output. (Note that code writer and script author may or may not be the same person)

Definition

These functions are currently defined in these ways both in use and implantation. Where everyone who writes code for someone else should use this syntax and code base should contain it’s implantation.

Debug setting : #define DEBUG
This would inform that script is in debug mode, given that there's only one debug level (suggestions?

The log function : log(variable, comment[])
Or should it be : log(variable, logcode, comment[]) // Depends on which would be more suitable. But I'd say this one.
The purpose of this function is to send common data to server log, for example, a player enters a bank.

The report function : report(info[],description[])
This function is the simple way of giving some information to server (log), for example, reporting test results.

The warning function : warning(info[], reason[], description[], comment[])
Or should it be : warning(warning_code, reason[], description[], comment[])
For reporting warnings, their cause, information and comment, for example, warning server that a file doesn't exist. Description is meant for further data about the warning meaning. The point of splitting possibly one text into 4 pieces is simple - not all warnings are important, and it's up to script author to decide how to handle them (for example, excluding comments).

The error function : error(info[], reason[], description[], comment[])
Or should it be : error(code, reason[], description[], comment[])
Difference here is that warning should be used in cases, when something could be wrong, while error indicates that something has gone wrong. For example, file read error.

Examples and defaults
<When accepted, there will be templates for every function>

Simple way of writing the log function :

pawn Код:

stock log(variable, comment[])
{
    printf("LOG : %d || %s", variable, comment);
}

This function would simply output all log data, without any filters. (But it may need to have multiple tags for "variable")

Logging simple action data:

pawn Код:

OnPlayerConnect(playerid) {
    log(playerid,"Player connected");
}

Here this example calls the log function and informs in comment that the value indicates id of connected player.
Now in examples such as this, I consider that usage of different purpose log codes may be vital for meaning of this function.

Warning simple problems in script : (Please report any mistakes!)

pawn Код:

new pKick[MAX_PLAYERS][128];

OnPlayerDisconnect(playerid, reason) {
    if(reason==PLAYER_KICKED) {
        if(!strlen(pKick[playerid])  // Note that I use here one function and skip { }
          warning("Missing data","Player has left without known reason","Script has detected missing data, this may happen if code isn't incorporated correctly","Always specify reason for kicking players!");
        else {
          new str[128+sizeof("Disconnected: ")];
          format(str,150,"Disconnected: %s",pKick[playerid]);
          log(playerid,str);
        }
    }

Changes and suggestions
<No changes so far>