Status: Revision 5.2 (2026-09-18). Implemented through stage 3d on feature branches in both repos; see Implementation status below. Decisions D1 to D8 are locked (§14). Scope: UntoldEngine (new UntoldComponentKit product, generated-project spec) and UntoldEditor (loader, inspector, menu host, panel, app bundle). No change to the ECS core, the .untoldscene format, or any existing component. Baseline: editor develop @ 4a95ce5 (v0.19.0); engine fork develop @ cd7ca92e (the revision the editor's Package.resolved pins); Xcode 27.0, Swift 6.4, macOS 27.0. Repos: miolabs/UntoldEngine, miolabs/UntoldEditor. miolabs/UntoldGaussianTwins and the twin demo adopt it afterwards (stage 5): that work is on hold until this feature has been tested. Working agreement: commit as work progresses and push branches to the miolabs fork; no pull request until the whole loop works end to end (§12 defines that bar).

Changes in revision 2: @Expose is now @UntoldAttribute; new EditorMenuPlugin with @UntoldMenu menu items (§5); plugin packages such as UntoldGaussianTwins bring their editor integration with them (§7.8); generated projects are XcodeGen projects, which corrects §9 and D5; spikes C and D added; the feature is tested on its own sample project first, and the twin demo is updated after that (§11, §12).

Revision 2.1: @UntoldMenu takes the root domain first, then the submenu path or just the title. Loaded code is tied to the editor's fixed root menus and cannot create new ones (§5.2).

Revision 4: loaded code can add kinds of entity to the editor's creation shelves (EntityPlugin, §5.6), with the three sorts a plugin needs: nothing to show, an editor-only representation, or a shape of its own that also exists in the game. The Inspector has one Add Component menu instead of two (§7.6).

Revision 4.1 (superseded by revision 5): a component could be locked to its kind of entity, so a torus's shape was never offered for a cube.

Revision 5: the base classes are named after what they are, and a kind of entity is a thing of its own. CodeComponent is ComponentPlugin, EntityTemplate is EntityPlugin, EditorExtension is EditorMenuPlugin (the engine already calls its extension points plugins: PhysicsBackendPlugin, RenderExtensionPlugin). An EntityPlugin stays bound to its entity and carries the entity's own properties, its geometry and its editor representation, which is now icons, points and polylines so a spline can show its control points (§5.6). The component lock of revision 4.1 is gone. ScenePlugin is the shared base of the two plugins bound to entities, ScenePluginSystem drives both, and ComponentAction is PluginAction. This document uses the new names throughout.

Revision 5.1: the two places plugins live are named apart. The project's own folder is Sources/<Project>Plugins (was <Project>Components, a leftover from when only components lived there), and a shared one is a plugin package, the term the engine's plugin docs already use: untold-package.json in its root, listed under pluginPackages in UntoldEditor.json. The sample package is SamplePluginPackage, its editor side the folder SampleEditorPluginPackage with the menu plugin SampleMenus; a package's editor-side library is named after its folder. The old folder name, keys and file name are still read and reported (§7.1).

Revision 5.2: control points can be dragged. .handles(properties:tint:) names SIMD3<Float> properties of an EntityPlugin; a click on one, with either button, puts the move gizmo on the point, and dragging an axis writes the property as an Inspector edit would, one undo step per drag (§5.6). Entities with only an editor representation get the gizmo too.

Branches, all pushed to the miolabs fork, no pull request opened:

One branch per repo instead of the one per stage planned in §11: the editor and the twins pin branch both name the engine branch, so stacked branches would have meant re-pinning all three at every stage. Commits are small and topical and can be regrouped for review.

Measured in the running editor on a sample project: launch to first library loaded 4.1 s including app start; save to new revision live 1.2 s; broken save to error with file and line 0.2 s, with the last good revision still running.

Each of these passed every unit test and failed only in a real build, which is why the plan insisted on running the packaged app and a generated game.

1. Hidden symbols in release. A subclass in a loaded library copies its base class's dispatch table, entries for internal members included, and release builds hide internal symbols. The packaged editor failed to load any component until entity, isAttached and hasStarted became final. scripts/verify-component-sdk.sh now checks this at packaging time: it compiles a fixture against the bundled SDK and confirms the executable exports every symbol it needs (103 today, with an entity plugin that has its own properties, a generated mesh and an editor representation in the fixture).
2. Xcode's debug dylib. Xcode builds an app's code into <App>.debug.dylib and leaves the executable as a stub, so scanning the main executable found nothing. discoverInApp() became discoverInApp(), which covers every image inside the app bundle.
3. Image paths. The loader records /private/var/... for a library opened as /var/.... Discovery now matches a path against the loaded images instead of trusting its spelling.
4. Entities pending destruction. scene.mask(for:) hides them, so the cleanup handler could not reach the instances to detach. The lookup uses the component bit instead.
5. The bundle script hardcoded a build path the newer SwiftPM does not use, and did not copy the editor's own resource bundle, so the packaged app crashed at launch outside the build tree. Both fixed.
6. Marker colors. The first viewport icons came out washed: the pixels are sRGB and the texture was read as linear. Only looking at the running editor showed it; the texture is rgba8Unorm_srgb now.

• Components from code are drawn by the Inspector directly, like Splat Twin, instead of being registered through addComponent_Editor: scene-composition mode whitelists registered components and would have hidden them, and the set of types changes whenever a library loads. They are added from the same Add Component menu as the engine's, under a "From Code" heading; the first version had a second button, which was one too many.
• The editor gained --open-project <folder>, and accepts a folder with a project.yml and no generated Xcode project.
• Each Swift module is a directory in the newer SwiftPM layout; the SDK packaging copies recursively.
• An unloaded type's saved values round-trip unchanged, not byte for byte: the scene encoder does not sort keys.
• BuildSettings.includesCodeComponents is opt-in, so projects generated without it are exactly what they were. The editor turns it on when it knows its own engine reference.

Nothing here can be driven from a script, because macOS refuses UI scripting without an accessibility grant:

• The Inspector renders every kind of field and edits are undoable.
• The one Add Component menu lists the engine's components, then the ones from code under "From Code".
• Rows for kinds of entity drag from the shelves into the viewport and the hierarchy; the Entities shelf appears and disappears with its contents.
• An entity of a kind shows its own block at the top of the Inspector, titled with the kind, and its fields edit it.
• How the editor representation looks on screen: the flag's tint, the spawn radius circle, and the spline's dots and control polygon staying visible over its tube.
• Clicking a spline control point puts the gizmo on it, dragging an axis reshapes the tube, one undo takes the drag back, and a left click on a dot does not drop the selection.
• The contributed menu items appear, toggle, and keep their checkmarks.
• Play, stop, and a rebuild that lands during play.

Examples/CodeComponents/README.md lists the steps.

• CreateProjectViewTests.test_createProjectView_resultProjectPathIsNilByDefault fails on the editor's pristine develop.
• Generated projects keep {{PROJECT_NAME}} in Main.storyboard: the variable pass skips storyboard files.

1. Components are written in Swift, in Xcode, by subclassing a base class the engine ships. Code is the primary interface; the editor views and tunes.
2. A property wrapper marks what the editor sees: @UntoldAttribute properties become inspector fields and are saved with the scene; actions become inspector buttons and script-callable functions.
3. When a project is opened, the editor finds the project's component sources, compiles them and loads them. A change made in Xcode is recompiled and shows up in the running editor without relaunching it.
4. The same sources compile into the final game on macOS, iOS and visionOS with no editor involvement and no dynamic loading.
5. Loaded code can also extend the editor itself. @UntoldMenu(.debug, "Splat Twin/…") declares a menu item under one of the editor's fixed root menus; when the library loads, the item appears there. The twin gaussian work is the first real consumer: it is a plugin, and its debug and preview menus should arrive with the plugin instead of being hardcoded in the editor. That adoption happens after this feature has been tested; the twin session is on hold until then.
6. Everything editor-only (compiler, loader, inspector, menu host) stays on macOS. The kit that game code depends on is platform neutral.

Not present today: any property metadata or reflection for components, any dynamic code loading (HotReloadingSystem.swift only swaps a hand-picked .metallib), any way for code outside the editor to add a menu item, a compile SDK in the app bundle.

Xcode ──edits──▶ project:  <Root>/Sources/<Project>Plugins/*.swift    ◀── same files, no editor ──┐
                 plugin:   <Plugin>/Sources/<Plugin>Editor/*.swift   (editor-only sources)         │
                                   │                                                               │
        editor: watch / "Build"    ▼                                                               ▼
        /usr/bin/xcrun swiftc -emit-library                                       Xcode / xcodebuild (static link)
        against the Component SDK shipped in the .app                                              │
                                   │                                                               ▼
                                   ▼                                               game binary: macOS / iOS / visionOS
        dlopen <Module>_r<N>.dylib ──▶ discovery ──▶ registries rebind                             │
                   │                          │                                                    │
                   ▼                          ▼                                                    ▼
        Inspector: @UntoldAttribute    Menu bar: @UntoldMenu      ◀── UntoldComponentKit: base classes, wrappers,
        fields, action buttons         items by domain                reflection, storage, system, registries

Three parts, in dependency order:

• A. UntoldComponentKit (engine package, new library product and target, like UntoldEngineAR). Platform neutral: Foundation, simd, ObjC runtime, UntoldEngine. Holds ComponentPlugin, @UntoldAttribute, EditorMenuPlugin, @UntoldMenu, reflection, the storage component, the per-frame system, registries and discovery, and the USC bridge.
• B. Editor (macOS only): source discovery, compiler, loader, reload and state migration, inspector section, menu host, Plugins panel, Component SDK inside the app bundle.
• C. Build system: generated XcodeGen projects link the kit and call registration; the app bundle script ships the SDK.

import UntoldComponentKit
import UntoldEngine
import simd

final class PlayerController: ComponentPlugin {
    @UntoldAttribute("Speed", range: 0...20) var speed: Float = 5
    @UntoldAttribute var jumpHeight: Float = 1.5
    @UntoldAttribute var lives: Int = 3
    @UntoldAttribute var invincible = false
    @UntoldAttribute var spawnOffset: SIMD3<Float> = [0, 1, 0]
    @UntoldAttribute(.color) var tint: SIMD4<Float> = [1, 1, 1, 1]
    @UntoldAttribute var target = EntityRef()                  // resolved by entity name
    @UntoldAttribute var footstep = AssetRef(category: .animations)
    @UntoldAttribute var stance: Stance = .idle                // String enum + CaseIterable: picker

    enum Stance: String, CaseIterable { case idle, walk, run }

    override class var actions: [PluginAction] {
        [
            PluginAction("Jump") { ($0 as! PlayerController).jump() },
            PluginAction("Reset") { ($0 as! PlayerController).reset() },
        ]
    }

    override func onStart() {
        // play mode began, or the entity was spawned during play
    }

    override func onUpdate(deltaTime dt: Float) {
        guard let transform else { return }
        if InputSystem.shared.keyState.wPressed { transform.position.z -= speed * dt }
    }

    func jump() { /* ... */ }
    func reset() { /* ... */ }
}

