Serialization Review

Overview

This skill audits JSON serialization implementation to ensure scenes, prefabs, and components serialize/deserialize correctly, maintain version compatibility, handle resource references properly, and follow established serialization patterns.

Table of Contents

• Overview
• When to Use
• Serialization Architecture
• Serialization Patterns
• Review Checklist
• Review Output Format
• Examples

When to Use

Invoke this skill when:

• Adding new serializable components
• Debugging scene save/load issues
• Implementing new asset types (prefabs, animations, tilemaps)
• Refactoring component data structures
• Versioning serialization format
• Questions about custom JsonConverter implementation
• Investigating data corruption or missing data after load

Serialization Architecture

SceneSerializer

Location: Engine/Scene/Serializer/SceneSerializer.cs

Responsibilities:

• Serialize/deserialize entire scene to/from JSON
• Handle entity hierarchy and component serialization
• Manage custom converters and serialization options

Key Methods: Serialize(Scene, path), Deserialize(path)

Custom Converters

Location: Engine/Scene/Serializer/

Existing Converters:

• Vector2Converter, Vector3Converter, Vector4Converter
• TileMapComponentConverter
• Component-specific converters for complex types

Serialization Patterns

1. JsonIgnore for Runtime Data

Pattern: Use [JsonIgnore] for runtime-only data

public class RigidBody2DComponent
{
    // Serialized properties
    public BodyType Type { get; set; } = BodyType.Dynamic;
    public float Mass { get; set; } = 1.0f;
    public bool FixedRotation { get; set; } = false;

    // Runtime-only (not serialized)
    [JsonIgnore]
    public Body? RuntimeBody { get; set; }

    // Runtime-only (not serialized)
    [JsonIgnore]
    public World? RuntimeWorld { get; set; }
}

Why?: Runtime objects (physics bodies, loaded meshes, textures) should not be serialized - they're recreated at runtime.

2. Resource Path Serialization

Pattern: Store paths, not loaded resources

public class SpriteRendererComponent
{
    // Serialize path, not loaded texture
    public string TexturePath { get; set; } = string.Empty;

    // Color is serialized
    public Vector4 Color { get; set; } = Vector4.One;

    // Runtime-only loaded texture (not serialized)
    [JsonIgnore]
    public Texture? LoadedTexture { get; set; }
}

// At runtime, load texture from path with error handling
if (!string.IsNullOrEmpty(sprite.TexturePath))
{
    try
    {
        sprite.LoadedTexture = textureFactory.LoadTexture(sprite.TexturePath);
    }
    catch (FileNotFoundException)
    {
        logger.Warn($"Missing texture: {sprite.TexturePath}");
        sprite.LoadedTexture = textureFactory.GetDefaultTexture();
    }
}

3. Custom Converter for Complex Types

When Needed:

• Custom serialization format or optimized JSON structure
• Backward compatibility with breaking changes
• Complex type handling (vectors, GUIDs, nested structures)

Review Checklist

When reviewing serialization implementation, verify:

1. Runtime Data Exclusion

• All runtime objects marked with [JsonIgnore]
• Physics bodies, loaded textures/meshes not serialized
• Cached/computed values excluded

2. Resource References

• Paths stored instead of loaded resources
• Valid path format (relative to project root)
• Missing path handling at load time

3. Circular References

• Entity parent/child relationships handled correctly
• Component cross-references resolved properly
• No infinite loops in serialization

4. Version Compatibility

• New fields have default values
• Removed fields handled gracefully
• Custom converters for breaking changes

5. Custom Converters

• Necessary (complex types, optimization, compatibility)
• Read/Write methods symmetric
• Registered in serialization options

Review Output Format

Report findings as:

Issue: [Serialization problem description] Component: [Component class name] Location: [File path and line number] Problem: [What will break or serialize incorrectly] Fix: [Code change with before/after] Priority: [Critical/High/Medium/Low]

Example Report

Issue: Runtime physics body being serialized Component: RigidBody2DComponent Location: Engine/Scene/Components/RigidBody2DComponent.cs:45 Problem: RuntimeBody property will serialize the entire Box2D body object, causing massive JSON files and deserialization failures (Box2D objects aren't JSON-serializable) Fix:

// Before
public Body? RuntimeBody { get; set; }

// After
[JsonIgnore]
public Body? RuntimeBody { get; set; }

Priority: Critical

Examples

For detailed guidance and comprehensive examples:

Custom Converters

Complete JsonConverter implementations with:

• Full AnimationComponent converter with error handling
• Vector3, GUID, and common type converters
• Registration and testing patterns
• Best practices for symmetric Read/Write methods

Common Issues

Anti-pattern catalog with before/after fixes:

• Runtime objects not marked [JsonIgnore]
• Loaded resources instead of paths
• Missing default values for new fields
• Circular references in entity hierarchy
• Platform-specific path separators
• Asymmetric converter implementations