sp_character_plugin #

A Flutter plugin for character management on iOS 17+ with SPAvatarKit integration.

Features #

• Character Management: Create, load, and manage 3D characters
• Real-time Animation: Support for real-time character animation
• iOS 17+ Support: Optimized for iOS 17 and above
• Dynamic Framework Loading: Automatically downloads SPAvatarKit framework during installation

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  sp_character_plugin: ^1.0.0-beta.6

Then run:

flutter pub get

iOS Setup #

Minimum Requirements #

• iOS 17.0+
• Xcode 15.0+
• Flutter 3.0+

Podfile Configuration #

Add the following to your ios/Podfile:

platform :ios, '17.0'

Privacy Permissions #

Add the following permissions to your ios/Runner/Info.plist:

<key>NSCameraUsageDescription</key>
<string>This app needs camera access for character capture</string>
<key>NSMicrophoneUsageDescription</key>
<string>This app needs microphone access for audio processing</string>

Usage #

Basic Character Widget #

import 'package:sp_character_plugin/character_widget.dart';

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: CharacterWidget(
          onCharacterLoaded: (character) {
            print('Character loaded: ${character.id}');
          },
          onError: (error) {
            print('Error: $error');
          },
        ),
      ),
    );
  }
}

Character Management #

import 'package:sp_character_plugin/sp_character_plugin.dart';

// Initialize the plugin
final plugin = SpCharacterPlugin();

// Load a character
try {
  final character = await plugin.loadCharacter('character_id');
  print('Character loaded: ${character.name}');
} catch (e) {
  print('Failed to load character: $e');
}

// Create a new character
try {
  final newCharacter = await plugin.createCharacter(
    name: 'My Character',
    modelPath: 'path/to/model',
  );
  print('Character created: ${newCharacter.id}');
} catch (e) {
  print('Failed to create character: $e');
}

Architecture #

The plugin uses a hybrid approach:

• Dart Layer: Provides the Flutter interface and character management logic
• iOS Native Layer: Handles SPAvatarKit integration and platform-specific functionality
• Dynamic Framework Loading: SPAvatarKit is downloaded automatically during pod install

Framework Integration #

SPAvatarKit is integrated as a dynamic dependency that gets downloaded during the CocoaPods installation process. This keeps the plugin package size minimal while providing full functionality.

Troubleshooting #

Common Issues #

1. Build Errors: Ensure you're using iOS 17.0+ and Xcode 15.0+
2. Framework Not Found: Run cd ios && pod install to download SPAvatarKit
3. Permission Errors: Add required permissions to Info.plist

Debug Mode #

Enable debug logging by setting:

SpCharacterPlugin.setDebugMode(true);

Contributing #

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License #

This project is licensed under the MIT License - see the LICENSE file for details.

Support #

For support and questions:

• GitHub Issues: Create an issue
• Email: [email protected]

Changelog #

See CHANGELOG.md for version history and updates.