RetinaPro for NGUI - Easy management of multiple devices pixel / screen resolutions

Very excited that our first Unity Asset Store tool is now available!

RetinaPro for NGUI On Unity Asset Store

I've been using this tool (or more accurately a version of it) for quite a while now and decided it was worth submitting to the Asset Store. If you are a user of NGUI (which is my fav. 2D SDK) you'll know that when maintaining your atlases it's easy to make mistakes especially if you have to consider 5 different sets of art (e.g. iPhone, iPhone@2x, iPad, iPad@2x, iPhone-568h@2x).

It's saved me 100's of hours across multiple projects by making it really easy to update / refresh all of the art assets per device into their respective atlases.

Feedback is appreciated. I'd like to make this the best tool that it can be.

 

Hi Ian,this looks very interesting,and could potentially save me a ton of time on my project,as unfortunately I dont get to work with Unity fulltime Im hoping to deploy my app on android as well as iOS platforms.In your description I don't see any specific reference to android devices,so Im just wondering is it possible to configure atlases for android devices also? Thanks in advance!

 

Thanks for your interest. I haven't specifically mentioned Android devices in the description because unfortunately it's not something I can easily test. However, it should work - there aren't any specific iOS requirements. It's all data driven using data the user supplies, so I'd say go for it. If you do run into issues contact me at the support email address and I'll do my very best to resolve your issue ASAP.

 

Hii it sound really cool. Does it work with FastGUI?

 

Thanks. I've never used FastGUI before. However, if you can control the destination asset folder that FastGUI copies your files to then I'm guessing you can.

RetinaPro requires the following folder structure:

Assets/Textures/rp_atlases/<device_name>/<atlas name>/file.png

Where 'file.png' is an art resource. FYI, to support the way NGUI handles atlas references (allowing you to swap device types at runtime) each atlas must contain the same filenames. e.g. if you have an image called 'button.png' for one atlas/device then all device versions of that atlas must share that same filename. This is because the sprite holds a reference of the image name and when you swap out the atlas it needs to be able to find that same image (albeit in another atlas at a different size).

Note: RetinaPro comes with a runtime script that handles all the atlas reference loading / swapping so you don't have to worry about the details. The included example scene shows how this works.

FWIW, you can modify the base Texture folder for RetinaPro if you're ok with changing the RetinaProConfig script. Note: future versions of RetinaPro will likely expose this via the GUI.

Code (csharp):

1.     public const string atlasTextureFolder = "/Textures/rp_atlases/";
2.  

 

• Switched retina pro data file from binary to xml (makes it easier when
  working with teams / merging).
• Upon pressing the 'Update button (see any RetinaPro window), any
  previous binary RetinaProBinData.txt file will be updated to the xml
  version.
• Fixed get_dataPath error.

 

This works on Android?
Can I use it on different Android aspect ratios?

 

Previously I said this. Give it a try and contact me if you run into issues.

 

I am getting a ton of MissingReferenceException errors on Unity 4.1 and NGUI 2.3.6 when I am trying to create the atlases. Any idea why this might be happening?

The errors are:

MissingReferenceException: The object of type 'Material' has been destroyed but you are still trying to access it.
Your script should either check if it is null or you should not destroy the object.
UnityEngine.Material.get_mainTexture () (at C:/BuildAgent/work/7535de4ca26c26ac/Runtime/ExportGenerated/Editor/Graphics.cs:1605)
UIDrawCall.Set (.BetterList`1 verts, .BetterList`1 norms, .BetterList`1 tans, .BetterList`1 uvs, .BetterList`1 cols) (at Assets/NGUI/Scripts/Internal/UIDrawCall.cs:251)
UIPanel.Fill (UnityEngine.Material mat) (at Assets/NGUI/Scripts/UI/UIPanel.cs:941)
UIPanel.LateUpdate () (at Assets/NGUI/Scripts/UI/UIPanel.cs:993)

NullReferenceException: Object reference not set to an instance of an object
BetterList`1[UnityEngine.Material].Contains (UnityEngine.Material item) (at Assets/NGUI/Scripts/Internal/BetterList.cs:216)
UIPanel.UpdateWidgets () (at Assets/NGUI/Scripts/UI/UIPanel.cs:851)
UIPanel.LateUpdate () (at Assets/NGUI/Scripts/UI/UIPanel.cs:983)

 

FWIW, I spoke with aikitect over email and the issue seems related to atlas names that contain spaces. aikitect removed the spaces and it fixed the issue. Having said that I did try to reproduce the issue here and could not.

 

We just bought it, and have already some issues, it's giving me issues with UIFont.cs. We are using Dynamic Font, so we modified the C# script.

This is the issue:
Assets/RetinaPro/Editor/retinaProAtlasWindow.cs(320,46): error CS1061: Type `UIFont' does not contain a definition for `pixelSize' and no extension method `pixelSize' of type `UIFont' could be found (are you missing a using directive or an assembly reference?)

 

What version of NGUI are you using? Versions prior to NGUI 2.3.2 require a fix made to a few of NGUI's scripts. The details are in the readme.txt file included with the RetinaPro package. One of those fixes is to add the pixelSize functionality to UIFont.

 

Ohh, sorry, I did that and try to open Windows/RetinaPro/Devices and Unity crash, doesn't say anything, just stay freeze and "Not responding"

 

Sorry you're having issues.

First of all, please send me the RetinaPro/Resources/RetinaProData.txt file to the support email address (see the readme.txt).

Given that you've modified RetinaPro and had an older version of NGUI installed. Can I ask you to try the following?

- Open a new blank / scene.
- Delete the RetinaPro folder from your Asset folder
- Update NGUI to latest version (I think it's 2.3.6)
- Reinstall the RetinaPro package

 

Fantastic plugin, this was exactly what I was after! Thanks for making this.

I have a question, I havent tested this yet, just got started setting it up, but can I use several fonts with this? I need to use at least two fonts for my game, so can I just add font atlases to Retina Pro and it will automatically work? Can I combine them all into one font atlas to reduce draw calls?

 

You're welcome!

Right now RetinaPro only supports one font per font atlas. So yes, you can use as many fonts as you want, but you can't currently combine them into a single atlas. In practice I've never found this to be a problem but I do understand your needs may be different.

Just add a new atlas and check the isFont for each font you want to add.

 

Great, that sounds good! I will just create more atlases then.

One more question, in your example, I see you have set NGUI's Scaling Style to "FixedSize" instead of "FixedSizeOnMobiles". Is it more ideal to use the latter for mobile, or should I set it to FixedSize too?

 

That option on NGUI's UIRoot script controls how it calculates the 'height' using minimum height, maximum height and manual height properties. RetinaPro sets all three properties to the device setting height. In that case setting it to 'FixedSize' is the same as selecting 'FixedSizeOnMobiles' and just setting the manual height property. If I get use cases from yourself or other customers where we need more control here I will add that functionality.

 

Thanks! That clears that up.

Another issue; when using the iPhone @x2 preview in Unity, the preview gives me gigantic images which are almost the same size as the iphone standard. The iPad and iPad x2 previews are however perfect. This makes it a bit hard to evaluate my work for the iPhone in the editor, but is there a way around this?

Also: when setting the Preview to @iPhone x2 , the manual/min/max height goes to 320, shouldn't it be going to 640?

 

What are the settings / values of the "@iPhone x 2" device?

 

They are at default (iphone@2x : pixel size: 0.5 w: 960 h: 640 and iphone: pixel size:1 w:480 h:320).

 

Did you set the size of the game window to 960x640? Not sure what else could be causing this - other than really large art files (i.e. larger than they should be).

 

Yes, the preview window is set to 960x640 as you can see in this screenshot.
Also, I am having trouble using the Make Pixel perfect button, it never quite gives me the correct size for some reason. Right now, the left top icon is it at iPad Retina size at 96x96, but it should be at 48x48. It seems like the Preview atlas set determines the pixel sizes set on bitmaps/labels, somehow.

 

The image has the preview window set to iPhone Tall (640 x 960). Should it not be iPhone Wide (960 x 640)?

Can you verify the image sizes under each of the Textures/rp_atlases/<device>/<atlas> folders to make sure they are the correct size. With this particular icon (are you referring to the GC icon?) what are the dimensions of each art file (for each device)?

 

One other thing - can you verify that each UI element (UIButton etc.) is pointing to the atlas reference (i.e. myAtlas) and doesn't have any device post fix on it (e.g. myAtlas~myDevice).

 

Well, my game is in portrait mode, so it has to be in iPhone Tall mode. Could that be the problem?
I have checked all of my textures, and they are correctly scaled. ie. the GC icon I showed is 96x96 for iPad Retina goes down to 48x48 on iPhone Retina/iPad.

After some testing and resetting up my scene, it seems to work better now. I have to turn on and off the preview a couple of times for it to work, but at least now I am getting decent results and not crazy-sized images. Very strange, but at least it works.

I

 

The preview tool isn't on / off. What it does is go through all the atlases in the resource folder and sets the atlas reference to the selected device. That's why it's important that all NGUI ui components refer to the main atlas (the one without the device post fix).

Regarding the resolution - yes, change the iPhone@2x device to be 640x960. The runtime atlas controller needs to be able to match the screen resolution against your device.

 

Ah I see. That makes sense. It's still a bit confusing in terms of setting up buttons and setting their pixel sizes in the editor though, but I'll try to work around this.

I will change my resolution around on all devices to accommodate my portrait mode then. Maybe you should add a button in the Device window that asks which orientation the game is in? I am probably not the only one making games in portrait mode, so this is nice to be able to change quickly.

 

You shouldn't have to set any pixel sizes on buttons. Any chance you can send me an example scene with the issue you're having?

It's important to be able to have a different atlas for portrait vs. a different atlas for landscape. However, I do see a case where the atlases could be identical and it would be nice to be able to save the wasted space and just have one atlas for both orientations.

 

Sure, do I just send you the scene file or do I have to send the entire project?

I tried inverting the pixel sizes of the devices, but I think this just made everything worse. Buttons started becoming huge both in the editor and the device. I think I have it working to a certain degree now, but neither of my two fonts are pixel perfect on any of the device I tested on (iPhone 5, iPad 4)

 

Create a test case showing the issue and ZIP up the entire Unity project.

 

After reviewing the project in question I've come up with this list of gotchas / helpful hints (I will add this to RetinaPro's readme.txt file for a future update):

- Textures that are not power-of-2 dimensions get converted by Unity's importer to be nearest-power-of-2. This causes issues when you're trying to display something "pixel-pefect". Solution here is to always make sure textures are power-of-2 or make them use the next size up.

- At runtime RetinaPro tries to match a device screen resolution to the current game resolution. If it finds a match it selects that set of atlases. If it fails it tries to match based on closest aspect ratio. It reports failure to match a device type as a warning in the log. (Note: 640x960 is not the same as 960x640).

- In NGUI 2.5.0 the sliced sprite is now a type of UISprite. It unfortunately uses the transform's scale to represent the size of your sliced sprite. The problem is there isn't any way to correct for pixel-perfect in this case. Workaround is to stick with UISprite / simple.

- Don't add BoxCollider components to NGUI elements as these will change size based on device screen resolution. Instead add them at runtime in Start() using:

Code (csharp):

1. NGUITools.AddWidgetCollider(mybutton.gameObject);

 

Ian gave me some fantastic support for his Retina Pro plugin and it is working perfectly for my project I wholeheartedly recommend this to anyone making mobile games/apps. Saved me a great deal of time.

Another tip I can give in regards to iPhone 5 is to remember to add it to the device list, at least if you are working in portrait mode as I am in my game.

 

Thanks!

 

Purchased the plug ...looks good !
Could you please make a small video tutorial for a standard setup ?
Is it recommended to use the same high definition atlas with different pixel size to save on application size for mobile devices ?
or every device needs to have its own atlas ?

 

Thanks!

I do intend to make one. I just haven't gotten around to it yet. The example scene is hopefully enough to get most people started. Feel free to reach out via the support email address or this forum thread.

Setup a RetinaPro device for every screen size that you use (treat landscape as a different screen size than portrait). You're not wasting space at runtime only in the final bundle. Tip: select the smallest screen size in RetinaPro's preview mode prior to building the player.

 

• Updated readme.txt to include helpful Hints and Common issues section
• Added retinaProUtil script; adds easy method to refresh UIWidget and BoxCollider sizes on UIPanels. Useful when activating a previously disabled panel.
• Added example script showing UIPanel visibility and refresh
• Added retinaProButtonActivate script replacement for NGUI UIButtonActivate

 

I just posted a tutorial / setup video to youtube. It's also available as a direct download here:

https://dl.dropboxusercontent.com/u/8270272/RetinaPro%20for%20NGUI%20Tutorial.mov

FWIW, I recommend watching it 1080p so that the small text is readable. Enjoy!

 

Thanks for the vid. This looks really useful. Will be grabbing it soon.

 

You're welcome.

 

Is it possible to add a script to change interfaces depending on devices ?
ie a different ui arrangement for iphone and different for ipad ?
many thanks

 

Yeah, it already handles that - drop the retinaProAtlasController script on a gameobject in your scene.

But I suspect I may not understand your question. Can you be more specific and perhaps describe the use case?

 

Thanks for the reply !
I would like to have a different arrangement of guis for iphone and ipad for example on ipad a sidepanel pops on from the side but on iphone a gui to pop from the bottom.
I thought of creating a script to enable and disable different gui roots depending on device accordingly but i imagine there could be a more elegant approach
Any ideas ?

 

Is there a reason you favor multiple UIRoot's vs. multiple UIPanel's?

I would build two UIPanel's, one for the iPad and one for the iPhone and activate the appropriate panel based on the current device type. When you activate the panel do this:

Code (csharp):

1.  
2. NGUITools.SetActive(myPanel.gameObject, true);
3. retinaProUtil.refreshWidgetPixelPerfect(myPanel.gameObject);
4.  

This will refresh the panel and ensure that it's pixel perfect based on the atlas reference. Let me know what you decide and / or if you run into issues. If you require an additional utility script to get this working with RetinaPro I can provide that.

 

Sounds Great !
will do that !

 

I have this but still not sure if I will use it.

Is the switching being done purely on screen resolution or on screen density?
http://docs.unity3d.com/Documentation/ScriptReference/Screen-dpi.html

Screen density seems to be the more accurate trigger, given there are two issues with making resolution independent apps: positioning of gui elements (via anchor in NGui) and scaling based on DPI.

ty!

 

The switching in RetinaPro occurs based on screen resolution. If an exact match cannot be made it tries a best match on the aspect ratio of the screen resolution.

If you're referring to switching an atlas based purely on DPI then in practice I'd say that you'll run into problems design wise. It's easy for artists / designers to target specific resolutions. They are known quantities in both size and resolution. One UI might look sparse if viewed on an iPad if it shared the same DPI an iPhone version.

FWIW, it would be fairly easy to change RetinaPro to switch based on DPI and you are welcome to modify it as such. If you do I'd be very interested to see the results. I could be persuaded to adding that to a future update. Let me know!

RetinaPro's strength is that you can easily create or refresh your atlases at the push of a button. Compare that to the using NGUI's / GUI in the unity editor for managing atlases. On a large project RetinaPro will save you hours of time and it also eliminates easy to make mistakes for example, updating an image in one device atlas and forgetting to update the atlas for some other device. Testing for those issues alone is very time consuming.

Hope that helps.

 

Thanks for the info.

Seems to be some dispute on NGui forum over the accuracy of the screendpi http://www.tasharen.com/forum/index.php?topic=832.25

It would be nice to get a definitive reply from Unity (though Arenmook should be pretty definitive I guess as he's working with Unity on the Gui now!)

 

You're welcome. Let me know if you have any further questions regarding RetinaPro.

 

• added support for portrait / landscape orientations
• added retinaProIgnoreUIRoot script. Drop this script on a gameobject that has a UIRoot script attached. Doing this will cause RetinaPro to ignore this UIRoot and thus not modify the manual height setting