How to View an Android Shared Preferences File

Here is what I do when I want to see the contents of an Android Shared Preferences file when I am debugging an app.

1. Change the AndroidManifest.xml so the app is debuggable. Add a line in the <application> tag.

android:debuggable=”true”

2. In Eclipse, run the application in the debugger. That is the “Run – Debug as …” menu item.

3. Run the app until you get to the point where you want to see the contents of a shared preferences file

4. Then start a terminal session and do the following commands after using the Android Debug Bridge (ADB) to start a shell.

adb shell
 $ run-as com.wglxy.starship
 $ ls

 $ cd shared_prefs
 $ ls
 $ cat game_data.xml

For your own app, be sure to replace the text in italics with your app’s package name and the name of the shared preferences file you want.

The two ls commands are there to reassure yourself that you are in the right place. The last command (cat) copies the contents of the shared preferences file to the Terminal window. After that, I usually copy all of the text from the Terminal windows to an editor or text viewer so I can take a close look at it.

I do not know exactly where this works. I work in Eclipse Indigo on a Macbook.  These steps work fine with my Nexus 7 tablet, which is running Android 4.4.2. However, it does not work on my Galaxy Nexus phone (Android 4.3).

Sorry for the imperfect solution, but I thought it would be better to share a partial solution because, when it does work, it is quick way to see what is going into your shared preferences files.

Acknowledgement

Thanks go to Dennis Kubes for writing “Read Android Data Folder Without Rooting“. It took me a while to figure out which devices I could use his suggestions for, but now I use it all the time.

Posted in Android | Tagged , , | 2 Comments

More Mobile Enemy in Starship App

For those of you who are following the progress of my Starship game app for Android, here is a short update. The latest alpha test version of the Android app is out. Version 0.93 features a more mobile enemy fleet. At level 1, the enemy move when a Commander ship is nearby. After level 1, all enemy ships move. Leaderboards are working again. Sign in to Google+ to use them. Touch Leaders on the Menu screen after you get through training.

To try the prerelease version of the app, go to the Google+ community and click the “Join” link:

Try the Starship app

Please note that improved graphics are on the way. Look for better graphics in the Beta test version, which should be available May – June 2014.

The latest demo video is on Youtube.

Related Articles

For software developers interested in how this app was constructed, read these blog articles.

Posted in Android | Tagged , , , | Leave a comment

Lessons from Angry Birds: My Thoughts on Android Game Tutorials

I would like share a few thoughts about designing tutorials for an Android game app. The game, which is a space war game, is not extremely complex but there is enough there that a casual player might have trouble getting started. Commanding a starship is, after all, not a simple task.

In this article, I will tell you what I did about that problem. I will tell you about what I learned about game tutorials from Angry Birds and how I built that into my own app. Figures 1 shows the end result in the Starship game. Figure 2 is an Angry Birds tutorial. To see the animations, there is a YouTube video later in this article.

ss-how-to-dock
Figure 1: Tutorial for How To Dock a Starship

angry-birds-slingshot-action-01
Figure 2: How to Use the Slingshot in Angry Birds

There is a little bit more to the story than Angry Birds. I also have been studying gamification and found several good presentations with advice from game designers about what helps you make good design decisions related to onboarding new players. I will discuss that too.

LESSONS FROM ANGRY BIRDS

Several months ago, I decided that I needed something to introduce players to the game that was more engaging and easier to grasp than written instructions on a screen. I looked around, but I didn’t find any advice that was particularly compelling about how to do this for an app. Looking on my phone, I asked myself: “What do other games do to get people engaged in the game and get them started?” Two old favorites do a great job with some simple animations: Fruit Ninja and Angry Birds.

Take a closer look at Angry Birds. When you first install and start, the game does two things for you early on. First, they tell you the story of what your task is, in only two screens — pictures, no words. The nest is empty; the eggs are missing; the pigs have the eggs; you must get them back.

angry-birds-eggs-goneangry-birds-pigs-have-eggs

