Thursday, June 8, 2017

Working Around Xcode Server CI Manual profile Issues

There's a few problems and issues to deal with when getting Xcode server to work and they've been mostly dealt with well in other blog posts.

The dreaded error you get with a manually provisioned profile is harder to get rid of:

Provisioning profile "MyApp Development iOS" doesn't include signing certificate "iPhone Developer: OS X Server (VQJ479QQTU)"

It occurs because when the Xcode server runs in the context of the OS X Server it has its own keychain called "Portal" and in that keychain it creates its own new certificates, which are accessible by the server process.

First get your CI server up and running and create a bot as described in the Apple macOS Server documentation for CI services, or a recent blog post.

If you've got a manually provisioned profile you'll get the error above.  Make sure that on your local development machine - e.g. your laptop - open Xcode and use the credentials export feature - it will ask for a password which you'll need to carefully record.

This will create an archive of the credentials including your certificates, keys, profiles and so on.  Copy that onto your macOS Server machine (e.g. using scp or a USB key or whatever) and then as the xcodeserver user that you created for the purpose open Xcode and import that archive, supplying the password created above.

Now open the Keychain Access program - I find its easiest to do this by invoking Spotlight with <cmd>-<space> and then typing "Key...".  Here you need to do the following

  • Click on "Portal" top left to open the "Portal" keychain
  • Select all the automatically created certificates that are complained of in the error e.g. 
    • iPhone Developer: OS X Server (VQJ479QQTU) 
  • Set these aside for safe keeping & then delete them.
    • Archive these off by choosing "File" > "Export Items...".
    • This is in case something goes wrong and you need to re-install them
    • Now choose "Edit" > "Delete"
  • Now click on "login" to open the "login" keychain.  
    • This is where Xcode's import developer accounts tool will have placed the certificates.
    • Select all of the certificates and drag them into the "Portal" keychain.
    • At the end your "Keychain Access" should look like this:

You should now be able to run an integration and Xcode server will find and use the correct certificates to support your manually assigned profiles.

Sunday, September 18, 2016

Burn your GANTT Charts & Deliver Game Releases Like a Boss

We all want to have our teams be treated as the awesome creative people they are, but there's deadlines and as producers & studio founders responsible for making sure the place stays afloat, how can we deliver our games on schedule and not put our peoples feet to the fire?

How about setting fire to your schedule for a damn start?  We all know the dates on those things are a straight-up fiction!  They weren't working anyway right?  The reason they fail is because of the Planning Fallacy - humans are fundamentally incapable of making accurate estimates of work to be done ahead of time.

There's alternative approaches where torching those old traditional MS Project style schedules may well be a good thing, especially if your studio is looking for a clean slate on your team dynamics.  My talk at Seattle's Mobile Game Forum on October 18th 2016 deals with this topic and I'm going to throw a few spoilers here (the image above is a slide from that talk) - but go see the talk if you can, as the full content will be there.

The different way of working is a methodology developed over a decade of working with creative teams.  I use it today at my studio Smithsoft Games.  At its core it's a "kind-of agile" modified for the small, distributed, start-up teams of frequent collaborators which typify my teams.
What works well for my team is ideas that are raided from the agile camp.  
I don't necessarily buy into the whole agile manifesto - because my teams & projects are usually distributed and multi-disciplinary so not always face-to-face.  We respond to players (our customers) but they are not around the table as we typically use metrics & the occasional field test session - so we don't have a customer figure handy as required by agile.

Instead I have found that what works well is to know the agile principles and use their best ideas as far as possible while working in a way that is resilient against breakdowns.  I call this "raiding agile".

Backlogs are the best idea ever, a great takeaway from the agile camp & the first and best step you can take along the road to delivering your game without crushing your people in a schedule hell is to switch to backlog driven development.

The basic approach we take (raiding agile) can be broken down into 3 parts:

  • Unleash your People
  • Tool up your Communication
  • Gamify your Planning

To get your head around the approach we take, basically just use one simple mnemonic - it all comes down to people-power: free your people & empower them to solve the problem of planning your project; communicate constantly and excellently with your people and gamify the planning using backlogs so that every day your people are doing the planning work of keeping your project on track and having fun while they do it.

