GeoSpace

A 2-D space shooter framework with hooks for AI agents.

============
Requirements
============

* Java Runtime Environment 1.6 or higher

========
Building
========

GeoSpace is distributed as several Maven projects which will resolve all dependencies to a custom
artifact repository also hosted on GitHub. (https://github.com/GeoJosh/geospace-repo). When checking
out the entire project the structure is as follows:

    + /
    |
    +--- /geospace-server    [ Main GeoSpace application. ]
    |
    |
    +-+- /geospace-artifacts [ Project to generate Web Service artifacts from the GeoSpace WSDL. These artifacts are  ]
    | |                      [ stored in the GeoSpace repository as geospace-artifacts and should not need building.  ]
    | |
    | +-+- /examples
    |   |
    |   +-- /geospace-artifacts-example [ An example implementation of the TargetingAgent utilizing the GeoSpace ]
    |                                   [ Web Service artifacts from the geospace-artifacts project.             ]
    |
    +-+- /geospace-remote    [ A proxy agent to communicate with GeoSpace via Web Services through an implemented ]
      |                      [ AbstractAgent class from the geospace-artifacts project.                           ]
      |
      +-+- /examples
        |
        +-- /geospace-remote-example    [ An example implementation of the TargetingAgent utilizing for use in ]
                                        [ conjunction with the geospace-remote proxy project.                  ]

The projects can be imported into most IDEs of your choice (Eclipse, Netbeans, etc.) and built using the IDE's
inbuilt capabilities. Alternately if you have Maven installed you can build the projects from the command line by
running the following:

    mvn clean install

============
Instructions
============

After building the geospace-server project you can run the main GeoSpace application from the command line by
executing the following from the geospace-server project root:

    java -Djava.library.path=./native/[system type] -jar target/geospace-server-1.0-jar-with-dependencies.jar

Specifically for each supported architecture:

Linux:

    java -Djava.library.path=./native/linux -jar target/geospace-server-1.0-jar-with-dependencies.jar

Mac OSX:

    java -Djava.library.path=./native/macosx -jar target/geospace-server-1.0-jar-with-dependencies.jar

Solaris:

    java -Djava.library.path=./native/solaris -jar target/geospace-server-1.0-jar-with-dependencies.jar

Windows:

    java -Djava.library.path=./native/windows -jar target/geospace-server-1.0-jar-with-dependencies.jar

Alternately, if the geospace-server project is imported into an IDE the application may be launched using the
IDE's inbuilt capabilities as long as at launch time the system property "java.library.path" is set according to
the system criteria above.

For development or personal preference purposes the following flags are available to modify application behavior:

    --alwaysrender
    Always render the GeoSpace frame even when the window does not have focus.

    --fullscreen
    Execute the GeoSpace frame in full screen mode.

    --nosound
    Disable all music and sound effects.

=================
Creating an Agent
=================

An GeoSpace agent is piece of software which communicates with the GeoSpace server to control the corresponding player.

There are currently three methods for developing a GeoSpace agent:

1. Bundle the agent along with the geospace-server project by extending the AbstractAgent class and rebuilding the project.
2. Implement an agent that directly communicates with the GeoSpace application via the Web Services interface.
3. Implement an agent that communicates with the GeoSpace application via the proxy geospace-remote application.

----------------
1. Bundled Agent
----------------

An example of these agents can be found in the example KeyboardAgent, MouseAgent, and TargetingAgentclasses within
the geospace-server project.

    1. Implement a concrete class extending geospace.control.agent.AbstractAgent.

    2. Implement the informGameState method. Note that it can be assumed that this method
       will be invoked at a rate of approximately 60Hz.

    3. Either rebuild the geospace-server application with the agent class or compile the
       agent jar and add it to the classpath.

    4. Add the full package and class name to the "agents" line of the geospace.properties file.

    5. Execute the geospace-server application and click on the desired player until the agent is listed.

    6. Click on the Start button.

    7. As the program runs informGameState will be called each time the game state updates. As required modify the
       class' agentController property to control your ship.

--------------------
2. Web Service Agent
--------------------

An example of these agents can be found in within the geospace-artifacts-example project.

    1. Access the GeoSpace WSDL at: http://localhost:10508/AgentService?wsdl or add the
       geospace-artifacts Maven artifact to your project.

    2. Implement the getLastGameState method. Note that this method will need to be polled and
       will be updated no faster than approximately 60Hz.

    3. Execute the geospace-server application.

    4. Click on the desired player until the "Unconnected Service Agent" is listed.

    5. Click on the Start button.

    6. When the program states that it is waiting for agents to connect execute your application.

    7. Execute the connectAgent method noting the authentication token that is returned.

    8. As the program runs execute getLastGameState to get the most recent game state and execute
       setControllerState as necessary.

--------------
3. Proxy Agent
--------------

An example of these agents can be found in within the geospace-remote-example project.

    1. Add the geospace-artifacts Maven artifact to your project.

    2. Implement a concrete class extending geospace.control.agent.AbstractAgent.

    3. Implement the informGameState method. Note that it can be assumed that this method
       will be invoked at a rate of approximately 60Hz.

    4. Execute the geospace-server application.

    5. Click on the desired player until the "Unconnected Service Agent" is listed.

    6. Click on the Start button.

    7. When the program states that it is waiting for agents to connect execute the geospace-remote application.
       Ensure that the compiled agent jar is on the classpath for the geospace-remote applications and pass the
       full package name and class as an argument. For example:
       
       java -cp 'geospace-remote-1.0-jar-with-dependencies.jar:../examples/geospace-remote-example/target/geospace-remote-example-1.0.jar' geospace.control.agent.remote.RemoteAgent geospace.control.agent.RemoteTargetingAgent

    8. As the program runs informGameState will be called each time the proxy detects a new game state update.
       As required modify the class' agentController property to control your ship.

================
Acknowledgements
================

Slick2D - http://slick.cokeandcode.com/
2D Java framework used to develop GeoSpace.

Maven - http://maven.apache.org/
GeoSpace build system.

GitHub - https://github.com/
Git repository hosting for GeoSpace.

======================
Music Acknowledgements
======================

A_Rival
    Stainless Steel         http://ocremix.org/remix/OCR00364/

DarkeSword
    Beamsabre Beat ZEROv2   http://ocremix.org/remix/OCR01235/

Disco Dan
    Metalman Goes Clubbing  http://ocremix.org/remix/OCR00848/

djpretzel
    Mute Radiology          http://ocremix.org/remix/OCR00061/

k-wix
    Origami Robots          http://ocremix.org/remix/OCR02289/

Rozovian
    Braincooler             http://ocremix.org/remix/OCR01916/
    Eat Your Own Dust       http://ocremix.org/remix/OCR01786/

Sixto Sounds
    The Skull Fortress      http://ocremix.org/remix/OCR02293/

WillRock
    Showdown                http://ocremix.org/remix/OCR02237/

===============
Release History
===============

1.0
Initial Release