Then comes the one and only bit of instruction. You see a simple animation that shows you how to touch the screen and pull back on the slingshot. That animation repeats until you, the player, get it and hit the next button (a checkmark). At that point, you are ready and the games start.

angry-birds-slingshot-action-01angry-birds-slingshot-action-02

Angry Bird became my model, at least as far as tutorials are concerned. A tutorial view pops up on top of the game and runs an animation. In the animation, a finger moves, screen touches are shown, and the resulting action is illustrated. The animation repeats until the player touches the Next button, ideally indicating that the instructions are understood. Two screenshots from my Starship game are shown below.

ss-how-to-firess-how-to-raise-shields

Unlike Angry Birds, there is a lot to learn in the Starship game. To command a starship, you have know these things: how to move, how to fire weapons, how to repair, how to scan for aliens, how to locate starbases, etc. Originally, I had thought that a few pages of help would be good enough. You’d read a few pages to learn what commands were available to you as a starship captain and off you’d go. Well, it didn’t take long to realize that there are way too many commands to qualify as “a few pages of help”. Besides, most people don’t want to read. They just want to shoot some aliens.

I adopted the Angry Birds style of tutorials and found ways to make use of them in the overall onboarding experience for new players. Level 1 of the game is where new players see them. (More on that in the next section.) In total, there are over ten different tutorial animations in the Starship app. You’ve seen a few screenshots above. If you want to see them in action, you can see several of them in the following short demo video.

.

LESSONS FROM GAME DESIGN

I have done a lot of research on game design and gamification lately. Some links are provided in the References section below. One of the most useful references was a presentation by Amy Jo Kim titled “Smart Gamification: Seven Core Concepts“. The topic is gamification, but what Amy Jo Kim does is share tips and advice that are based on her experience as a game designer.

The most important lesson for me was the concept of a player lifecycle. There are three stages: novices, regular, and enthusiasts expert. Amy Jo Kim suggests that you design the player journey from novice to expert.

player-lifecycle

For that point in the presentation, go here: http://www.youtube.com/watch?v=F4YP-hGZTuA#t=501. The whole presentation is great. Be sure to listen to it.

Amy Jo Kim also says: “Newbies need to learn the ropes … think about the first 1-2 months of the player’s experience”. She urges you to figure out the “arc of learning” that you will guide newbies along.

I took that to heart and made the entire first level of the Starship game be the training level for newbies. I incorporated that into the flow of the game. The game begins with you in training. You take on training missions which allow you to advance through the ranks of Weapons Officer, Navigator, Commander, and finally, Captain.  Upon promotion to Captain, you are given command of a very powerful starship. Your mission as Captain is to find and destroy alien starships that have invaded the galaxy.

Even as Captain, your first few missions are in region of the galaxy that is smaller in size and that has few alien ships to destroy. That, I hope, further smooths the transition from newbie to regular.

DOES IT WORK? IS IT EFFECTIVE?

I have told you a little about what I did and why. Two main things were tried:

  • Angry Birds tutorial style
    Difference – many tutorials, not just one.
  • Amy Jo Kim’s suggestions for player lifecycle

I tried to make onboarding interesting by having the player advance through the ranks. I tried to create a sense of achievement and reinforce that with badges for individuals and ranks.

The following questions are unanswered, and I was hoping that some of you Android developers and other blog readers could help me out.

  1. Does an Angry Birds style tutorial work? Do you really know what to touch to make something happen?
  2. Is it effective to earn ranks while you learn the game?
  3. Or does it make it look like the game is not interesting?
    In other words, does it take too long to get to a game that’s fairly challenging?

You will have a better sense of the game experience if you try the app. It’s available in the Google Play store as an Alpha test app. To get the app, just visit the Starship app community on Google+. Click the image below or the link below it. Once you get to the community page, click the “Ask to Join” link on that page to request an invitation. Download instructions are on the community page.

ask-to-join-alpha-test
Try the Starship App