So how does it work in practice?

Unleash Your People

James Everett talks on "Trust in Game Design NZGDC 2016"
Unleashing your people is about trust.  Trust is a top item in the agile manifesto and something crucial to getting your team working.  Top designers & producers in game development already know this even if they don't use agile.

In the seminal 1999 book “Peopleware: Productive Projects and Teams” Di Marco and Lister explain that management’s job is not to make people work.  Instead your job is to make it possible for them to work.

As a leader, you work to build trust: work to be in a situation where the people who work on your team trust you, and more importantly you trust them.

Your success will be defined not by how carefully you lay your plans; but by how well you recover when they go wrong.  And you will go wrong.  When it happens, your team will be there; if you have built trust.

If you try to impose control from the top, it amounts to a lack of trust that people will work what’s needed for the project.  Having your people waiting around for sign-off, when they could be working is waste.

Having people get into what I call the “Inbox” mentality where they live their work lives like a rat in a cage pressing a bar, checking for the next item of work to be given to them by their supervisor.  That is not how lean effective teams work.  Companies that operate via their inbox, and pleasing bosses, lose the ability to respond quickly; they sacrifice agility and vibrancy for no actual gain.

Tool up your Communication

OK, so we’re going to TRUST our people, empower them to work on the project.  How do we as leaders make sure that the project is on track then?  Isn’t it our job to motivate them?

Imagine the throughput of your team is defined by this triangle - in this model the sides remain in constant proportion.

Once you have hired someone competence is fixed. Lets assume you have a team and you want to make the best of them.

Motivation - You could be forgiven for thinking that comes from being paid.  Some think in a dated way, an authoritarian way that motivation must be imposed from the top.  Let me tell you for creative people it comes from a raft of things, such as accomplishment, and recognition.

But in my experience its the communication which winds up being the restricting factor MOST often.  If you improve communication that you will begin to reach the potential of the motivated competent team.

Technical projects have failures - but those are due to human reasons.  Most often from a lack of shared understanding.  The best bang for your buck, for improving team performance, is time spent on communication.  And that means written, and verbal, charts on the wall, wiki pages - anything that gets a shared message across.

Your job as leader is to filter outside impacts that can derail the team, simplify the view they have of the overall product and provide a compass set on true north.  Provide a consistent drum-beat that gives the project a cadence.  Through that repeated message infect the team with your own enthusiasm for the mission of the immediate project goals.

“We are going to ship the beta in March” - keep talking about what that will mean, and what it will look like.  Check back to see if people understand what that goal is - when it bites, what counts as success.

Have GBC - a great big chart stuck physically to the wall that shows that goal.  If I walk up to one of your team members and ask what is the next big milestone, whats in it and when is it due?  It should roll off their tongue instantly - if not, then that is on you.

Be Precise & Specific

Systematize names for things and use them across the board.  Don’t use vague words like “the build” or worse “IT”.  Make sure your tools, your plans and your verbal communications always use the same terms.  People cannot see inside your head.
When will “IT” be ready?  
Is “IT” done yet?
 If you ask an artist working on a concept for a character when will “IT” be ready, does that mean the concept, or a set of poses, and clothes?  Use the milestone and feature names to avoid the “IT” problem.

Make Sure Communication is Two-Way

So you’re communicating clearly with your trusted team.  Is that communication two-way?  Trust comes when your team knows that they can tell you ANYTHING without fear.  That comes when you admit you don’t know.

Google’s 3 year long study Project Aristotle set out in 2012 to see what made the best teams.  Their leads had believed conventional wisdoms like the teams that did the best were the ones that had the most talented members.  But it had not been studied to find out how true that was.

Turns out that people needed Psychological Safety which is ‘‘a sense of confidence that the team will not embarrass, reject or punish someone for speaking up’’

As a leader you have to make sure that members of your team are rewarded for contributing their slice of wisdom.

Have you heard a conversation where there’s that one person who “knows more” than every one else?  Others should “shut up” because the authority is talking?

