manage-world-lifecycle

name	manage-world-lifecycle
description	Understand and extend the CLOiSim world load → plugin start → reset → save lifecycle. Use when: debugging world loading failures, troubleshooting plugin startup coordination, fixing reset behavior, extending the world save pipeline, diagnosing physics mode switching issues, understanding PluginStartTracker events.

Manage World Lifecycle

Reference guide for the complete CLOiSim simulation lifecycle: world loading, plugin startup coordination, runtime reset, and world state persistence.

When to Use

• Debugging why a world fails to load or hangs during plugin startup
• Adding a new component that needs to participate in the reset cycle
• Understanding the PluginStartTracker event system
• Extending WorldSaver to persist new element types
• Diagnosing physics simulation mode switching issues
• Coordinating multi-plugin dependencies during startup

Lifecycle Overview

┌─────────────────────────────────────────────────────────┐
│ LOAD                                                     │
│   Main.LoadWorld()                                       │
│   ├─ SDF.Root.DoParse() → parse SDF XML                │
│   ├─ Physics.simulationMode = Script                    │
│   ├─ Import.Loader.Start() → create GameObjects         │
│   ├─ Wait: worldRoot.childCount > 0                     │
│   ├─ PluginStartTracker.Bind(worldRoot)                 │
│   ├─ Physics.SyncTransforms()                           │
│   ├─ Physics.simulationMode = FixedUpdate               │
│   ├─ ResetWorld() [initial reset]                       │
│   └─ Wait: AllStarted == true                           │
├─────────────────────────────────────────────────────────┤
│ RUN                                                      │
│   Normal simulation loop                                 │
│   ├─ FixedUpdate: physics                               │
│   ├─ Update: sensors, UI                                │
│   └─ Plugins: TX/RX threads running                     │
├─────────────────────────────────────────────────────────┤
│ RESET (Ctrl+R)                                           │
│   Main.ResetSimulation()                                 │
│   ├─ SensorRenderManager.Pause()                        │
│   ├─ SimulationWorld.SignalReset()                       │
│   ├─ ResetWorld()                                       │
│   │  ├─ Helper.Base.Reset() for each helper             │
│   │  ├─ Device.Reset() for each device                  │
│   │  └─ CLOiSimPlugin.Reset() for each plugin           │
│   ├─ Wait 0.1s                                          │
│   └─ SensorRenderManager.Resume()                       │
├─────────────────────────────────────────────────────────┤
│ FULL RELOAD (Ctrl+Shift+R)                               │
│   Destroys world root, reloads from SDF                  │
├─────────────────────────────────────────────────────────┤
│ SAVE (Ctrl+Shift+S)                                      │
│   WorldSaver.Update()                                    │
│   ├─ ClearAllComments()                                 │
│   ├─ UpdateGUI() → camera pose                          │
│   ├─ UpdateModels() → model poses, static flags         │
│   └─ UpdateRoads() → road spline points                 │
└─────────────────────────────────────────────────────────┘

Plugin Startup Coordination

PluginStartTracker

Monitors all CLOiSimPlugin instances under a loaded root and fires events as they start:

// Bind to a loaded world/model root
var tracker = new PluginStartTracker();
tracker.ProgressChanged += OnPluginProgressChanged;   // (started, total)
tracker.AllStartedEvent += OnAllPluginsStarted;        // fires once
tracker.Bind(worldRoot);

// ProgressChanged fires for each plugin that completes OnStart()
// AllStartedEvent fires when StartedCount == TotalCount

Plugin Startup Flow

Each CLOiSimPlugin follows this internal sequence:

Awake()
  └─ OnAwake() [abstract] — set _type, cache components

Start() [coroutine]
  └─ OnStart() [abstract] — register ports, add threads
     ├─ RegisterTxDevice() / RegisterRxDevice()
     ├─ RegisterServiceDevice() / RegisterClientDevice()
     ├─ AddThread(port, threadFunction, device)
     └─ yield return null

  └─ Raises Started event → PluginStartTracker.OnPluginStarted()

Waiting for All Plugins

// In Main.cs — world is not considered loaded until all plugins start
private void OnAllPluginsStarted()
{
	_pluginAllStarted = true;
	BridgeManager.PrintAllocatedHistory();
}

// LoadWorld() waits in a while loop:
while (!_pluginAllStarted)
	yield return null;

Reset Cascade

ResetWorld() resets components in three phases:

void ResetModel(GameObject targetObject)
{
	// Phase 1: Reset poses (Helper.Base components)
	foreach (var helper in targetObject.GetComponentsInChildren<Helper.Base>())
		helper.Reset();
	// → Restores initial pose via PoseControl
	// → Rewinds animation state

	// Phase 2: Reset devices
	foreach (var device in targetObject.GetComponentsInChildren<Device>())
		device.Reset();
	// → Clears message queues
	// → Resets synthetic timestamps

	// Phase 3: Reset plugins
	foreach (var plugin in targetObject.GetComponentsInChildren<CLOiSimPlugin>())
		plugin.Reset();
	// → Calls OnReset() [virtual]
	// → Plugin-specific state restoration
}

