Overview

Relevant source files

• README.md
• Source/boss.json
• boss.json

Purpose and Scope

This document provides a high-level introduction to READCOM.Core.Delphi, an interactive story-telling engine built with Delphi and FireMonkey. It covers the system's purpose, architectural concepts, major components, and their relationships.

For detailed information on specific subsystems:

• Project organization and Boss package management: see Project Structure
• Detailed architecture patterns: see Architecture Overview
• Story item implementation details: see Story Item System
• Navigation and flow control: see Story Navigation System
• UI components: see User Interface Components
• Development setup and workflow: see Development Guide

---

What is READCOM.Core?

READCOM.Core.Delphi is a reusable interactive story-telling engine that enables creation of hierarchical, multimedia narratives with user interaction, puzzle mechanics, and non-linear navigation. The system supports image, audio, and text content types organized in a tree structure where each node can be a navigation point, collectable item, or interactive element.

The engine is delivered as:

• READCOM.Core package: Core library with 23 units Source/READCOM.Core.dpk1-23
• dclREADCOM.Core package: Design-time IDE integration (Windows only) Source/dclREADCOM.Core.dproj
• READCOM.Core.Demo application: Reference implementation and demo Demo/READCOM.Core.Demo.dproj

Sources: README.md1-21 Source/boss.json1-19 boss.json1-19

---

Core Value Proposition