Knowledge is not a high-watermark.  Even if someone is still learning compared to an experienced person remember this: the contributions of even the most inexperienced member of your team is never submerged by another.  Team members contributions overlap. 

Make sure their slice of wisdom is heard.  They may have had the one vital clue for the success of a critical part of the project. 

Use Tools to Help Make This Happen

How can ensure that all team members are contributing in that communication two-way street?  Obvious ways are to show leadership in meetings.  Make sure your loud confident types cede the floor and don’t interrupt.  Try a round-table technique for your stand-ups and other essential meetings.  Use a “speakers totem” if necessary to shut up repeated interrupters.

Even better - and this is a nice segue into the next of the 3 tricks - consider using tools that gamify and level the playing field when it comes to meetings like the daily standup.  At Smithsoft we use the Slack on-line chat tool, with its scriptable bot, to manage our daily standup.  Wikis, source control, online-test-plans, and Drop Box all have their place too.  Trello and the Google suite of cloud-collaboration & document tools are also great.

The single best communication tool is working software.  An up-to-date version of the game, which everyone on the team can access.  Your tech team should prioritise what’s called “continuous integration” - which basically means automatically getting new builds when changes are made.

Team members who are remote or working remotely, or from home are not out of the loop.  Breakdowns & mismatches are avoided.

Yes - there’s value in face-to-face, or video conference hook-ups, but their usefulness has to be balanced with the time-wasting aspect.  Making people report in personally to a meeting like little tin-soldiers might give a feeling of control, but once you’ve dished out that sermon on the mount, how much of it actually sank in?  Meetings, and especially ones where the communication is mostly all one way is a number one time-waster that you can move away from as you pursue a lean and creative team methodology.

Gamify Your Planning

OK, you’ve unleashed your people and tooled up your communication.  Now you have everything buzzing, how to make sure you get the project delivered out of all that energy?

It turns out that there is one huge shift you can make with your project management; if you’re not doing this already, prioritize people over days.

At the beginning of a two week period, the team goes through one by one & makes a list of all the tasks they will commit to complete that period.  We call the period a “sprint”.  As far as possible teams should be multi-disciplinary with artists, technical artists, programmers, QA people and designers all working side by side on functional areas of the game.  This way they see & communicate issues in real time.

Team members only commit to what they know they can do, and they OWN that.  The whole team agrees that those tasks advance the mission of the project, by delivering value to your players.  Because you’ve communicated the mission to them, they know what success looks like, they know to measure each and every task against that vision to see if it is up to snuff; before adding it into the sprint.

The tasks then become cards in a game, played in rounds & turns.  This leads to ceremony around the working day which structures your teams work in a way that makes it obvious when the agreed upon plan is strayed away from.  The rules of the game help reinforce ways-of-working that stop the classic mistakes of human nature such as "The Planning Fallacy".

Well, you might now say, great - I’ve burned my GANTT chart and I don’t know what we’re delivering any more!

Actually you do.  Because you have used communications, with specific clear terminology, and you have working software, you know exactly what you’re delivering.  You see it every day.

Its the working software - the current build of the game.

And actually you know MORE - because you can look ahead and see where the trend line goes.  How many stories are we getting through?  This is the teams VELOCITY.  You can use a fancy graph like this one.  But the best thing is just to put a big chart on the wall and use a marker pen to keep it up to date.  Or just track the velocity as a number.  If you like you can break it down by team member.

How many tasks are left?  You know your delivery dates - simply draw a line across  your backlog at the cut off date and you can SEE what features are in and what don't make it.

But I have to have my feature!  

OK, sure - time to horse trade, what other feature do you want to swap out so that the one you want in makes the cut?

Now you have a dialog that allows you to negotiate and still have a working game.

Closing:  People Before Tools

Beware of becoming seduced by tools.  A lot of managers I have worked with in the past will say things like "We're using Trello" or "We're using Jira" as though that completely describes the ways of working of the team or studio.

A burn-down chart like the one above is not your process.  If that starts to happen, go back to basics and use a number of a rough chart on the wall.  

