ASECO 2.x developer guidlines/suggestions

[Assembler Maniac]

ASECO 2.x plugin coding guidelines/suggestions

• use single-quotes for strings, unless the string needs to contain multiple
  single-quotes itself. The reason for this is that when PHP sees a
  double-quoted string, it searches for variable references within it ("text
  {$something->varhere} or $varhere") every time it encounters that string. By
  using single-quotes you avoid this parsing and speed up string handling.
• consistent indenting/braces. Please Use Tabs!!! Pick a style for new php
  files and stick with it in that file. If you're modifying someone elses code,
  try to use that style of indent/brace. It's incredibly difficult to be reading
  code and come to a block where it looks like this:

  Code: Select all

  if ($this->something)
  	{
  	// do something here
  	if ($somevar == 'whatever') {
  		// do something else here
  	}
  	}
  
  or when it looks like this
  
  if ($this->something) {
  	// do something here
  	if ($somevar == 'whatever')
  		{
  		// do something else here
  		}
  }

  It's difficult because there's two closing braces at the same level
  in the first example, and what looks like a missing one in the second. It can
  be hard to see, without reading and backtracking, if there's an accidental (or
  missing) brace in there.
• If you create a plugin, make sure you include a readme file with directions
  on using the plugin (plugin-name.readme.txt will work) in the aseco root
  directory, put any configuration files in the newinstall directory.
  Instructions should include things like what order plugins must appear in (for
  dedimania, it's important that plugin.checkpoints.php come before
  plugin.dedimania.php).
• Object vars don't have to be named with the plugin name at the beginning.
  They aren't global anymore, each plugin owns it's own vars. If the plugin is a
  conversion from somewhere else, it's understandable, but there's no need to
  create new ones that way too.
• When using $this->Aseco->getPlugin('whatever') method, set a $this->var for it in the init script if it's used more than a few times. One of the dedimania scripts had 47 instances of getPlugin('DediMania'). Each time it had to go get the object by calling the function. A plugin reference never gets stale because it's a static object. By assigning it once to a var, you avoid all the overhead of re-getting it each time. These types of changes can also reduce the risk of memory leaks.