Rules the kit enforces or documents:

• Subclass ComponentPlugin. final is recommended. Generic classes are not discovered. No initializer parameters: the kit constructs every instance with init() and then applies saved values.
• Only stored properties wrapped in @UntoldAttribute are shown and saved. Everything else is runtime-only state.
• actions is an explicit table in v1. An attribute on the function itself needs a Swift macro (§5.5, D6).
• Lifecycle, in order: onAttach() (instance bound to an entity, edit or play), onStart() (play begins), onUpdate(deltaTime:) (each frame in play), onFixedUpdate(deltaTime:) (fixed step, in play), onStop(), onDetach(), and onEditorChanged(property:) (the inspector wrote a value; edit mode only).
• Access: entity: EntityID, transform: LocalTransformComponent?, the scene global and every public engine API. ComponentPluginRegistry.entities(with: PlayerController.self) and ComponentPluginRegistry.component(PlayerController.self, on: entityId) replace queryEntities for kit types.
• Isolation rule. Component sources may import only UntoldEngine, UntoldComponentKit, plugin modules declared for the project, Foundation and simd. They must not reference types from the app target: the editor compiles this folder on its own, and its compile error is the guard.

Optionals are not supported in v1. Adding a kind is one conformance to UntoldAttributeValueType in the kit plus one control in the editor.

