Pge Module Creating A guide to help you develop your own modules for PGE

[8ennett 0]

So this tutorial is designed for people who want to start creating their own modules for the Praetorian Game Engine. It assumes you have a basic knowledge of PHP, MySQL, HTML and CSS.

 

PGE isn't just about using the engine to create yourself a game limited by the modules that are available for you to download from the project site, but about giving you a platform to easily develop your own additions to your game easily and professionally and with little effort.

 

This tutorial will cover the following concepts:

Directory Structure

Module Setup

Main and admin page

Database management

Available config variables

Error and information messages

Styles and layout

Custom cron jobs

Available classes and functions

There are two different types of module for PGE. The first are referred to as modules. These are additions which once installed will be displayed on the left hand main menu of PGE. The second type are referred to as addons. The addons actually install to a module directory named Downtown (although users can rename the menu item) and is a sub-catalogue of other modules. This makes things easier as Modules are designed for main operations in PGE such as the home page, player profiles and the support system and addons are designed for more mass listings in the Downtown section. If all addons and modules were displayed on the main menu then it would become pretty long and ruin the look and feel of your game. Choosing wether you should make your new module a Module or Addon is the first thing you should do. Just remember that Addons cannot be accessed when a player is in hospital or prison.

 

There isn't much different when developing modules and addons, the setup files, directory structures, icons and so on are all identical. All you need to remember is when developing a module the directory it is contained in will be modules/mymodule and with addons it is modules/downtown/addons/myaddon.

 

For the purpose of this tutorial we will assume you are developing a module.

 

Directory Structure

 

Directory structure is very important in module development as PGE looks for specific files when installing and running your module. In your local copy of PGE, go to the root directory then to modules/ and create a new folder. Now the name of this folder is going to be your modules system name so try to make it unique otherwise it may conflict with a different modules system name which would mean you could only install one or the other. Maybe think of a prefix for your module names such as codeteam_mymodule. Also be sure to make your folder name all lowercase to prevent confusion.

 

So lets say you have created the directory modules/abc_bank.

 

It's important to add here, if you are creating an addon instead of a module then you will need to create a 15x15 gif image named icon.gif (modules/downtown/addons/abc_bank/icon.gif) and this icon will be displayed next to your addons name in the Downtown module. If you are making a module then you don't need to create this icon.

 

Module Setup

 

Create the new php file 'modules/abc_bank/setup.php'. This file contains all the setup information and general PGE config for your module and is included in every instance of your module when playing the game. The setup is simply a list of variables with their appropriate values. Some of these variables are required and others are optional.

 

Required Variables

$modulename = The name displayed on the module installation screen

$moduleversion = The version number of your module (text string)

$moduleauthor = Your name or your development teams name

$modulewebsite = Your website address

$moduledescr = A brief description of your module

$menuname = This is the default name of the main left menu item or downtown item if an addon

$menupermissions = Default module permissions, possible values are Super, Admin, Mod, User (use no spaces, eg. SuperAdminModUser)

 

Optional Variables

$viewinprison = Only set this if you want your module to be loadable even when the player is in prison (not available for addons)

$viewinhospital = Same as above except applies when in hospital instead of prison

 

There are other variables that can be put in here which will be covered later in the tutorial.

 

