GETTING STARTED

SUBMODULES

Multi-Game uses git submodules to reference the dependent projects that make it work.  
We have split off the project into four separate aspects: Deploy, Engine, Games and
Research.  Each submodule contains it's entire history from the onset of the project
and will allow us to publish our finished games and research more quickly.

To get started right away, simply do the following from the top of this project (MultiGame):

    $git submodule init
    $git submodule update

Then checkout the development branch in the module you want and you're ready to contribute!

    $cd "SUB_MODULE"
    $git checkout -B development

If you're using git-flow, you could then start work on "featureName" with the following:

    $git flow init
    $git flow feature start "featureName"

NOTE: Be sure to use "git submodule update" when moving in-between branches at the top-level.

JBOSS AS6 CONFIGURATION

1. MySQL-DS.xml and Persistence.xml.

   Hibernate is the default database provider for JBoss BUT Multi-Game is configured to run
   with MySQL.

   For convenience, we have placed a sample mysql-ds.xml file in the resources of the
   EcosurJPA module, which can be used with a properly configured MySQL server
   
   NOTE:  Users may also use the default hibernate dialect to work with the default JBoss
   database (hsql) by modifying the marked and commented areas of the persistence.xml file
   and commenting out the mysql specific locations.

2. Local users and roles.  The file "jbossws-users.properties" controls user access to
   the server as part of the local file domain.  Please edit this file to contain the
   users and passwords that you wish to authenticate.  The file "jbossws-roles.properties"
   must be modified to contain the username + "=" and the group "MultiGame" for all users
   created in the jbossws-users.properties file that need access to multi-game.

3. Topics and ConnectionFactory. The file "hornetq-jms.xml" contains the definitions of the
   two Topics that the game subscribes to. This file is included in the WAR file generated by
   this project and included in the deployable EAR.


MYSQL DATABASE CONFIGURATION

   In order to use MySQL with MultiGame you will need to do the following on the server
   where your application server is installed.

   1. Install MySQL.
   2. Connect to local MySQL server as root, and create the database "multigame".
   3. Create and Grant all rights to user 'mg'@'localhost' on multigame:
            grant all on multigame.* to 'mg'@'localhost' identified by 'secret'
   4. Add the mysql-connector jar to the default lib directory. For example, on JBoss:
            mv mysql-connector-java-5.1.17-bin.jar $JBOSS_HOME/server/default/lib
   5. Start the server and deploy the ear generated by the EcosurEAR project. Note: the 
      tables will be created by JPA on deploy, wiping out any previous data that may have 
      been in the database.

   Note:  If you change the username or password in step 3, please update the
      deployed mysql-ds.xml and restart the JBoss server.


GLASSFISH 3.1 CONFIGURATION

The following configuration changes must be made on the Glassfish server to which
the EAR file is being deployed:

1.  Persistence.xml.

    Hibernate must be configured as the provider in the persistence.xml file.
    In addition, the correct datasource name must be specified. Please make changes to
    the persistence.xml file to reflect your environment by modifying the marked
    and commented sections.

2.  A JMS connection factory must be created with the following details:
    a) "Name" set to "MultiGameConnectionFactory"
    b) "Resource Type" set to "java.jmx.TopicConnectionFactory"
    b) "Transaction Support" set to "XATransaction"

3.  A new JMS "destination resource" must be created with the following details:
    a) "JNDI Name" set to "MultiGame"
    b) "Physical Destination Name" set to "MultiGame"
    c) "Resource Type" set to "javax.jms.Topic"
    d) All other fields may remain in default state.

4.  A new JMS "destination resource" must be created with the following details:
    a) "JNDI Name" set to "Lobby"
    b) "Physical Destination Name" set to "Lobby"
    c) "Resource Type" set to "javax.jms.Topic"
    d) All other fields may remain in default state.

