HowToDev

HowTo for Developers

< Start

• HowTo for Developers
  • Mapping on rendered images
    • Image optimisation
  • Add a new scene
  • JavaFX

Mapping on rendered images

There are three use cases for mapping areas in a rendered image:

1. The image was newly rendered and the existing mappings must be adjusted
2. Add a new mapped area in an existing image
3. The rendering is new

The first and the last case are very similar. Only in the first case the entries already exist and have to be replaced. All the mapping in the game (not the startup) are defined in mainScreen.xml. For each rendering there is a image section. within this section each area is defined with a polygon. The polygon has a speaking name identifying the part of the image in a unique way. A z-index can also be specified. This index specifies the back to front order. This allows simpler definitions of shapes if another shape is in the forefront. A high index indicates the object to be in the back. An area is defined by a number of points.

<!-- Properties for the images -->
<images>
    <image name="portScene.png" crop="BOTTOM" maxCrop="920" type="o">
        <!-- coordinates of the polygon in the unmodified image -->
        <polygons>
            <polygon name="LoadingCrane" z-index="1">
                <point x="558" y="755"/>
                <point x="558" y="628"/>
                <point x="591" y="583"/>
                <point x="610" y="494"/>
                <point x="762" y="500"/>
                <point x="760" y="538"/>
                <point x="720" y="634"/>
                <point x="716" y="755"/>
            </polygon>
                        ...
               </polygons>
       </image>
       ...
</images>

To figure out the coordinates open the image in painting application like Gimp. Move the cursor to a location that defines a corner of the shape and note the location within the image. Repeat this until you have all the points making up the shape. The coordinates reference points in the image with the original resolution. In the game the image will probably be scaled. The same scaling will be applied to the coordinates.

Image optimisation

As there might be different resolutions there are three ways the image is prepared before it is displayed:

1. If it is to large and part of it can be cut away to get a better match that is done as a first step
2. Proportional scaling
3. Adding black borders

For the first step to work additional data must be specified in the image tag. The optional crop attribute defines where the image can be croped (TOP, RIGHT, LEFT, BOTTOM). The cropMax attribute then defines the maximal amount that can be cut away.

Add a new scene

1. Create an entry in mainScreen.xml to define the image that is used in the scene. Define at least one polygon to get back to the previous scene
2. Add a polygon in the previous scene to navigate to the new scene
3. Create an event handler for the scene extending ScenePolygonInitialzer. It must have a default constructor, using the scene image name to call the super constructor and be declared as Component
4. For each polygon defined in for the scene add a case in the createEventHandler method. The case is the name of the polygon.
5. Create a new enumeration entry for the scene in EScene
6. Add the event handler initializer in PolygonInitializerFactory and add a case for the new scene in getScenePolygonInitializer
7. In MainGameView.getImageNameFromScene add the case for the image name
8. Add a new enumation entry in EViewChangeEvent
9. Implement the handling of the switch to the new scene.

All these steps are staigt forward when starting at the definition of the scene in the mainScreen.xml and implementing the switch to the new scene. Starting the application now will gradualy pop up exceptions pointing to the next step to be implemented.

JavaFX

As JavaFX comes bundled with the JDK, it is not available as a Maven artifact and only is included in the Oracle JDK 7 or as separate distributable. In the future this should change as JavaFX has become open source with coming release of Java 8. For now you might be required to install the Maven dependency into your local repository, to get it to work. For Linux you can install the JavaFX jar file using the following line:

mvn install:install-file -Dfile=/usr/lib/jvm/jdk1.7.0_25/jre/lib/jfxrt.jar -DgroupId=com.oracle -DartifactId=javafx -Dversion=2.2 -Dpackaging=jar

The location of your JDK may vary. For Windows consult this blog where a console script is available for installation into the repository.