# Understanding LongEventHandler.QueueLongEvent() in RimWorld Modding

[ekudram]

Understanding LongEventHandler.QueueLongEvent() in RimWorld Modding

🎮 The Problem: UI Stutter During File Operations

When mods save data to disk during gameplay, there's a potential issue: UI stutter. Even on modern SSDs, writing large JSON files can cause a brief hiccup in the game's frame rate. On mechanical hard drives, this is much worse.

🔍 The RimWorld Solution: LongEventHandler.QueueLongEvent()

RimWorld provides a built-in solution for this exact problem:

LongEventHandler.QueueLongEvent(() =>
{
    // Your file saving code here
    SaveMyDataToJson();
}, 
"RICS_SavingData",                    // Text shown to user
true,                                 // Run asynchronously
null,                                 // Exception handler
showExtraUIInfo: false,
forceHideUI: true);

🧠 How It Actually Works

The Magic: Deferred Execution

When you call QueueLongEvent(), RimWorld doesn't execute your code immediately. Instead:

1. Game continues running - Players keep playing normally
2. Your code gets queued - Added to RimWorld's internal task queue
3. RimWorld finds the right moment - Executes when it won't disrupt gameplay
4. Optional UI feedback - Can show progress bar if you want

The Key Insight

Even when the game is paused (in a dialog), there's still rendering happening:

• Animations (spinning icons, progress indicators)
• UI updates (tooltips, highlights)
• Background processing (other mods, game systems)

Direct File.WriteAllText() = Immediate execution = Potential micro-stutter
QueueLongEvent() = Deferred execution = Smooth gameplay

📊 Real-World Example from RICS

Here's how RICS uses it:

// ❌ WRONG - Causes potential stutter
public static void SaveDataBad()
{
    string json = SerializeData();
    File.WriteAllText("data.json", json);  // Blocks main thread!
}

// ✅ CORRECT - No stutter, async execution  
public static void SaveDataGood()
{
    LongEventHandler.QueueLongEvent(() =>
    {
        lock (lockObject)  // Still need thread safety
        {
            string json = SerializeData();
            File.WriteAllText("data.json", json);
        }
    }, null, true, null, false, true);
}

🎯 When to Use It

Use QueueLongEvent() For	Don't Use It For
Saving large files (>1KB)	Tiny config files
Complex calculations	Simple math operations
Database operations	Memory-only operations
Network requests	UI event handlers
Any disk I/O	Anything time-critical

🔄 RICS Data Flow Architecture

Understanding this helps explain why RICS is architected this way:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│    JSON File    │◄───┤    Save/Load    │◄───┤ LongEventHandler│
│   (Persistent)  │    │   (Disk I/O)    │    │  (Async Queue)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         ▲                         ▲                    ▲
         │                         │                    │
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Dictionary    │    │  Game Systems   │    │     UI/Editor   │
│  (Memory Cache) │───►│  (All Commands) │◄───┤   (User Input)  │
│                 │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
        Runtime Operations              Trigger Save Only on Changes

Key Principle: JSON is only for persistence. All runtime operations use the in-memory Dictionary for performance.

🛡️ Why This Matters for Streamers

Streamers often have:

• Chat commands that modify settings in real-time
• Viewer interactions during gameplay
• No tolerance for stutter (looks unprofessional)

Using QueueLongEvent() ensures:

1. Smooth gameplay even while saving
2. No dropped frames on stream
3. Professional appearance to viewers

🧪 Testing the Difference

You can test this yourself:

// Add to your mod for testing:
[DebugAction("Test", "Test Sync Save", allowedGameStates = AllowedGameStates.Playing)]
public static void TestSyncSave()
{
    // Create a large dataset
    var bigData = new StringBuilder();
    for (int i = 0; i < 10000; i++)
        bigData.AppendLine($"Line {i}: {new string('X', 1000)}");
    
    // ❌ Sync save - watch for stutter
    File.WriteAllText("test_sync.json", bigData.ToString());
    Messages.Message("SYNC save done - did you stutter?", MessageTypeDefOf.NeutralEvent);
}

[DebugAction("Test", "Test Async Save", allowedGameStates = AllowedGameStates.Playing)]
public static void TestAsyncSave()
{
    var bigData = new StringBuilder();
    for (int i = 0; i < 10000; i++)
        bigData.AppendLine($"Line {i}: {new string('X', 1000)}");
    
    // ✅ Async save - smooth gameplay
    LongEventHandler.QueueLongEvent(() =>
    {
        File.WriteAllText("test_async.json", bigData.ToString());
    }, "Saving test data...", true, null);
    
    Messages.Message("ASYNC save queued - should be smooth", MessageTypeDefOf.NeutralEvent);
}

🎓 The Big Picture

Why RICS uses this architecture:

1. Performance: Memory is faster than disk
2. Reliability: Single source of truth (Dictionary)
3. User Experience: No stutter during saves
4. Mod Compatibility: Plays nice with other mods
5. Streamer-Friendly: Professional, smooth operation

📚 Further Reading

• RimWorld LongEventHandler Documentation
• Unity Threading Best Practices
• RICS Source Code

💬 Discussion

Q: Why not just use Task.Run() or threads?
A: RimWorld's Unity engine has specific threading requirements. LongEventHandler is the approved, safe way to do background work.

Q: What about error handling?
A: QueueLongEvent() has an exceptionHandler parameter for proper error handling in the game's context.

Q: When should I NOT use it?
A: Don't use it for time-critical operations that must complete immediately (like processing a chat command that needs instant feedback).

---

This is why RICS saves data the way it does. It's not an oversight - it's a deliberate design choice for performance and user experience.