AppleHillsProduction/docs/state_machine_save_load_integration.md

State Machine Save/Load Integration

Date: November 2, 2025
Status: ✅ Complete

Overview

Integrated the Pixelplacement StateMachine framework with the AppleHills save/load system by directly modifying the library source files and providing a clean API for state persistence.

Architecture

Two-Method Pattern

States use a clean, explicit lifecycle pattern:

1. OnEnterState() - Called when entering state during normal gameplay
2. OnRestoreState(string data) - Called when restoring state from save file
3. SerializeState() - Returns state data as JSON string for saving

How It Works

Normal Gameplay:

Player triggers transition → ChangeState("Chase")
├─ StateMachine.Enter() activates GameObject
├─ IsRestoring = false
└─ Calls state.OnEnterState()
   └─ Full initialization: animations, events, movement

Save/Load:

StateMachine.SerializeState()
├─ Returns current state name
└─ Calls currentState.SerializeState()
   └─ State returns its internal data as JSON

StateMachine.RestoreState(data)
├─ Sets IsRestoring = true
├─ ChangeState(stateName) - activates GameObject
│  └─ Does NOT call OnEnterState() (IsRestoring=true)
├─ Calls state.OnRestoreState(stateData)
│  └─ State restores without animations/effects
└─ Sets IsRestoring = false

Files Modified

1. State.cs

Location: Assets/External/Pixelplacement/Surge/StateMachine/State.cs

Added:

• OnEnterState() - virtual method for normal state entry
• OnRestoreState(string data) - virtual method for restoration
• SerializeState() - virtual method for serialization

2. StateMachine.cs

Location: Assets/External/Pixelplacement/Surge/StateMachine/StateMachine.cs

Added:

• Implements ISaveParticipant interface
• saveId field (serialized, set in inspector)
• IsRestoring property (public, readable by states)
• HasBeenRestored property
• Modified Enter() to call OnEnterState() when not restoring
• SerializeState() implementation - collects state name + state data
• RestoreState() implementation - restores to saved state
• Registration with SaveLoadManager via BootCompletionService
• Unregistration on destroy

3. GardenerChaseBehavior.cs (Example Migration)

Location: Assets/Scripts/Animation/GardenerChaseBehavior.cs

Migrated from:

• Start() method with initialization

To:

• OnEnterState() - starts chase tween
• OnRestoreState(string) - positions gardener without animation, resumes tween from saved progress
• SerializeState() - saves tween progress and completion state

Usage Guide

For Simple States (No Data to Save)

public class IdleState : State
{
    public override void OnEnterState()
    {
        // Normal initialization
        PlayIdleAnimation();
        SubscribeToEvents();
    }
    
    public override void OnRestoreState(string data)
    {
        // Minimal restoration - just set visual state
        SetAnimatorToIdle();
    }
    
    // SerializeState() not overridden - returns empty string by default
}

For Complex States (With Data to Save)

public class ChaseState : State
{
    private float progress;
    
    public override void OnEnterState()
    {
        StartChaseAnimation();
        progress = 0f;
    }
    
    public override void OnRestoreState(string data)
    {
        if (string.IsNullOrEmpty(data))
        {
            OnEnterState(); // No saved data, initialize normally
            return;
        }
        
        var saved = JsonUtility.FromJson<ChaseSaveData>(data);
        progress = saved.progress;
        
        // Position objects without playing animations
        SetPosition(saved.progress);
    }
    
    public override string SerializeState()
    {
        return JsonUtility.ToJson(new ChaseSaveData { progress = progress });
    }
    
    [System.Serializable]
    private class ChaseSaveData
    {
        public float progress;
    }
}

For States That Don't Need Save/Load

States that don't override the new methods continue to work normally:

• Existing states using Start() and OnEnable() are unaffected
• Only states that need save/load functionality need to be migrated

Setup in Unity

1. Add Save ID to StateMachine:

   • Select GameObject with StateMachine component
   • In inspector, set "Save Id" field to unique identifier (e.g., "GardenerStateMachine")
   • Leave empty to disable saving for that state machine

2. Migrate States:

   • For each state that needs saving:
     • Move initialization logic from Start()/OnEnable() to OnEnterState()
     • Implement OnRestoreState() for restoration logic
     • Implement SerializeState() if state has data to save

Benefits

✅ Clean separation - Normal vs restore logic is explicit
✅ No timing issues - Explicit method calls, no flag-based checks
✅ Opt-in - States choose to participate in save/load
✅ Backward compatible - Existing states work without changes
✅ Centralized - StateMachine manages registration automatically ✅ State-level data - Each state manages its own persistence

Migration Checklist

For each state machine that needs saving:

• Set Save ID in StateMachine inspector
• Identify states that need save/load
• For each state:
  • Move Start() logic to OnEnterState()
  • Implement OnRestoreState() (handle empty data case)
  • Implement SerializeState() if state has data
  • Test normal gameplay flow
  • Test save/load flow

Completed Migrations

✅ GardenerChaseBehavior

• Saves tween progress and completion state
• Restores gardener position without animation
• Resumes tween from saved progress if not completed

Notes

• All changes to Pixelplacement code are marked with // === APPLE HILLS SAVE/LOAD INTEGRATION === comments
• If Pixelplacement framework is updated from GitHub, reapply these changes
• SaveLoadManager.IsRestoringState global flag is NOT used - each StateMachine has its own IsRestoring flag
• States can check StateMachine.IsRestoring if needed, but typically don't need to