Tutorial: Fast migration of Graphics 1.0-based projects to Graphics 2.0

Graphics 2.0 Demo Contest Winners

Graphics 2.0 iconIf you have a Graphics 1.0-based project and want to take advantage of all the new features, updates, and fixes in Graphics 2.0, then you can migrate your code with the help of our Graphics 2.0 Migration Guide.

In this post, I’ll talk about the Graphics 1.0 Compatibility Mode. This is probably the fastest path for existing projects. However, you will not be able take full advantage of new Graphics 2.0 features (see Limitations below).

Graphics 1.0 Compatibility Mode

With Graphics 1.0 Compatibility Mode, you can use most of the original Graphics 1.0 behaviors. For many projects, all you have to do is add one line to your config.lua file and you’re done!

application = {
   content = {
      graphicsCompatibility = 1,  -- This turns on Graphics 1.0 Compatibility mode

      width = 320, height = 480, scale = "letterbox",

Real-World Scenario

“Great, but what about a complex, real-world project?”

Challenge accepted! Earlier this morning, we converted a complex, real-world project, Major Magnet, to Graphics 2.0 using V1 Compatibility Mode. The steps were trivial:

  1. Modify config.lua as above.
  2. Include the sprite legacy library.

The second step was necessary only because Major Magnet relies on two 3rd-party libraries: ParticleCandy and TextCandy, which in turn rely on the legacy sprite library. So, all that was needed was to copy over and require() the sprite.lua file inside the project.

Enterprise Projects

If you’re a Corona Enterprise developer, you can also take advantage of the 1.0 compatibility mode. The one thing you’ll need to do is update your projects:

  1. iOS: Ensure that the project links against CoreVideo.framework and GLKit.framework.
  2. Android: Update AndroidManifest.xml so that it requires OpenGL-ES 2.0.


Graphics 1.0 compatibility mode works great in a lot of situations, but it’s not for everyone. Graphics 2.0 features will only be supported in true 2.0-based projects, so if you want to use the power of Graphics 2.0, you should migrate your code to 2.0 instead of relying on the compatibility mode.

If you’ve been experimenting with 1.0 compatibility mode, some new features may appear to work, but there’s no guarantee that they’ll continue to work under V1 Compatibility, especially in subsequent releases and/or platforms. Relying on Graphics 2.0 features while in 1.0 compatibility mode is done at your own risk!


If you’re using the widget library, most widgets work as intended. However, newTableView() and newScrollView() use a new Graphics 2.0 feature (containers), so some changes will be required in regards to positioning these widgets (usually they will be offset by half the width and height). Please see the Migration Guide for details.

3rd-Party Libraries

If your project uses the following 3rd-party libraries, here are some tips and observations based on what I’ve seen:

  • Particle Candy: This requires the old sprite library, so use the sprite legacy library. [UPDATE]: ParticleCandy has been updated for Graphics 2.0.
  • Text Candy: This also requires the old sprite library. [UPDATE]: TextCandy has been updated for Graphics 2.0.
  • Director: This only seems to work in Graphics 1.0 Compatibility Mode. You may experience touch issues if you run this directly as a 2.0 project.
Share this post....Share on Facebook0Share on Google+6Tweet about this on TwitterShare on LinkedIn0

This entry has 13 replies

  1. Alex says:

    I am getting lots of issues with groups positioning, after migrating a few Kwik projects to the new API. If I set the group.anchorChildren = true, the group gets the original position. However, setting the group.anchorX/Y (in the past I used setReferencePoint to midcenter) and trying to rotate it (using transition), rotates the group as the center was (real position) 0,0.

    If I set group.anchorChildren = false, the rotation works fine but the group position goes to (real position) 0,0, instead being rendered in the desired position (for example, the center of the screen).

    Have you seen that?

  2. Star Crunch says:

    Well, I dove right in. :) Not as bad as I expected, but a LOT to change; thankfully mostly just a few features, it seems. And a few bug reports to file. :(

    Sort of a related question: Is there a (reasonably future-proof) way to determine, from code, if we’re running in Starter or higher? Seeing as you can play with the features in the simulator, there’s a few things I’d like to make go either way.

  3. Stephen says:

    That Sprite legacy library really helped me migrate my project. I’m relying heavily on the old sprite library (I know, I know) and the Legacy library probably saved me a week or two of work. It took me about a day to get my project working with G2.0 in compatibility mode so now I won’t miss any of the new bug fixes and non graphics related bug fixes. Thanks for that Library!

  4. I am having issues with text sizing since updating to the new public release (2013.2076). The problem occurs when I get and set the size of the text after creating it. For the sake of illustrating my point, if you create text with a fontSize of 20 and then get the size with TextObj.size it comes back as 10 on iphone4.
    However setting the size using TextObj.size = 20 results in the size doubling to 40.
    I remember this happening a year or so ago and the way round it was use display.contentScaleX with the size returned, but this was fixed somewhere along the line of daily builds, and now its back.
    Can anyone advise on this? Is this a bug?

    • Please can someone at corona look into this text size issue as soon as possible. It’s set me back a day trying to figure out what to do about it and I don’t know which previous daily build to go back to.

  5. jolzy says:

    Walter can you tell me if i wan to use the previous public build would that be a problem to publish my game to appstore and the android market?

    I dont need to use any of the advanced graphics stuff and I am still using the old Sprite sheet and iI guess the legacy Sprite.lua. but the other issue is the particle candy guys only allow to download the new version wich is only compatible with the 1276

  6. @jolzy: just drop us an email ( info -at- x-pressive.com ) if you need to obtain a previous (Graphics 1.0 compatible) version of Particle Candy, Text Candy or Widget Candy. We did not receive such requests yet, so we think these are rare cases only -but if you started a huge project some time ago and don’t want to migrate to Graphics 2.0 for now, we can help you out for sure.

  7. Felix B says:

    I see the same problems with the text size.
    After the update (I dont know which, but I assume that its the one with the graphics 2.0)
    all my text is double the size then before…
    If I start now putting all sizes half, will I have to change that back within a few updates??

    Felix, whos crazy about all the problems with graphics 2.0

  8. Nick says:

    I have a project which uses the SpriteGrabber lib. I’ve successfully added

    local v1compatibility = require(“sprite”)
    [to main.lua]

    However, in SpriteGrabber, there’s another legacy call “require(“sprite”)”. I changed that to “local sprite = require(“sprite”)” — so I’m no longer getting crashes, but now having issues that the sprites no longer have the touch events assigned to them. Is this a namespacing issue? Any hints on how to modify the SpriteGrabber require statement to enable v1compatibility there as well?

    • Dougi says:

      Hi Nick. Did you find a solution to this one? Struggling with the same thing myself today.

      Does anyone know if there is an updated version of spriteGrabber that will work with the setting:

      graphicsCompatibility = 1

      …in the config file?

      I am actually using texture Packer (just updated it) and using the following line to grab a sprite with two positions:

      local baby = i.spriteSheet:grabSprite( “baby”, true, {pos1={1,1,1,0}, pos2={2,1,1,0}});

      Sprites are called baby-1.png and baby-2.png. This worked previously. Now I seem to get the first sprite on the sprite sheet regardless of any spritegrabber params.

      Any thoughts welcome please.


      • MrB says:

        same problem
        did you find a fix ?

Leave a reply

You may use these HTML tags and attributes: <a href="" title="" rel=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>