ExstoCreateAPlug

From GMod Wiki

This page has been nominated for deletion. Deletion is due within approximately 30 days from nomination, unless the deletion has been disputed on the talk page. See more pages nominated for deletion here. Reason for deletion: Not what Garry wants the wiki to be used for Last Edit was made on 11/16/2011

Contents 1 Introduction 1.1 How Exsto Manages Plugins 2 Getting Started 3 Customizing the Plugin

Introduction

This segment of the wiki will teach you (the reader?) about how to create a fully functional plugin for Exsto Core. You don't exactly have to read the ENTIRE wiki page, as it will cover everything in the Exsto API. On that note, lets explain a little bit about how Exsto manages plugins. (as of Rev100)

How Exsto Manages Plugins

To sum it up:

 1. Exsto reads the exsto/plugins folder and includes and AddCSLuaFile's the plugins based on prefix (sv_, cl_, sh_) respectively.
 2. Exsto executes that file normally like any other thing using include or AddCSLuaFile will do. (The plugin HAS to be coded a certain way though.  More on that below.)
 3. The plugin's Init function is called, and all the plugin's hooks get set up and are called.

Exsto also supports dynamic loading and unloading of plugins. However, this system only works with support from the plugin developers. Plugins need to be coded in mind that Exsto can and will attempt to unload them, so plugins need to be ready to proceed with an unloading sequence when asked. Otherwise, the plugin will not properly unload itself. (As in, it will still be running)

Getting Started

Due to Exsto's requirements with unloading and loading, it requires a set specific style of coding used in each plugin. Here I will show you the specifics of getting started.

First off, we want to create a plugin in the Exsto plugin directory. Lets start by naming the file 'sh_funstuff.lua'. Then, copy and paste the following into the file's contents. This code is the basic code you want in all of the plugins you create.

 
local PLUGIN = exsto.CreatePlugin()
	PLUGIN:SetInfo( {
		Name = "Documentary Plugin";
		ID = "doc_plug";
		Desc = "A plugin that shows of Exsto's API.  Also used as documentation.";
		Owner = "Prefanatic";
	} )
 
function PLUGIN:Init()
end
 
PLUGIN:Register()
 

If you think that looks overwhelming, I'm going to spend time bit by bit explaining what each function does. If you do not need an explanation, move down to "Customizing the Plugin".

To start our little tour of this header and footer plugin, lets first take a look at line 1.

 
local PLUGIN = exsto.CreatePlugin()
 

That line is defining our plugin object from Exsto. Exsto creates a metatable object that already contains predefined functions for communication with Exsto Core. The defined plugin object can now be accessed with PLUGIN.

 
PLUGIN:SetInfo( {
	Name = "Documentary Plugin";
	ID = "doc_plug";
	Desc = "A plugin that shows of Exsto's API.  Also used as documentation.";
	Owner = "Prefanatic";
} )
 

That selection of code dictates plugin information. It only requires one argument, which is a table filled with statistics like Name, ID, Desc, and Owner. Failure to run this function from the plugin results in a crippled and potentially unwanted plugin. Please follow suite and run this. To describe what each variable does, heres a little bulleted list for you.

 * Name --> The display name of the plugin.
 * ID --> An all lowercase, no space ID for the plugin to be stored as.
 * Desc --> The description of the plugin.  What does it do?
 * Owner --> Who made this sexy thing?

 
function PLUGIN:Init()
end
 

Pretty self explanatory. All of your code that you want to initialize with goes here. That hook is called when the plugin is activated by Exsto. NOT when the script is loaded. Anything on the outside of this function will be run anyways, making the plugin dirty and cause potential issues with the reload system.

 
PLUGIN:Register()
 

Registers the plugin with Exsto. Failure to do this results in improper loading of the plugin. It will also cause issues with Exsto Cloud.

Load up Exsto and check the console. You should see an awesome message print about loading the plugin. If not, you either placed it in the wrong place, or you never registered the plugin properly. If it did register, pat yourself on the back. You just learned a part of Exsto Core!

Customizing the Plugin

Now that we have successfully created a working plugin, we want to add some awesome functions to it. Lets use the internal hook system to print a message to the client when they join. To do that however, we need knowledge of plugin hooks, and the Exsto print functions. Lets start with this basic function hook.

 
function PLUGIN:PlayerInitialSpawn( ply )
	print( ply:Nick() .. " has joined through the Exsto hooks!" )
end
 

No need to use hook.Add with Exsto. This method that is provided with the function hook names allow for a clean unload and reload. With this, every time a player joins the game, it will print that little string we have created. Lets bump this up a bit and use the Exsto printing functions.

 
function PLUGIN:PlayerInitialSpawn( ply )
	exsto.Print( exsto_CLIENT, ply, "You have joined the server!" )
end
 

Using the exsto.Print function, we can call a multitude of printing styles to various people. In this case, we have decided to use the method 'exsto_CLIENT' on 'ply', with the message 'You have joined the server!'. The exsto_CLIENT method dictates that that message will be send to the object selected, and be printed on their client. Lets try something a bit more challenging.

 
function PLUGIN:PlayerInitialSpawn( ply )
	exsto.Print( exsto_CHAT, ply, COLOR.NAME, "You ", COLOR.NORM, "have joined the server!" )
end
 

In that method, exsto_CHAT, we are sending a chat message to the ply object, with the proceeding data. exsto_CHAT reads from left to right in order of what to display first to the chat box. As such, we start with COLOR.NAME, which is the redish color you see in exsto commands. Anything following that color will be that color. We then proceed with "You ", followed by COLOR.NORM, which is a white color. Everything proceeding COLOR.NORM is white. Now, what if we want EVERYONE to know the player has joined the game?

 
function PLUGIN:PlayerInitialSpawn( ply )
	exsto.Print( exsto_CHAT_ALL, COLOR.NAME, ply:Nick(), COLOR.NORM, "has joined the server!" )
end
 

Quite simple, almost the same as the other method. We just used exsto_CHAT_ALL instead of exsto_CHAT, and we removed the ply object, as it is not required anymore. One last thing to toy around with the print system. There are also functions that act like normal player object functions.

 
function PLUGIN:PlayerInitialSpawn( ply )
	ply:Print( exsto_CHAT, COLOR.NAME, ply:Nick(), COLOR.NORM, "has joined the server!" )
end
 

That method performs exactly the same thing as the exsto.Print exsto_CHAT method; it is just a different coding style. You may use whatever you prefer, depending on personal tastes.

That should be it for this little snipit of plugin development. Here is the full file that we have so far;

 
local PLUGIN = exsto.CreatePlugin()
	PLUGIN:SetInfo( {
		Name = "Documentary Plugin";
		ID = "doc_plug";
		Desc = "A plugin that shows of Exsto's API.  Also used as documentation.";
		Owner = "Prefanatic";
	} )
 
function PLUGIN:Init()
end
 
function PLUGIN:PlayerInitialSpawn( ply )
	--exsto.Print( exsto_CLIENT, ply, "You have joined the server!" )
	--exsto.Print( exsto_CHAT, ply, COLOR.NAME, "You ", COLOR.NORM, "have joined the server!" )
	--exsto.Print( exsto_CHAT_ALL, COLOR.NAME, ply:Nick(), COLOR.NORM, "has joined the server!" )
	ply:Print( exsto_CHAT, COLOR.NAME, ply:Nick(), COLOR.NORM, "has joined the server!" )
end
 
PLUGIN:Register()