Monday, July 4, 2016

SVN Externals Application II

In the previous post, we checked out SVN Externals to build an XNA solution with the majority of game code written in an external library and scaled out across multiple game clients including Android + iOS.

As an example, the XNA and System Testing snake simulation was scaled to demonstrate SVN Externals.
However, all code here is in trunk; larger scale development requires release tags and feature branches. Let's check it out!

Pre Requisites
This post assumes you already have Tortoise SVN installed on Windows and svnx installed on Mac OS/X.
Also, consider configuring the $SVN_EDITOR on Windows and Mac OS/X in order to edit SVN properties:
set SVN_EDITOR=notepad.exe     ; Windows PC
export SVN_EDITOR=vi           ; Mac OS/X
Conventions
This post uses the following convention to substitute "$DEMO" for root node of all demo code samples:
$DEMO = https://svn/Demo       ; Subversion
$DEMO = C:\svn\Demo            ; Windows PC
$DEMO = /svn/Demo              ; Mac OS/X

Subversion
Create top level Demo node in Subversion SVN. Add 1x sub-node for XNA library and 4x sub-nodes for each client: WP7, Windows, Android, iOS. Ensure all sub-nodes have branches, tags and trunk folders:
 Alias  Platform  Development  Framework  Description  Source Code
 XNA  Windows PC  Visual Studio 2010  XNA 4.0  Game library  Download
 WP7  Windows PC  Visual Studio 2010  XNA 4.0  Game client  Download
 Win  Windows PC  Visual Studio 2012  MonoGame 3.4  Game client  Download
 And  Mac OS/X  Xamarin Studio  MonoGame 3.5  Game client  Download
 iOS  Mac OS/X  Xamarin Studio  MonoGame 3.5  Game client  Download

Tagging
Before beginning new development, it's often best practice to tag your current release build from trunk.

Note: when you create a tag in Subversion, you are not tagging the SVN Externals repository, you are tagging your working copy. If you do not specify the revision then SVN Update will always get latest!

Therefore, you should always explicitly set the revision of svn:externals property when you create a tag:
svn propset svn:externals 'Common -r2276 $DEMO/XNA/trunk/XNA.Common' .

If you have Tortoise SVN 1.9.4 installed then you can use the new --pin-externals option for svn copy. This will automatically set the SVN revision in the tag for you without manual lookup in the SVN logs.
svn copy --pin-externals svn:externals $DEMO/trunk $DEMO/tags/1.0.0.0 -m "1.0.0.0"

For completeness, here are all TAGS 1.0.0.0 cut from previous SVN Externals Application blog post:
 Alias  Command
 XNA  svn copy --pin-externals $DEMO/XNA/trunk $DEMO/XNA/tags/1.0.0.0-XNA -m "1.0.0.0-XNA"
 WP7  svn copy --pin-externals $DEMO/WP7/trunk $DEMO/WP7/tags/1.0.0.0-WP7 -m "1.0.0.0-WP7"
 Win  svn copy --pin-externals $DEMO/Win/trunk $DEMO/Win/tags/1.0.0.0-XNA -m "1.0.0.0-Win"
 And  svn copy --pin-externals $DEMO/And/trunk $DEMO/And/tags/1.0.0.0-And -m "1.0.0.0-And"
 iOS  svn copy --pin-externals $DEMO/iOS/trunk $DEMO/iOS/tags/1.0.0.0-iOS -m "1.0.0.0-iOS"

SVN Upgrade
On Mac OS/X it is most likely that you cannot use the new --pin-externals option for svn copy as the svn version is too low. Here are some basic instructions to upgrade to, for example, SVN 1.8 on Mac OS/X.

However, upgrading may cause svnx incompatibility. Also, higher versions may require an upgrade to serf. A better approach may be to cut all tags on Windows PC and SVN Update all tags on Mac OS/X.

Branching
Larger features usually require longer development time and it's often best practice to cut feature branch from trunk. Applying SVN Externals to branching and merging back into trunk may result in a similar flow:

 1. Cut branches: XNA library and Win client (and other clients)
 2. Update SVN Externals in Win client to XNA branch (not trunk)
 3. Make all code feature changes in XNA library and Win client
 4. Merge XNA library [trunk down to branch + branch up to trunk]
 5. Merge Win client [trunk down to branch + branch up to trunk]
 6. Delete dead branches cut from above accordingly

Implementation
1. Cut branches: XNA library and Win client (and other clients)
svn copy $DEMO/XNA/trunk $DEMO/XNA/branches/FeatureX -m "FeatureX"
svn copy $DEMO/Win/trunk $DEMO/Win/branches/FeatureX -m "FeatureX"

2. Update SVN Externals in Win client to XNA branch (not trunk)
Launch command prompt, navigate to $DEMO\Win\branches\FeatureX\$FOLDER where $FOLDER is the parent folder that hosts Windows Game project. Common branched XNA library code will be linked here.
cd $DEMO/Win/branches/FeatureX
svn propget -R svn:externals

cd $FOLDER
svn propedit svn:externals .
Edit SVN Externals Subversion Properties from previous to current:
 Previous  Current
 $DEMO/XNA/trunk/XNA.Common Common  $DEMO/XNA/branches/FeatureX/XNA.Common Common
svn update
svn commit -m "Update branch"