If you have any general thoughts on game tutorials or comments about the tutorials in Starship, I’d appreciate hearing from you in the Comments section below or within the Alpha test community.

DEMO EXAMPLE AND SOURCE CODE

In a future article on this blog, I will explain how I built the tutorials. I started with the animation examples in Android API Demo sample app and saw how they had a set of objects define drawing operations on a Canvas. I built on that idea so I could have several animations working in combination for a tutorial.

REFERENCES

I have been studying game design, gamification, and other topics over the last 18-24 months. Many of the ideas for tutorials and onboarding that I am trying in the Starship app were inspired by the following presentations.

Gabe Zichermann
Fun is Future: Mastering Gamification
Some of his points:
- Onboarding tutorials should be built into the first level of the game.
- “The early days of any game are super important …”
- “What we used to call the tutorial level, but now we just call it level 1″:
“in the olden days …”  and “… reveal the complexity of the game in slow steps”.

Amy Jo Kim
Smart Gamification: Seven Core Concepts for Creating Compelling Experiences.
For the key points, see the “Lessons From Game Design” section above.

In general, anything you find from Amy Jo Kim is worth looking at. Here are two more that I recommend: Lifecycle Design for Social GamesSmart Gamification: Designing the Player Journey.

Posted in Android, Game Design | Tagged , , , , | 1 Comment

Java Version of Super Star Trek

I built a version of Super Star Trek in Java. This version of the Star Trek text game is based on the work of the SST2k project.

Star Trek, a text-based computer game, has a long history. It originated back in the 1970′s and there have been many variations of it since then. According to the Wikipedia article on the Star Trek text game, the SST2k project started in 2005. It is based on the C port of Tom Almy, which was done in the early 2000s.

srs-with-enemy-ships

Original SST Source Code

Example of Game Play

A bit of game play is shown below. Remember that this is a text-based game. The player is prompted for a command. The player enters a command and something happens in response. Refer to the SST documentation page for the set of commands for SST.

Briefly, here’s what is going on. your ship is the E in the scan view; stars, an asterisk (*), empty space, a dot (.); and enemy ships are represented by a K. The sequence we see below is a short range scan, followed by automatic phaser fire directed at any enemy ships in range, and then another short range scan. Note the changes in condition, energy, shields, etc. as the battle progresses.

srs-with-enemy-ships

phaser-fire-on-enemy

srs-with-enemy-and-damage

My Modifications

My goal was to see if I could build an Android app based on the game. I found that there were a few things that I thought would make the game experience better.

The first thing I changed is what you see with a short range scan (SRS). The original game shows the quadrant you are in, no matter your sector position within the quadrant. I changed it so your ship is always in the center of the scan. You see the ship (E) and four sectors away. The effective viewing area of SRS is a 9 x 9 area, rather than the 10 x 10 area of the original. You can see that in the figures (above). Dashes are shown in row 10 and column 10, indicating that no information is available about those sectors. The end result is more realistic view of space. The ship’s scanner has the same range in all directions.

Placing the ship at the center of SRS is a significant change to the game.  What you can see, which enemy ships are nearby, and how you move to far away quadrants are just a few of the aspects of the game that change.

The original game had another feature that I thought made the galaxy a bit hard to understand. Each time you entered a new quadrant, the positions of what was in the quadrant changed. The counts were invariant — same number of stars,  number of enemy ships, number of bases — but the locations changed. I put in an option so that even the old style game can be played with nonrandom quadrants.

To support these two changes, I changed how the game sets up and changed what information is stored to preserve the state of the game. To support nonrandom quadrants, there is no choice but to generate the contents of space at the start of the game.

Commands I introduced or modified for the wglxy variation of the game include:

  • LRM – long range move.
    A command like “lrm 3 5″ moves the ship to quadrant 3 5.
  • PHASERS S – phaser fire, directed at a specific sector.
    A command like “pha s 200 4 8″ directs 200 units of phaser power at sector 4 8.
  • MINE – Mine crystals from the planet you are orbiting.
    The original game requires that you be on the planet, having gone there via a shuttle. In my variation, mining just happens as long as you are in orbit.

