User Tools

Site Tools


dev:plugin:start

eXpansion plugin pack uses a slightly modified structure of Plugin then the default one(\ManiaLive\PluginHandler\Plugin). We did this in order to centralize some of the functionality needed in many plugins.

Basic Exemple

namespace ManiaLivePlugins\eXpansion\test;
 
class test extends \ManiaLivePlugins\eXpansion\Core\types\ExpPlugin {
 
    function exp_onInit() {
         //Do Stuff
    }
 
    function exp_onLoad() {
         //Do Stuff
    }
 
    function exp_onReady() {
         //Do Stuff
    }
}

As seen the default onInit, onLoad and onReady methods have been replaced by exp_onInit, exp_onLoad and exp_onReady. This 3 are called at the same time as the orginal ones, they just might not be called if some conditions

Features

Centralize Chat

We do this to allow 2 things. Parsing Text to allow color changes to be made easy and to Redirect the chat. This means, that when sending chat to the server chat you should use the methods we created dedicated to do that. Messages send to the server has been separated in 2 groups, a normal message and an announcement. This allows the redirection to be made separately for both of them, but changes nothing of how to use the chat output.

Out Put Chat

Instead of using

$this->connection->chatSendServerMessage("My message", $login);

To send a message you will need to use

$this->exp_chatSendServerMessage("My message", $login);

The 2 calls are bassically identical, if you use $login=null the message will be sent to all players.

Optimization for i18n Chat

The Basic plugin also supports multiple languages. If you send your message as explained earlier it will work but won't be optimized. eXpansion pack will search for a translation of your text, and that is an operation that is a bit heavy. Ideally the search for the translated text should be done only once.

To do this we will initialise the messages on Init.

private $msg_needBeAdmin;
public function exp_onLoad() {
        $this->msg_needBeAdmin = exp_getMessage('#admin_error#You need to be an Admin to use that command');
        //More stuff
}

The exp_getMessage will return a object containing all the translation in any language of that text. To send this message to a player you just need to do :

$this->exp_chatSendServerMessage($this->msg_needBeAdmin , $login);

This way finding the text in the correct language will be nearly 10 times faster.

Chat Coloring

One of the features added is the coloring of text using the Aseco like codes. The default configuration can be found in the ManiaLivePlugins\eXpansion\Core\Config file. All variables name for colors are prefixed with the Color_. For exemple this code :

	public $Colors_admin_error = '$f44';

allows you to transform this message :

$this->exp_chatSendServerMessage("#admin_error#There was an error", $login);

into the equivalent of

$this->exp_chatSendServerMessage("$f44There was an error", $login);

If you plugin needs a color code you should add it to the default config file. But if you are building an external plugin(Not part of eXpansion) and would like to use this feature you still can. you need to register your color code to the Color parser. You can do that quite easily :

$colorParser = ManiaLivePlugins\eXpansion\Core\ColorParser::getInstance();
 
$colorParser->registerCode('my_code','$FFF');

Of course this technique will also work with the i18n optimisation technique. They should be used together !

ReConfigure the Default Colors

Information Here : Core plugin configuration

Value replacement

In some cases you may wan't to put variable values in your chat. You can of course do :

$this->exp_chatSendServerMessage("Value : ".$value, $login);

But you will lose compatibility with i18n. To get around this you may use a sprintf integrated to the chat

$this->exp_chatSendServerMessage("Value : %1$s", $login, array($value);

Once more this technique is compatible with the i18n; we recommend that you use the optimized way along this to send chat's.

More about i18n

You can also use the i18n support in windows and buttons. You can find more information about it here : Core Multiple Language Support

Chat Routing

As explained earlier the chat is separated in 2, normal message and announcement you can redirect any of the 2 chats of any eXpansion plugin. To do so you need to call one of the 2 methods.

You can call this method to redirect the normal message

public function exp_activateChatRedirect(array($object, $fun));

or

public function exp_activateAnnounceRedirect(array($object, $fun));

To redirect all announcements

to recover the normal message you need a method like this one

function chat($message, $login);

to recover the nannouncement you need a method that dosen't take a login

function chat($message);

Exemple Code

namespace ManiaLivePlugins\eXpansion\test;
 
class test extends \ManiaLivePlugins\eXpansion\Core\types\ExpPlugin {
    public function exp_onReady() {		
		/**
		 * Redirecting The Announcements of the Admin Groups plugin
		 */
		$this->callPublicMethod('eXpansion\\Chat_Admin', 'exp_activateAnnounceRedirect', array($this, 'announce'));
		$this->callPublicMethod('eXpansion\\Chat_Admin', 'exp_activateChatRedirect', array($this, 'chat'));
 
    }
 
    public function announce($message) {
       //Do stuff
    }
 
	public function chat($message, $login) {
       //Do stuff
    }
}

As you can see every plugin needs to be redirected separately, you don't redirect all of the chats at once.

Do not forget to unregister your plugin if your plugin is unloaded :

$this->callPublicMethod('eXpansion\\Chat_Admin', 'exp_deactivateAnnounceRedirect');
$this->callPublicMethod('eXpansion\\Chat_Admin', 'exp_deactivateChatRedirect');

Game Mode Compatibility Checking

Another feature is the ability to define the Game modes for which you plugin is compatible. If it isn't compatible the plugin will be automatically unloaded. If the game mode changes then the unloaded plugins will be checked again if they are compatible with the new game mode they will be loaded. Of course if any loaded plugin isn't compatible with the new game mode it will be unloaded.

To have your plugin loaded and unloaded automatically you just need to specify the game modes your plugin is compatible with at the initialization. If you don't specify a compatibility your plugin will be considered as compatible with all GameModes

function exp_onInit() {
	$this->exp_addGameModeCompability(\DedicatedApi\Structures\GameInfos::GAMEMODE_ROUNDS);
	$this->exp_addGameModeCompability(\DedicatedApi\Structures\GameInfos::GAMEMODE_TIMEATTACK);
	$this->exp_addGameModeCompability(\DedicatedApi\Structures\GameInfos::GAMEMODE_TEAM);
	$this->exp_addGameModeCompability(\DedicatedApi\Structures\GameInfos::GAMEMODE_CUP);
}

This plugin is compatile with round mode, time attack … but not laps mode or any script mode

YOu can also specify scripts for which you plugin is copatible

function exp_onInit() {
	$this->exp_addGameModeCompability(\DedicatedApi\Structures\GameInfos::SCRIPT, "stunt.txt");
}

Game Compatibility Checking

Since ManiaLive is a controller for ShootMania as well as TrackMania we may have plugins working on 1 game and not another. It is important not to allow plugins incompatible with a game to load. / TODO /

dev/plugin/start.txt · Last modified: 2013/07/17 10:08 (external edit)