It is also important to remember that your setup.php variables must be contained within an if statement that tests if the variable $setupinclude is set. This variable is set just before this setup file is included in PGE and is a means of preventing the setup page from being accessed directly (by typing http://forums.xisto.com/no_longer_exists/) instead of being included. Since this page really only contains variables then it's not so important but it's good to get in to the habit, especially with your main and admin pages.

 

So here is an example setup.php file which we will use for our bank module.

 

<?php if (isset($setupinclude)){ $modulename = "PGE Bank"; $moduleversion = "1.0"; $moduleauthor = "Martyn Bennett"; $modulewebsite = "http://drug-mann.com;; $moduledescr = "A bank where a player can deposit and withdraw their money to keep it from getting mugged.";  $installq[0] = "ALTER TABLE `".$configprefix."userlist` ADD `bank` INT( 20 ) NOT NULL DEFAULT '0'";  $uninstallq[0] = "UPDATE ".$configprefix."userlist SET money=money+bank"; $uninstallq[1] = "ALTER TABLE `".$configprefix."userlist` DROP `bank`";  $menuname = "Bank"; $menupermissions = "SuperAdminModUser"; $viewinprison = true; $viewinhospital = true; } ?>

As you can see this is our bank setup file and can be view whilst in both hospital and prison, default permissions are for everyone and the menu name is just Bank. Also notice the install query and the uninstall queries. When installing the module we add an extra field to the USERLIST table called bank where players can deposit their money, and when uninstalling first we put all the money in the bank back in to the players hand first, then we remove the bank field from the table. Also notice the [0] and [1] increment. You could alternatively use the php array() function to set your $uninstallq variable like so:

 

$uninstallq = array(0=>"UPDATE ".$configprefix."userlist SET money=money+bank", 1=>"ALTER TABLE `".$configprefix."userlist` DROP `bank`");

Either way is fine, as long as PGE can loop through the array to execute each query. You may have notice the variable $configprefix in the queries there as well just before the userlist table name. That will be explained to you later in the databases section.

 

Main And Admin Pages

 

Now you have your setup file you are ready to start creating your module. In the abc_bank directory create another new file and name it abc_bank.php. When searching the directories for each module to load PGE will look for a file with the EXACT same name as the directory it's in. It won't work if you put in an index.php file or such like, so make sure it is the same as the directory name. Next inside your new abc_bank.php file you will need to include the following php code just like with the setup file:

 

<?php if (isset($homeinclude)){ // Your module goes here } ?>

The $homeinclude variable ensures that it is PGE accessing the php page instead of someone just typing in to their browser http://forums.xisto.com/no_longer_exists/. Be sure that all your module content is contained within this IF statement, and if you create other php files in your module and include them in your abc_bank.php file then use the same system to ensure they are not being accessed outside of PGE. This is also the reason why it is essential that GLOBAL VARIABLES are turned off in your php.ini file before you can install PGE.

 

If you want your module to include an admin panel where game admins can change certain aspects of your module then you will need to create two new directories and a couple of files. First create a directory (in your abc_bank directory) named images (again, all lowercase) then inside that create an image named admin.png. This is going to be the icon displayed on the PGE module admin tab, it can be any dimensions as PGE automatically resizes it. You don't need to create this icon, however it creates a sense of individuality between modules. Next, in the abc_bank directory again create a new folder name admin and in that create a php file named admin.php (so modules/abc_bank/admin/admin.php). Remember to enclose the contents of this module inan IF statement the same as with the abc_bank.php file.

 

Now you have the template for creating your module and it is now installable and uninstallable. Give it a go by going in to the addons and modules section of the admin panel and clicking install on the list of uninstalled modules.

 

Database Management

 

The key thing to remember when running your queries is that the database connection is already open and so there is no need to run mysql_connect(), mysql_select_db() mysql_close() as this is all done for you. Running mysql queries is simply a matter of putting in mysql_query(). If you do enter any of these functions that have already been run then it could cause problems in PGE.

 

There is another important thing you need to know about running mysql queries. When typing in your query and declaring the table name, you MUST insert the config variable named $configprefix. This is a PGE config variable (covered in the next section) and it is for people who require a table prefix for their databases. So the table name is userlist however the web host requires all table names have a prefix of myname_, the table userlist then becomes myname_userlist. The PGE admin should have configured the table prefix before hand in PGE so the prefix myname_ is stored in the variable $configprefix. So instead of running the following query:

 

mysql_query("SELECT id FROM userlist WHERE name='8ennett'");

You would instead run this query:

 

mysql_query("SELECT id FROM ".$configprefix."userlist WHERE name='8ennett'");

Which translates into "SELECT id FROM myname_userlist WHERE name='8ennett'". If you fail to insert the $configprefix variable before your table names then on copies of PGE that require a table prefix the query will fail, resulting in your module not being fully compatible with a large portion of PGE installations.

 

Available Config Variables

 

So all the standard config variables are available to your modules without needing to call them. You must also remember that these are reserved variables so writing new values in to them in your module can seriously mess up PGE. On top of the config variables being avaiailble, the entire contents of the USERLIST table for the current player is stored as an array in $_SESSION['user']. So if you want to access the current players money it is stored in $_SESSION['user']['money'], or the current players name then $_SESSION['user']['name'] and so on. Here is a list of the config variables:

 

$confighost = Database host

$configuser = Database username

$configpass = Database password

$configdb = Database name

$configprefix = Table prefix

$configport = Database port

 

$configenginerelease = The current release version of PGE

$configsitename = Your sites name

$configsiteaddress = The base address of your site

$configsiteadminemail = Main admins email address

$configsitecopyright = Who owns the copyright on the site

$configsitestyle = The current style of the site

$configsitecharset = The character set for all text

$configsiteerrorbox = The error box used to display messages

$configsiteerrorboxtimeout = The amount of time an error box is displayed for in seconds

 

$configsitewhoseonline = How long a player is inactive in seconds before being classed as OFFLINE

$configsitedisable = How long in seconds a players account is disabled if they enter the wrong pass $configsitedisableamount times

$configsitewrongimage = How many times a player gets the anti-spam question wrong before they are logged out

$configsitedisableamount = How many incorrect logins before the account is disabled

$configshowimage = The odds a player is taken back to the anti-spam question

$configavatarsize = The max size of a players avatar file in bytes

$configsiteleveluphp = The amount of hpmax a player receives when levelling up

$configsitelevelupen = Same as above but with energy, enmax

$configsitelevelupst = Same again but with stamina, stmax

$configsitelevelupxp = The multiplier for next xp goal

 

$configsmtp = The method used to send emails

$configsmtpserver = The SMTP server used to send emails

$configsmtpport = The SMTP Port

$configsmtpusername = If SMTP server requires SSL validation this is the username

$configsmtppassword = Same as above but the password

$configmailphploc = The location of the PEAR Mail.php file

$configmailvalid = The email sent out to validate an account

$configmailpass = The email sent out for a lost password

$configsiteintro = The introduction text displayed on the index page of the site

$configsiteregoff = The BBCode message displayed on the index page when new registrations are turned off

$configsiteservoff = The BBCode message displayed when the server is turned off

 

Error and information messages

 

You may have noticed the messages that pop up in a time-delayed box on the screen when using PGE. These error boxes are very easy to set and use BBCode so you can stylise your messages and include images as well if you like. To display a message simply set the variable $error with your message, that's it. PGE will then convert that string in to an message box alert using the default errorbox. So if you want to set an error alert and set the text to red you would use the following code:

 

$error = '[colour=#FF0000]You have entered an invalid number[/colour]';

This will then display an errorbox alert with your message in red text in it.

 

Styles and layout

 

Adhering to the styles layout is important, because if someone decides to change their site style to a different one you want your module to change with it right? It would probably be best if you went through one of the existing PGE modules to get a fuller idea of the styles you can use for different html elements and have a look through the default stylesheet too. I'll outline some key styles here for you now on constructing a basic framework to display your module in.

 

To create the main container for your window it is simply a table with two cells, the table being given a class name of "moduletable", the first cell (and first row) is "moduletablehead" and the second cell (and second row) is "modulerow". Here is the example code:

 

<table cellpadding="0" cellspacing="0" class="moduletable">   <tr>	 <td class="moduletablehead">Bank</td>   </tr>   <tr>	 <td class="modulerow">Module content goes here</td>   </tr> </table>

So you can see that in the first cell is where you put the header for your module and the second is where the rest of the module content goes to. Remember also about the limitations of width. The width of free space inside your module container is at maximum 570px-580px. Anything wider than this will begin disfiguring the layout of PGE.

 

Custom cron jobs

 

PGE has four seperate cron jobs to work with, one that runs every five minutes (try to avoid using this as it can start to bog down the server the more players there are), one that runs every hour on the hour, one that runs daily and one that runs weekly (the server is taken offline during these last two as they are usually the heaviest on the database and need to adjust players stats all at once without giving anyone an advantage). There are two seperate methods for adding your own cron job/s to PGE.

 

The first is very simple and similar to queries that run when installing and uninstalling modules. Create a new array in your setup.php file and name the variable either $cronfive[0], $cronhour[0], $cronday[0] or $cronweek[0] depending on how often you want the query to run. So example code:

 

$cronday[0] = "UPDATE ".$configprefix."userlist SET bank=bank+(bank*0.02) WHERE bank>0";

Now this statement runs once a day and adds 2% interest to everyones bank account where players actually have money in the bank.

 

Now this method is only for running standard mysql queries. Sometimes you need to add a bit more and run certain tests, check variables and so on which requires php to achieve so this is incorporated in the second method.

 

To run a php script that contains all the data you need for your cron create a new file in your modules/abc_bank/ directory named either cronfive.php, cronhour.php, cronday.php or cronweek.php and PGE will call this php script when it is time to run the cron. To prevent unauthorised running of the cron as with the admin and main pages, contain all the php in the script in an IF statement like so:

 

<?php if (isset($runcustomcron)){   // Cron php goes here } ?>

Available classes and functions

 

I'm not going to run through the entire list of available functions, that will be available in the PGE Developers Handbook once it has been written. I'll outline a couple of important functions which will give your module a more integrated feel with PGE.

 

userName($userid);

$userid is the id of whatever players name you want to display. Try to avoid echoing $_SESSION['user']['name'] and instead use this function. It displays the users name, makes the name a hyperlink to their account and the title of the anchor is the players account type (Admin, Moderator, User) and is displayed when you mouse over the link.

 

getProfileImage($userid);

Returns the file path of a players avatar image and returns the path to the nopic.png image if the player hasn't uploaded an avatar. Use in the src="" in a <img> html tag like '<img src="<?php echo getProfileImage($_SESSION['user']['id']); ?>" />'.

 

getNPCImage($npcid)

The same as the above function however input the NPC's id instead and it will return the NPC's image.

 

resizeImage($originalImage, $return, $toWidth, $toHeight)

This function is used to scale down images so they do not disfigure your modules. $originalImage is the link to where the original image is. $return has a value of either width or height and returns the scaled down value of the $return. $toWidth is the maximum width of the scaled image and $toHeight is the same but with height. This feature is commonly used with the getProfileImage() and getNPCImage() functions like so:

 

<img src="<?php echo getProfileImage($_SESSION['user']['id']); ?>" title="<?php echo $_SESSION['user']['name']; ?>" width="<?php echo resizeImage(getProfileImage($_SESSION['user']['id']), 'width', 150, 150); ?>" height="<?php echo resizeImage(getProfileImage($_SESSION['user']['id']), 'height', 150, 150); ?>" border="0"/>

BBCode($str);

Formats $str and replaces all BBCode tags (eg. [colour=#FF0000]Error[/colour]) with html tags that give the effect of the BBCode. You will need to echo this function as it only returns the string, it doesn't echo it.

 

checkUserTransfer($id1, $id2, $alert, $type);

You may offer players the ability to transfer items and cash between each other. This function should be run to when ever a player tries to initiate a transfer between account. It first checks to see if the players have the same IP, if they do the function returns a false value and inputs a new case in the admin/mod case list outlining what type of transfer. If the players have the same IP AND have identical passwords it probably means they are one and the same person with multiple accounts and both accounts are automatically disabled and the function still returns a false value. If everything is fine then this function returns a true value. $id1 is the userid of the player initiating the transfer. $id2 is the player $id1 is trying to send to. $alert is the BBCode friendly alert message input in the admin/mod case file and $type is the name of the alert type ('Money Transfer', 'Item Transfer' etc.). Here is an example of its use:

 

if (checkUserTransfer($_SESSION['user']['id'], $otherplayer['id'], '[user]'.$_SESSION['user']['id'].'[/user] tried to send   .number_format($moneytosend).' to [user]'.$otherplayer['id'].'[/user]', 'Money Transfer')){   // Continue sending money } else {   $error = '[colour=#FF0000]Could not send money![/colour]'; }

Conclusion

 

So this is a rough guideline for developing your own modules for PGE. This version of the tutorial is accurate for PGE version 0.9.1b and should probably be compatible with later versions too. I hope this is helpful and gets you on your way. It's taken me some time to write lol I had to have several breaks so I didn't end up repeating myself and stop making sense. Ironically I have written this tutorial to both get you going on developing your modules and to pay off my arrears with my webhost so I can put the project site back up.

 

Have fun and happy developing!

[yordan 10]

Sorry, but I didn't understand how the engine works.Is it for text-based game?Or can you display an image (the room where the character is or the action scene) and wait for a word or a click?

[8ennett 0]

You would have to be familiar with the engine first I suppose before this tutorial would make sense. Why not give it a go?

The engine creates a text based rpg that is also massively multiplayer. When I say text based that just means that the game is mostly compiled from text and images, not like the old text adventure games like Zork lol. You have characters stats such as money, health, level etc. Have you ever played games online similar to ones like http://md1.mafiadeath.com/ (I wouldn't recommend that one though, they are the reason I decided to build my own lol)? The object of the game is to increase your stats and become the most powerful character in the game so you can lord it over your underlings lol ok so that's not the real object of the game but that's why most people play them. There's some example images in my mmorpg tutorial series as well that should give you a better idea of how it works.

The modules and addons are simply extensions to your game, a bank, a gym, an airport. Different modules can be downloaded from the project site (well soon they can be anyway) and each one helps to shape your game. You simply put the module in to the modules directory, go in to the admin panel in your game and click install on the modules list each module you want to install. I've tried to make adding new features to your game very easy for amateur users and make development of modules simple for those who have php abilities.