You will also note the addition of one device to the original set of devices. To go along with the LRM move command, I added a new device to avoid landing on an existing star or blackhole when you move into a quadrant. I called the device a “collision avoidance device”. If it is functioning properly, the ship can jump to a different quadrant and not have to worry if it will be destroyed as it arrives. If it is damaged, the ship runs the risk of being destroyed.

I added a new way to set up the the game with preset quadrants. A preset file can be used to indicate the positions of stars, blackholes, planets, bases, and enemy ships. That means that the same game be played more than once. It’s also useful to compare one person’s performance against another.

The start up for a game asks you to choose the length of game, difficulty level, and which variation of the game you want. My variation is the “wglxy” variation. Variation “plain” matches pretty much what was in the SST2k code of March 2012. Variations “almy” and “fancy” are more like “plain” because I have not finished adding all the features from the Sst2k code.

sst-start

Java Source Code

The Java code I built is based on a clone of the SST2k, as of March 2012.

Current version of the Java port is available as a zip file on the Sst download page at Wglxy.com. As described above, the Java code is not a 100% match of the code. Some features have not been completed, and some new features have been added. This code compiles and runs inside of Eclipse Indigo, with Java 1.6 as the compiler.

The C code from Sst2k is accessible on the Sst download page at Wglxy.com.

Acknowledgements

According to the SST2k documentation page, the project contributors are David Matuzsek, Paul Reynolds, Tom Almy, Stas Sergeev, Don Smith, and Eric Steven Raymond.

All of us who are fans of the game are grateful for the work you have done on the original game and for the recent work to preserve and improve the game.

 

Posted in Game Design, Java | Tagged , , , , | 2 Comments

Android Rotate and Scale Bitmap Example

I built an Android demo app so I could test my understanding of displaying bitmaps on a canvas. I had done scaling of bitmaps, rotation of bitmaps, and translation from one origin to another, but I had not done more than one of those transformations at a time.

three-at-once-largerThe demo app is shown in the figures above. There are two images in the center of the screen. Each image is scaled to fit within the light blue region. When you press the Rotate button, each of the images is rotated around its center, while maintaining its position in the center of the region on the screen. The Scale button resizes the images. There are three different sizes. Each time you touch Scale, it switches to the next size. The Offset cycles you through four different offsets.

In the app MainActivity, two instances of StarshipView are in the layout. In the onCreate method, each view is assigned a bitmap.

sv.setBitmapFromResource (R.drawable.starship1);
 sv.setScale (1.0f);
 sv.invalidate ();

The onClick method in MainActivity gets called whenever a button is clicked. The code in onClick finds the two views in its layout and sets properties that control the amount of rotation, size of the bitmap, and x and y offsets.

sv.setScale (newScale1);
 sv.setDegrees (degrees1);
 sv.setOffsetX (newOffset1);
 sv.setOffsetY (newOffset1);
 sv.invalidate ();

Inside class StarshipView, in the onDraw method, the bitmap  assigned to the view is written to the canvas. The code is actually very simple, once you get comfortable with using Matrix objects to do the work. Here’s what goes on in the onDraw method of class StarshipView.

First, the Matrix object is set so it will fit the bitmap into the rectangle for the view. For this demo app, I chose some interesting sizes to test this part of the code. The starship image is 512 x 512. It is scaled to fit into the 96 dp area on the left. The star field image on the right is 96 x 96 is displayed in the 120 dp square on the right.

The second step is to translate the view up and left by half the width and half the height. That is done because rotation is around the top left point (the origin) of the view. Rotation follows that step. It is very simple: “matrix.postRotate (rotation)”.

/**
 * Draw the bitmap onto the canvas.
 *
 * The following transformations are done using a Matrix object:
 * (1) the bitmap is scaled to fit within the view;
 * (2) the bitmap is translated up and left half the width and height, to support rotation around the center;
 * (3) the bitmap is rotated N degrees;
 * (4) the bitmap is translated to the specified offset valuess.
 */
