[dominik523]

y_groups

Introduction
What are groups? An admin level is a group of players, a gang is a group of players, a team is a group of players, a faction is group of players - why have different code for each of these things? y_groups is an abstraction of all of these things now supported by most of the YSI libraries to allow you to define exactly who can do what.

Download
This library is a part of YSI, which can be found here. Keep your eye on that topic and your server log for updates.

YSI Download Topic

Use
To demonstrate the use of the group system, this is an example of an admin "/ban" command:

Код:

#include <YSI\y_commands>
#include <YSI\y_groups>

new
	Group:g_grAdmin;

public OnGameModeInit()
{
	// Create the admin group.
	g_grAdmin = Group_Create("admins");
	new
		cmd = Command_GetID("ban");
	// Make normal people unable to use this command.
	Group_SetGlobalCommand(cmd, false);
	// Make admins allowed to use this command.
	Group_SetCommand(g_grAdmin, cmd, true);
}

public OnPlayerLogin(playerid)
{
	// Some sort of admin check.
	if (/* player is an admin */)
	{
		Group_SetPlayer(g_grAdmin, playerid, true);
	}
}

YCMD:ban(playerid, params[], help)
{
	if (help)
	{
		return SendClientMessage(playerid, 0xFF0000AA, "Bans a given player");
	}
	else
	{
		new
			pid;
		if (sscanf(params, "r", pid)) return SendClientMessage(playerid, 0xFF0000AA, "Usage: /ban <id/name>.");
		else if (pid == INVALID_PLAYER_ID) return SendClientMessage(playerid, 0xFF0000AA, "Invalid player to be banned.");
		else
		{
			Ban(pid);
			return SendClientMessage(playerid, 0xFF0000AA, "Player banned.");
		}
	}
}

Notice that there is no permission checking in the command at all - which makes it VERY easy to dynamically update who can and can't use the ban command. You may decide you want to let a normal user use it, in which case the following bit of code could be used:

Код:

Command_SetPlayerNamed("ban", playerid, true);

Players can be in multiple groups - if ANY of the groups they are in can use a feature, they can use a feature. There are plans to add an "exclude" option, so if a player is in a group who are banned from a feature then they can't use it, even if they are in another group which can. This could be useful for making people jailed - just make a "Jailed" group and exclude it from using everything, then people can be easily jailed without loosing all their other information.

Foreach
YSI groups are foreach compatible - just specify which group you would like to loop through the players of:

Код:

new Group:a = Group_Create("group");

Group_SetPlayer(a, 5, true);
Group_SetPlayer(a, 7, true);
Group_SetPlayer(a, 89, true);
Group_SetPlayer(a, 50, true);

foreach (Group(a), playerid)
{
    printf("%d", playerid);
}

That code will give an output of:

Код:

5
7
50
89

Global Group
The global group is the group of all players, and always exists. Everyone is always in the global group, you can't be removed at all, and by default the global group can do everything. If you create a new command, the global group can use it - you have to explicitly remove something from the global group, as shown in the example above.

If you know the old YSI system, this was called the "default" group, but I've had to change it to "global" or functions listed later would be called "SetDefaultDefault".

Distribution

This system uses the YSI master system, which means that if you create a group in one script, you can instantly use it from any other running YSI script. So your nice admin filterscript can define who are admins, and your gamemode can use that information in commands.

Functions

The functions provided by the group system are actually dynamic depending on what other YSI libraries you include. There are the basic functions and library specific functions. Note that if you do not include y_groups, the library specific functions will not exist, neither will they exist if you don't include the library with which they work.

• Core Functions
• Код:

  Group:Group_Create(name[]);

  Creates a group with the given name. By default groups can do nothing - you have to add functionality to them.
• Код:

  Group_SetPlayer(Group:group, player, bool:set);

  Either adds or removes a player from a group, depending on the value of "set" (true adds, false removes).
• Код:

  bool:Group_GetPlayer(Group:group, player);

  Returns true if a player is in the given group, false otherwise.
• Код:

  Group_SetName(Group:group, name[]);

  Sets the name of a group. Note that the name can be NULL:
  
  Код:

  Group_SetName(g_grAdmins, NULL);

• Код:

  Group_GetName(Group:group);

  Gets the name of a group.
  
  Note that there are a few other core functions not listed here because they are currently just an interface to incomplete functionality.
  
• Library Functions
  Every library defines a set of group functions*, for the list below replace "<...>" with the library prefix. The currently supported libraries are the "Command" and "Class" libraries.
• Код:

  Group_Set<...>(Group:group, element, bool:set);

  Either adds or removes an item from the specified group. Examples:
  
  Add a class to a group:
  Код:

  new
  	Group:g = Group_Create(NULL);
  
  Group_SetClass(g, gSomeClass, true);

  Remove the "/me" command from the global group:
  Код:

  Group_SetCommand(GROUP_GLOBAL, Command_GetID("me"), false);

  Note here that "GROUP_GLOBAL" (defined as "Group:-1") can be used in addition to the dedicated functions below.
  
• Код:

  Group_SetGlobal<...>(element, bool:set);

  Adds or removes something from the global group. Examples:
  Код:

  Group_SetGlobalClass(gSomeClass, true);
  Group_SetGlobalCommand(Command_GetID("me"), false);

• Код:

  Group_Set<...>Default(Group:group, bool:set);

  When you create a new element, for example a new command or a new class, they will normally be unuable by a group until you explicitly add it. This function changes the default so if the parameter is "true" people in a group can use any new items until they are explicitly removed.
  
  Note that using this function will reset all existing permissions for the current group.
• Код:

  Group_SetGlobal<...>Default(bool:set);

  By default the global group can use everything, and if new features are made it can use them too. This can be changed using this function.
  
  Note that using this function will reset all existing permissions for the global group.

Footnote

*These functions are defined automatically - look in "YSI\internal\y_groupsecond.inc" for the code if you're interested.

Note:
This thread was originally written by ******. I'm just reposting it here.