DS-Asset_Export_to_JSON/README.md

# Asset Export to JSON - Unreal Engine Editor Extension

## Overview

This editor extension provides a comprehensive asset export system that converts Unreal Engine assets to JSON format for LLM-based combat balance analysis. The feature extracts detailed data from various asset types to create text-based documentation that can be analyzed by AI systems.

**Purpose**: Enable comprehensive combat balance analysis by providing structured, text-based representations of game assets suitable for Large Language Model (LLM) processing.

**Supported Asset Types**:
- **DataTable** - Complete row and column data
- **Blueprint** - Variables, functions, components, event graphs with node connections
- **AnimMontage** - Sections, notifies, custom properties, slot animations
- **CurveTable** - Key-value curve data (RichCurves and SimpleCurves)

## Features

### Configuration-Based Export
- **Project Settings Integration**: Configure export paths in `Edit → Project Settings → Plugins → Asset Export to JSON`
- **Persistent Configuration**: Settings saved to `Config/DefaultEditor.ini` for team sharing via SVN/Git
- **Multi-Folder Support**: Export from multiple folder paths with single click
- **Asset Type Filtering**: Enable/disable specific asset types via settings

### Comprehensive Data Extraction

#### Blueprint Export
- Variables with types and default values
- Functions with inputs/outputs
- Component hierarchy
- **Event Graphs**: Complete node graph with:
  - Node types, titles, positions, comments
  - Pin types, directions, default values
  - Connection graph between pins
  - Node-specific properties

#### AnimMontage Export
- Sections with start/end times
- Slot animation tracks with segments
- **Notify Events**: Complete notify data including:
  - Notify type and trigger times
  - Custom properties from notify classes
  - Blend in/out settings
  - Track indices and sync markers

#### CurveTable Export
- Support for both RichCurves and SimpleCurves
- Key data with time, value, tangent information
- Curve interpolation modes

### Output Management
- **Timestamped Exports**: Optional timestamped subfolders for export history
- **Type-Separated Files**: Separate JSON files per asset type (DataTable.json, Blueprint.json, etc.)
- **Pretty-Printed JSON**: Human-readable formatting with indentation
- **Duplicate Detection**: Prevents duplicate exports when folders overlap

## Installation

### 1. File Structure

Copy the following files to your project:

**New Files** (copy to `Source/WorldStalkerEditor/Utility/`):
```
AssetExportSettings.h
AssetExportSettings.cpp
AssetExporterToJSON.h
AssetExporterToJSON.cpp
```

**Modified Files** (merge changes manually):
- `WorldStalkerEditor.h` - See MERGE_INSTRUCTIONS.md
- `WorldStalkerEditor.cpp` - See MERGE_INSTRUCTIONS.md

### 2. Build Configuration

Add to your `WorldStalkerEditor.Build.cs`:

```csharp
PublicDependencyModuleNames.AddRange(new string[] {
    "AssetRegistry",
    "Json",
    "JsonUtilities"
});

PrivateDependencyModuleNames.AddRange(new string[] {
    "UnrealEd",
    "Engine",
    "Slate",
    "SlateCore",
    "ToolMenus",
    "DeveloperSettings"
});
```

### 3. Rebuild Project

```batch
# Generate Visual Studio project files
GenerateVSProjectFile.bat

# Build the editor module
# Or rebuild from Visual Studio
```

## Configuration

### Step 1: Open Project Settings

Navigate to: `Edit → Project Settings → Plugins → Asset Export to JSON`

### Step 2: Configure Export Paths

**Export Folder Paths** (Array):
- Add folder paths relative to `/Game/` content directory
- Example paths:
  - `Blueprints/Enemy`
  - `Blueprints/Characters`
  - `Blueprints/Abilities`
  - `DataTables`
- Use the `+` button to add new paths
- Use the `-` button to remove paths

**Default Paths** (automatically configured):
```
Blueprints/Enemy
Blueprints/Characters
Blueprints/Abilities
DataTables
```

### Step 3: Configure Output Settings

**Output Directory**:
- Default: `Exports` (relative to Content folder)
- Set custom path if desired

**Create Timestamped Folder**:
- Enabled: Creates subfolder like `Export_2025_01_15_143022`
- Disabled: Overwrites files in output directory

### Step 4: Select Asset Types

Enable or disable export for specific asset types:
- ☑ Export DataTables
- ☑ Export Blueprints
- ☑ Export AnimMontages
- ☑ Export CurveTables

## Usage

### Quick Export

1. Open Unreal Editor
2. Navigate to: `Tools → WorldStalker → Export Assets to JSON`
3. Wait for export to complete (notification dialog will appear)

### Export Output

Files are saved to: `Content/Exports/` (or configured output directory)

**Output Structure** (with timestamped folder):
```
Content/
└── Exports/
    └── Export_2025_01_15_143022/
        ├── DataTable.json
        ├── Blueprint.json
        ├── AnimMontage.json
        └── CurveTable.json
```

### Output Format Examples