3. Make all code feature changes in XNA library and Win client
After making all code changes to feature branch, ensure you increment the build number for next release. Navigate to game client AssemblyInfo.cs file. Increment AssemblyVersion + AssemblyFileVersion values:

For example increment version from previous "1.0.0.0" to current "1.1.0.0"
 Platform  File  Property
 Android  AndroidManifest.xml  Increment Version number
 iOS  Info.plist  Increment Version
Note: updated version number should be synch'd in Xamarin Studio Project Options | Application tab


4. Merge XNA library [trunk down to branch + branch up to trunk]
First, merge trunk down to branch (as changes may have been checked-in on trunk prior to the merge)
cd $DEMO/XNA/branches/FeatureX
svn update
svn merge $DEMO/XNA/trunk
svn commit -m "Merge trunk down to branch"

Next, merge branch up to trunk to (re-)integrate changes from shared XNA library to all upstream clients
cd $DEMO/XNA/trunk
svn update
svn merge --reintegrate $DEMO/XNA/branches/FeatureX
svn commit -m "Merge branch up to trunk"

5. Merge Win client [trunk down to branch + branch up to trunk]
Important: first revert SVN Externals in Win client to XNA trunk as XNA trunk and branch are now synch'd
cd $DEMO/Win/branches/FeatureX
svn propget -R svn:externals

cd $FOLDER
svn propedit svn:externals .
Edit SVN Externals Subversion Properties from previous to current:
 Previous  Current
 $DEMO/XNA/branches/FeatureX/XNA.Common Common  $DEMO/XNA/trunk/XNA.Common Common
svn update
svn commit -m "Revert branch"

Next, merge trunk down to branch
cd $DEMO/Win/branches/FeatureX
svn update
svn merge $DEMO/Win/trunk
svn commit -m "Merge trunk down to branch"

Finally, merge branch up to trunk
cd $DEMO/Win/trunk
svn update
svn merge --reintegrate $DEMO/Win/branches/FeatureX
svn commit -m "Merge branch up to trunk"

6. Delete dead branches cut from above accordingly
svn delete $DEMO/XNA/branches/FeatureX -m "Delete branch"
svn delete $DEMO/Win/branches/FeatureX -m "Delete branch"

For completeness, here is one way to remove the SVN Externals property from working copy folder:
svn propdel svn:externals $DEMO/Win/branches/FeatureX/$FOLDER

Tagging
When it is appropriate, tag the new build as per updated build version number 1.1.0.0 from above:
 Alias  Command
 XNA  svn copy --pin-externals $DEMO/XNA/trunk $DEMO/XNA/tags/1.1.0.0-XNA -m "1.1.0.0-XNA"
 WP7  svn copy --pin-externals $DEMO/WP7/trunk $DEMO/WP7/tags/1.1.0.0-WP7 -m "1.1.0.0-WP7"
 Win  svn copy --pin-externals $DEMO/Win/trunk $DEMO/Win/tags/1.1.0.0-XNA -m "1.1.0.0-Win"
 And  svn copy --pin-externals $DEMO/And/trunk $DEMO/And/tags/1.1.0.0-And -m "1.1.0.0-And"
 iOS  svn copy --pin-externals $DEMO/iOS/trunk $DEMO/iOS/tags/1.1.0.0-iOS -m "1.1.0.0-iOS"


Summary
To summarize, here code has been shared from a single external library across multiple game clients; However, SVN Externals could be used to scale out shared data + content across multiple clients too!

Wednesday, June 1, 2016

SVN Externals Application

In 2015, Candy Kid was written in XNA as a simple maze chase video game. The majority of game code was written in an external library and scaled out across multiple game clients including Android and iOS. In order to avoid problems with Copy + paste programming to multiple clients, SVN Externals was used.
Let's check it out!

SVN Externals allow an Subversion repository to be checked out within a directory in that working copy. Here all common code in external repository linked through "Common" directory across multiple clients.

Pre Requisites
This post assumes you already have Tortoise SVN installed on Windows and svnx installed on Mac OS/X.
Also, consider configuring the $SVN_EDITOR on Windows and Mac OS/X in order to edit SVN properties:
set SVN_EDITOR=notepad.exe     ; Windows PC
export SVN_EDITOR=vi           ; Mac OS/X
Conventions
This post uses the following convention to substitute "$DEMO" for root node of all demo code samples:
$DEMO = https://svn/Demo       ; Subversion
$DEMO = C:\svn\Demo            ; Windows PC
$DEMO = /svn/Demo              ; Mac OS/X
Example
As an example, let's scale the XNA and System Testing snake simulation to demonstrate SVN Externals. Create top level Demo node in Subversion SVN. Add 1x sub-node for XNA library and 4x sub-nodes for each client: WP7, Windows, Android, iOS. Ensure all sub-nodes have branches, tags and trunk folders:
 Alias  Platform  Development  Framework  Description  Source Code
 XNA  Windows PC  Visual Studio 2010  XNA 4.0  Game library  Download
 WP7  Windows PC  Visual Studio 2010  XNA 4.0  Game client  Download
 Win  Windows PC  Visual Studio 2012  MonoGame 3.4  Game client  Download
 And  Mac OS/X  Xamarin Studio  MonoGame 3.5  Game client  Download
 iOS  Mac OS/X  Xamarin Studio  MonoGame 3.5  Game client  Download

