(Quick Reference)

4 Plugin Usage - Reference Documentation


Version: 0.3.2

4 Plugin Usage

So, you want to create your own game. That's great.

This chapter describes how to create a new game by using the Little Goblin plugin. As an example I will use the reference implementation, which is currently (as of version 0.3.2) a part of the main plugin, but should really be put into a separate application to keep framework and individual game mechanics apart.

So follow along for a tour … you can find the source code at GitHub: Schedim source code

4.1 How to create a new game

A new app

Create a new grails application. On the command line type:

grails create-app schedim

Of course, it would be nice if you were to come up with your own name instead of Schedim ;) Schedim are a kind of mythological creatures from the Kabbalah (elemental spirits).

Grails creates a new application in a folder by the given name (schedim). Open the application in your favorite IDE, for example Eclipse STS or IntelliJ IDEA. It is also a good idea to create a repository for the software in a source code management system like git or subversion. If you got your game in a SCM (and keep backups...), you do not have to fear losing your code or breaking it beyond repair by making changes to it.

Your new grails application should start out looking like this:

In the new application, open grails-app/conf/BuildConfig.groovy and add the line

compile ':goblin:0.3.2'

to the dependencies closure.

If you now type

    // waiting some time
    grails run-app
    // waiting some more

You will see a message like "Server running. Browse to http://localhost:8080/schedim" If you visit this URL, you will see something like the following:

The many controllers are provided by Little Goblin. But since the database is still empty and no start page has been defined, we still have some work to do.

Landing page configuration

As you can see, the default page of the new game leaves something to be desired. But we can redirect visitors from the base URL to a page of our own choosing.

In the file grails-app/conf/UrlMappings.groovy, modify the static mappings definition:

class UrlMappings {
    static mappings = {
	      constraints {

} } "/"(view:"/portal/landing") "500"(view:'/error') } }

Now, if you visit http://localhost:8080/schedim, you should be redirected to the Little Goblin's default landing page:

This still does not look like the test server's page, but it's a start.

Database installation

You may run your game entirely from RAM without any persistent database installed. But while this is great for testing (you get a new database with every start), for a production setting it will probably be less than ideal, because you loose your entire game state once the server shuts down.

If you want to go beyond an in-memory setup, you should install a proper database like Postgresql - this is easy to setup. On Windows, you can use PgAdmin which comes with the database executable to setup a first database called schedim, with a user goblin and password goblin.

If you decide to go with Postgresql (you could also use MySQL or MS-SQLserver etc), please add the following postgresql driver to you dependencies closure in BuildConfig.groovy:

        // automatically download and install the Postgresql driver:
        runtime 'postgresql:postgresql:9.1-901.jdbc4'
        // or use the MySQL one:
        // runtime 'mysql:mysql-connector-java:5.1.20'

Please note that depending on the Postgresql or Mysql configuration, you may need to allow connections from localhost:

--- in pg_hba.conf: add a separate line:
 host	schedim	     all	      trust

Database configuration

Next you will need to configure the connection to the database. This is stored in /grails-app/conf/DataSource.groovy

There are three distinct environments under which your game will be running -

  • development, which means you run it via run-app from the Grails console.
  • test, during testing the game will be running with the in-memory H2 database (leave settings as-are).
  • production, which is activated when the schedim.war is deployed into a Tomcat (or other) server.

Add the following settings to your DataSource.groovy:

    development {
		dataSource {
			dbCreate = "update"
			pooling = true
			logSql = false
			driverClassName = "org.postgresql.Driver"
            dialect = "org.hibernate.dialect.PostgreSQLDialect"
            url = "jdbc:postgresql://"			
			username = 'goblin'
			password = 'goblin'


production { dataSource { dbCreate = "update" pooling = true logSql = false

driverClassName = "org.postgresql.Driver" dialect = "org.hibernate.dialect.PostgreSQLDialect" url = "jdbc:postgresql://" username = 'goblin' password = 'goblin' autoReconnect = true properties { maxActive = -1 minEvictableIdleTimeMillis=1800000 timeBetweenEvictionRunsMillis=1800000 numTestsPerEvictionRun=3 testOnBorrow=true testWhileIdle=true testOnReturn=true validationQuery="SELECT 1" } } } }

If you are using MySQL, use the following lines:

driverClassName = "com.mysql.jdbc.Driver"
		dialect = 'org.hibernate.dialect.MySQL5InnoDBDialect'
		url = "jdbc:mysql://localhost:3306/schedim"

Note the setting for dbCreate: currently they are all set to update, so that Grails tries to add anything new you create. It should not delete any database tables or otherwise break something, just add new stuff.

Once you have a production-ready game, you should set dbCreate to 'none' in the production environment settings.

Security configuration

Little Goblin uses the Grails Spring Security Plugin to enable authentication and authorization of users. You may of course decide to use another security mechanism (or write a game that does not require a login...) but I recommend you just use the following settings in your Config.groovy - after all, Little Goblin is about reducing the time for setup.

grails.plugins.springsecurity.userLookup.userDomainClassName = 'de.dewarim.goblin.UserAccount'
 grails.plugins.springsecurity.userLookup.authorityJoinClassName = 'de.dewarim.goblin.UserRole'
 grails.plugins.springsecurity.authority.className = 'de.dewarim.goblin.Role'
 grails.plugins.springsecurity.userLookup.passwordPropertyName = 'passwd'
 grails.plugins.springsecurity.authority.nameField = 'name'
 grails.plugins.springsecurity.successHandler.defaultTargetUrl = '/portal/start'
 grails.plugins.springsecurity.dao.reflectionSaltSourceProperty = 'username'

You may have noticed the defaultTargetUrl: by changing this you can determine to which page a user will be redirected after login by default. In this case it's the start action of the portal controller.

If you now visit the login page and try to login with the default test user, you will see an error message - which is perfectly ok at this moment, since there are no users in the database.

First failed login: your game is secure...

Adding data

At the moment, your database is completely empty - it should contain just the tables for the Little Goblin domain classes, but not a single row of data. That is about to change...


4.2 The landing page

A browsergame starts with a landing page, where the visitor gets a first impression on what the site is all about.

The landing page is mostly static. It can be found in grails-app/views/portal/landing.gsp

It contains the following parts:

  • The links to the login and registration pages
  • The optional Facebook like button
  • A language chooser (currently supported: French and English)
  • Some information about Little Goblin

The layout is governed by a special file, the sitemesh layout definition in grails-app/views/layouts/main.gsp.

If you want to change the general look and feel, making changes to main.gsp is the easiest way to get this done. This file also includes the CSS responsible for styling the HTML elements. That file can be found in web-app/css/main.css.

So, to change the landing page, you can start with:

  • grails-app/views/portal/landing.gsp
  • grails-app/views/layouts/main.gsp
  • web-app/css/main.css

To activate the Facebook like button, edit your application-config.groovy file (named after your application, for example goblin-config.groovy) and add:

facebook {
    // this enables Facebook-JavaScript snippets on your landing page:
    // show the like button:
    enableLikeButton = true

// if set to true, allow login via Facebook - not implemented yet. enableFacebookLogin = false

// your server's URL and Facebook appId myUrl = 'http://schedim.de/' appId = '217240194988212' }