README.md

MSAgent Viewer - SwiftUI GUI App

macOS application for viewing and exploring Microsoft Agent character files (.acs).

Requirements to build and run:

• macOS 13.0 (Ventura) or later
• Xcode 14+ or Swift 5.9+ command line tools
• MSAgentReader library (included in this package)

# Run with Easy script
./run-gui.sh

# or
swift run MSAgentViewerGUI

# or
.build/debug/MSAgentViewerGUI

Core Functionality

• File Loading

  • Drag & drop support
  • File browser (Open dialog)
  • Keyboard shortcut (⌘O)

• Character Info Display

  • Name and description
  • Version and GUID
  • Size (width × height)
  • Stats cards (animations, images, audio)
  • Color palette info
  • States list with animations
  • Multi-language support (shows all localized versions)

• Animation Browser

  • Sidebar navigation
  • All animations listed
  • Frame count display
  • Click to view

• Frame Viewer

  • Image rendering from ACS data
  • Background loading (non-blocking)
  • Loading indicators
  • Image compositing (first image of multi-image frames)

• Playback Controls

  • Previous frame button
  • Play/Pause button
  • Next frame button
  • Frame slider (for frames > 1)
  • Automatic playback loop

• Frame Details

  • Duration display
  • Image count
  • Overlay count
  • Branch count

Roadmap

tbh: I doubt these will happen

• Multi-image compositing - Composite multiple images per frame
• Mouth overlay rendering - Show lip-sync overlays
• Export current frame - Save as PNG
• Export animation - Save as GIF
• Audio playback - Play frame sounds
• Better timing - Use actual frame duration values
• App Bundle CI & releases

  For a proper macOS .app bundle that you can double-click:
  
  1. Open Xcode
  2. File → New → Project → macOS → App
  3. Name: "MSAgent Viewer"
  4. Add MSAgentReader as local package dependency
  5. Replace ContentView.swift with MSAgentViewerGUI.swift
  6. Build (⌘B) and Run (⌘R)
  
  The .app will be in `DerivedData` and can be copied to Applications.