Gamedev File Structure

File structures for game development. Not as sexy as adding a new effect to the game's visuals. Nonetheless, it needs to be dealt with.

When I was starting my first game last year I was looking for this type of information for ideas and inspiration how to organize my projects, but I couldn't find any good resources. That rings extra true when you narrow it down to game development with Swift using Xcode.

This is a breakdown of how I organized my latest game project in Xcode, version control and storage.

Ever-evolving

I recently finished my second game¹ after having put my first game on hold for a while. Which kinda makes my second game the first, but more on that in another post to come.

I started the second game as I felt I had learned so much since I began working on the first game. I wanted to try a new structure of my approach to game development on a new fresh canvas. I will now go back and reapply this structure to my first game.

My game project structure did evolve a lot between the two games. And it is ever-changing and as I've now started pre-production on my third game, where I'm fine-tuning, streamlining and revising it even more.

But for now, let's focus on how the second game ended up being handled.

Code

I use Git to version control the main codebase and I keep the repository origin on GitHub.

This has worked out fine, as the games I've been working on are not that heavy on art and sound. The repository sizes has a small footprint.

The day I start a game that relies on more large assets I'll consider using Git LFS as the next step up.

In Xcode I organized my last game like this:

Game Repository
+-- Shared
    +-- Entities
    +-- Components
    +-- Scenes
    +-- UI
    +-- Audio
    +-- Log
    +-- Utilities
    +-- Preload
    +-- Assets
    +-- Level.swift
    +-- ECS.swift
    +-- GameData.swift
    +-- GameConfig.swift
    +-- GameManager.swift
    +-- SceneManager.swift
+-- iOS
+-- tvOS
+-- macOS
+-- Nexus
+-- GameMath
+-- Tools

A quick breakdown what goes in each folder/file above.

Entities / Components: The ECS, unique game mechanics.
Scenes: Different game scenes with all possible game states, including the main finite game state machine.
UI: The HUD, all-in game overlays and UI elements like buttons and labels.
Audio: My audio players and mixer. In my next game these are moved to the engine framework.
Log: Debug logging and plenty of signposts for measuring performance.
Utilities: Convenience methods and different extensions of Apple's frameworks.
Preload: Handles preloading from disk and the decoding of assets into memory and onto the GPU. This is now mature enough to have been graduated into my engine framework for the next game.
Assets: Graphics, sound effects, music, level data, json... You name it, it's here.
Level.swift: Constructs a playable level from data on disk.
ECS.swift: Game specific extensions of my ECS.
GameData.swift: Data persistent between levels.
GameConfig.swift: A central place to tweak game config and stats for entities.
GameManager.swift: Where it all begins...
SceneManager.swift: Fade in / fade out. Handles adaptation to different screen sizes.
iOS / tvOS / macOS: The unique code for each platform target.
Nexus: My lightweight game engine framework. Reduces common boilerplate code between games.
GameMath My math library. Fills in the blanks of all necessary math operations not covered by Apple's frameworks. Did I hear trigonometry?
Tools: Game specific tools. Mainly command-line. Converters, generators² and automation.

I have an old Mac mini with Xcode server that runs a small test suite for each platform when I make a new commit to the repository as an extra safety net to reduce the risk of breaking things.

Assets

The assets that are in the code repository above are the final, small, optimized exported versions. But then you need a location to work on the original source assets and store them, with versioning.

I've chosen Git LFS for that and I keep the origin repository on Azure DevOps as they have a generous free tier that works for me.

Assets Repository
+-- Art
    +-- Entities
    +-- FX
    +-- Output
    +-- UI
+-- Audio
    +-- Title Music
    +-- In Game Music
    +-- Sound Effects

A short breakdown of what might be noteworthy of the above structure.

Art: Here goes the Photoshop, Blender, Illustrator and other art files. The Output directory is where I send exported/rendered versions of assets. I then have my conversion script in Tools in the code repository that builds the Xcode asset catalog from here with optimized versions for different devices and screens.
Audio: Not much to say about this, I store all audio related work here. I make music and sound effects in Logic Pro X and I found saving the work using Organize as folder instead of as package, when saving the project, a bit more friendly when working with version control.

The Rest

Apart from the files that makes up what will become the game, there's a bunch of other types of files being generated during the game's development cycle.

I've chosen to keep them on an ordinary cloud based sync service. I'm using iCloud Drive as I had a huge amount of unused storage available there. Otherwise I'd considered Dropbox.

This could go in version control instead, but I felt that using a cloud drive for this made more sense. I can access the files everywhere, if I get any ideas when I'm out and about I can open the documents on my iPad and edit them on the go. Or use my Apple Pencil to illustrate ideas or flows.

On top of that, it makes it easier to share this folder with non-coding people that I might give access to, for additional input or help with these parts.

iCloud Drive
+-- Concept Art
+-- Documentation
+-- Marketing

And the breakdown.

Concept Art: My early initial drawings and collections of inspirational art and mood boards. PureRef is a great tool to organize inspirational art.
Documentation: Game Design Documents, my time log and asset tracking spreadsheets.
Marketing: Videos and screenshots for Apple Store. Videos to share on social media. I actually haven't really had time to do any marketing, at all. Additional content will likely appear here later on. For now I've put my focus mainly on getting games done and build personal gamedev habits and workflows that works for me.

Conclusion

I hope you found the breakdowns of how I organized my last game project helpful. You might have got some useful ideas from how I organize my game projects that you can use or tweak.

As I mentioned earlier, it is ever-evolving, and I've made multiple adjustments for the next game that I've started working on. I might revisit this article and make an updated version in a year from now.

Keep coding!

References

Hypastorm. Hypastorm is a fast, casual, twin stick action shooter. ↩
Xcode assetcat gen. Xcode asset catalog generator for game development. ↩