Most of these are things I've seen many times in my wanderings through php code. I'm guilty of some of them too (although after I've gone through code a few dozen times, I usually manage to catch most of them).

If anyone is interested, I have a code formatting program built into the editor I use (Multi-Edit) that can be used to make everything at least look consistent. It re-formats all blocks (if while for function class) as well as things like how the = symbol is used (space before & after, no space at all). It can be run on an entire directory of files or just one at a time. It only takes a few mins to set up for each formatting type too. (only 2 major ones that I know of, brace on the same line, and brace indented on line following)

[edit]: removed block about using & for pass by ref in funcs after Xymph informed me that php does it that way as a standard now.

[edit2]: added getPlugin info

[Xymph]

[*]when creating functions that can take an object as a parameter, use the & character so the object is used by reference instead of a copy of it. By not using the &, you force PHP to try and decide if it would be better to make a copy of the object or not. This takes time several ways: trying to figure out if a copy should be made, making the copy, destroying it when the function is done. By using it as reference, php doesn't have to decide on whether or not to copy it, and it uses no extra memory for a copy of the data.

In my experience objects are always passed by reference into functions, and that's also explicitly written in the manual under the 'new' section:

When assigning an already created instance of a class to a new variable, the new variable will access the same instance as the object that was assigned. This behaviour is the same when passing instances to a function. A copy of an already created object can be made by cloning it.

And indeed it was necessary in XAseco to use clones in a few places when I modified an object within a function but needed the original object later in the calling code.

[Assembler Maniac]

[*]when creating functions that can take an object as a parameter, use the & character so the object is used by reference instead of a copy of it. By not using the &, you force PHP to try and decide if it would be better to make a copy of the object or not. This takes time several ways: trying to figure out if a copy should be made, making the copy, destroying it when the function is done. By using it as reference, php doesn't have to decide on whether or not to copy it, and it uses no extra memory for a copy of the data.

In my experience objects are always passed by reference into functions, and that's also explicitly written in the manual under the 'new' section:

When assigning an already created instance of a class to a new variable, the new variable will access the same instance as the object that was assigned. This behaviour is the same when passing instances to a function. A copy of an already created object can be made by cloning it.

And indeed it was necessary in XAseco to use clones in a few places when I modified an object within a function but needed the original object later in the calling code.

Long time since I read the php manual. There's been a lot of changes. Last I knew it would try to decide based on how it was used in the function and clone/ref based on that. Thanks.

[w1lla]

Maybe a suggestion on how to check if an admin is in the certified group in admingroups.xml

It used to be:

Code: Select all

	if($this->Aseco->isAdmin($player, 'ADMINS')) {
		$level = '$390Admin $fff';
	} elseif($this->Aseco->isAdmin($player, 'SUPERADMIN')) {
		$level = '$390MasterAdmin $fff';
	} elseif($this->Aseco->isAdmin($player, 'OP')) {
		$level = '$390Operator $fff';
	} else {
		$level = '$39fPlayer $fff';
	}

How will it be...?

[Assembler Maniac]

Maybe a suggestion on how to check if an admin is in the certified group in admingroups.xml

It used to be:

Code: Select all

	if($this->Aseco->isAdmin($player, 'ADMINS')) {
		$level = '$390Admin $fff';
	} elseif($this->Aseco->isAdmin($player, 'SUPERADMIN')) {
		$level = '$390MasterAdmin $fff';
	} elseif($this->Aseco->isAdmin($player, 'OP')) {
		$level = '$390Operator $fff';
	} else {
		$level = '$39fPlayer $fff';
	}

How will it be...?

It has never worked like that in ASECO 2.x. You shouldn't be checking to see if an admin is in a particular group. Those group names can be changed by the admin, and aren't hardcoded anywhere. The whole grouping concept is that any given group can have specific abilities, and you need only check to see if a given authitem is true/false. Creating a new group is pretty easy. Just copy the authitem list and put it into a new group, then add logins. The whole system was designed for maximum flexibility so the admin isn't stuck with just a few groups. They can easily add as many as they want.

If I make it so you can name the group with a tag in admingroups.xml and add a function to get the tag for the group the player is a member of, would that work for you?

Code: Select all

function getAdminTag($player) {
	$login = $player->login;

	if (count($this->admin_groups)) {
		$login = strtoupper($login);
		$group = strtoupper($this->admin_groups['SETTINGS']['TMLOGINS'][0][$login][0]);
		if ( $group == '' || !isset($group) ) {
			return 'Player';
		}

		$group_tag = $this->admin_groups['SETTINGS']['GROUPS'][0][$group][0]['GROUP_TAG'][0];

		if (!isset($group_tag)) {// if it's not set in a particular group, supply a default one
			switch($group) {
				case 'SUPERADMIN' :
					$group_tag = 'SuperAdmin';
					break;

				case 'ADMINS' :
					$group_tag = 'Admin';
					break;

				case 'OP' :
					$group_tag = 'Operator';
					break;

				case 'JROP' :
					$group_tag = 'Jr. Operator';
					break;

				default :
					$group_tag = 'Player';
					break;
			}
		}

		return $group_tag;
	} else {
		for ($i = 0; $i < count($this->admin_list['TMLOGIN']); $i++) {
			if ($this->admin_list['TMLOGIN'][$i] == $login) {
				return 'MasterAdmin';
			}
		}
	}
	return 'Player';
}

If there's no tag found for a group, it'll default to the group name (all upper, or maybe I'll hard code some basic names for the existing groups that it's installed with). If the player isn't in a group, it'll default to 'Player'.

[w1lla]

well i think then alot of plugins need to rewritten as

Code: Select all

$this->Aseco->isAdmin($player_item))  {

does not work properly for example the plugin.playerjoin.php.

It does not show the admin.

viewtopic.php?f=124&t=15462

[nocturne]

well i think then alot of plugins need to rewritten as

Code: Select all

$this->Aseco->isAdmin($player_item))  {

does not work properly for example the plugin.playerjoin.php.

It does not show the admin.

viewtopic.php?f=124&t=15462

As mentioned in the other thread, without an authitem it uses 'AdminSuper.' If the admin doesn't have that authitem, it returns a false. Easy fix, just add a generic 'Admin' authitem to all your groups, then use that in the check. AM has already mentioned that he is adding an isAnyAdmin to accomplish this, though..

[w1lla]

Its fixed.

Through lan you also need to add the ip of the one joining.

Cant aseco be dealt with only login? and not based on lan ip.

[Assembler Maniac]

Ok, let me clear up some things.

The isAdmin function changed in ASECO 2.2.1 (never officially released). The reason for it is simple: rather than keep looking up a player item with every admin check, the whole player item is sent to isAdmin instead.

As far as sample code goes, nothing has been released yet, so there will still be some things to clean up. ASECO 2.2.2 and above will require the TMServer to be the current one or newer. There's too many differences in ASECO now to be able to use old & new servers. I'm trying to make sure people that have current plugins out have the chance to adjust them to the new features/events.

Admin groups: you do NOT use the group name for anything inside of the running ASECO. The names are there so the operator can assign rights to players as a group. It's very similar to an SQL server, or Windows Domain. You grant a group a set of privileges, then when a person logs into the game, they get their authorizations as set in the group. You wouldn't write code to that says "is $user in PrinterAdmin group" when you want to find out if they can change a printer driver, you write it so it says "is $user allowed to AlterPrinterSettings" and let the system tell you yes/no.

Proper call for checking to see if someone has admin ability for a feature (providing that authitem isn't a part of the addChatCommand):
if(isAdmin($player, 'PassCancelVote')) // code follows

LAN based logins: I'll have to check to see the format of the login again. Been a while since I looked at it, but from what I remember, there's absolutely no checking when you play a LAN game and you can set your login to be anything. However, since LAN play is usually among friends, or small groups of people, I'll see if I can strip out the IP stuff and just use the login.

[afisse]

hi all

where can i find documentation of Aseco
i need to know the Aseco class, and all the methods of it
now i know registerEvent, addChatCommand, but it's not enough

Thanks a lot

Galaad