Every PluginAction is registered in USCActionRegistry as "<TypeName>.<ActionName>" when its type registers, and removed when the type is replaced. A USC script attached to the same entity can call it with callAction("PlayerController.Jump"). The inspector shows one button per action, in edit mode and in play mode. Edit-mode actions are authoring helpers; their effects are not tracked by undo (the play-mode snapshot already protects the scene during play).

Components describe entities. An EditorMenuPlugin describes what a loaded library adds to the editor itself. It is discovered the same way as components, instantiated once when its library loads, and ignored entirely in a game.

This is the twins plugin's editor side, replacing GaussianTwinPreviewSettings and the hardcoded Splat Debug tree:

import UntoldComponentKit
import UntoldEngine
import UntoldGaussianTwins

final class GaussianTwinsEditor: EditorMenuPlugin {
    @UntoldMenu(.view, "Preview Splat Twins",
                tooltip: "Swap meshes linked to a .untoldgs twin for the splat as the scene camera approaches.")
    var previewTwins = true

    @UntoldMenu(.debug, "Splat Twin/Disable HZB Occlusion Cull") var disableHZBCull = false
    @UntoldMenu(.debug, "Splat Twin/Disable Opaque Depth Test") var disableDepthTest = false
    @UntoldMenu(.debug, "Splat Twin/Blend Cap") var blendCap: BlendCap = .c64      // enum: radio submenu

    @UntoldMenu(.debug, "Splat Twin/Reset Link Adoption")
    var resetAdoption = UntoldMenuAction { GaussianTwinSystem.shared.resetSceneLinkAdoption() }

    enum BlendCap: String, CaseIterable { case c64 = "64", c128 = "128", unlimited = "Unlimited" }

    override func menuDidChange(_ domain: UntoldMenuDomain, _ path: String) {
        if previewTwins { GaussianTwinSystem.shared.install() } else { GaussianTwinSystem.shared.uninstall() }
        GaussianDebugOptions.shared.disableHZBOcclusionCull = disableHZBCull
        GaussianDebugOptions.shared.disableOpaqueDepthTest = disableDepthTest
    }

    override func onSceneReset() { GaussianTwinSystem.shared.resetSceneLinkAdoption() }
    override func onUnload() { GaussianTwinSystem.shared.uninstall() }
}

Options: key: (key equivalent), tooltip:, persist: (default true), enabled: (closure evaluated when the menu opens).

Domains. The first argument names one of the editor's root menus. The set is closed and owned by the kit and the editor, so loaded code can never create a root menu:

Path rules: the second argument is the item title, optionally preceded by submenu names separated by /, as in "Splat Twin/Blend Cap". It never names a root. Items are grouped per extension and keep declaration order; a second declaration of the same domain and path is rejected with an error in the Components panel. Built-in items cannot be overridden. Adding a domain means changing the kit and the editor together.

onLoad(), onUnload(), onSceneReset() (a scene was loaded or cleared, or the project switched: the three places the editor calls GaussianTwinPreviewSettings.sceneDidReset() today), onPlayModeChanged(_:), onEditorUpdate(deltaTime:) (edit mode, optional), menuWillOpen() (refresh wrapped values from outside state so checkmarks stay truthful), menuDidChange(_ domain:_ path:).

The wrapper owns the value. The editor persists it per project in UserDefaults under editor.menu.<project-hash>.<domain>.<path> and re-applies it on load and after every reload, then calls menuDidChange once per item. That reproduces what GaussianTwinPreviewSettings does by hand with editor.gaussianTwins.preview. persist: false opts out.