Sample
The following code sample builds the snake simulation initially as an XNA solution. After the code sample has be fully tested in isolation, additional clients are added to share "Common" code using SVN Externals.

XNA Game library [PC]
Launch Visual Studio 2010. Create blank solution. Add the following 4x new C#/.NET projects to solution:
 Project  Type  Dependencies  Description
 XNA  XNA 4.0 Game  XNA.Common  Entry point and game specific code
 XNA.Common  XNA 4.0 Game Library  log4net | Ninject  Generic game library for all clients
 XNA.SystemTests  Windows Class Library  NUnit [only]  Used for game library system tests
 XNA.UnitTests  Windows Class Library  NUnit | Rhino Mocks  Used for game library unit tests
Important: create a directory symbolic link using mklink to Content folder in order to run system tests.
// mklink /D C:\SnakeDemo.XNA.Content C:\SnakeDemo.XNA\bin\x86\Debug\
protected const String CONTENT_ROOT = @"C:\SnakeDemo.XNA.Content\";

Notes
Common project properties include: Treat warnings as errors "All" + Release version Debug Info "none".
Manually edit system and unit test projects in Notepad and add following XML to mitigate MSIL warning:
<PropertyGroup>
  <ResolveAssemblyWarnOrErrorOnTargetArchitectureMismatch>None</ResolveAssemblyWarnOrErrorOnTargetArchitectureMismatch>
</PropertyGroup>

WP7 Game client [PC]
Launch Visual Studio 2010. Create Windows Phone Game 4.0 project. Include all relevant game content.
Use SVN Externals to link common XNA library game code (above) through "Common" directory in client:

In Windows Explorer, navigate to $DEMO\WP7\trunk\$FOLDER where $FOLDER is the parent folder that hosts Windows Phone Game 4.0 project. This is where SVN Externals will link common XNA library code.

Right click $FOLDER | Tortoise SVN | Properties | New... | Externals. In popup window click New button:
 Local path:  Common
 URL:  $DEMO/XNA/trunk/XNA.Common
 HEAD revision  Checked
 Peg:  empty
Note: an optional SVN revision number can be entered in "Peg:" textbox to pin to static code check-in.

Right click $DEMO\WP7\trunk | Tortoise SVN | Check for modifications. Commit change made from SVN Externals. SVN Update to download "Common" directory from $DEMO\XNA\trunk\XNA.Common in WP7.
cd $DEMO\WP7\trunk
svn propget -R svn:externals
svn commit -m "Add SVN Externals"
svn update
Finally, in Visual Studio 2010 click "Show All Files" button. Right click "Common" directory | Include In Project. Build project. Right click $DEMO\WP7\trunk | Check for modifications. Commit changes made. Done!

iOS Game client [Mac]
Launch Xamarin Studio. Create MonoGame iPhone/iPad Application. Include all the relevant game content.
Use SVN Externals to link common XNA library game code (above) through "Common" directory in client:

Launch terminal prompt, navigate to $DEMO/iOS/trunk/$FOLDER where $FOLDER is the parent folder that hosts MonoGame iPhone/iPad Application. This is where SVN Externals will link common XNA library code.

Type in the following SVN commands:
cd $DEMO/iOS/trunk/$FOLDER
svn propget svn:externals

svn propset svn:externals 'Common $DEMO/XNA/trunk/XNA.Common' .
svn propget svn:externals

svn status
cd $DEMO/iOS/trunk
svn commit -m "Add SVN Externals"
svn update
Finally, in Xamarin Studio right click solution | Display Options | Show All Files. Right click "Common" directory | Include To Project. Build project. In svnX, Check for modifications. Commit changes made. Done!

Repeat this process for the remaining projects: Windows Game client [PC] + Android Game client [Mac]

Jenkins
Don't forget to uncheck "Ignore externals" under Subversion modules on all the automated client builds!

Summary
To summarize, SVN Externals has proved effective to scale common game code linked to multiple clients. However, all code here is in trunk; larger scale development requires release tags and feature branches.

This will be topic in the next post.

Thursday, March 17, 2016

3D City Code Complete

3D City is a simple "Shoot 'em up" video game originally programmed StevePro Studios in New Zealand, in January 1988. The game was written using BASIC programming language built on the Sega SC-3000.

Inspired from previous posts on Sega Console Programming and z88dk Programming Setup, 3D City was the impetus to build an 8-bit video game in C / Z80 assembler to target the Sega Master System (SMS).

Let's check it out!
Download source code here.

Sega Retro Gaming post documents how to play video games like 3D City on PC using Fusion emulator.
z88dk Programming Setup post documents development environment required to build C / Z80 source.
Instructions
Simple! Move target and shoot all enemy ships before they kill you. 4x misses and it is Game Over.
Hint: hold controller Button2 down while moving target slows target down for more focused attack.

ROM Hacking
You can hack this ROM! Download and dump 3Dcity.sms into Hex Editor, e.g. HxD, and modify the bytes:
 ADDRESS  VARIABLE  DESCRIPTION
 0x00C0  Death  Non-zero = invincibility!
 0x00C1  Level  0=easy (default) 1=hard.
 0x00C2  Enemy  0=3x enemies else 1 or 2.
 0x00C3  Music  0=music on otherwise off.
 0x00C4  Sound  0=sound on otherwise off.
 0x00C5  Tiles  0=tiles scroll yes else no.
 0x00C6  Stars  0=stars flash yes else no.