The truth is not some graph produced by a tool - its what your people are producing and what the working software says.

Also I'm not saying this way is simple: its hard, and our teams still struggle every day to stay on target.  But at least by putting people first you as a leader, studio founder or producer are not trying to do all the planning with bogus numbers on a fictional GANTT chart, and you have help with planning from your team.

In closing I’d just like to summarise: you can beat the Planning Fallacy & other mistakes, by getting your team to divide a creative milestones into small, simple, same-sized, swappable stories stored into a prioritized backlog.  

Good luck and have fun!

Tuesday, August 2, 2016

Pandora's Books Coming Soon!

Lately all my time has been devoted to Game Development so I have not been posting much.  What have I been up to?

Since January 2016 with Space-Bot Alpha behind me, I expanded the studio and bet the farm on a new game Pandora's Books.

It's a game about Pandora who opens the wrong book and releases the chaos wizard & his minions onto the worlds of classic stories.  As a player your job is to unscrambled the mixed up words, to defeat the wizard & his minions, and save the cities of these timeless tales.  The game ships with War of the Worlds unlocked and as you play you collect clues that can be used to help when you're stuck on a word, and also saved up to unlock books.

The team has been amazing, and last week we pushed the game to Apple's App Store editorial team in the hope of getting a feature!  This is the "big time" for me, and I guess even if we don't get the much-vaunted Apple feature we still have a great game which will go live on August 18th.

If you want to follow my journey as an Indie Game Developer why not subscribe to follow this blog and keep up with future posts?

Thanks for reading!

Sprite Kit for the Win

My game development work these days is all done in Apple's Sprite Kit, which is a dedicated 2D game development technology.  To my knowledge Apple is the only device vendor making game APIs like Sprite Kit.  Google has some back-end stuff but nothing to put sprites on the screen.

Sprite Kit is a "no engine solution".

The correct term for it is framework: Sprite Kit is not an "Engine".  You hear that as a common term around game dev circles: "what engine are you using?".  Sprite Kit is a "no engine solution".  In this article I lay out my reasons for choosing Sprite Kit for my professional studio's development, and what this distinction means in practice.

Editing a Sprite Kit Scene in Xcode

In game dev you try to separate code from assets, functionality from data, as you do in regular programming or good software engineering.  A key difference is the degree of separation and what role your game plays on the device when you use a framework rather than an engine.

  • With a framework you are actually writing a computer program,  in essence, and that program is an executable, which runs on the platform making calls via a framework API to load assets and data.  There may be tools to create data like levels and maps into a form that the framework API calls can consume.  But those tools only exist as part of a set of programmer's productivity helpers, and typically its possible to edit that data using other tools if needed.  
  • Essentially in the engine case, your game is NOT a program, its all data.  The engine is in charge, and you provide your game as a package of data for the engine to operate on.  The engine has a combined editor and previewer that encapsulates the entirety of your creative process, capturing your scripts, assets and other inputs into a package and giving an almost-real-time view of the game.

What is it that we get from game engine makers, like GameMaker, Adventure Game Studio, Unity3D, Unreal Engine or CryEngine?  They ship pre-packaged functionality, such as "place that quad over there with this texture on it", and "apply that animation to this object node".  You provide a package of data, which includes visual assets such as images & models, and logic assets such as scripts, that the game engine loads and at various times to render and evaluate.

Framework eg Sprite Kit vs an Engine
What is the real-world implication of this?  Basically you can only do (easily) what the engine provides for.  If you write a script or make an object that invokes cool engine functionality you can move mountains and make magic.  But when you try to just make a button behave like you want, and the engine doesn't support that it becomes ridiculously painful.  Mountains of code or even an external plugin has to be used.

  • With an engine
    • some incredible things are easy, and 
    • easy things are (often) strangely hard. 
    • publishing/shipping is way harder than it should be 
  • With a framework API 
    • everything is possible, and 
    • easy things are (often) a bit hard
    • shipping is what they do best
