PbML is a small size object-oriented language designed with Play-By-Mail (or turn-oriented) multi-user games in mind. The Yagga environment uses PbML files to describe the simulated world and its interaction with the players.
Basic concepts are:
0.1 Basic structure of a PbML world
A game designer uses PbML to write down one or more ".PbML" files to describe its fantasy world in which players will play and struggle for victory.
It is not important if there is one or a thousand files of world description written in PbML. The Yagga environment is configured to read in all the PbML files in a certain directory, so one can feel free to write the world in several files as one pleases. It is even not mandatory to define a class in a single file. If a class definition is found in several files, than the final class will be the merging of every attribute definition, every method definition found across multiple files for that particular class.
Please see the documentation of the YAGGA environment (appendix A.0) for a detailed description on how to configure Yagga.
It is clear that plug-ins will be basically PbML files "installed" by copying them in the world directory! See the chapter on "Plug-ins and Add-ons" for further details. In this document when we refer to "PbML world" we mean all the PbML files used to describe a simulated world, unregarding to the number of files involved. A typical game is made up of several turns. Each "turn" the Yagga environment collects all the info from the players, read up the world's data, make the world evolve one step, writes down the data (the new status for the next turn) and sends players the information that belongs to each one of them. Once players have read the info, have decided new commands to give to their units, they send back the info to the Yagga environment (the server) and the cycle repeats...
PbML is driven by events, that is a PbML world has not a main method (as in Java or C++), but works in reaction to certain events.
Events are predefined (and thus we refer to them as "phases"). The Yagga environment knows the phases and start by calling all the methods that are written to "handle" a certain phase.
This works in a simulated-parallel way, that is all the methods called to handle a certain phase are run in parallel, on the same set of data, and modifications to the data are made at the same time once all the methods have terminated their execution.
See chapter 1 (Phases) for a detailed explanation.
A PbML world interacts with the player by sending them "views".
A View is a set of generic info about something that the client program uses
to present the player info a bout the world.
Thus, the actual data are not sent to the player's client program, instead the
game designer must specify what to send to the player. Of course the information
sent via the "views" can be anything, can reflect the actual status of the world,
can cheat the player into believing s/thing is s/thing else and so on. Views
are just a mean to send information to the player.
The client program shows them to the human in a human-readable form, but the client doesn't know anything more that what can be found in the views
If the game designer forgets to issue a command that sends the player at least one view, then this player won't see absolutely nothing.
See chapter 4 (Views) for a detailed explanation.