ZAP Engine

Directories
The game code is organized in folders to keep things well organized as well as help the development of features in separated modules. As the huge number of directories and their name can be confusing at first, we will try here to clarify things and explain what each directory does.

You will not find every single module directory, but the categories are there as well as an example. As you see, the main work is in the modules directory, and actually as a game owner or developer, this is the main area you should concentrate yourself. Of course you will need to modify the home files too to reflect what you want to say about your game, and the templates to customize the look & feel.

You may still wonder why we took the road of such complex hierarchy instead of placing all files in one nice and unique directory. There are multiple reasons behind this decision.

One is obvious for anyone which owned a successful game for a while. As soon as you start to work on your game, you add yet more and more features to it, to keep players on board, and of course each new feature means yet a new file or more (unless you code all in one HUGE file, something you don't do, right?). Doing that, you will soon discover that your directory will be full of files, which you don't really actually remember what they do and what uses them why? Because it starts to be impossible to clarify for which features you use them. Of course you could use some sort of "prefix" like "battle_" for all the battle files, but then why not place them safely into a sub directory called battle?

The second reason, is, as we want to develop this engine as a collaboration of multiple person, we could enter in conflict about file names, or people trying to modify things while others edit the same files. To avoid such situations, the engine check those modules directories automatically and extract the list of files needed. Therefore you don't have a huge "switch" which branch to your php file, and you don't need to edit the core file to add yet a new module. Less for the developer, as well as safer for the collaboration.

Modules

How modules are organized
Modules must be placed in one of the sub directories inside /modules and must be self contained into a directory. Each module must contain a file called "part.def" (which stand for "part definition"). This file is a text file containing the logical name (can contain only characters and underscores), and the PHP file which will handle the module (start file which can call other files of course).
Different sorts of modules
As you have seen from the directory structure, there isn't only one kind of modules but actually many different.

Actions
Used to store modules which do not produce any "output" to the game, like a logout.
Admin
Administrative tasks. Only administrators will have access to modules found in this directory. The engine will check the role of the player before allowing any kind of interaction here.
Events
Background events which doesn't require player actions. Like energy refill.
Interface
Interface components like side menu, stat overview and more.
Locations
Locations which allow players to interact with the world, like a messaging system, a chat, market places or more. This is the section which will certainly contain more modules than the others.

How to design a new module
For the purpose of the explanation let's take as an example we want to create a player market, where players are able to buy / sell items to other players via the market.

As you immediately see (or should) this is a location module, already by the fact it's something the players will interact with and is part of the world. Think also that as this is something which needs to display its output in the content area of the template, you don't have much choice left.

We then open the directory modules/locations and will create a sub directory here. Let's call it "market". Inside our fresh new "market" directory, we will need to create our "part.def" file which is composed by a logical name and the PHP file to call. This may be the content of the file:

player_market,market.php

This is the main task, and now let's create the market.php file which could contain about anything you may want. But here we will just put some small code to produce some result.

With this last file, your first module is finished, and you can directly check it. No need to modify any other files as the ZapEngine will automatically detect the module and display it on the side menu.

As you will certainly need to have a bit more code than this you may wonder if you need to include something to have access to the database or other base functionalities. The answer is no, everything will be provided directly to your module, and you just have to concentrate on it and not on which file you need to include to make it work.

	Documentation:
	Directories The game code is organized in folders to keep things well organized as well as help the development of features in separated modules. As the huge number of directories and their name can be confusing at first, we will try here to clarify things and explain what each directory does. You will not find every single module directory, but the categories are there as well as an example. As you see, the main work is in the modules directory, and actually as a game owner or developer, this is the main area you should concentrate yourself. Of course you will need to modify the home files too to reflect what you want to say about your game, and the templates to customize the look & feel. You may still wonder why we took the road of such complex hierarchy instead of placing all files in one nice and unique directory. There are multiple reasons behind this decision. One is obvious for anyone which owned a successful game for a while. As soon as you start to work on your game, you add yet more and more features to it, to keep players on board, and of course each new feature means yet a new file or more (unless you code all in one HUGE file, something you don't do, right?). Doing that, you will soon discover that your directory will be full of files, which you don't really actually remember what they do and what uses them why? Because it starts to be impossible to clarify for which features you use them. Of course you could use some sort of "prefix" like "battle_" for all the battle files, but then why not place them safely into a sub directory called battle? The second reason, is, as we want to develop this engine as a collaboration of multiple person, we could enter in conflict about file names, or people trying to modify things while others edit the same files. To avoid such situations, the engine check those modules directories automatically and extract the list of files needed. Therefore you don't have a huge "switch" which branch to your php file, and you don't need to edit the core file to add yet a new module. Less for the developer, as well as safer for the collaboration. Modules How modules are organized Modules must be placed in one of the sub directories inside /modules and must be self contained into a directory. Each module must contain a file called "part.def" (which stand for "part definition"). This file is a text file containing the logical name (can contain only characters and underscores), and the PHP file which will handle the module (start file which can call other files of course). Different sorts of modules As you have seen from the directory structure, there isn't only one kind of modules but actually many different. Actions Used to store modules which do not produce any "output" to the game, like a logout. Admin Administrative tasks. Only administrators will have access to modules found in this directory. The engine will check the role of the player before allowing any kind of interaction here. Events Background events which doesn't require player actions. Like energy refill. Interface Interface components like side menu, stat overview and more. Locations Locations which allow players to interact with the world, like a messaging system, a chat, market places or more. This is the section which will certainly contain more modules than the others. How to design a new module For the purpose of the explanation let's take as an example we want to create a player market, where players are able to buy / sell items to other players via the market. As you immediately see (or should) this is a location module, already by the fact it's something the players will interact with and is part of the world. Think also that as this is something which needs to display its output in the content area of the template, you don't have much choice left. We then open the directory modules/locations and will create a sub directory here. Let's call it "market". Inside our fresh new "market" directory, we will need to create our "part.def" file which is composed by a logical name and the PHP file to call. This may be the content of the file: player_market,market.php This is the main task, and now let's create the market.php file which could contain about anything you may want. But here we will just put some small code to produce some result. <PHP echo "Welcome to the market {$uservals['USERNAME']}!"; ?> With this last file, your first module is finished, and you can directly check it. No need to modify any other files as the ZapEngine will automatically detect the module and display it on the side menu. As you will certainly need to have a bit more code than this you may wonder if you need to include something to have access to the database or other base functionalities. The answer is no, everything will be provided directly to your module, and you just have to concentrate on it and not on which file you need to include to make it work.