These attributes mean that engines are great for prototyping (as long as your prototype is a game that the engine can easily make) but things get hard quickly when you try to exert your will and design intent over the game; and also when you start to get closer to publishing and want to integrate platform API's for things like In-App Purchases.

Having said that engines like Unity are incredibly powerful and talented 3D programmers have produced a lot of common 3D rendering functionality into a tightly honed and well-documented beast which you can call on to get your game up and running quickly.  Of course you don't get this for free: a professional studio has to pay $1500 USD for each of Unity Pro, Unity iPhone and Unity Android - so a total bill of $4500 USD (or around $6000 AUD) per seat.  And then you pay that again when Unity goes up a major version number.  Its worth every penny - if you need that 3D functionality.

The essential trade-off is that particular engines are well-suited to producing a particular type of game.  In fact most engines already have a type of game in mind.  Unity is ideally suited to games where a 3D avatar in either 1st person or 3rd person is running around a world, followed by a camera.

You can of course fix that camera, get rid of the avatar, and place a 2D orthographic scene in the view to thereby construct a 2D game.  This is kind of like using a Mack truck as a garden shed: you've got all this powerful 3D architecture under the hood, and your fixing most of it in place so that you just use the 2D side of it.  But as mobile devices get bigger and more powerful, and include 3D rendering hardware it turns out you can get away with doing this.

As a programmer however, you can do away with all this extra baggage and enjoy the following benefits:

  • faster load times (no 3D engine to load)
  • zero cost per seat development
  • less licensing hassles
  • traction with Apple
  • immediate access to Platform API's
    • App Slicing
    • In-App Purchases
  • open source community
    • 3rd party stuff often $0
What are the drawbacks:
  • You need a programmer
  • Non-tech team member friction
  • Less off-the-shelf "store" assets
  • Code is not cross-platform
One of the difficulties with Sprite Kit is that many artists, animators and other creative professionals who are not programmers do not have experience with it yet, and thus find it hard to directly contribute their assets to it, and work with the tool set.

However I think this will change as Apple has a huge commitment to making coding with Swift and Xcode more open and available to the wider creative community.

The Sprite Kit route was a no-brainer for me as I have a career as a software engineer behind me in my game development.  Also I had my previous experience with Cocos2D which has a very similar API.  I don't need the features that Unity excels in such as 3D.  As a founder of a studio I don't want our IP saddled permanently with the licensing and lock-in hassles of being welded to Unity3D - which is a proprietary technology.  Unity also likes to monitor your games so that it can tell if you're adhering to the licensing conditions and it requires you to notify your players of this.  Basically for me its about having control over my game and my IP.

Swift, and pretty much all the Xcode & Apple toolchain is Open Source and Xcode itself is at the end of the day just an IDE, so there is nothing stopping me editing my code in JetBrains AppCode or other tools.  I could edit my assets in other tools such as for example Texture Packer, and TileEd.

Want to give Sprite Kit a serious try for your studio's next game?  I strongly suggest going and buying Ray Wenderlich's PDF book "2D iOS & tvOS Games by Tutorials".  They update their stuff and you get the updates for free, and despite the title its not just a starter book, it teaches you 90% of what you need to get going, and gives a huge bunch of sample code as well.

Your mileage may vary.  But have a look at the pros and cons, and especially try to think of the longer game if you're a professional studio, or consider that you might want to be a buy out option so that you can at some point exit your studio.  Due diligence and buy-out exits are much easier when you have the fewest possible licensing hassles linked to your IP.

I hope this article helps, and if you share some of the same aspects that I do when it comes to game development you can be clearer about your choice of engine or framework.

Thanks for reading!

Sunday, October 25, 2015

Block Twitter Trolls with GGAutoblocker

Because I'm an indie game developer, social media is basically the only way I can afford to promote my games, and thus pay the rent.

Without the budget of a big studio to pay for advertising & marketing getting on Twitter, Facebook, Google Plus and a bunch of other sites and forums is the only way I have of effectively communicating to folks about the games I build.  That means "just get off the Internet" is not an option for me.

