JCardGame
 
 

 

In the following tutorial we introduce to the fundamental ideas of the JCardGame framework. The paradigm of "Learning by Examples" is applied where each little example is fully functional and has a special didactical intension. The examples are not yet real games to play with, but serves as demonstration of a specific feature of JCardGame. All sources and sprite images are included in the JCardGame distribution.

(see also "How to use Auto Zoom in Grid and Pixel Games") .

How to use Auto Zoom in Android Card Games

Applications on smartphones (Apps) must display well on very different devices from small handheld phones to large tablets. This is a special challenge that can cause lot of work for the App programmer. Devices running Android Version 3 and up can use a build-in auto zoom feature. But often the graphics becomes blurred when zoomed by the OS, especially on these new big tablets with their superb screen resolution. JGameGrid provides an auto zoom feature that adapts sprite images automatically to the current screen resolution when the sprite image is loaded from the disk. JCardGame goes still a step further: Card and hand positions are also affected by the zoom factor which simplifies the layout of the card game considerably. During development a virtual coordinate system can be used that will be transformed to real (screen) coordinates depending on the current screen size at runtime.

For many card games a square or rectangular game board is used that fits the screen. Therefore the constructor of a CardGame instances takes a layout enumeration that defines how the screen is used. The following BoardTypes are supported:

 
HorzSquare
HorzFull
HorzSplit
 
HORZ_SQUARE
HORZ_FULL
HORZ_SPLIT

.

 
VertSquare
VertFull
VertSplit
 
VERT_SQUARE
VERT_FULL
VERT_SPLIT

All card images and locations are automatically zoomed by a zoom factor calculated from the current screen size. Collision and touch areas are displaced and zoomed accordingly. The zoom factor may also be set by setZoomFactor(). A zoom factor 1 disables auto zoom.


Guidelines for using auto zoom:

  • Assume a fixed size game, e.g. 1000x1000 pixels, assuming a virtual coordinate system x = 0..1000, y = 0..1000.
  • Use card pictures with image sizes that fit well into this window (e.g. 100x150 pixels)
  • Use GameGrid constructor with windowZoom(1000)
  • Design your layout (location coordinates) by using virtual coordinates. Be aware that all location methods of hands and cards (cardActors) takes and returns virtual coordinates. (Other actors still use the real coordinates.)

In the following example we show how to use the HORZ_SPLIT type. (You could also use HORZ_FULL with a transparent board and border color and draw the background using standard GGBackground methods, eventually showing a nice logo on the game carpet.) A card talon is created at the left side of the card board. In the control area a button "Take" is displayed. When the button is clicked, the card on top of the talon is moved to the pile.. When the talon is empty, a status text is displayed.

We locate the button in the center of the control area. We don't want the button size to be zoomed automatically, so it maintains its size even on small screens. To achieve this, we set the zoom factor manually to 1 before loading the button sprite. We save the old zoom factor and restore it after to avoid any side effects. For the locations of the button and the status text, we use virtual coordinates. The center is at vertical coordinate 300, but the horizontal coordinate must be calculated from getVirtualPgWidth() which returns the current virtual playground width. The virtual locations are transformed to real locations in the addActor() call.

Remember that in JGameGrid for Android you should never instantiate an actor (a deck, a hand, etc.) before main() is started, because the internal initializing process is not yet executed at this moment. Of course you may declare them as instance variables and instantiate them in main().

package ch.aplu.cardex12;

import android.graphics.Color;
import ch.aplu.jcardgame.*;
import ch.aplu.android.*;

public class CardEx12 extends CardGame
{
  public enum Suit
  {
    SPADES, HEARTS, DIAMONDS, CLUBS
  }

  public enum Rank
  {
    ACE, KING, QUEEN, JACK, TEN, NINE, EIGHT, SEVEN, SIX
  }

  private Deck deck;
  private Hand talon;
  private Hand pile;

  public CardEx12()
  {
    super(Color.rgb(20, 80, 0), Color.WHITE, BoardType.HORZ_SPLIT, 
            windowZoom(600));
  }

  public void main()
  {
    deck = new Deck(Suit.values(), Rank.values(), "cover");
    talon = deck.dealingOut(1, 9)[0];
    StackLayout talonLayout = new StackLayout(new Location(200, 300));
    talon.setView(this, talonLayout);
    talon.draw();
    pile = new Hand(deck);
    StackLayout pileLayout = new StackLayout(new Location(400, 300));
    pile.setView(this, pileLayout);
    pile.draw();

    final TextActor ta =
      new TextActor("Talon empty", Color.RED, Color.TRANSPARENT, 20);
    final Location loc = new Location(620, 580);  // Virtual loc

    double zCurrent = getZoomFactor();
    setZoomFactor(1);
    GGPushButton takeBtn = new GGPushButton("takebtn");
    setZoomFactor(zCurrent);  // Restore old zoom factor
    takeBtn.addPushButtonListener(
      new GGPushButtonAdapter()
      {
        public void buttonPressed(GGPushButton btn)
        {
          if (!talon.isEmpty())
          {
            Card top = talon.getLast();
            top.transfer(pile, true);
          }
          else
          {
            if (!ta.isVisible())
              addActor(ta, loc.toReal());
          }
        }

      });
    Location buttonLoc = new Location(300 + getVirtualPgWidth() / 2, 300);
    addActor(takeBtn, buttonLoc.toReal());
  }
}

(Enjoy how it is easy to animiate a card moving from one hand to another.)

Execute the program locally using WebStart.

GGLogo
Download Android app for installation on a smartphone or emulator.
Download sources (CardEx12.zip).
Create QR code to download Android app to your smartphone.
Install/Start app on a USB connected smartphone or a running emulator.
(This is a WebStart signed by the University of Berne, Switzerland. It installs some helper files in <userhome>.jdroidtools.If you did not install the Android SDK, you may install a slim version of the Android-Emulator in <userhome>.jdroidemul using this link, To start the emulator, execute ExecEmul.jar found in <userhome>.jdroidemul)


 
HorzZoom