Friday, May 25, 2018

UE4, Perforce, Plug-ins, and Special Characters

Even though I'm not on the university's payroll for the summer, I have spent a lot of time in the lab the last three weeks. I will be writing a project retrospective about the Fairy Trails project in the coming days, but suffice it to say for now that, as in Collaboration Station Enhanced, there have been some complications getting the iOS build together. I estimate that I have spent roughly 15 hours in the studio working on Fairy Trails since the semester ended. The first problem was that UE4.18 contains a defect wherein the shipping build for iOS games accesses a private API for the Metal rendering system. This was supposed to be fixed in a QFE, but it actually wasn't. One alternative is to rebuild the engine from source with the offending code fixed, but I decided to go with what seemed the more prudent approach: upgrade to 4.19.

In order to make sure there was no cruft left over from 4.18, I created a clean workspace. I rebuilt the iOS app and got ready to submit it for review to the App Store, but that's when I noticed something strange: the app icon had changed from the custom one to the engine's default. I looked at the Project Settings for iOS, and sure enough, many of the icons were not set correctly. Why would an engine upgrade change that? I put the new icons in and carried on. I kept running into problems, though, and searching the Web gave me some conflicting information about what was broken in 4.18, what was fixed in 4.19, and what was not quite fixed in 4.19. Many hours were spent fiddling with file names, resizing icon images, and even ripping open an IPA and poking around inside of it.

Frustrated and uncertain whether I had just introduced new problems, I decided late this morning to do set up a new, clean workspace to work in. I had pushed so many bits around in the other one that I wasn't sure I accurately remembered what I changed any more, and it certainly wasn't reproducible. I looked at the settings in the clean workspace... and the icons were wrong again in the project settings! What gives?

As I put the icons back in the settings window again, I happened to have the log open, and I saw that the version control system was actually generating errors each time I set an icon. The complaint was a bit vague, but the essence was that it didn't know how to handle file names with '@' in them. At first blush this seems fine; who in their right mind would put special characters into a file name? However, doing so a convention for Apple icon files, where a standard icon might have a file named Icon40.png for a 40x40 icon, but a high-res version might be called Icon40@2x.png for 80x80 or Icon40@3x.png for 120x120. Here, then, was a source of many hours being lost! When my student team members had set up the icons, they confidently used the UE4 Perforce plug-in integrated into the engine, but (a) they didn't see the messages in the logs and (b) they didn't verify that the list of files in the changelist matched what they had actually touched. Only the low-res icon files were therefore tracked in version control and checked out into the clean workspace. This explains why one of my student team members was able to create IPA files with no problems: he was working in his own workspace, where the files were sitting happily in the Intermediate folder while not being properly tracked in the Build folder.

It was not the first time that blind trust in the UE4 integrated plug-in caused us problems. We follow the recommended convention of having a "ToImport" folder that is in the root folder of the project, and this folder is where we keep raw assets for import into UE4. This way, if someone wants to edit, say, a texture or a sound, they check out the file, make the change, and easily reimport it into UE4. However, the Perforce plug-in does not check for changes in the ToImport folder since it's not within its purview. This led to students making changes and trusting in the plug-in, only to have the .uasset files submitted without the corresponding raw assets.

In the future, I need to be more strict in warning the students against trusting the Perforce plug-in. It provides a convenient view of what assets are checked out by other developers, which is something the team used regularly and found very valuable. However, for the actual check-in process, I need to make sure they're using something like P4V, with it's excellent "Reconcile offline work" feature.

As I write this, the Fairy Trails app is in queue to be reviewed for an App Store listing. I am working on a conference paper with a deadline right around the corner, but I hope to share some stories about this past semester's immersive learning project in the next few days.

No comments:

Post a Comment