Skip to content

README.md

Latest commit

 

History

History
107 lines (83 loc) · 3.24 KB

README.md

File metadata and controls

107 lines (83 loc) · 3.24 KB

MSAgentReader

This library implements a complete parser for the MSAgent ACS file format based on the MSAgent Character Data Specification v1.6. It can read original MSAgent character files and extract:

Implemented

  • Binary Parsing: Complete little-endian binary reader with proper bounds checking
  • ACS Header: Read file signature and data locators
  • Character Info: Parse character metadata including:
    • Versions (character and animation set)
    • GUID identification
    • Dimensions (width/height)
    • Transparent color index
    • Feature flags (voice, balloon, standard animation set)
    • Voice/TTS settings with optional extra data
    • Word balloon configuration
    • Color palette (up to 256 colors)
    • System tray icon
    • Character states and associated animations
    • Localized information (multilanguage support)
  • Animation System:
    • Animation metadata (name, transition type, return animation)
    • Frame sequences with duration and exit frames
    • Branch points with probability
    • Frame images with positioning offsets
    • Mouth overlays for different phonemes (7 types)
  • Image Handling:
    • Image metadata with checksums
    • Lazy loading of image data
    • Decompression using MSAgent's custom algorithm
    • Region data (transparency masks)
    • CGImage creation from indexed color data
    • PNG export (macOS only)
  • Audio Support:
    • Audio file references
    • RIFF/WAV data extraction
    • WAV file export (macOS only)
  • Decompression: Full implementation of MSAgent's proprietary compression:
    • Bit-level LZ-style compression
    • Run-length encoding
    • Back-reference decompression
    • Variable-length encoding

Building

swift build

# Build GUI app
swift build --product MSAgentViewerGUI

Usage

As a Library

import MSAgentReader

// Load an ACS file
let acsFile = try ACSFile(fileURL: URL(fileURLWithPath: "path/to/character.acs"))

// Access character information
print("Character: \(acsFile.characterName ?? "Unknown")")
print("Size: \(acsFile.characterInfo.width)x\(acsFile.characterInfo.height)")
print("Animations: \(acsFile.animations.count)")

// Load and access animations
try acsFile.loadAnimation(at: 0)
if let frames = acsFile.animations[0].frames {
    print("First animation has \(frames.count) frames")
}

// Export images
try acsFile.loadImage(at: 0)
if let cgImage = try acsFile.createCGImage(at: 0) {
    // Use cgImage...
}

CLI tool

# View character information
.build/debug/MSAgentViewer path/to/character.acs --info

# List animations
.build/debug/MSAgentViewer path/to/character.acs --animations

# Export images to PNG
.build/debug/MSAgentViewer path/to/character.acs --export-images

# Export audio to WAV
.build/debug/MSAgentViewer path/to/character.acs --export-audio

# Show everything
.build/debug/MSAgentViewer path/to/character.acs --all

License, Creds & References

This library is provided as-is for educational and development purposes. MSAgent is Copyright © 1996-1998 Microsoft Corporation. Blabla.