@Override public void onDraw(Canvas canvas) {
 if (pBitmap == null) return;
 // Use the same Matrix over and over again to minimize 
 // allocation in onDraw.
 Matrix matrix = mMatrix; 
 matrix.reset ();

 float vw = this.getWidth ();
 float vh = this.getHeight ();
 float hvw = vw / 2;
 float hvh = vh / 2;
 float bw = (float) pBitmap.getWidth ();
 float bh = (float) pBitmap.getHeight ();

 // First scale the bitmap to fit into the view. 
 // Use either scale factor for width and height, 
 // whichever is the smallest.
 float s1x = vw / bw;
 float s1y = vh / bh;
 float s1 = (s1x < s1y) ? s1x : s1y;
 matrix.postScale (s1, s1);

 // Translate the image up and left half the height 
 // and width so rotation (below) is around the center.
 matrix.postTranslate(-hvw, -hvh);

 // Rotate the bitmap the specified number of degrees.
 int rotation = getDegrees ();
 matrix.postRotate(rotation);

 // If the bitmap is to be scaled, do so.
 // Also figure out the x and y offset values, which start 
 // with the values assigned to the view
 // and are adjusted based on the scale.
 float offsetX = getOffsetX (), offsetY = getOffsetY ();
 if (pScale != 1.0f) {
  matrix.postScale (pScale, pScale);

  float sx = (0.0f + pScale) * vw / 2;
  float sy = (0.0f + pScale) * vh / 2;

  offsetX += sx;
  offsetY+= sy;

 } else {
  offsetX += hvw;
  offsetY += hvh;
 }

 // The last translation moves the bitmap to where it has to be to have its top left point be
 // where it should be following the rotation and scaling.
 matrix.postTranslate (offsetX, offsetY);

 // Finally, draw the bitmap using the matrix as a guide.
 canvas.drawBitmap (pBitmap, matrix, null);

}

Once the bitmap is rotated, it needs to have its location translated to the place where it should display in the view. That is specified in the offsetX and offsetY values. So you see one more matrix.postTranslate call in the method.

The final action in the onDraw method is the drawing of the bitmap. Notice that the drawBitmap method uses the Matrix with the various transformations encoded in it.

Source Code

You can download the source code for this demo from  the Wglxy.com website. Click here: download zip file from wglxy.com. The zip is attached at the bottom of that page. After you import the project into Eclipse, it’s a good idea to use the Project – Clean menu item to rebuild the project.

This demo app was compiled with Android 4.4 (API 19). It works in all API levels from API 10 on up.

References

As with many other problems, I found very good advice on StackOverflow. A StackOverflow post on rotating images around the center of the image helped me.

Posted in Android | Tagged , , , , | 1 Comment

Making Promo Videos for Your Android App

I found an article that explains how to make videos of your Android app in action. You can use these videos for promoting your app. See “How To Record Your Android Device’s Screen“.

It is very easy to do. All you have to do is use the ADB (Android Debug Bridge) tool in Eclipse. Connect your device and then start the ADB shell with something like this:

adb shell screenrecord /sdcard/adb_movies/m1.mp4

Once you start it, it records whatever you do on your device. Stop the recording by typing Ctrl-C. It then saves an mp4 file.

I tried it out on my Starship app, which is currently under development. The end result on Youtube is here:

 

Posted in Android | Tagged , , | 1 Comment

New Turn-based Space War App for Android

I’m using the new features in Google Play for staged rollouts of Android apps. It’s a great way to distribute pre-release versions of an app for alpha and beta test. Please try my new turn-based space war app: Starship.

Learn to command a starship

Fight epic battles

A demo on Youtube is here:

Try Starship Now

If you would like to destroy some alien starships and save the galaxy:

Posted in Android, Game Design | Tagged , , , | 2 Comments