characterbook_file_formats

A pure Dart library for reading and writing file formats used by the CharacterBook application:

• .character – character sheets
• .race – race descriptions
• .chax – character templates
• plus standard JSON exports

No Flutter, Hive, or UI dependencies. Use it in any Dart project: CLI tools, servers, or other Flutter packages.

---

🚀 Installation

Add to your pubspec.yaml:

dependencies:
  characterbook_file_formats: ^1.0.0

Then run:

dart pub get

---

📖 Usage

Reading a file

import 'dart:io';
import 'package:characterbook_file_formats/characterbook_file_formats.dart';

void main() async {
  final file = File('aragorn.character');
  final character = await CharacterBookFileParser.readFile(file) as Character;
  
  print('Name: ${character.name}');
  print('Race: ${character.race?.name}');
}

Writing an object to a file

import 'dart:io';
import 'package:characterbook_file_formats/characterbook_file_formats.dart';

void main() async {
  final elfRace = Race(
    id: 'elves_high',
    name: 'High Elves',
    description: 'An ancient and wise race.',
    lastEdited: DateTime.now(),
  );

  final file = File('high_elves.race');
  await CharacterBookFileParser.writeFile(file, elfRace);
}

Manual JSON handling

import 'dart:convert';
import 'package:characterbook_file_formats/characterbook_file_formats.dart';

void main() {
  const jsonString = '{"id":"123","name":"Gandalf",...}';
  final jsonMap = jsonDecode(jsonString) as Map<String, dynamic>;
  
  final character = Character.fromJson(jsonMap);
  
  // Back to JSON
  final backToJson = jsonEncode(character.toJson());
}

---

🧩 Supported Models

Model	File Extension	Purpose
Character	.character	Complete RPG character sheet
Race	.race	Race description, biology, and lore
QuestionnaireTemplate	.chax	Template for quick character creation
Relationship	–	Connections between characters (JSON export)
Note	–	Notes linked to characters
Folder	–	Folder structure (type, color, contents)
CustomField	–	Additional key–value fields for sheets

All models support:

• toJson() / fromJson()
• copyWith()
• overridden == and hashCode
• immutability (@immutable)

---

🔍 Automatic File Type Detection

The CharacterBookFileParser utility detects the data type from JSON content:

final json = jsonDecode(await file.readAsString());
final type = CharacterBookFileParser.detectType(json);
// CharacterBookFileType.character, .race, .template, .unknown

---

🧪 Testing

The library includes a comprehensive unit test suite. Run it locally with:

dart pub get
dart test

---

🤝 Contributing

Pull requests and bug reports are welcome!
Main application repository: CharacterBook.

---

📄 License

MIT License. See the LICENSE file.

---

🔗 Related Projects

• CharacterBook – original Flutter application.
• Pub.dev – package page.