5.  Security

    A.  The "Default Principal to role mapping" option must be checked on the security
        configuration screen.
    B.  A JMS user must be created in the file-realm for secure messaging.
        1.  Click on the "file" security realm.
        2.  Click on manage existing users.
        3.  Add the user "j2ee" with any password (authentication is not checked
            by password for a MessageBean.
    C.  At least one user must be created in the "file-realm" of JAAS for logging in
        and playing the games.
        1.  Click on the "file" security realm.
        2.  Click on manage existing users.
        3.  Add a user with the group MultiGame, the username you want and the password.

    Note:  security can be modified within the build to work with any other JAAS
    components available on the Server.  The "j2ee" user is required for the
    message bean to be able to receive messages and message other secured EJB
    components.

6.  Hibernate

    We use two non-jpa specific Hibernate annotations in the internal ordering of several
    entity collections, and therefore, must use hibernate as a persistence provider.
    To deploy on Glassfish, you will need to install and enable it via the "Update Tool"
    provided on the bottom-left hand side of the Admin screen.  Select and check "hibernate"
    from the available frameworks and click install.

    You will need to restart the server to make hibernate available for the application.

6.  Database.

    **** IMPORTANT ****
    Before deployment, the local Glassfish Derby database must be up and running:

    %> asadmin start-database

    if you use the "_default" Glassfish Derby datasource.


FLEXMOJOS INTERNATIONALIZATION CONFIGURATION

 This project is internationalized in English and Spanish, so it requires access to
 the Spanish flex framework locale files.  

 Unfortunately flex mojos requires localized versions of the flashplayer core libraries. 
 These must be imported from the us_US bundle.

 mvn install:install-file -DgroupId=com.adobe.flex.framework -DartifactId=flash-integration
     -Dversion=4.1.0.16076 -Dclassifier=es_ES -Dpackaging=rb.swc
     -Dfile=/path/to/flex-sdk-4.1.0.16076/frameworks/locale/en_US/flash-integration_rb.swc

 mvn install:install-file -DgroupId=com.adobe.flex.framework -DartifactId=playerglobal
    -Dversion=4.1.0.16076 -Dclassifier=es_ES -Dpackaging=rb.swc
    -Dfile=/path/to/flex-sdk-4.1.0.16076/frameworks/locale/en_US/playerglobal_rb.swc

 For more information:
    http://groups.google.com/group/flex-mojos/browse_thread/thread/5b5ff62290d1cb56/d7013abdae604828


FLEX CONFIGURATION

FRAMEWORK RUNTIME SHARED LIBRARIES

  This project uses signed framework libraries distributed by adobe and not present
  in public repositories for legal reasons.

  These must be imported into your local repository

  mvn install:install-file -DgroupId=com.adobe.flex.framework -DartifactId=textLayout
    -Dversion=4.1.0.16076 -Dpackaging=swz
    -Dfile=/path/to/flex-sdk-4.1.0.16076/frameworks/rsls/textLayout_1.1.0.604.swz

  mvn install:install-file -DgroupId=com.adobe.flex.framework -DartifactId=framework
    -Dversion=4.1.0.16076 -Dpackaging=swz
    -Dfile=/path/to/flex-sdk-4.1.0.16076/frameworks/rsls/framework_1.1.0.604.swz

  mvn install:install-file -DgroupId=com.adobe.flex.framework -DartifactId=spark
    -Dversion=4.1.0.16076 -Dpackaging=swz
    -Dfile=/path/to/flex-sdk-4.1.0.16076/frameworks/rsls/spark_1.1.0.604.swz

  mvn install:install-file -DgroupId=com.adobe.flex.framework -DartifactId=sparkskins
    -Dversion=4.1.0.16076 -Dpackaging=swz
    -Dfile=/path/to/flex-sdk-4.1.0.16076/frameworks/rsls/sparkskins_1.1.0.604.swz

  mvn install:install-file -DgroupId=com.adobe.flex.framework -DartifactId=rpc
    -Dversion=4.1.0.16076 -Dpackaging=swz
    -Dfile=/path/to/flex-sdk-4.1.0.16076/frameworks/rsls/rpc_1.1.0.604.swz

FLEX UNIT 4

  We are currently using FlexUnit 4 for the Flex based part of our unit tests. In order
  to run these tests (and have the build successfully complete), you will need the flash
  player on your build path, referenced as "flashplayer". There is an excellent write-up on
  what to do if you have any troubles, especially if you're using OSX, in the following blog
  post:

  http://seanp33.wordpress.com/2010/09/16/flexmojos-mac-osx-and-the-stand-alone-flash-player-debugger/


**  All other dependencies are managed by means of Maven and repositories included in 
    the top-level pom.xml. **