#ifndef _HACK_MANAGER_H_
#define _HACK_MANAGER_H_

#define PEEK(addr)   (*(unsigned char *)(addr))
#define POKE(addr, data) (*(unsigned char *)(addr) = (data))

#define HACKER_START  0x00C0

extern unsigned char hacker_death, hacker_level, hacker_enemy, hacker_music;
extern unsigned char hacker_sound, hacker_tiles, hacker_stars;

void engine_hack_manager_init()
{
  hacker_death = PEEK(HACKER_START + 0);  // 0x00C0
  hacker_level = PEEK(HACKER_START + 1);  // 0x00C1
  hacker_enemy = PEEK(HACKER_START + 2);  // 0x00C2
  hacker_music = PEEK(HACKER_START + 3);  // 0x00C3
  hacker_sound = PEEK(HACKER_START + 4);  // 0x00C4
  hacker_tiles = PEEK(HACKER_START + 5);  // 0x00C5
  hacker_stars = PEEK(HACKER_START + 6);  // 0x00C6
}

#endif//_HACK_MANAGER_H_
Credits
StevePro Studios would like to thank the following, esp. at SMS Power, for making this project possible:
 haroldoop  Adapt z88dk (C cross-compiler) for Z80 systems + generate SMS ROMs
 Maxim  BMP2Tile  Converts BMP images into 8x8 SMS tile data
 Martin  Mod2PSG2  Music tracker software for SMS sound chip
 vhelin  WLA-DX  Z80 multi platform cross Assembler package
 Martin  SMS Examine  Z80 disassembler recompilable by WLA-DX
 Bock  Meka  SMS emulator (excellent debugging features)
 Steve Snake  Fusion  SMS emulator used for general play testing
Important: the psgmod.asm file (Mod2PSG2) was customized thus ASM could be invoked from C code.

Summary
In fact, the Homebrew community at SMS Power celebrates Sega 8-bit preservation and fanaticism each year with its annual competitions. Therefore, this is an opportunity to enter 3D City for 2016. Good luck!

Friday, January 1, 2016

Retrospective VII

Last year, I conducted a simple retrospective for 2014. Therefore, here is a retrospective for 2015.

2015 Achievements
  • Consolidate numerous "XNA" ideas from this blog into single game project
  • Write C# / XNA game code linked to multiple MonoGame / Xamarin clients
  • Use 2D Independent Rendering to target a multitude of screen resolutions
  • Employ better Indie dev. source control systems + continuous integration
  • Commit to Retro Games: more active on social media Facebook + Twitter
  • Salvage ITIN acquired from "XNA and TAX" required for mobile publishing
  • Write WiX / XNA Installer seamlessly download + install PC game version
  • Self-publish Retro Candy Kid mobile platforms: iOS, Android, Kindle + PC
Note: complete game project in C# / XNA published on non-XBLIG platforms is an achievement!

2016 Objectives
  • Expand XNA / MonoGame topics to include localization, custom shaders
  • Apply similar XNA / MonoGame techniques to transition XNA / Unity3D
  • Research additional Indie portals to publish including Steam Greenlight
  • Publish more source code. Checkout sources other than CodePlex (Git)

In 2015, StevePro Studios consolidated many ideas from this Indie game development blog to produce game project to be self-published on PC (outside XBLIG) but also on mobile platforms: iOS and Android.

The game project "Retro Candy Kid" was inspired by the original 8-bit title Candy Kid: a "type-in" video game published by New Zealand's Sega Computer Magazine in the September 1984 issue, pages 17-18.

"Retro Candy Kid" was re-written in C#/XNA 4.0 and employed many techniques discussed in this blog:
 Agile Software Development  Data Driven Design
 Dependency Injection  System Testing
 IoC Container (Ninject)  Level Validation
 Unit Testing  
 Test Driven Development  

However, now that XNA is "dead", this was also an opportunity to transition away from XNA 4.0 to other options e.g. MonoGame and use Xamarin for iOS / Android port. TODO: future project may use Unity3D.

Quality vs. Velocity
Finally, by leveraging techniques (above), 95% of all game code was written in an external library that was unit tested in isolation plus integration done via system testing with minimal client UI intervention.

This development style facilitates high level of code quality written extremely fast to get the best of both worlds: Game finished in short timeframe with low (zero) bug count: critical for Indie game development!

Summary
To summarize, "Retro Candy Kid" proved successful game project because of all points outlined above.
As such, this type of game project is perfect candidate for 8-bit console port e.g. Sega Master System!

Sunday, November 15, 2015

Candy Kid is Live

Retro Candy Kid is live! The game is currently available on the iOS App Store and Android Google Play.
Additional platforms include: Amazon for Android/Kindle, Amazon for PC, itch.io for PC and Indie City.
Click here for more information on Candy Kid "How to Play" which includes secrets, hints, tips n' tricks!

