Add Asset Export to JSON feature for LLM combat balance analysis
Features: - Export DataTable, Blueprint, AnimMontage, CurveTable to JSON - INI-based configuration via UDeveloperSettings - Comprehensive Blueprint EventGraph extraction - Enhanced AnimMontage with CustomProperties from Notifies - Project Settings integration (Edit -> Project Settings -> Plugins) - Tools menu integration (Tools -> WorldStalker -> Export Assets to JSON) Files added: - AssetExportSettings.h/cpp - UDeveloperSettings configuration class - AssetExporterToJSON.h/cpp - Core export implementation - README.md - Comprehensive feature documentation - MERGE_INSTRUCTIONS.md - Integration guide for existing files Unreal Engine 5.5.4 compatible
This commit is contained in:
348
README.md
Normal file
348
README.md
Normal file
@ -0,0 +1,348 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user