#### DataTable.json
```json
[
  {
    "AssetName": "DT_CharacterStats",
    "AssetPath": "/Game/DataTables/DT_CharacterStats",
    "RowCount": 10,
    "Columns": ["Name", "Health", "Attack", "Defense"],
    "Rows": {
      "Warrior": {
        "Name": "Warrior",
        "Health": "1000",
        "Attack": "150",
        "Defense": "100"
      }
    }
  }
]
```

#### Blueprint.json
```json
[
  {
    "AssetName": "BP_Enemy_Goblin",
    "AssetPath": "/Game/Blueprints/Enemy/BP_Enemy_Goblin",
    "ParentClass": "WSCharacterBase",
    "Variables": [
      {
        "Name": "MaxHealth",
        "Type": "float",
        "DefaultValue": "500.0"
      }
    ],
    "EventGraphs": [
      {
        "GraphName": "EventGraph",
        "Nodes": [
          {
            "NodeTitle": "Event BeginPlay",
            "NodeClass": "K2Node_Event",
            "Pins": [...]
          }
        ],
        "Connections": [
          {
            "SourceNode": "Event BeginPlay",
            "SourcePin": "then",
            "TargetNode": "Set Max Health",
            "TargetPin": "execute"
          }
        ]
      }
    ]
  }
]
```

#### AnimMontage.json
```json
[
  {
    "AssetName": "AM_Attack_Combo",
    "AssetPath": "/Game/Animations/AM_Attack_Combo",
    "SequenceLength": 2.5,
    "Sections": [
      {
        "SectionName": "Combo1",
        "StartTime": 0.0,
        "EndTime": 0.8
      }
    ],
    "Notifies": [
      {
        "NotifyName": "DamageNotify",
        "TriggerTime": 0.5,
        "NotifyType": "AnimNotify",
        "CustomProperties": {
          "DamageMultiplier": "1.5",
          "HitboxSize": "100.0"
        }
      }
    ],
    "SlotAnimTracks": [...]
  }
]
```

## Troubleshooting

### No Output Files Generated

**Problem**: Export completes but no JSON files are created
**Solution**: Check that export paths contain assets of the enabled types

### Duplicate Assets in Output

**Problem**: Same asset appears multiple times in JSON
**Solution**: This is now prevented by duplicate detection - check for overlapping folder paths in settings

### Build Errors After Integration

**Problem**: Compilation errors about missing headers
**Solution**: Ensure all dependencies are added to `.Build.cs` file (see Installation section)

### Export Hangs on Large Projects

**Problem**: Export takes very long time
**Solution**: Reduce number of export paths or disable asset types not needed

### Settings Not Persisting

**Problem**: Configuration resets after editor restart
**Solution**: Check that `Config/DefaultEditor.ini` is writable and not locked

## Technical Details

### Unreal Engine Version
- **Tested on**: Unreal Engine 5.5.4 (Custom Build)
- **API Compatibility**: Uses UE 5.5+ CurveTable API (GetRichCurveRowMap/GetSimpleCurveRowMap)

### Module Dependencies
- **AssetRegistry** - Asset discovery and filtering
- **Json/JsonUtilities** - JSON serialization
- **UnrealEd** - Editor integration
- **ToolMenus** - Menu extension system
- **DeveloperSettings** - Project settings integration

### Performance Characteristics
- **Recursive Search**: Searches all subfolders of configured paths
- **Memory Usage**: Loads assets one at a time to minimize memory footprint
- **Export Speed**: ~10-50 assets per second depending on asset complexity

### Blueprint Event Graph Extraction
The system traverses the Blueprint graph structure to extract:
- All nodes from `UbergraphPages` (event graphs)
- Node metadata (class, title, position, comments)
- Pin information (type, direction, default values)
- Connection graph between pins (LinkedTo relationships)
- Property values from graph nodes

### AnimMontage Custom Property Extraction
Custom properties are extracted from Notify objects by:
1. Iterating through all `AnimNotifyEvent` entries
2. Reflecting on Notify object class properties
3. Filtering for editable properties (`CPF_Edit` flag)
4. Serializing property values to JSON

## Known Limitations

1. **Blueprint Visual Script Logic**: Exports node graph structure but not visual script bytecode execution flow
2. **Binary Assets**: Cannot export binary data (meshes, textures, audio)
3. **Complex Property Types**: Some complex UObject properties may export as object references only
4. **Large Blueprints**: Very large blueprints with thousands of nodes may take significant time to export

## Development History

**Initial Release**: INI-based configuration system with comprehensive asset extraction

**Key Design Decisions**:
- INI-based configuration chosen over checkbox UI for repeated use convenience
- UDeveloperSettings integration for team collaboration via version control
- Duplicate detection prevents redundant exports from overlapping folder paths
- Pretty-printed JSON for human readability and LLM processing

## Support

For issues, questions, or feature requests:
1. Check this README and MERGE_INSTRUCTIONS.md
2. Review Output Log in Unreal Editor for error messages
3. Contact: jinilkim@actionsquare.com

## License

Copyright Epic Games, Inc. All Rights Reserved.
Part of the WorldStalker (DungeonStalkers) project.