amaze/release_notes.txt

aMaze
=====

aMaze is a 3D maze game for Nokia Asha software platform and Series 40 full
touch phones. This Nokia example game demonstrates the use of Mobile 3D Graphics
API, gestures, and accelerometer sensor. The concept of the game is classic and
simple: guide the marble through the maze by tilting the phone until the time
runs out. The gestures utilised in the game are pinch-to-zoom and double tap. 

This example application is hosted in Nokia Developer Projects:
- https://projects.developer.nokia.com/amaze
- https://projects.developer.nokia.com/amaze/wiki

What's new in version 1.1
-------------------------
- Nokia Asha software platform 1.0 support added.
- Game speed better normalised for phones with different processing capacity.
- Minor performance improvements.
- GameModel and InteractionManager classes removed and their implementation was
  merged to MazeCanvas.
- Some bug fixes.


1. Project structure and implementation
-------------------------------------------------------------------------------

1.1 Folders
-----------

 |                  The root folder contains the project files, the Application
 |                  Descriptor file, the license information and this file
 |                  (release notes).
 |
 |- binaries        Contains the installable binaries.
 |
 |- res             Contains the application resources (e.g. graphics assets).
 |
 |- src             Contains the application source code.

1.2 Important files and classes
-------------------------------

Note that some files/classes are omitted from the following tree.

 src/ com.nokia.example.amaze
 |- Main.java...........................The MIDlet main class.
 |- SplashScreen.java...................The splash screen implementation.
 |
 |- com.nokia.example.amaze.gestures
 |  |- SafeGestureInteractiveZone.java......The rectangle where the gestures are
 |  |                                       recognised.
 |  |- SafeGestureListener.java.............The interface for gesture listeners.
 |  |- SafeGestureRegistrationManager.java..The intelligent manager for
 |                                          registering gesture listeners.
 |
 |- com.nokia.example.amaze.model
 |  |- MarbleModel.java.................The model of the marble.
 |  |- Maze.java........................The model of the maze.
 |  |- MyTimer.java.....................A generic, easy-to-use timer.
 |
 |- com.nokia.example.amaze.sensors
 |  |- AccelerationProvider.java........The interface that provides
 |  |                                   accelerometer sensor readings.
 |  |- AccelerationProviderImpl.java....The actual implementation of the
 |                                      accelerometer sensor readings provider.
 |
 |- com.nokia.example.amaze.ui
 |  |- CameraAnimator.java..............A utility class for camera animations.
 |  |- DoubleTapDetector.java...........Listens to touch events and notifies the
 |  |                                   listener if a double tap event is 
 |  |                                   detected.
 |  |- MazeCanvas.java..................The game view that ties everything
 |  |                                   together. The view also acts as the game
 |  |                                   engine running the main loop. All the
 |  |                                   touch interaction and command handling
 |  |                                   is implemented in this class.
 |  |- Menu.java........................A generic menu with support for
 |  |                                   customisable menu items.
 |  |- WorldBuilder.java................Contains the methods for creating the
 |                                      game levels.


1.3 Used J2ME and Nokia UI API classes
--------------------------------------

Note: Some, less meaningful packages and classes omitted.

- javax.microedition.lcdui
  - Canvas
  - Display
  - Displayable
  - Font
  - Graphics
  - Image

- javax.microedition.lcdui.game
  - GameCanvas

- javax.microedition.m3g
  - Appearance
  - Background
  - Camera
  - Graphics3D
  - Mesh
  - Node
  - RayIntersection
  - Transform
  - World
  
- com.nokia.mid.ui
  - DeviceControl

- com.nokia.mid.ui.orientation
  - Orientation
  - OrientationListener
  

2. Compatibility
-------------------------------------------------------------------------------

Compatible with Nokia Asha software platform 1.0 and Series 40 full touch
phones. Developed with Nokia Asha SDK 1.0. Tested with Nokia Asha 501, 311 and
306.

2.1 Known issues
----------------

- The performance is satisfactory only with Nokia 311.
- Collision detection is not perfect:
  - Sometimes the marble gets momentarily stuck on the edges of maze walls.
  - Sometimes the marble can pass through maze walls.
- Only partial landscape support implemented.
- No sound effects implemented.


3. Building, installing, and running the application
-------------------------------------------------------------------------------

3.1 Preparations
----------------

Check that you have Nokia Asha SDK 1.0 installed.

3.2 Packaging the application using Nokia Asha SDK 1.0
------------------------------------------------------

You cannot install the application on the device with the IDE, but you can 
package the application: After you have imported the project, locate the
Application Descriptor in the Package Explorer window and open it. Open the 
Overview tab (by default it is the first tab on the left) and click Create
package. Select the destination directory and click Finish.

3.3 Installing application binary to phone
------------------------------------------

Connect the phone to the computer with USB cable or Bluetooth. Locate the
application binary (.jar file). Copy the file to your phone, locate it and tap
to install. With Series 40 phone you can install the file using Nokia Suite:
Drag the file from the file explorer on top of the connected phone image in the
Nokia Suite window.

After the application is installed, locate the application icon from the
application menu and launch the application by selecting the icon.


4. License
-------------------------------------------------------------------------------

See the license text file delivered with this project. The license file is also
available online at
https://projects.developer.nokia.com/amaze/browser/amaze/trunk/Licence.txt


5. Related documentation
-------------------------------------------------------------------------------
- Getting started with Mobile 3D Graphics API:
  - http://www.oracle.com/technetwork/systems/3dgraphics-155829.html


6. Version history
-------------------------------------------------------------------------------

1.1 Nokia Asha software platform 1.0 optimisation
1.0 Initial release