Here is a complete list of all links to download and install Retro Candy Kid (includes free version)
 Platform  Device  Link  Link (FREE)
 Apple iOS  Retro Candy Kid  Retro Candy Kid FREE
 Google Android  Retro Candy Kid  Retro Candy Kid FREE
 Amazon  Android / Kindle  Retro Candy Kid  Retro Candy Kid FREE
 Amazon  PC  Retro Candy Kid  Retro Candy Kid FREE
 itch.io  PC  Retro Candy Kid  Retro Candy Kid FREE

Builds
Previous posts on Candy Kid port to iOS / Android platforms assumed pre-requisite bundle identifier, certificates and provisioning profiles setup. However, here are couple additional build settings to add:

Android Settings
In Xamarin Studio, right click project. Choose Options | Android Build | Advanced tab. Ensure all 5x Supported ABIs are checked from list to support: armeabi, armeabi-v7a, x86, arm64-v8a, x86_64:
UPDATE: Android OS 6.0.1 release seems to cause an issue with 64-bit architectures ABIs + may throw FATAL UNHANDLED EXCEPTION: NoAudioHardwareException: OpenAL drivers could not be found.

If this is the case then ensure the following 3x Supported ABIs are checked: armeabi, armeabi-v7a, x86:

iOS Settings
In Xamarin Studio, right click project. Choose Options | iOS Build. Ensure all 3x Supported architectures are checked: ARMv7 + ARMv7s + ARM64. Also, configure correct distribution signing identity + profile.

Uploading
Previous posts on Candy Kid port to iOS / Android end with deployment process: Archive for Publishing. Let's complete the deployment process: document signing the application and publishing to the stores.

Android References: Signing the Android Application package and Publishing Application to Google Play.
iOS Reference: Publishing to the App Store. Includes information to create and install Distribution Profile.

Publishing
Choose a unique game title, short description and bullet points to be applied consistently across stores.
 Title  Retro Candy Kid
 Short description  Super cool 80s retro arcade simple maze chase video game
 Keywords  80s, retro, arcade, video, game
 Full description  * Eat all candy in maze to pass each level.
 * Eat bonus optional but increases score.
 * Avoid 3x Candy Mamas who chase you.
 * Avoid trees (Death trees kill on contact).
 * Simple! Addictive! Fun!

Price Point
Should you publish your game as paid version or free? If paid then choose the price point; e.g. Tier 1:
USD   $0.99
CAD   $1.19
GBP   £0.79
EUR   €0.99
NZD   $1.29
AUD   $1.49
JPY    ¥120
CNY   ¥6.00

Images
Check out each platform: different resolutions for box art images, promotional screen shots, icons etc.
Google Play Store
 Hi-res icon  512 x 512 32-bit PNG (with alpha)
 Feature Graphic  1024 w x 500 h JPG or 24-bit PNG (no alpha)
 Promo Graphic  180 w x 120 h JPG or 24-bit PNG (no alpha)
 TV Banner  320 w x 180 h JPG or 24-bit PNG (no alpha)

iOS App Store
 4.7-inch 1334 x 750
 5.5-inch 1920 x 1080
 4-inch 1136 x 640
 
 3.5-inch 960 x 640
 iPad 1200 x 900
 iPad Pro 1200 x 900

Amazon App Store
 Small icon 114 x 114
 Large icon 512 x 512
 Screenshots 1280 x 800
 
 Amazon Fire TV Screenshots  1280 x 800
 Promotional image  1024 x 500
 

Videos
If you develop on Windows then most platforms accept MP4 videos that can be uploaded to You Tube. Good idea to crop the window borders especially on Apple otherwise you may be Metadata Rejected!

iOS App Store
Videos on App Store must be between 15-30s. Also, Apple has very strict video codec that must be set. The following assumes promotional video created using Camtasia with the same iOS resolutions (above)

Camtasia
Record 30s MP4 video for e.g. 4-inch iOS Device. Launch Camtasia | Drag MP4 file into Clip Bin twice.
Project Settings | Recording Dimensions | 1136x640 | Ok. Produce video: Custom Settings 1136x640.
 VIDEO
 Format MP4 (recommended)
 MP4 Frame rate 30 fps
 Encoding mode Bitrate
 Bitrate 1500 Kbps
 
 AUDIO
 Encode audio CHECKED
 Bitrate 48 KBPS
Bigasoft
Finally, use Bigasoft Total Converter to crop Windows borders. If you download and install this as trial software then you can only save half the output. Hence reason to double the saved MP4 video (above)
 4.7-inch 1334 x 750  Left: 16 Top: 42  Right: 10 Bottom: 10
 5.5-inch 1920 x 1080  Left: 24 Top: 58  Right: 24 Bottom: 17
 4-inch 1136 x 640  Left: 14 Top: 36  Right: 13 Bottom: 10
 iPad 1200 x 900  Left: 17 Top: 51  Right: 15 Bottom: 14

iTunes Connect
Most platforms such as Google Play Developer Console allow you to enter the Developer name, i.e.
Name other than your legal birth name to represent your Indie Game Studio e.g. StevePro Studios.

However for Apple, if you are an independent (or sole trader) then you must use your legal name;
This is what appears on iTunes; to change this as Company name then you need D-U-N-S Number.

Finally, Apple will not publish your game until you have completed "Agreements, Tax, and Banking". Entering Contact and Bank Info is clear but Tax Info may be more challenging for non-U.S. citizens!

