add-sdf-element

name	add-sdf-element
description	Extend the SDF parse → import → implement pipeline with a new element type. Use when: adding support for a new SDF XML element, extending world/model import, creating new Helper MonoBehaviours.

Add a New SDF Element

Procedure for adding support for a new SDF XML element through the full pipeline: Parser → Importer → Implementer → Helper.

When to Use

• Adding a new SDF element type (e.g., <heightmap>, <population>, <atmosphere>)
• Extending an existing element with new child elements
• Creating a new category of scene object that needs runtime state tracking

Architecture

SDFormat package (Parser)  →  Import.Loader (Importer)  →  Implement.* (Implementer)
        ↓                            ↓                            ↓
  C# domain class           Unity GameObjects created    Components/colliders/renderers
                                     ↓
                              Helper.* MonoBehaviour (runtime state)

Procedure

1. Extend the SDFormat Parser Package

The parser lives in the external com.lge-ros2.sdformat Unity package. Add or extend a domain class:

// In the SDFormat package:
namespace SDFormat
{
    public class MyElement
    {
        public string Name { get; set; }
        public Math.Pose3d RawPose { get; set; }
        public string PoseRelativeTo { get; set; }
        // Add fields matching SDF XML attributes/children
    }
}

Ensure the parser populates this class from the corresponding XML element. If the element is a child of <model>, <link>, <world>, etc., add a collection property to the parent:

// In the parent class (e.g., Model):
public IReadOnlyList<MyElement> MyElements => _myElements;

2. Add Virtual Method in Import.Base.Common

Edit Assets/Scripts/Tools/SDF/Import/Import.Base.Common.cs:

protected virtual object ImportMyElement(in MyElement element, in object parentObject)
{
    PrintNotImported(MethodBase.GetCurrentMethod().Name, element.Name);
    return null;
}

If the element needs post-processing (after children are created):

protected virtual void AfterImportMyElement(in MyElement element, in object targetObject)
{
    PrintNotImported(MethodBase.GetCurrentMethod().Name, element.Name);
}

3. Add Iteration in Import.Base

Edit Assets/Scripts/Tools/SDF/Import/Import.Base.cs — add a batch import method:

private void ImportMyElements(IReadOnlyList<MyElement> items, in object parentObject)
{
    foreach (var item in items)
    {
        var createdObject = ImportMyElement(item, parentObject);
        // If the element has sub-elements:
        // ImportGeometry(item.Geom, createdObject);
        // StorePlugins(item.Plugins, createdObject);
    }
}

Wire it into the appropriate parent import method (e.g., in ImportLinks(), ImportModels(), or Start()).

4. Create Loader Override

Create Assets/Scripts/Tools/SDF/Import/Import.MyElement.cs:

/*
 * Copyright (c) 2026 LG Electronics Inc.
 *
 * SPDX-License-Identifier: MIT
 */

using UE = UnityEngine;

namespace SDFormat
{
    using Implement;
    namespace Import
    {
        public partial class Loader : Base
        {
            protected override object ImportMyElement(in MyElement element, in object parentObject)
            {
                var targetObject = parentObject as UE.GameObject;

                var newObject = targetObject.CreateMyElement(element);

                return newObject;
            }
        }
    }
}

5. Create Implement Extension Methods

Create Assets/Scripts/Tools/SDF/Implement/Implement.MyElement.cs:

/*
 * Copyright (c) 2026 LG Electronics Inc.
 *
 * SPDX-License-Identifier: MIT
 */

using UE = UnityEngine;

namespace SDFormat
{
    namespace Implement
    {
        public static class MyElement
        {
            public static UE.GameObject CreateMyElement(
                this UE.GameObject targetObject, in SDFormat.MyElement element)
            {
                var newObject = new UE.GameObject(element.Name);
                newObject.tag = "MyTag";  // Use existing tag or request a new one

                newObject.transform.SetParent(targetObject.transform, false);

                // Apply SDF pose
                if (element.RawPose != null)
                {
                    var (pos, rot) = element.RawPose.ToUnity();
                    newObject.transform.localPosition = pos;
                    newObject.transform.localRotation = rot;
                }

                // Add Helper for runtime state
                var helper = newObject.AddComponent<Helper.MyElement>();
                helper.Pose = element.RawPose;
                helper.PoseRelativeTo = element.PoseRelativeTo;

                // Create Unity components (renderers, colliders, etc.)
                // ...

                return newObject;
            }
        }
    }
}

6. Create Helper MonoBehaviour (If Needed)

Create Assets/Scripts/Tools/SDF/Helper/MyElement.cs:

/*
 * Copyright (c) 2026 LG Electronics Inc.
 *
 * SPDX-License-Identifier: MIT
 */

using UE = UnityEngine;

namespace SDFormat
{
    namespace Helper
    {
        public class MyElement : Base
        {
            [UE.Header("SDF Properties")]
            public string myProperty;

            new protected void Awake()
            {
                base.Awake();
                // Element-specific initialization
            }

            new protected void Start()
            {
                base.Start();
                // Element-specific startup
            }

            // Override if this element has runtime state to reset
            // public new void Reset()
            // {
            //     base.Reset();
            // }
        }
    }
}

7. Wire Into Orchestration

Depending on when the element needs to be processed, wire it into the orchestration flow in Import.Base.cs:

Immediate processing (during parent import):

// In ImportLinks() or ImportModels():
ImportMyElements(model.MyElements, newModelObject);

Deferred processing (needs other elements to exist first, like joints):

// Store during import:
protected void StoreMyElements(IReadOnlyList<MyElement> items, in object parentObject)
{
    foreach (var item in items)
    {
        _myElementObjectList.Add(item, parentObject);
    }
}

// Process later in Start():
private void ImportDeferredMyElements()
{
    foreach (var item in _myElementObjectList)
    {
        ImportMyElement(item.Key, item.Value);
    }
}

The orchestration order in Base.Start() is:

1. ImportWorld → ImportModels (creates GameObjects)
2. Deferred joints (needs both parent/child links)
3. Deferred grippers
4. ImportActors
5. SpecifyPose (applies all poses)
6. Deferred plugins (needs full articulation hierarchy)

Key Patterns

• Coordinate conversion: Always use SDF2Unity methods (ToUnity(), Position(), Rotation()) — never manually swap axes
• Partial class: Import.Loader is a partial class split across files. Each new element gets its own Import.*.cs file
• Extension methods: Implementers are static extension methods on GameObject in the SDFormat.Implement namespace
• Helper.Base inheritance: Always call base.Awake() and base.Start() — they handle pose control and root model discovery
• Tags: Use existing Unity tags (Model, Link, Visual, Collision, Sensor, Light, Actor, Marker, Props, Geometry, Road). Adding new tags requires editing ProjectSettings/TagManager.asset
• ArticulationBody disabled: During import, ArticulationBody components are disabled. SpecifyPose() re-enables them after all poses are applied

Checklist

• SDFormat package domain class created/extended
• Virtual method added in Import.Base.Common.cs
• Iteration method in Import.Base.cs
• Loader override in new Import.MyElement.cs partial class file
• Implement extension methods in Implement.MyElement.cs
• Helper MonoBehaviour (if runtime state needed) in Helper/MyElement.cs
• Wired into orchestration at correct stage
• Coordinate conversion uses SDF2Unity methods
• License header on all new files
• Uses tabs for indentation, Allman braces