SimulationWorld Reset Signal

SimulationWorld sends a reset signal to the external ROS bridge:

// Triggered by Main.ResetSimulation()
SimulationWorld.SignalReset();
// → Sets _signalReset = true
// → ClientThread sends messages.Param { "reset_simulation": true }
// → External bridge receives and resets its state

World Save Pipeline

WorldSaver serializes current scene state back to the loaded SDF XML:

// UpdateModels() for each model in scene:
// 1. Remove stale <include> elements
// 2. Remove <model> elements not present in scene
// 3. For each child in WorldRoot:
//    - Get Helper.Model → original model path
//    - Create/update <include> or <model> element
//    - Set <static> from GameObject.isStatic
//    - Set <pose> via Unity2SDF.Pose(position, rotation)

// UpdateRoads() for each road:
// 1. Remove all <road> elements
// 2. Recreate from Main.RoadsRoot children
// 3. Save spline knots as <point> elements

// UpdateGUI() for camera:
// 1. Get Camera.main transform
// 2. Convert to SDF pose via Unity2SDF.Pose()
// 3. Write to <gui><camera><pose>

Physics Mode Switching

During world loading, physics must be paused to prevent objects from falling while being constructed:

// Before construction:
Physics.simulationMode = SimulationMode.Script;
// → Physics does NOT run automatically
// → Objects can be positioned without falling

// After construction:
Physics.SyncTransforms();
// → Syncs all manually-set transforms to physics engine
Physics.simulationMode = SimulationMode.FixedUpdate;
// → Normal physics simulation resumes

Procedure: Adding a New Resetable Component

To make a new component participate in the reset cycle:

1. If it's a Helper — inherit from Helper.Base and override Reset():

   public class MyHelper : Base
   {
       private float _initialValue;
   
       new protected void Start()
       {
           base.Start();
           _initialValue = currentValue;
       }
   
       public new void Reset()
       {
           base.Reset(); // Resets pose
           currentValue = _initialValue;
       }
   }
   

2. If it's a Device — override OnReset() in your Device subclass:

   protected override void OnReset()
   {
       // Clear accumulated state
       _accumulatedData = 0;
   }
   

3. If it's a Plugin — override OnReset() in your CLOiSimPlugin subclass:

   protected override void OnReset()
   {
       // Reset plugin-specific state
       _commandBuffer.Clear();
   }
   

Procedure: Extending World Save

To save a new element type in WorldSaver:

1. Add an Update*() method:

   private void UpdateMyElements()
   {
       // Remove stale elements
       var staleNodes = _worldNode.SelectNodes("my_element");
       foreach (XmlNode node in staleNodes)
           _worldNode.RemoveChild(node);
   
       // Add current elements from scene
       foreach (var element in FindMyElements())
       {
           var xmlNode = _doc.CreateElement("my_element");
           xmlNode.SetAttribute("name", element.Name);
   
           // Convert pose to SDF
           var sdfPose = Unity2SDF.Pose(
               element.transform.position, element.transform.rotation);
           // Write pose to XML...
   
           _worldNode.AppendChild(xmlNode);
       }
   }
   

2. Call it from Update():

   public void Update()
   {
       ClearAllComments();
       UpdateGUI();
       UpdateModels();
       UpdateRoads();
       UpdateMyElements(); // Add here
   }
   

Critical Pitfalls

Pitfall	Details	Mitigation
Plugin start order is undefined	Plugins start in parallel via background threads. Do NOT assume plugin A starts before plugin B.	Use AllStartedEvent to synchronize cross-plugin dependencies.
Reset called during initial load	ResetWorld() runs once during LoadWorld() before plugins finish starting.	Ensure OnReset() handles being called before OnStart() completes.
Stale plugin references	PluginStartTracker.Bind() walks the scene once at load time. Dynamically added plugins are NOT tracked.	Rebind if plugins are added post-load.
Transform sync timing	Manual transform changes during runtime are not synced to physics automatically (autoSyncTransforms is off).	Call Physics.SyncTransforms() after manual teleport operations.
Physics mode must bracket construction	Objects fall during construction if physics is FixedUpdate.	Set SimulationMode.Script before creating objects, restore after.
SensorRenderManager must pause during reset	Sensors continue rendering during reset, producing stale/corrupt data.	Always Pause() before reset, Resume() after.
WorldSaver removes XML comments	ClearAllComments() strips all <!-- --> from the saved file.	Don't rely on XML comments surviving save cycles.

Key Events Reference

Event	Source	Fired When	Listeners
CLOiSimPlugin.Started	Each plugin	OnStart() coroutine completes	PluginStartTracker
PluginStartTracker.ProgressChanged(int, int)	Tracker	Each plugin starts	Main → UI progress
PluginStartTracker.AllStartedEvent	Tracker	All plugins started	Main → finalize load