Under Tax Info | U.S Tax Forms, there is option to enter US Tax ID. Non-U.S. citizens may apply for an ITIN if their country has a tax treaty with the U.S. thus in order to claim a reduction in U.S. income tax.
Link to complete Part II "Claim of Tax Treaty Benefits". Answers very similar to Microsoft "XNA and Tax"
The beneficial owner is claiming the provisions of Article 12 of the treaty identified on line 9a above to claim a 0% rate of withholding on (specify type of income): Royalties.
Explain the reason the beneficial owner meets the terms of the treaty article:
I am a XXXX citizen and resident of XXXX receiving royalties from U.S. source.


Amazon AppStore
Also, if you do apply for an ITIN (above) then you can re-use if/when you publish to Amazon AppStore!

Summary
Please show your support for Retro Games and buy Candy Kid today! Now available on iOS and Android.

Saturday, October 31, 2015

Candy Kid How to Play

Candy Kid is a simple maze chase video game originally programmed in 1984. Re-written in XNA and ported to iOS / Android using MonoGame, the Pacman clone has more features that can be found here.

In the old days of retro gaming, cartridge-based video games had very few instructions in game. The game would be distributed with "How to Play" instruction manual. This post attempts to replicate that.

Let's check it out!
Goal
The goal of Candy Kid is very simple: eat all the candy to pass each level! Here are some more tips:
 Eat all candy in maze to pass each level  Avoid the 3x Candy Mamas who chase you
 Eat bonus optional but scores more points  Avoid trees (death trees kill on contact!)
Note: eat all candy + all bonus rewards extra 5,000 pts. Every fifth perfect level rewards 10,000pts.

Characters
Here are the characters. There are basically 2x types: Candy Kid (you) and Candy Mama (enemy)
 "Kid"  Candy Kid. You must eat all the candy to pass each level.
 Simple!
 "Pro"  Candy Mama #1. Super aggressive. High attack range.
 Favorite direction: Horizontal (will go side-to-side first).
 "Adi"  Candy Mama #2. Aggressive / passive. Medium attack.
 Favorite direction: Vertical (will go up-and-down first).
 "Suz"  Candy Mama #3. Super passive. Low attack range.
 Favorite direction: Random (will go anywhere first).
Note: if Candy Mama can manoeuvre either horizontal or vertical then choose favorite direction first.

Navigation
During any non-game screen, tap current screen to progress to next screen; e.g. tap Title Screen to navigate to Main Menu screen. Also, hit back button to navigate back to previous screen at any time.

However, on iOS devices there is no back button! Therefore, touch the left or right of the border trees;
this action will navigate back to previous screen. See below, tap in either white rectangle to go back:
During game play, tap in the middle of maze to pause game. See below, tap in white rectangle to pause:
Options
Most options in Candy Kid are self-explanatory, e.g. Music On / Off, Sound On / Off, Continues On / Off.
Listed below are some interesting options. Tap "Game Options" from Main Menu to get to Options menu.

General Info
Tap "Instructions". Tap either "Kid", "Adi", "Suz" or "Pro" to select alternate color sprite (in rectangles):

General Game
Tap "Avoid Trees" to alternate "Avoid Trees" that block and "Death Trees" that kill player on contact:
Tap "Exits Public" to alternate "Exits Public" to wrap around tunnels and "Exits Closed" to close them:

Gamer Option
Gamer can have 4x speeds: Slower, Medium, Faster, Insane. Gamer fast and enemy slow or vice versa!
Tap "Arrows: 4Way" for "one thumb" player navigation. Otherwise use "UDLR" = Up, Down, Left, Right:

Enemy Option
Tap "Enemy Attack" to alternate "Attack" when the Candy Mamas kill you and "Docile" when they don't.
Tap "Enemy Resets" to alternate enemy "Resets" back to base when Kid dies and "Cont's" to continue.
Enemy can have 4x speeds: Slower, Medium, Faster, Insane. Enemy fast and gamer slow or vice versa!
Finally, cycle through "Adi", "Suz", "Pro" to enable Candy Mama to chase; "No" means they're disabled.

Tips n' Tricks
Candy Kid is a tile-based game thus once direction is chosen then it is not possible to change mid-tile. Therefore, when confronted by Candy Mama, wait 'til they choose their move direction and then move.

Watch out for "Suz": she is super passive and usually evades Kid; you may collide with her more often.
Make good use of tunnels when enabled, especially for faster speeds. Eat candy in the dead-ends last!

Secrets
During game play, tap on "giant" white candy to get free man! See below, white candy is in rectangle: Note: "giant" white candy will only ever be found at Candy Kid or Candy Mama starting position (base).
Important: every fifth level there is 50-50 chance of "giant" white candy so be on lookout these levels!

Trial Game
All the instructions above relate to the fully unlocked game. However, if you would like to try before you buy then there is a free version of the game. The following features are not available in the free version:
 Free man  Disabled. Normally you get free man every 20,000 pts.
 Level Select  Only small percentage of all levels are unlocked to play.
 Instructions  Disabled. Not possible to select alternate color sprites.
 Gamer Option  Unlimited continues disabled. Game over immediately.
 Gamer Option  Num. lives feature is disabled. Only ever have 3x lives.
 Enemy Option  Candy Mamas always attack! Kid invincibility disabled.
 Enemy Option  "Adi", "Suz", "Pro" always enabled and chase all times.
 Secrets  Disabled. There is no "giant" white candy for free man.