But guess what else - apart from the game playing public who might be interested in my stuff - is on the internet? - Troll Hunter
Trolls.  Folks who love to attack, based on gender, or anything they perceive as weakness, and who use tactics ranging from obscure ranting arguments to outright threats to make life on the Internet into a living hell.

Well, it turns out there is something you can do about it - block them!  

But wait I hear you say, can't they just change from the last anonymous account they used to yet another new one?  Aren't I just going to be playing whack-a-mole waiting for these idiots to crop up on my feed before I block them?

This is where you need some help from the professionals!  An engineer named Randi Harper has come up with a tool called GGAutoBlocker which automates the pain of keeping up with block lists, at least so far as Twitter is concerned.

Here's how to use it. You might want to keep this page open on say the left side of your screen, while you open a new browser window on the right side. Then start by right-clicking (and choose open a new window) this link to GGAutoBlocker which will take you to step 1.

This is the site (which is actually a page in Randi's blog) which has two links you need.  Right-click the first one and open in a new tab, to get to step 2.

By following the link from the GGAutoBlocker page you'll find yourself on's website where you can sign up to use their Twitter blocking services, by hitting the sign-up button.

The sign-up button will take you to a page that allows's web-app to access Twitter on your behalf.  Sign in here with your Twitter credentials.  Make sure you use the Twitter credentials - username & password - that you use for the account you want to be protected by the block list. Is it safe?  Its as safe as any service these days, and if you later decide you don't want doing stuff on your behalf you can go into your settings on and nix the permissions.

Now you are all signed up to use BlockTogether, you need to get to the specific GGAutoBlocker block list.  Go back to the tab from Step 1 with the GGAutoBlocker page, and click the link for the actual block list. You're one step away from blocking Twitter trolls!

You should now have the GGAutoBlocker block list page up on listing thousands of trolls to block.  Now you can just click the blue button to block all the trolls on the list!

What if Someone is Wrongly Blocked?

What and GGAutoBlocker is doing is recording & automatically blocking all the trolls that were identified by Randi's automated scripts.  Its really the same thing you can do manually by blocking someone on Twitter.  Now there's of course a chance someone you really wanted to hear from was blocked but you can fix that in a second by just using Twitter to unblock them.  There's more advice about how that works on's website.

This Only Works for Twitter - what about Facebook & other sites?

That's true.  You could support Randi and other's in their work on OAPI which is trying to do more to prevent online abuse. Until more tools become available there are still good privacy controls in Facebook, Google and other services that you can use to block people.  Sorry its so horrible out there.

Isn't it Wrong to just Block People?

No, you don't have to listen to people whose goal it is to hurt you.  They might have a bunch of free speech arguments, but really they don't care about anyone's freedom except their own ability to freely cause harm.  Randi has a bunch more on this topic on her "Frequently Yelled Statements" page.  I like how its called that instead of "Frequently Asked Questions".

Sarah, you're a Terrible Person for Supporting This

No, actually I'm really not.  For anyone determined to push this line I say "Just go ahead and make a comment so I can block you".  :-)

But seriously your freedom to speak does not extend to this forum which is my own blog.  Here I can block comments if I like.  If you want freedom to attack people go and do it elsewhere.

Freedom of speech does not guarantee me - or anyone else - listening.

The People behind this GGAutoBlocker are Terrible People.

That's what's called an Ad Hominem attack.  There's a lot of inflated claims, and just plain falsehoods generated by the very trolls who are blocked by this tool.  The internet troll's stock in trade is fabricating things & wildly exaggerating others to attack, defame, gaslight & discredit anyone they take aim at.  Blocking such liars is the first step to taking away their power to hurt folks.


I hope this guide helps someone and if you have any relevant comments feel free to leave them below.

Tuesday, September 8, 2015

CPAN modules on Mac OSX

Got problems with PKG_CONFIG_PATH on Mac when trying to install Perl modules via CPAN?

Update: take care, see message at the bottom of this post BEFORE typing any of the commands listed here.

Maybe this will help.  First some background.

I wanted to write a Perl script and use the Text::Hunspell perl module plus whatever dependencies it required.  I know from experience its a pain to install a module with all its dependencies, so I usually use CPAN for that stuff.

To access CPAN on Mac just open a Terminal window and type

perl -MCPAN -e shell

That will take you into a shell environment for the CPAN command line utility, from where you can first configure CPAN (usually pretty much automatically by hitting return to accept all its defaults) then install packages via:

install Text::Hunspell

You can discover the names of packages you might want by browsing CPAN itself using your web browser.  For example if you're looking for XML parser modules just type "xml parser" in the search box.  There heaps and heaps of great free modules there for just about anything you can imagine.

Now the problem comes on Mac where your module you want to install depends on some binary program that you've installed, but which Perl cannot find.  Because Perl is built on C and has a Unix like behavior for compiling and otherwise dealing with binary programs it will fall back to trying to use the pkg-config utility to find the binary programs.

In my case I had installed Hunspell from the source package available on their website.  Once I had downloaded the .tar.gz file I built it via:

cd ~/build
tar xf ~/Download/hunspell-1.3.3.tar
cd hunspell-1.3.3
sudo make install

If you're trying to do the same thing, or trying to build some other software and are getting errors about the compiler and toolchain, make sure that first you have installed the command line version of the Xcode tools.  There's a good guide on this Rails site.  If you can type

gcc -v

and get something like

Apple LLVM version 7.0.0

Then you already have the tools.  Otherwise follow the guide to make sure you have Xcode installed and then run

xcode-select --install install then.

OK.  We have a new binary program - in my case hunspell - installed in /usr/local - and now we want to hook up Perl to it but there is a problem.  Perl won't look in /usr/local by default and thus you will get failures from CPAN's shell when you try to install.

To fix this in my case I installed pkg-config from the handy installer on this page.  You want the link that says Download: PkgConfig.pkg - once downloaded install it as usual for .pkg files but note you'll need to right-click and "Open" it as its not signed.  Note that pkg-config gets installed under /opt/pkgconfig/bin.

Once its installed you'll need to tell your shell how to find the relevant files: add these lines to your bash profile by editing the appropriate file:


...and adding the following lines:

export PATH="$PATH:/opt/pkgconfig/bin"
export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig"

Now you're ready to run the Perl CPAN shell again.  One more thing however:  if you are going to install CPAN modules for the whole of your Mac OS X system, rather than just to your local user account you may run into issues.

If you run the following command:

sudo perl -MCPAN -e shell

to install as root, or if you ask Perl to go to sudo for you, then your build environment may not get the environment variable that you so painstakingly added to your bash profile.  To fix this pass the -E switch to sudo like this:

sudo -E perl -MCPAN -e shell

Now you should be good to go ahead and install loads of cool Perl modules!  Have fun.

Update: If you run perl unprivileged by typing 

perl -MCPAN -e shell

Then you will get a prompt inside CPAN asking you if you want to use local::lib - if you accept that you'll get a mysterious environment variable added to your .bashrc that causes your perl installs to go into your home directory, e.g. ~/perl5

This just wasted several hours as following that CPAN could not find those modules and you get piles of errors about modules not found, wrong versions, and missing dependencies.  It's because the MakeMaker is installing its stuff into the ~/perl5 directory as instructed by PERL_MM_OPT.  But CPAN is not looking there.

To discover if you've hit this issue type 


in a Terminal and check if one of the variables is PERL_MM_OPT.  If it is then local::lib as implemented by the CPAN shell has modified your .bashrc for you.  Nice.

Just edit .bashrc to remove the offending lines (they're documented here) and then start a new Terminal window to get the shell environment minus the option.  Now to be safe delete the ~/perl5 directory, the ~/.cpan directory and start again from scratch with your privileged CPAN using sudo as above:

sudo -E perl -MCPAN -e shell

If you really want to use local::lib then try looking up separate doc for that.  Its beyond the scope of this post.

Thursday, August 6, 2015

Fixing SKLabelNode performance issues

I'm loving working with the Sprite Kit API for game development.  Using all the tools I'm effective with, that other software dev folks would know: a good code editor, nice tool chain and a well-documented API; I can really get stuff done.

In a primarily graphical environment sure you can lay things out visually, but for the thing I'm currently trying to do - layout a virtual keyboard for a game - I need to do it programmatically so I can cope with changes in screen size.

But: I found some issues with the layout code pausing big time, during the load sequence.  This was revealed by testing on a 3 year old iPad Mini that I keep around just because its great at exposing these sorts of problems.

Folks, do not EVER rely on testing your game or app in the simulator.  Use a device ALWAYS.  Once you have your project mostly done and discover you've introduced some horrible performance issue, its going to be impossible to find.

This one manifested as an ugly lag in the response after hitting the "Play" button and it needed to be fixed.  I used the Xcode tool "Instruments" and fired up the Time Profiler to drill and find the culprit.  If you've never used Time Profiler before there's a good Ray Wenderlich tutorial on it.  I also used a home grown time logging tool, the code for which I have stuck up on GitHub.  Being able to instrument my code by hand is a great complement to using the Instruments tool.  Here's some of the output from my tool:

Time stamps:
    Before press play button - 0.0
    Play button pressed - 0.00773762501194142
    Starting transition - 0.322784499992849
    Game Scene didMoveToView start - 0.323094458348351
    Scheduled music - 0.323781083337963
    setupGamePlay: done setupCarousel - 0.329451166675426
    setupGamePlay: done setupMonsters - 0.678052625007695
    setupGamePlay: done setupMissile - 0.945051541668363
    setupGamePlay: done targetMissileAt - 0.94512124999892
    Setup Gameplay - 0.945148375001736
    About to create keyboard - 1.07598399999551
    addKeys: About to calculateKeyCapMetrics - 1.07624216665863
    About to create SKLabelNode - 1.07625199999893
    About to set label text - 1.07641391665675
    About to set font size - 4.5479717499984
    About to set font color - 4.55641954168095
    Done with label - 4.55644533334998
    calculateKeyCapMetrics: about to setup frame - 4.56316420834628
    calculateKeyCapMetrics: about to calculate frame - 4.60020420834189

    calculateKeyCapMetrics: done - 4.60023920834647

There's a 3-4 second delay there while the SKLabel's text is set! That's crazy!

Luckily that is a one off, and subsequent calls to set the text with the same font turn out to be fast. Very interesting. More investigation with the Time Profiler:

It reveals that the iOS True Type font system is having to load the font - its a custom one that I added to the project, not one that ships with iOS. Its during the first load and unpacking all the font information that the delay is incurred. I guess there might be some reading from flash of the iOS device in that as well.

Right: so that makes it a good candidate for pre-loading after the start scene has been displayed but before the player presses the start button.

So, off I got and implement pre-loading of the font.
    func preloadResources() {
        let label = SKLabelNode(fontNamed: "Ancona-Ex")
        label.text = "preload"

    override func update(currentTime: NSTimeInterval)
        if !preload

With that done, time to run a new profile session:

Time stamps:
    Before press play button - 0.0
    Play button pressed - 0.00989962500170805
    Starting transition - 0.318517291656462
    Game Scene didMoveToView start - 0.318650125002023
    Scheduled music - 0.318978958326625
    setupGamePlay: done setupCarousel - 0.324560000008205
    setupGamePlay: done setupMonsters - 0.69843762498931
    setupGamePlay: done setupMissile - 0.969889125000918
    setupGamePlay: done targetMissileAt - 0.969957374996739
    Setup Gameplay - 0.969982250011526
    About to create keyboard - 1.11275391667732
    addKeys: About to calculateKeyCapMetrics - 1.11366166666267
    About to create SKLabelNode - 1.11367308333865
    About to set label text - 1.11383529167506
    About to set font size - 1.11686108334106
    About to set font color - 1.12038704167935
    Done with label - 1.1204140833288
    calculateKeyCapMetrics: about to setup frame - 1.12638933333801
    calculateKeyCapMetrics: about to calculate frame - 1.1502004583308

    calculateKeyCapMetrics: done - 1.15022912499262

Time to create the label text has now dropped away to nothing! Nice.

Hope that helps someone else working with SKLabelNode and custom fonts.