Little Goblin - architectural overview
Little Goblin is a Grails application and which leads to a typical layout following the convention over configuration principle. This page is intended to give you an overview about what goes where in this type of application. You should open the Little Goblin project in your IDE (for example, IntelliJ IDEA) and have a look at the project's files.
conf (Configuration files)
The conf folder contains the configuration files for Little Goblin.
The BootStrap class is executed on each start of the application by the server. If your database is empty, it will create the whole reference implementation from scrap. If you are going to develop your own game based upon Little Goblin and need some heavy customizing, this is the file where you can create new objects or change the initial configuration.
In the DataSource class your database type is defined and configured. You can use PostgreSQL and MySQL or any other Hibernate compatible database. During development, the DataSource is configured to delete the content of the database and create all tables anew, so changes in the program's structure will be reflected automatically in the database.
Little Goblin, like most Grails applications, follows the MVC (Model-View-Controller) pattern. A Controller sits between the database model (and the domain objects) and the view (what gets delivered to the user's browser as HTML code).The controller's job is to check the user's input, compute the effects of the user's action using the domain objects from the database with the help of some Service objects and render the results based upon what the view templates define in the presentation layer.
Example: the FightController
The FightController is a piece of code that determines the flow of events when a user starts a fight. It loads the PlayerCharacter, the Mob (monster), calls upon extra classes (like the FightService) to determine who goes fist in a round of combat and generally checks what happens. Then, it fills all the results and game data into a template file (called a View) and renders it to HTML, which is then send back to the user who can now decide what he wants to do with the new situation.
The domain directory contains the domain classes, which are the blueprints of definitions of all domain objects in Little Goblin. A domain object is one which pertains to the specific domain of a program. For example, a game needs a player object. Strings, Integers (1,2,...), Boolean (true, false) - those are not domain specific, and in fact they are already defined by the Groovy and Java language. But the things which make up the larger structures of this game framework, those are (mostly) defined inside the domain folder - if they are persistent.
Persistent objects are kept in database tables and fetched whenever needed. So, if you do not log in to play, your player character will stay in the database all day long and will probably not change. But when you play, the object is retrieved from the database, and the columns for name, levels, gold and so on will be turned into objects to be changed. And after the controllers and service classes are done with them, the data that makes up your character is persisted to the database once more.
The domain classes are almost all interconnected. A Mob (Monster) is based upon MobTemplate, which is based upon Creature. And each MobTemplate may have zero, one or more Image objects associated with it. And each Image is related to an Artist - and a License. So, a domain class in Little Goblin defines two basic properties of the domain object: what values it holds (an Artist has a name, just like a MobTemplate has one), and what kind of relations it has to other game objects. Some relations are one-to-one (Image to Artist),while other may be one-to-many (MobTemplate to Images) or many-to-many (Categories to Items).
i18n - Internationalization
The i18n directory contains the messages.properties files for the different languages in which Little Goblin is or may be available. A message file contains key-value pairs, separated by a "=". So, this paragraph has the message id "arch.i18n.desc". If a language file contains this message id and a corresponding translation or text, it will be displayed when a user requests this page in that language.
How does Little Goblin know which language you want? Your browser sends a list of preferred languages to the server. Grails then picks the first one from the list (as this is probably the most important one) and when it has to display a page with a message id in it, it looks if it has an entry in that language's file. Otherwise, the default message (in English) is displayed.
Currently, all translations are inside those message files. At some future time, they will probably transferred into the database, which will make it easier to change them and add new message ids dynamically. If you add a message id to the master file (messages.properties), you should do so at the bottom so the translators can easier find the new entries. (It is probably also a good idea to keep a change log in comment form inside the files, so you can see when entries have changed).
Service classes are used to encapsulate pieces of game logic. They also are often used to access methods that can be re-used in several controllers. For example, the FightController checks if a player character or monster is still alive and determines the order of events during combat. While there may be many domain objects of any one domain class, services are single classes that are only created once. They do not store their state in the database, because normally they do not have any state. They just live to serve.
A View is a file that describes how information collected by the controller from domain model objects is to be displayed. Perhaps you know ASP, PHP or JSP files, which mix (a little) program code and HTML. GSP (Groovy Server Pages) are not much different. Those files, which may include references to smaller building blocks, define how the user interface of Little Goblin looks like. If you want to change how stuff is displayed, you have to edit the views.