Of course you can unlock game at any time, especially when you exit free version there is upsell screen:
Please show your support for Retro Games and buy Candy Kid today! Now available on iOS and Android.

Tuesday, September 15, 2015

Candy Kid iOS Port

In the previous post, we introduced Candy Kid: a simple maze chase video game re-written in XNA 4.0.
We outlined the tasks to port Candy Kid to Android platform using MonoGame. Now we will focus on iOS.

Let's check it out!

Setup
This post assumes you have Mac OS/X and XCode installed. Also, that you have an Apple Developer account and relevant Certificate(s) and Provisioning Profiles installed to deploy code to iOS devices.

MonoGame
Download and install MonoGame for MacOS. Here is tutorial to create cross platform MonoGame.

Xamarin Studio
Download and install Xamarin Studio. Setup an account; a trial version can be used just to get started!
Launch Xamarin Studio | Click Login. Enter your email + password and click the "Create Account" link.

From here you will be prompted to create a Xamarin account: enter name, email address and password. Check "Start 30-day Xamarin trial immediately". Click Accept. Log in to Xamarin Studio to activate a/c.

Choose File menu | New | Solution. Expand Other | Miscellaneous | MonoGame iPhone/iPad Application.
Project Name: CandyKid.iOS. Choose project Location. Click Create button. Update changes to Main.cs
using System;
using Foundation;
using UIKit;

namespace WindowsGame
{
  [Register ("AppDelegate")]
  class Program : UIApplicationDelegate 
  {
    private WindowsGame.AnGame game;

    public override void FinishedLaunching (UIApplication app)
    {
      game = new WindowsGame.AnGame();
      game.Run();
    }

    static void Main (string [] args)
    {
      UIApplication.Main (args,null,"AppDelegate");
    }
  }
}
Before writing any new code or porting any existing, ensure the following tasks are completed:
  • Rename Game1.cs to AnGame.cs
  • Rename all references from Game1 to AnGame
  • Use default root namespace of WindowsGame
  • Delete Default.png and GameThumbnail.png
Build solution. Error: Entitlements.plist template 'Entitlements.plist' not found
Right click CandyKid.iOS project | Options | Build | iOS Bundle Signing. Remove "Entitlements.plist"
Build solution. Error: The minimum deployment for Unified application is 5.1.1, current target is '4.2'
Right click CandyKid.iOS project | Options | Build | iOS Application. Change Deployment Target to 5.2.
Rebuild solution fine. Attach iOS device. Click Play button. The default template code should deploy ok.

Libraries
Candy Kid references the following libraries: Ninject for IoC Container and Xml.Linq for Serialization.
Right click References | Edit References... "All" tab | Scroll to bottom. Check "System.Xml.Linq". OK.

Packages
Right click Packages folder. Right click "MonoGame.Framework.iOS" node. Choose Update as necessary.

Update: at the time of this writing the latest MonoGame.Framework.iOS package is version 3.4.0.459.
However, if you would like to target iOS 9.0 then you can manually download version 3.5.0.628 here.

Right click Packages folder | Add Packages... Enter "Portable Ninject" into Search bar on top right.
Select "Ninject for Portable Class Libraries" | Add Package. Portable Ninject reference also added.

Project Properties
Right click CandyKid.iOS project. Choose Options. Ensure the following options are set on sub tabs:

iOS Application
 Application Name Candy Kid
 Bundle Identifier Enter bundle identifier
 Version 1.0.0
 Build 1.0.0
 Devices Universal
 Deployment Target 5.2
 Device Orientation Landscape Left | Landscape Right
 Status Bar Style Hide during application launch
Also, update AssemblyInfo.cs file under Properties folder. Synchronize "1.0.0" as the AssemblyVersion.

Compiler
 Define Symbols IOS
Repeat all settings for both Debug and Release build configurations!

Code
Import all C#/.NET code from original XNA 4.0 project. Here are some options to exit game on iOS:
// Option #1. P/Invoke exit().
#if IOS
  [DllImport("__Internal", EntryPoint = "exit")]
  public static extern void exit(int status);

  exit(0);
#endif

// Option #2. NSThread.exit().
#if IOS
  Foundation.NSThread.exit();
#endif

// Option #3. Throw an exception.
#if IOS
  throw new System.DivideByZeroException();
#endif
Also, if you'd like to upsell full version of your game to unlock then open the url in the native browser:
#if ANDROID
  string url = @"Enter URL to full version of game";
  UIKit.UIApplication.SharedApplication.OpenUrl(Foundation.NSUrl.FromString(url));
#endif
Content
MonoGame iPhone/iPad Application templates add a "Content" folder as default location for all Content.
Right click "Content" folder | Add New Folder. Candy Kid uses the 4x following subfolders (listed below):

Data
Contains flat TXT + XML data files to be consumed by the game. Do not need to be built as XNB files!
Right click each data file | Properties | Build action: Content | Copy to output directory: Copy if newer
Fonts
Font XNB files may need to be rebuilt for Mac OS/X using the MonoGame Pipeline; instructions below:
Right click each font file | Properties | Build action: Content | Copy to output directory: Copy if newer

Sound
Sound effect XNB files may need to be rebuilt for Mac OS/X using the MonoGame Pipeline; see below:
Right click sound effect | Properties | Build action: Content | Copy to output directory: Copy if newer