@UntoldMenu(.debug, "SplatTwin", .bool) func setSplatTwin(_ on: Bool) and @UntoldMenu(.debug, "Splat Twin/Reset") func reset() put the attribute on the function. Swift only allows custom attributes on functions through macros, so this form arrives with the macro package (D6): a member marker @UntoldMenu plus a type-level macro that synthesizes the same descriptors the wrappers produce. Semantics are identical: for .bool the editor owns and persists the state and calls the function on load and on every toggle. The property form above needs no macro and ships in v1.

A plugin's entity is not always a mesh. It can be a torus, but it can also be a spawn point, which the editor must show and the game must not; a spline, which is a tube in the game and a tube plus control points in the editor; or a rules object, which nothing shows. Loaded code adds such kinds with an EntityPlugin.

The plugin is the entity, not a recipe for one. An instance stays bound to each entity of the kind, is saved with the scene, and is bound again on load, in the editor and in the game. Everything that is part of the entity lives on it:

public final class SplinePathEntity: EntityPlugin {
    @UntoldAttribute("Start") public var start: SIMD3<Float> = [-1.5, 0, 0]          // its own properties
    @UntoldAttribute("Start Handle") public var startHandle: SIMD3<Float> = [-0.5, 1, 1]
    // ...
    override public func onAttach() { rebuild() }                                    // its geometry
    override public func onEditorChanged(property _: String) { rebuild() }

    override public var editorRepresentation: EditorRepresentation {                 // its editor representation
        EditorRepresentation([
            .polyline([start, startHandle, endHandle, end], closed: false),
            .points([start, end], tint: [1.0, 0.75, 0.2]),
            .points([startHandle, endHandle], tint: [0.35, 0.8, 1.0]),
        ])
    }
}

An entity can have geometry, an editor representation, both or neither: torus, spawn point, spline, game rules. Icons are hidden by geometry in front of them, like the editor's light markers; lines and points are drawn over everything, so a handle inside a mesh stays visible. All of it is drawn in the editor's light marker pass, so it is absent in play mode and cannot reach a game. Lines reuse the pipeline of the selection box and are white; points are small billboards.

Handles. .handles names SIMD3<Float> properties, and each is a draggable point. The property is the truth and the dot follows it, so nothing new exists in the hierarchy, the scene file or play mode (the alternative, editor-only child entities, would have needed meshes to be pickable, a serializer rule to skip them, and removal at play). A click near a dot, with either button and within 14 points of it on screen (each handle is projected with the camera's own matrices, which a test checks against the engine's click ray), selects the entity and puts the move gizmo on the point instead of on the entity; the gizmo's own axis drag then writes the property through ScenePluginSystem.setAttribute, so onEditorChanged rebuilds the geometry as the point moves, and the drag is registered as one undo step. The selected handle is drawn white and holds while its entity stays the active one; the rotate and scale gizmos go back to the entity. Entities whose only presence is an editor representation get the gizmo too, so a spawn point can be moved in the viewport.

Shelves are a closed set, for the reason the menu roots are (§5.2): .primitives and .lights put the row under the built-in ones, and .entities is a third shelf that the Content browser shows only while it holds something. Rows behave like the built-in rows: drag into the viewport or onto the hierarchy, or double-click. The payload carries the kind's type name under its own key, so the existing drop decoding tells it from an asset, a light or a primitive.

Component or entity. A ComponentPlugin is something any entity could have. What could only ever belong to one kind of entity is not a component: it is a property of that entity. Revision 4 had it the other way round (a one-shot EntityTemplate plus a TorusShape component, then, in 4.1, a way to lock that component to its kind). The lock was a symptom: a component that can only be tied to one entity is part of the entity, so it became the entity's own properties and the lock went away.

For shapes the engine does not ship there was no public way in: Mesh.makeMeshes is internal. BasicPrimitives.createMesh(from: MDLMesh) is the one engine addition. Generated geometry is recorded by the scene as a procedural mesh name the engine does not know, which it restores as a cube; the plugin then replaces it on attach, and setGeneratedMesh carries the old submesh's material over, so material edits survive both a rebuild and a reload. A mesh built this way is part of the entity, and the editor's remove policy keeps it.

Entity plugins are discovered and registered per library revision like the other plugins, unregister with their library, and are listed in the Plugins tab. ScenePluginSystem.discoverInApp() registers them in a game too, where EntityPluginRegistry.shared.instantiate(_:at:entityName:) makes the same entities in code.

UntoldAttribute<Value> and UntoldMenu<Value> are class-based property wrappers conforming to AnyUntoldAttribute / AnyUntoldMenu (label or path, kind, hints, getAny(), setAny(_:)). untoldAttributes() and untoldMenuItems() walk Mirror from the root superclass down, in declaration order, and strip the _ prefix from each wrapped property's label. Because the wrapper is a reference the instance owns, the inspector and the menu host write through the same object the code reads. No key paths, no code generation. Verified in spike B (§8).

ScenePluginsComponent: Component, Codable is the only engine component the kit adds. It holds [Slot] where a slot is typeName, payload: [String: UntoldAttributeValue] and instance: ComponentPlugin?.

Why not one engine component per user type:

• Engine component IDs are keyed by ObjectIdentifier of the Swift type. Every reload produces new types, so each reload would burn one of the 128 slots per user type.
• Scenes must load before the library is available (and in a fresh editor without one). A slot with instance == nil keeps its payload, round-trips it untouched on save, and is bound when the type appears. The inspector shows it as "not available in the loaded library".

Registered once with encodeCustomComponent(type: ScenePluginsComponent.self). The payload written under customComponents["ScenePluginsComponent"]:

{
  "components": [
    {
      "type": "PlayerController",
      "properties": {
        "speed": 12.5,
        "spawnOffset": [0, 1, 0],
        "target": { "entity": "Enemy01" },
        "stance": "walk"
      }
    }
  ]
}

Serialization is reflection-driven, not synthesized Codable. Two reasons: spike B showed that a subclass of a Codable class does not get synthesized coding for its own properties, and reflection tolerates properties added or removed between reloads (missing: default kept; extra: dropped with a log line).

ComponentPluginRegistry and EditorMenuPluginRegistry map unqualified type names to types, with a revision stamp. discover(imagePath:) uses objc_copyClassNamesForImage and keeps classes whose superclass chain reaches ComponentPlugin or EditorMenuPlugin. No entry point and no hand-maintained list. Spike C proved it for a loaded dylib and for classes compiled into an executable with -O -whole-module-optimization -dead_strip, where nothing references them. The game calls discoverInApp(). Duplicate names across modules are rejected with an error. rebind(name:to:) is what a reload calls: same name, new type, old instances migrated (§7.5).

ScenePluginSystem: EngineExtension, id com.untoldengine.componentkit. update forwards to onUpdate only while gameMode is true; fixedUpdate forwards to onFixedUpdate (already gated by the engine). It ticks after input and scene-graph traversal and before LOD and batching, which is where EngineExtensionRegistry.updateExtensions sits in runFrame. startPlayMode() / stopPlayMode() mirror USCSystem.

ComponentRegistry.register(componentType: ScenePluginsComponent.self) calls onDetach on every live instance when an entity is destroyed. Callbacks run on the engine's simulation thread: main on macOS and iOS, the compositor render thread on visionOS (runFrame is driven from there in XR). Components must not touch SwiftUI or UIKit state directly. The kit builds in language mode 6; user sources compile in language mode 5 (same as the editor and generated games).

Two places, named apart on purpose. The plugins folder belongs to the one game: part of the app like any source folder, no manifest, created by the editor. A plugin package is a Swift package of its own that several projects share (UntoldGaussianTwins), with a Package.swift for games and an untold-package.json for the editor; it is the "plugin package" of the engine's plugin architecture docs. Either can hold component, entity and editor menu plugins. BuildSystem.pluginsFolderName(forProject:) is the one place the folder name lives; the names from before the rename (<Project>Components, the components and plugins keys, untold-plugin.json) are still read, and each is reported in the Plugins tab and the console with what to rename it to, so projects made earlier keep working.

UntoldEditor.json (optional, project root):

{ "pluginsFolder": "Sources/SplatTwinPlugins",
  "pluginPackages": [ { "path": "../../../Libs/UntoldGaussianTwins" } ] }

untold-package.json (plugin package root):

{ "id": "com.miolabs.untold.gaussianTwins",
  "module": "UntoldGaussianTwins",
  "runtimeSources": "Sources/UntoldGaussianTwins",
  "editorSources": "Sources/UntoldGaussianTwinsEditor" }

If the plugins folder is missing, the panel offers Create plugins folder, mirroring ScriptProjectManager.initializeProject.

Compiling against the editor's own modules is what lets loaded code share the editor's engine (one scene, one registry). The bundle ships Contents/Resources/ComponentSDK/:

ComponentSDK/
├── Modules/
│   ├── UntoldEngine.swiftmodule          (+ .swiftdoc)
│   ├── UntoldComponentKit.swiftmodule    (+ .swiftdoc)
│   └── UntoldGaussianTwins.swiftmodule   (every plugin the editor links; listed in sdk.json)
├── CShaderTypes/
│   ├── *.h                               (UntoldEngine imports this clang module)
│   └── module.modulemap                  (rewritten with a relative umbrella; SwiftPM's points at the checkout)
└── sdk.json   { swiftCompilerVersion, engineRevision, target, languageMode, providedModules }

When the editor runs from source, the SDK resolves to the build directory next to the executable. Two SwiftPM layouts exist and the resolver probes both: .build/<triple>/<config>/Modules/ (classic build system, what the editor's current .build uses) and .build/out/Products/<Config>/ (the newer build system Swift 6.4 selected in the spikes). create_app_bundle.sh gains the copy step and writes sdk.json.

ComponentCompiler runs /usr/bin/xcrun swiftc by absolute path (the user's swift on PATH can be a swiftly shim; on the baseline machine it points at a missing toolchain):

/usr/bin/xcrun swiftc -emit-library -parse-as-library \
  -o <cache>/<Module>_r<N>.dylib -module-name <Module>_r<N> \
  -emit-module -emit-module-path <cache>/<Module>_r<N>.swiftmodule \
  -module-alias <Plugin>=<Plugin>_r<N>            (one per reloadable plugin this module imports)
  -swift-version 5 -Onone -g -D UNTOLD_EDITOR \
  -target arm64-apple-macosx14.0 -sdk "$(xcrun --sdk macosx --show-sdk-path)" \
  -I <SDK>/Modules -I <cache> -Xcc -fmodule-map-file=<SDK>/CShaderTypes/module.modulemap \
  -Xlinker -undefined -Xlinker dynamic_lookup \
  <every .swift in the source folder>

<cache> is ~/Library/Caches/com.untoldengine.studio/Components/<project-hash>/. Build order: package runtime modules, then package editor modules, then the project module. Diagnostics go to the Log Console and the Components panel. The compile runs as a TaskCenter task with cancel. Pre-flight: swiftc --version must equal sdk.json.swiftCompilerVersion; otherwise one clear error names the required Xcode. -D UNTOLD_EDITOR lets sources guard editor-only code with #if UNTOLD_EDITOR.

ComponentLibraryLoader loads plugin runtime libraries with RTLD_NOW | RTLD_GLOBAL and everything else with RTLD_NOW | RTLD_LOCAL, then runs discovery on each image. Spike D showed why: a module that imports a reloadable plugin resolves the plugin's symbols through the flat namespace, which only sees global images. Libraries are never dlclosed: Swift runtime metadata cannot be unloaded safely. N increments per build and every module name is unique per build, which avoids the ObjC runtime's duplicate-class registration (spike A). -module-alias keeps import UntoldGaussianTwins valid in source while the real module is UntoldGaussianTwins_r<N> (spike D).

Runs on the main thread between frames (the draw loop is on main; a DispatchQueue.main block lands between two MTKView draws):

1. If play mode is on, stop it. This restores the pre-play snapshot, so play-mode drift is never migrated.
2. Snapshot: every slot's live instance is reflected into its payload. Extensions get onUnload().
3. Load revision N+1 of every rebuilt module, discover, rebind every type by name. Types that disappeared keep their payload and lose their instance.
4. Re-instantiate components: init(), apply payload (missing property: default; extra property: dropped, logged), onAttach(). Instantiate extensions, rebuild their menu items, re-apply persisted values, call onLoad() then menuDidChange per item.
5. Refresh inspector and hierarchy. USC action registrations are replaced.

The old libraries stay mapped. Their memory cost is roughly the dylib size per reload and is shown in the panel.

• A DispatchSource watcher on every reloadable source folder, debounced 300 ms, triggers compile + reload when Rebuild on save is on. Off by default on the first open of a project; the panel asks once. A manual Build button always exists. The editor only ever compiles the opened project's component folder and the plugins that project declares.
• Components from code are rendered by ScenePluginInspectorView, drawn by the Inspector directly like Splat Twin so scene-composition mode keeps them, and styled like the engine's components. Per attached instance: display name, remove button, the field form generated from untoldAttributes(), then action buttons. Unknown types render as a read-only row that keeps their payload. There is one Add Component menu (AddComponentMenu): the engine's components, then the registry's types under a "From Code" heading. Edits go through EditorUndoManager.registerValueChange, mark the scene dirty, and call onEditorChanged(property:).
• The Content browser's Primitives and Lights shelves list the entity kinds loaded code added under the built-in rows, and an Entities shelf appears while it has any (§5.6).
• A Plugins tab beside Log and Tasks: per-module status (r<N>, built at, compiler), discovered components with instance counts, loaded extensions with their menu paths, entity kinds with their shelf, the error list (click opens the file at the line in Xcode via xed --line), and the buttons Build, Rebuild on save, Open in Xcode, Reveal folder.
• Everything sits behind EditorFeatureFlags.enableCodeComponents.

EditorMenuHost owns every contributed NSMenuItem. It builds items from untoldMenuItems() of each loaded extension, maps each domain to its root menu (Debug and Tools are shown only while they hold items), tags items with their owner revision, and on reload removes the old revision's items before building the new ones. It is the NSMenuDelegate for contributed menus: menuNeedsUpdate calls the extension's menuWillOpen() and then syncs checkmarks and radio marks from the wrapped values, the same pattern the app delegate uses today for its own items. A click writes the wrapper, persists the value, and calls menuDidChange(domain, path).

A plugin package keeps its runtime where it is (Sources/UntoldGaussianTwins, linked by games through SwiftPM as today) and adds an editor-only folder, Sources/UntoldGaussianTwinsEditor, which no game target compiles.

Two loading modes:

• The editor links the plugin (the twins today). The SDK provides the runtime module, the loader compiles only the plugin's editor sources, and their symbols resolve into the running editor exactly as engine symbols do. There is one GaussianTwinSystem. This is the mode to start with.
• The editor does not link the plugin. The loader compiles the runtime sources as <Module>_r<N>, loads it globally, and aliases it for everything that imports it. This works for Swift-only plugins without resources, which is what UntoldGaussianTwins is (three files, one dependency). Plugins with metallibs or C targets need a resource story first and are out of scope for v1.

A plugin must never be present both ways at once: a statically linked copy and a loaded copy would mean two singletons, with the inspector talking to one and the menu to the other. sdk.json.providedModules is what the loader checks.

Migration of the twins integration happens after the feature has been tested on the sample project (stage 5), in two steps:

1. Menus and system lifecycle move to GaussianTwinsEditor (§5.1): Preview Splat Twins, the Splat Debug toggles and radio submenus, the Working Set submenu, install/uninstall and sceneDidReset. GaussianTwinPreviewSettings.swift and the menu code in UntoldEditorApp.swift are deleted. The editor keeps linking the plugin.
2. The Splat Twin inspector section, align mode and link persistence stay in the editor for now. They are SwiftUI views over editor internals, and the declarative API here cannot express them. They move when an editor UI module exists for plugins to import (out of scope, listed in stage 4). After that the editor stops linking the plugin.

Spikes A and B ran on 2026-09-14, C and D on 2026-09-17. Appendix B has the commands.

• Compiling against the editor's real UntoldEngine.swiftmodule (it imports CShaderTypes and Metal) with the SDK layout in §7.2, from a bundled app and from a source build, in both SwiftPM layouts.
• -target and deployment-target agreement between the editor binary and the loaded dylibs.
• Removing and rebuilding contributed NSMenuItems across a reload while a menu is open.
• Wall time of a full compile (expected 1 to 3 s for a handful of files) and of the reload protocol on a scene with a few hundred instances.

Generated projects and the twin demos are XcodeGen projects. Their app target's sources are Sources/ minus GameData, so Sources/<Project>Plugins/ is compiled into the app with no new target. Three changes:

1. XcodeGenProjectSpec.generateYAML adds the kit to the app target's dependencies:

    dependencies:
      - package: UntoldEngine
        product: UntoldComponentKit

2. The engine package reference comes from BuildSettings instead of the hardcoded upstream URL and branch: develop, and defaults to the revision the editor was built with (D8). While the kit exists only on the fork, projects that use it point at https://github.com/miolabs/UntoldEngine.git.
3. The generated GameScene registers before loading scenes:

private func configureEngineSystems() {
    gameMode = true
    AnimationSystem.shared.isEnabled = true
    ComponentPluginRegistry.discoverInApp()
    ScenePluginSystem.install()          // registers the EngineExtension and the storage component's serializer
    ScenePluginSystem.shared.startPlayMode()
    /* ... */
}

Scenes decode customComponents as they do today; slots bind to the statically linked types; onAttach and onStart run. iOS and visionOS use exactly this path. Nothing dynamic ships in a game. EditorMenuPlugin subclasses compile into the game only if their file is not guarded by #if UNTOLD_EDITOR; they are never instantiated there.

XcodeGen lists files at generation time, so the editor re-runs xcodegen generate after it creates the plugins folder or a new plugin file (BuildSystem already locates the tool). For an existing project such as SplatTwin or BedroomTwin, Create component package adds the dependency line to project.yml, regenerates, and prints the registration snippet to the Log Console.

SwiftPM-style projects (the legacy BuildTemplates.packageSwift path) get the same result with a <Project>Plugins library target that the executable depends on.

Branches are cut from the fork's develop. The editor feature branch points its engine dependency at the engine feature branch by name. Commits and pushes to the fork are fine at any time; no pull request until §12's end-to-end bar is met.

Order: 1 before 1b and 2; 2 before 2b, 2c and 3; 3b needs 1b and is what stages 2 to 3 are tested against; 5 starts only after the end-to-end test passes; 4 is independent items. Stage 2 alone is already useful: libraries load once at project open, and a relaunch picks up changes.

• Stage 1. A test target defines a ComponentPlugin subclass with every supported kind; untoldAttributes() lists them in order; a scene saved with the kit's payload loads back with equal values; a scene saved with a type the test image does not contain round-trips its payload unchanged; onUpdate runs only in game mode; USC callAction("Type.Action") invokes the action on the entity; an EditorMenuPlugin subclass reports its menu descriptors with parsed paths.
• Stage 1b. A project created from the editor builds in Xcode with a components folder that contains the starter component, and the running game instantiates it from the saved scene.
• Stage 2. Opening a project with a plugins folder compiles it, the Plugins panel lists the types, and Add Component offers them. A compile error appears in the panel and the Log Console with file and line, and clicking it opens Xcode at that line. From a bundled app the compile uses only files inside Contents/Resources/ComponentSDK.
• Stage 2b. Every kind renders its control; edits are undoable and mark the scene dirty; values survive save and reload of the scene.
• Stage 2c. An extension's @UntoldMenu(.debug, "Splat Twin/…") items appear when its library loads, under the editor's Debug root, which was hidden while empty; an item cannot name or create a root menu; toggles show checkmarks, enums show radio marks, values persist across relaunch, and the menu disappears when the project closes.
• Stage 3. Editing and saving a component in Xcode while the editor is open, with rebuild-on-save on, updates the inspector within a few seconds; instance values survive the reload; a renamed property falls back to its default and logs; a removed type keeps its payload and shows as unavailable; menu items are rebuilt with their values kept.
• End to end (the bar for opening pull requests). Run on Examples/CodeComponentsSample. The project opens in the editor. Its components compile, load, are editable and hot-reload. The sample extension's Debug menu and the sample plugin's menu appear on load, keep their values across reload and relaunch, and disappear when the project closes. The sample app builds in Xcode with the same component sources and behaves the same from the saved scene.
• After the bar (stage 5). The twins plugin's menus come from the plugin's own editor sources, no twin menu code remains in the editor, and the twin demo builds for visionOS with a components folder.

Kit tests run on macOS in swift test and are platform neutral apart from discovery, which is tested on macOS only. Editor tests use @testable import UntoldEditor under swift test --filter UntoldEditorTests as today. The dynamic-loading integration test builds fixtures with the same compiler invocation the editor uses, against the test process's own build directory, and loads them: one standalone module, and one plugin runtime plus a dependent module through an alias. It is the automated form of spikes A, C and D and guards the same-compiler contract; it runs only when xcrun swiftc is available (skipped otherwise, never failed). Menu host tests work on descriptors and an NSMenu built in memory; no window is needed.

Engine

• Package.swift: product UntoldComponentKit, target Sources/UntoldComponentKit, test target.
• Sources/UntoldComponentKit/: ComponentPlugin.swift, UntoldAttribute.swift, UntoldAttributeValue.swift, EntityRef.swift, AssetRef.swift, PluginAction.swift, EditorMenuPlugin.swift, UntoldMenu.swift, ScenePluginsComponent.swift, ComponentPluginRegistry.swift, EditorMenuPluginRegistry.swift, ImageDiscovery.swift, ScenePlugin.swift, ScenePluginSystem.swift, USCBridge.swift, EntityPlugin.swift, EditorRepresentation.swift.
• Sources/UntoldEngine/Mesh/BasicPrimitives.swift: createMesh(from:).
• Sources/UntoldEngine/BuildSystem/XcodeGenProjectSpec.swift: kit dependency, configurable engine reference.
• Sources/UntoldEngine/BuildSystem/BuildTemplates.swift: registration call, starter component file, SwiftPM template target.
• Sources/UntoldEngine/BuildSystem/BuildSystem.swift: add-to-existing-project helper, xcodegen generate re-run.
• docs/API/UsingCodeComponents.md, docs/index.md link.

Editor

• Sources/UntoldEditor/Components/: ComponentSourceLocator.swift, EditorProjectManifest.swift, PluginPackageManifest.swift, ComponentSDK.swift, ComponentCompiler.swift, ComponentLibraryLoader.swift, ComponentReloadCoordinator.swift, ComponentSourceWatcher.swift, ComponentsPanelView.swift, ScenePluginInspectorView.swift, EditorMenuHost.swift.
• Sources/UntoldEditor/UntoldEditorApp.swift: hand the menu bar to EditorMenuHost; in stage 3b, delete the twin and splat debug items.
• Sources/UntoldEditor/Editor/InspectorView.swift: the code component blocks and the one AddComponentMenu.
• Sources/UntoldEditor/Components/: also AddComponentMenu.swift, EntityPluginPlacement.swift, EntityPluginShelfViews.swift, EditorRepresentationRenderer.swift.
• Sources/UntoldEditor/Editor/AssetPlacement.swift, AssetBrowserView.swift, AssetBrowserNavigationState.swift: the entity plugin row payload, the rows on the shelves, the Entities shelf.
• Sources/UntoldEditor/Renderer/EditorRenderPasses.swift: markers drawn in the light marker pass.
• Sources/UntoldEditor/Editor/ComponentEditorForm.swift: new EditorField kinds.
• Sources/UntoldEditor/Editor/EditorView.swift: discovery on project open, play-mode start/stop, scene-reset notifications to extensions, bottom-panel tab.
• Sources/UntoldEditor/Config/EditorFeatureFlags.swift: enableCodeComponents.
• create_app_bundle.sh: Component SDK copy and sdk.json.
• Tests/UntoldEditorTests/: one file per new type plus ComponentLoaderIntegrationTests.swift.

UntoldGaussianTwins

• untold-package.json, Sources/UntoldGaussianTwinsEditor/GaussianTwinsEditor.swift.

Spike A, host package: a library target exporting public var sharedCounter, a Registry class, a Plugin protocol, register(_:), and an @inline(never) function the executable never calls; an executable that dlopens each argument, dlsyms untold_plugin_entry, calls it, and prints the global. Build with /usr/bin/swift build -c release. Compile and run the plugin:

BIN=.build/release
/usr/bin/swiftc -emit-library -o libPlugin.1.dylib -module-name GameComponents_r1 \
  -I "$BIN" -I "$BIN/Modules" Plugin.swift -Xlinker -undefined -Xlinker dynamic_lookup
"$BIN/HostApp" libPlugin.1.dylib
nm -m libPlugin.1.dylib | grep 'dynamically looked up'

Spike B: a single file with the class wrapper, its protocol, a ComponentPlugin base with the reflection walk, and a PlayerController subclass; compile with /usr/bin/swiftc -O reflect.swift and run.

Spike C: a discoverComponents(imagePath:) function built on objc_copyClassNamesForImage and class_getSuperclass; two subclasses nothing references. Build the three-file executable with -O, with -O -Xlinker -dead_strip, and with -O -whole-module-optimization -Xlinker -dead_strip, and pass _dyld_get_image_name(0). For the dylib case the host dlopens the path and passes the same path to discovery.

Spike D:

swiftc -emit-library -parse-as-library -emit-module -emit-module-path out/TwinLib_r1.swiftmodule \
  -module-name TwinLib_r1 -o out/TwinLib_r1.dylib -I "$BIN" TwinLib.swift -Xlinker -undefined -Xlinker dynamic_lookup
swiftc -emit-library -parse-as-library -module-name GameComponents_r1 -module-alias TwinLib=TwinLib_r1 \
  -o out/GameComponents_r1.dylib -I "$BIN" -I out Project.swift -Xlinker -undefined -Xlinker dynamic_lookup
"$BIN/HostApp" G:out/TwinLib_r1.dylib out/GameComponents_r1.dylib     # "G:" = RTLD_GLOBAL in the spike host