Where Should We Place Demo Apps for UntoldEngine?

[miogds]

Current Setup

Right now, the UntoldEngine repository is structured as a Swift package. Inside the Sources folder we currently include:

• Multiple demo apps, each defined as an executable target.
• One library target for the UntoldEngine itself.
• One Editor target, which is macOS-only.

This works fine for macOS, but it has serious limitations for other Apple platforms (iOS, visionOS, tvOS, etc.). Running demo apps as Swift package executables on those platforms is either very difficult or not even possible.

Because of this, testing and maintaining cross-platform demos is unnecessarily complex. A better structure is needed.

---

Proposal: Move Demo Apps Outside Sources

Instead of keeping demos inside the package, we move them out and let them reference UntoldEngine as a Swift Package dependency. Each demo would then be a standalone Xcode app project, making it much easier to configure and run across different Apple platforms.

---

Options

Option 1: Keep Demos in the Same Repository

• Place demo apps at the root level of the UntoldEngine repo, outside of the Swift package.
• Each demo becomes an Xcode project referencing the UntoldEngine package.

There are two possible layouts here:

1. One Xcode project with multiple targets (one target per demo app and we can share code).
2. One Xcode project per demo app (separate projects, all in the repo).

Pros

• Engine and demos stay together, no extra repos.
• Easier to keep demos in sync with engine changes.

Cons

• Repo size and complexity increase.
• Developers who only want the engine must still clone/download all demos.

---

Option 2: Create a Separate Repository for Demos

• Create a new UntoldEngine-Demos repository.
• Each demo is an Xcode project that pulls in UntoldEngine as a package dependency.

Pros

• Cleaner separation between engine core and demos.
• Developers can choose whether or not to clone demos.
• Easier to version, tag, and release demos independently.

Cons

• Requires coordination across two repositories.
• Slightly more overhead to keep demos aligned with engine updates.

---

Recommendation

• If we value tight integration and simplicity for contributors, Option 1 makes sense.
• If we prefer clean separation and a lighter repo for the engine, Option 2 will be more sustainable in the long run.

---

👉 What do you think?

[untoldengine]

We’d like to keep a runnable demo inside the package—ideally just for macOS. The reason is that it gives new developers the quickest way to try out the engine: open the package, pick the demo target, and hit Run. That way they don’t need to set up an Xcode project first, and it also doubles as a simple smoke test that the engine builds and runs correctly.

Have you run into any issues with other targets when going this route? The idea would be to keep only the macOS demo inside the package, and move iOS/visionOS examples into a separate Examples/ folder or a template repo.

I'm open to suggestions if there is a better approach to onboarding new developers. Also, my intent is to keep the demo project as minimal as possible.

[miogds]

For the SwiftUI Demo app on iOS, I had some trouble making it run, but for tvOS and VisionOS, I couldn’t, so I created an Xcode Project that uses the code. For example, for the new Xcode 26 and iOS 26, it doesn't run anymore.

We can keep the 2 demo projects as they are now because they are minimal and only for macOS, but for the other demos? I like to create a demo for every feature. I like more small demos for a feature and other demos that combine features so the new developer can understand how everything works and how they can combine and use them together for different scenarios. But these demos should be in another folder, not inside the Sources of the package because most of them will be multiplatform with the Xcode project.

I like the idea of being an independent repo, but maybe not for now because it has to be maintained separately. I like that idea of not downloading all demos I think I will create for all the features, but this could be a future improvement because for now we don't have many demos and it's easy to keep in sync with the engine if it’s in the same repo.

So I go forward and create an Examples or Demo folder in the repo? I will have the minimal just plain SwiftUI demo app and the SceneBuilder Demo app at the moment

[untoldengine]

Yep, for iOS it seems you have to create an external Xcode project for it to work.

I already have a Game Demo template, which I'm currently updating with the latest changes. (None of my recent changes have been pushed yet)
https://github.com/untoldengine/UntoldEngine-Game-Template

However, the repo was made for macOS project. Maybe we can replace the Xcode project and create a new multiplatform project. What do you think?

[untoldengine]

Sorry, I don't think I answered your question. Yes, let's create an Examples folder that users can run.

I'm thinking about your proposal. I also like the idea of keeping the engine slim (no examples/demo, just source code). I'll get back to you on this one.

[miogds]

OK. I will wait for your thoughts on this one. For now, I will create the Examples folder and all of the examples I'm creating so you can try as soon as you merge the pull request or go to the branch.

Also, I was looking at the demos, and because the editor is a standalone package now, the simple demo doesn't make any sense. The Game demo does because it shows you a simple game... but in the editor, you can load the demo assets, and you play the same game that the Game demo... so I don't know if this structure will make sense in the long run.