Feature	Description
Cross-Platform	Single codebase targeting 8 platforms: Windows (32/64-bit), Android (ARM32/ARM64), iOS (device/simulator), macOS (Intel/Apple Silicon)
Interface-Based Design	Polymorphic content through IStory, IStoryItem, IImageStoryItem, IAudioStoryItem, ITextStoryItem interfaces
Factory Pattern	Extensible type system via IStoryItemFactory and IStoryItemFactoryRegistry for runtime instantiation
Dual Serialization	Text-based (.readcom) and binary (.readcombin) formats with automatic detection
Hierarchical Navigation	Tree-structured stories with path-based lookup syntax (/, ~, ., .., ID, #, @)
Puzzle Mechanics	Tag matching system (AreTagsMatched) for conditional progression and locked story points
Mode Support	EditMode, InteractiveStoryMode, GuidedInteractiveStoryMode, AnimatedStoryMode via TStoryMode enumeration

Sources: boss.json1-19 Source/boss.json1-19

---

Architectural Layers

READCOM.Core follows a layered architecture with clear separation of concerns:

Architectural Layers:

1. Data Model Layer: Interface contracts (IStory, IStoryItem and specializations) define polymorphic behavior
2. Factory Layer: Registry pattern (IStoryItemFactoryRegistry) enables runtime type instantiation without hard-coded dependencies
3. Business Logic Layer: TStory/TEditableStory encapsulate navigation, tag matching, and state transitions
4. Presentation Layer: FireMonkey TFrame-based components (TStoryItem hierarchy) implement visual rendering
5. Application Layer: READCOM.App.Main handles initialization, command-line parsing (-thumb, -html), and form creation
6. Resource Layer: Centralized icons (54 SVG) and themes accessible throughout the UI

Sources: boss.json1-19 Source/boss.json1-19

---

Package Structure and Dependencies

Dependency Management:

All dependencies are managed through Boss Package Manager with three-tier configuration:

• boss.json1-19 - Root level configuration pointing to Source and Demo projects
• Source/boss.json1-19 - Core package dependencies (7 Zoomicon packages)
• Demo/boss.json - Demo application dependencies

Current version: 19.0

Sources: boss.json1-19 Source/boss.json1-19

---

Consuming Applications

READCOM.Core is consumed by three production applications:

Application	Repository	Purpose
Reading Communities App	READCOM_App	Interactive multimedia stories for literacy and reading comprehension
iLearnTsakonika	iLearnTsakonika_App	Language learning application for Tsakonian Greek dialect
Adventure in Tsakonia	AdventureInTsakonia_App	Interactive adventure game set in Tsakonia region

Each application integrates READCOM.Core through the interface layer (IStory, IStoryItem) and can provide custom story item types via factory registration.

Sources: README.md12-16

---

Platform Support Matrix

Platform	Architecture	Target	Package Output	Status
Windows	Win32	Desktop	.bpl, .exe	Full support + design-time
Windows	Win64	Desktop	.bpl, .exe	Full support + design-time
Android	ARM v7a (32-bit)	Mobile	.apk + system JARs	Production ready
Android	ARM64 v8a (64-bit)	Mobile	.apk + system JARs	Production ready
iOS	ARM64	Device	.ipa	Production ready (requires code signing)
iOS	ARM64	Simulator	.app	Development only
macOS	Intel x64	Desktop	.app bundle	Production ready
macOS	Apple Silicon (ARM64)	Desktop	.app bundle	Production ready

Platform-Specific Notes:

• Design-time package (dclREADCOM.Core) is Windows-only
• Mobile platforms include touch-optimized UI and camera integration via TTakePhotoFromCameraAction
• Graphics renderer selection via CheckSafeMode(): Skia, Metal (iOS/macOS), Vulkan (Android)
• Conditional compilation via {$IFDEF ANDROID}, {$IFDEF IOS}, {$IFDEF NOSTYLE} directives

For details on multi-platform development, see Multi-Platform Build System and Multi-Platform Development.

Sources: boss.json1-19 Source/boss.json1-19

---

Core Interfaces and Classes

Data Model Interfaces

Interface	Purpose	Key Members
IStoreable	Base persistence	Load(), Save()
IStoryItem	Story element contract	30+ properties: ID, Parent, StoryPoint, Home, Collectable, Tags, UrlAction, FactoryCapacity, Content: TBytes
IImageStoryItem	Image content	Image: TBitmap, SVGText: String, Looping: Boolean
IAudioStoryItem	Audio playback	Audio: IMediaPlayer, Play, AutoPlaying, Looping
ITextStoryItem	Text display	Text: String, Font: TFont, Editable, HorzAlign
IStory	Story container	ActiveStoryItem, HomeStoryItem, RootStoryItem, StoryMode

Implementation Classes

Class	Base	Interface	File Location
TStoryItem	TFrame	IStoryItem	Source/READCOM.View.StoryItems.pas
TImageStoryItem	TStoryItem	IImageStoryItem	Source/READCOM.View.StoryItems.Image.pas
TAudioStoryItem	TStoryItem	IAudioStoryItem	Source/READCOM.View.StoryItems.Audio.pas
TTextStoryItem	TStoryItem	ITextStoryItem	Source/READCOM.View.StoryItems.Text.pas
TStory	TComponent	IStory	Source/READCOM.Model.Story.pas
TEditableStory	TStory	IStory	Source/READCOM.Model.Story.Editable.pas

For detailed interface documentation, see Core Data Models.

Sources: boss.json1-19

---

Key Subsystems

Navigation and Flow Control

• Story Points: Navigable nodes marked with StoryPoint property
• Path-based Lookup: GetStoryItem() supports / (root), ~ (home), . (current), .. (parent), ID-based, # (index), @ (name) syntax
• Tag Matching: AreTagsMatched() implements puzzle mechanics where moveable items must match anchored item tags
• URL Actions: UrlAction property with TagsMatching modes (!, ?, ??, ???) for conditional navigation

See Story Navigation System for details.

Visual Hierarchy

• TStoryForm: Main window with ZoomFrame (scalable display) and StructureView (hierarchy browser)
• TStoryItem: Base TFrame component with Border, Background, and Glyph (TMediaDisplay)
• TStoryHUD: Control panel with ActionList (20+ actions) for file operations, navigation, editing, and view controls

See User Interface Components for details.

Factory and Cloning System

• IStoryItemFactory: Interface for creating story item instances
• IStoryItemFactoryRegistry: String-to-factory mapping for runtime instantiation
• GetClone(): Method on IStoryItem for creating copies based on FactoryCapacity property

See Factory Pattern and Cloning for details.

Resource Management

• Icons DataModule: TSVGIconImageList with 54 SVG graphics
• Themes DataModule: Light/Dark mode support
• Localization: Centralized string resources via READCOM.App.Messages

See Resource Management for details.

Sources: boss.json1-19

---

Serialization Formats

READCOM.Core supports dual serialization formats with automatic detection:

Format	Extension	Description	Detection Method
Text-based	.readcom	Human-readable Delphi object notation starting with object keyword	Stream inspection: first 6 bytes = "object"
Binary	.readcombin	Compact binary format	Default if not text format

Both formats support:

• Hierarchical story structure
• Deferred content loading via Content: TBytes property
• Custom property serialization via DefineProperties()
• Recursive loading of nested story items

Content loading pipeline: LoadFromStream() → format detection → LoadReadCom() (text) or LoadReadComBin() (binary) → Loaded event → specialized content handlers.

See Content Serialization and Persistence for details.

Sources: boss.json1-19

---

Version and License

• Current Version: 19.0 boss.json4 Source/boss.json4
• License: MIT License README.md5
• Repository: https://github.com/Zoomicon/READCOM.Core.Delphi README.md1-2

Sources: README.md1-21 boss.json1-19 Source/boss.json1-19

---

Next Steps

• Setup: See Getting Started for installation and running the demo
• Project Organization: See Project Structure for build system details
• Architecture Deep Dive: See Architecture Overview for design patterns
• Development: See Development Guide for extending the system