Proposal: Scripting System for the Editor

[miogds]

With the new editor, we need a way to implement logic without having to recompile the editor each time we want to adjust behaviors. This becomes especially relevant for AI in NPCs, custom input bindings, or even state machines.

Right now, since everything is tied to Swift, every change requires a full compile in Xcode to test functionality. While that works for final builds, it slows down iteration during editor/game testing.

On macOS, we could theoretically load plugin code, but that’s not possible on VisionOS or other Apple platforms. Additionally, App Store restrictions forbid this approach. Swift REPL (the scripting version of Swift) is also macOS-only and not available to third-party apps.

Possible Paths

Path 1: macOS Editor + VisionOS Proxy

• Release a full editor for macOS.
• Provide a VisionOS proxy editor, which streams editor information from macOS via remote rendering (available from macOS 26 / VisionOS 26).
• This allows loading and running Swift code dynamically on macOS and reflecting results on VisionOS.

Pros:

• Easier to implement at the beginning, with small incremental changes.
• Reuses Swift compilation directly on macOS, no need to build a new interpreter.

Cons:

• The VisionOS editor would not work standalone — it would always require a macOS host.

---

Path 2: Custom VM Scripting System

• Build our own VM/interpreter that runs inside the editor.
• This avoids Apple restrictions, since interpreted scripting is allowed.
• Could support Lua, JavaScript, Python, or others.
• Personally, I prefer Swift (to keep everything consistent), but this would mean implementing our own Swift parser/interpreter.
• Even a limited Swift grammar (e.g., without generics) would be acceptable at first.

Pros:

• More extensible in the long term.
• Ability to onboard more people who prefer or already use other languages.

Cons:

• Slower execution of the code, even in Swift, since it runs through an embedded interpreter.
• We need to provide a coder view panel ro window to be able to write code inside the editor

---

Path 2.5: Visual Scripting as a Bridge

• Provide a visual scripting environment (like Blueprints) to encapsulate Swift scripting.
• Users implement logic via nodes/bubbles → converted into Swift source code during Xcode project generation.
• Benefits:
  • Faster to release an alpha version.
  • More accessible to users who aren’t comfortable with code.
  • Final builds still compile Swift for maximum performance.
  • We don't need to provide any code editor / panel only the bubble canvas which it's easier to implement

---

💡 My personal preference: A custom Swift interpreter with visual scripting as an early milestone. This keeps everything consistent, avoids platform restrictions, and provides a smoother long-term path.

---

Note: The choices here, the path we choose in this area, also be an important step in implementing the plugin/component extension system because they are related.

---

👉 What do you think?

[untoldengine]

I totally see the benefits of adding a scripting language to the editor. It would be a very cool addition. At the same time, I’ve been bitten by this in the past — back when the Untold Engine was still written in C++, I tried implementing a basic scripting system, and it turned out to be more work than I expected. Debugging in particular became a nightmare.

That said, I’m definitely open to exploring your proposal. You mentioned writing a Swift interpreter, correct? I have a suggestion here: there’s a scripting language called Gravity (gravity-lang.org) that might work for us. It uses a syntax very similar to Swift, which would feel natural for Apple developers. I’ve actually used it before in the engine and is quite nice. Moreover, the developer is super friendly and helpful. If we go down that path, I could even reach out to him for guidance. This way, we don’t need to build our own interpreter from scratch, and we can move faster.

I think our initial goal should be an editor + scripting support, and leave visionOS as a next feature. That way, we can test out scripting before introducing another variable. What do you think about this approach?

[miogds]

The question about VisionOS, I think VisionOS could have a huge impact if we support it at least now, there's a new VisionPRO M5 around the corner. Even though maybe we can do the editor proxy app in the VisionOS, which basically renders everything in the macOS and stream to VisionOS app.

I mean, in the editor app we can focus on optimization for macOS, not worry about VisionOS for that, but still supporting the VisionOS features ( doing all the work on the macOS version ) which also will improve just the renderer. To make it clear, all the tests, optimization, and flow of development will be macOS-related like now, and we create a remote render view on VisionOS so we will be able to see on visionOS on realtime, and we keep working on the render to be able to render the standalone game in the visionOS but not worrying about the editor stuff.

[untoldengine]

Ah, I see what you mean. The VisionOS will act just as a viewer. Ok, I think this will be good for the engine, so let's go for it.

[miogds]

Adding a scripting system is a lot of work, but usually is worthy. I like to go ahead and plan for that, instead of taking the short path.

Anyway, I heard about gravity, never tried it before, but I will review it. Still, what is the path? Do we go with gravity fully or my "path 2.5" implementing the gravity and the visual scripting tool (on top of gravity) ? Or do we go just by code?

[untoldengine]

Honestly, I prefer Path 2.5.
I like the idea of using Swift as the interpreter because it will play well with the engine ecosystem.

My main concern is about time and burnout. Building an interpreter is a big undertaking, and we need to be realistic about how long it would take to get something stable. I think the best approach is to start small, prove out the basics, and then grow it over time.

How do you envision the first MVP version of the interpreter? And what kind of timeline do you think would be realistic to get it up and running?

Aside from that, I think this will be fun to implement.

[miogds]

From my experience doing a visual code (bubbles / node coding) on top of an interpreter is really a huge task because you need to prove that you give enough functionality in a condensed and simple way. This means a lot of iteration on the design to be ready for the public.

The good thing is that I already did that a long time ago for a custom engine I had, so I'm pretty confident that I can make it work in less than a month.