Song source MP3 files can usually be used as original format; should not need be rebuilt for Mac OS/X.
Right click song file | Properties | Build action: BundleResource | Copy to output directory: Do not copy
Note: there may be issues MP3 songs on low-end devices: MediaPlayer API may cause game to crash!
Also, it may be required to use alias with MediaPlayer API; for example, you may need to write code:
using Microsoft.Xna.Framework.Media;
using MediaPlayerX = Microsoft.Xna.Framework.Media.MediaPlayer;

public class SoundManager
{
  public void StartMusic()
  {
    if (MediaState.Playing != MediaPlayerX.State)
    {
      MediaPlayerX.Play(Assets.Song);
      MediaPlayerX.IsRepeating = true;
    }
  }
  public void PauseMusic()
  {
    if (MediaState.Playing == MediaPlayerX.State)
    {
      MediaPlayerX.Pause();
    }
  }
  public void ResumeMusic()
  {
    if (MediaState.Paused == MediaPlayerX.State)
    {
      MediaPlayerX.Resume();
    }
  }
  public void StopMusic()
  {
    if (MediaState.Playing == MediaPlayerX.State)
    {
      MediaPlayerX.Stop();
    }
  }
}
Finally, it has been noted that the MediaPlayer.Play(Song) API may cause delay when looping MP3 songs;
Alternative: replace MediaPlayer(Song) with SoundEffectInstance, however XNB file will be much larger!

Textures
Copy all source texture images, for example: BMP, JPG, PNG files from the original XNA game project.
Right click texture | Properties | Build action: BundleResource | Copy to output directory: Do not copy

Resources
Update all relevant Universal Icons, Launch Images and iTunes Artwork for iOS device compatibility.
Right click CandyKid.iOS project. Choose Options | iOS Application | Set all icons and images here:

App Icons
 iPhone iOS 5,6  57x57 Icon.png
 iPhone @2x iOS 5,6  114x114 Icon@2x.png
 iPhone @2x iOS 7  120x120 Icon-60@2x.png
 iPad iOS 5,6  72x72 Icon-72.png
 iPad @2x iOS 5,6  144x144 Icon-72@2x.png
 iPad iOS 7  76x76 Icon-76.png
 iPad @2x iOS 7  152x152 Icon-76@2x.png

Spotlight & Settings Icons
 iPhone Spotlight iOS 5,6  29x29 Icon-Small.png
 iPhone Spotlight @2x iOS 5,6  58x58 Icon-Small@2x.png
 iPad Spotlight iOS 5,6  50x50 Icon-Small-50.png
 iPad Spotlight @2x iOS 5,6  100x100 Icon-Small-50@2x.png
 Spotlight iOS 7  40x40 Icon-Small-40.png
 Spotlight @2x iOS 7  80x80 Icon-Small-40@2x.png

iPhone Launch Images
 Standard 320x480 Default.png
 Retina (3.5-inch) 640x960 Default.png
 Retina (4.0-inch) 640x1136 Default-568h@2x.png
Important: if Retina (4.0-inch) launch image is not set then iPhone 5 resolution will not be supported!

iPad Launch Images
 Portait 768x1024 Default-Portrait.png
 Landscape 1024x768 Default-Landscape.png
 Retina Portait 1536x2048 Default-Portrait@2x.png
 Retina Landscape 2048x1536 Default-Landscape@2x.png

iTunes Artwork
 Standard 512x512  iTunesArtwork.png
 Retina 1024x1024  iTunesArtwork@2x.png

MonoGame Pipeline
If you require MonoGame to build platform specific XNB content files then use the MonoGame Pipeline
Choose Finder | Applications | Pipeline. MonoGame Pipeline launches. Choose File | New. Save project.

Right click project | Add | Existing Item. Add an existing content file e.g. Emulogic.spritefont | Open.
Right click file | Rebuild. An exception may be thrown but the XNB file is still available in bin folder.

Right click project | Add | Existing Item. Add an existing content file e.g. Celebrate.wav file | Open.
Right click file | Rebuild. Assuming Pipeline is installed correctly, the XNB file available in bin folder.

Access Denied
When using MonoGame Pipeline tool, you may receive Access Denied error, especially with MP3 files.
This may be because the ffmpeg binary (and ffprobe binary) needs executable permissions to be set.

Launch Terminal window to manually change executable permissions. Type the following (as root):
cd /Applications/Pipeline.app/Contents/MonoBundle
chmod +x ffmpeg
chmod +x ffprobe

Deployment
Attach iOS device to Mac OS/X. Xamarin Studio, click arrow next to build configuration | Select device.
Click Play button. iOS device launches game as "Evaluation Software". Build will expire within 24 hours.

Alternative: right click CandyKid.iOS project | Archive for Publishing. Click Sign and Distribute button.
Select iOS Distribution Channel as "AdHoc" | Next. Select Signing Identity and Provisioning Profile.
Choose Next to Publish as Ad Hoc. Click Publish button. Choose Location | Save. Now reveal in Finder.
Double click IPA binary file. iTunes launches ok. Select device | Apps | Candy Kid. Click Install | Apply.
Summary
That concludes the Candy Kid port to iOS platform. Outstanding: Candy Kid published on iOS / Android!