Also, I have experience in developing a visual language like Unreal Blueprints (avoiding things that I don't like) and interpreting the whole Swift language to execute code or even translate it to another language (I also have a project in the company that translates Swift directly to JavaScript to execute in the web on realtime).

But before I do an estimation of the time, I would like to try the Gravity-Lang because it is not the same, supporting Swift as a language or the Gravity Swift like scripting runtime. Because maybe it's worth working and test with Gravity just now (avoiding doing the Swift interpreter at the beginning ) and we can move faster in the development of other areas.

[untoldengine]

If need be, I can connect you with the Gravity developer.
Thanks

[miogds]

That sounds good. But let me first study a bit how it works, and later I will talk with you to put me in contact. Thanks!

[untoldengine]

Of course.
Thanks!

[miogds]

I’ve been reflecting on the idea of integrating a scripting system, and I’d like to share some thoughts. While I strongly believe a scripting system can expand flexibility and enable runtime behavior changes, we also need to define clear use cases where it makes sense—and where it doesn’t.

By nature, any scripting system will be slower than compiled code. So rather than trying to use it for everything, I suggest focusing on scenarios where the trade-offs (flexibility, iteration speed, extensibility) outweigh the performance costs.

---

Two Types of Script Systems

1. Visual Scripting (Proposed name: wait... wait... UntoldScript !!! 😅)

• Audience: Designers, 3D artists, animators, and non-programmers.
• Use Case: Quick prototyping and iteration. Visual scripting allows team members without coding skills to create and test gameplay logic directly in the editor (e.g., “move forward” bubble linked to a player).
• Inspiration: Unreal Blueprints have shown the value of this approach. Many teams using Unity struggled when non-programmers had to learn C#.
• Proposal: Build our own visual scripting system instead of relying on an external runtime. This ensures we have full control and integration with our engine.

2. Text-Based Scripting

• Audience: Developers and contributors extending game logic with more complex behaviors.
• Use Case: Runtime extensions, component creation, and logic that is too advanced for visual scripting.
• Proposal:
  • Start with Gravity-lang as the main supported scripting language.
  • Implement a plugin system so the community can extend support to other languages.
  • Divide supported scripting languages into two categories:
    1. Component Extension Scripts – High-performance, typed, and ideally capable of generating Swift code (e.g., Gravity, Lua). These should run efficiently on every frame if needed.
    2. Behavior Scripts – For less performance-critical logic (e.g., AI decision-making, high-level events). These could include languages like Python, .NET, or JavaScript.

---

Summary of Proposal

• Visual Scripting (UntoldScript):

  • Primary scripting option.
  • Accessible to both programmers and non-programmers.
  • Enables rapid iteration during design and development.
  • Native to our project, not tied to external runtimes.

• Text-Based Scripting:

  • Start with Gravity-lang.
  • Provide a plugin system to expand to other languages.
  • Split into:
    • Component Extensions → focus on performance, compiled to Swift when possible.
    • Behavior Scripts → flexible, less performance-sensitive, community-expandable.

---

Closing Thoughts

After studying Gravity-lang, I’m convinced it’s a good starting point. However, for visual scripting, I believe we should build our own system (UntoldScript) rather than layering it on top of Gravity. This way, we retain control and keep the system tailored to our needs.

---

👉 @untoldengine What do you think?

[untoldengine]

I barely saw this. GitHub is not that good at informing when a new message comes in. I'll give you a response tomorrow morning.

[miogds]

I also posted several comments in other discussions.

[untoldengine]

I’ve been thinking more about your proposal. What if we find a middle ground between the both ideas:

What if we build a small Untold Script Core (USC) — a minimal command set that represents engine actions like PlayAnimation, ApplyForce, If, and Delay.

• Visual Scripting (UntoldScript) would be the main authoring layer that outputs this IR (intermediate representation).
• The engine could then either:
  • Interpret the IR (safe, flexible — ideal for triggers and event logic), or
  • Generate Swift code from it (fast path — ideal for per-frame component logic).

This gives us the flexibility of scripting without adding an external runtime or language to maintain.

Example

Take a simple node chain:

[OnTriggerEnter(tag:"Ball")] → [If speed < 5] → [ApplyForce(direction:forward, magnitude:50)]

When saved, the editor turns it into a small internal script (IR):

Event("OnTriggerEnter")
If Less(GetFloat("speed"), 5)
    Call Physics.ApplyForce(entity:self, direction:forward, magnitude:50)
End

Then, at runtime, the engine decides how to run it:

• If it’s a trigger or event graph:
  The interpreter runs it directly — perfect for collisions, cutscenes, or scripted events.
• If it’s a per-frame behavior:
  The IR is compiled into Swift, for example:

if entity.speed < 5 {
    physicsSystem.applyForce(entity, direction: .forward, magnitude: 50)
}

• We stay 100% native — no FFI bridges or embedded runtimes.
• We can start small (events and triggers) and scale to behaviors over time.
• Keeps debugging, profiling, and optimization entirely inside the Swift toolchain.

What do you think?

[miogds]

I like the idea. If we can have our own IR code, we can translate from other scripting languages or even other languages, even if they don't support compilation or binary distribution. Also, having our own IR means we can pseudo-compile for the platform that is running and save it for later. If you don't change the script code or node, the system always loads the pseudo-binary. Python uses that strategy.

[untoldengine]

Yep, exactly — and it’ll be much easier to implement and actually have something to show early on. 🚀