Fantasy Framework

Fantasy provides two tools to automatically generate C# code from .proto protocol definition files:

1. Fantasy.ProtocolExportTool (CLI): A command-line tool designed for CI/CD integration and automated scripts. It supports both interactive and silent modes.
2. Fantasy.ProtocolEditor (Visual Editor): A cross-platform desktop application built with Avalonia. It includes a .proto editor with syntax highlighting, code completion, and visual configuration editing for RoamingType.Config and RouteType.Config.

Core Capabilities:

• Parses .proto files to generate message classes, OpCode enums, and Helper extension methods.
• Supports multiple serialization formats: ProtoBuf, MemoryPack, and Bson.
• Performs format validation (detecting duplicate fields, incorrect interface types, etc.).
• Ensures protocol ID stability via OpCode.Cache (incremental updates).
• Supports sub-package protocol exports with independent directories.
• Enables shared OpCode caching across main protocols and sub-packages to prevent ID conflicts.

The TimerComponent is a core scheduling component within a Scene. It is used for delayed execution, periodic tasks, asynchronous waiting, and countdowns.

Recommendation: Use FTask methods to simplify your implementation. Only access scene.TimerComponent.Net directly when you require low-level interfaces or specific overloads.

Key Rules for Usage:

• Server-side usage: On the server, prioritize using FTask.Wait, FTask.OnceTimer, or FTask.RepeatedTimer.
• Lifecycle Management: Timers belong to a Scene. When a Scene is destroyed, all associated timers are automatically cleaned up.
• Manual Cancellation: For repeated timers, you must manually cancel them. Ensure you save the returned timerId to perform the cancellation later.
• Hot Reloading: For business logic that requires hot-reload friendliness, prefer using a pattern where a "Timer triggers an Event" rather than using an Action callback.
• Precision: Timer precision is dependent on the Update() frequency and is not absolute real-time.

The EventAwaiterComponent is a high-performance, type-safe asynchronous waiting component. It allows coroutines to await specific types of events and provides a mechanism for other parts of the code to Notify those events.

Unlike the standard Event system (which is a one-to-many Publish-Subscribe model where listeners execute immediately), EventAwaiter is a one-to-many Wait-Notify model where the waiter actively waits for a result.

Key differences:

• EventAwaiter: Uses await Wait<T>() + Notify<T>(). Supports returning data via EventAwaiterResult<T>. Best for scenarios where you need to wait for a specific condition or response (e.g., waiting for a player to click a dialog button).
• Event: Uses Publish() + Listeners. No return value. Best for decoupled, event-driven architectures (e.g., notifying the system that a player leveled up).

// EventAwaiter: Waiting for a player to confirm a dialog (attached to the player entity)
var player = scene.GetEntity<Player>(playerId);
var result = await player.EventAwaiterComponent.Wait<PlayerConfirmEvent>();
if (result.ResultType == EventAwaiterResultType.Success)
{
    ProcessConfirm(result.Value);
}

// Event: Publishing a level up event to all listeners (at Scene level)
scene.EventComponent.Publish(new PlayerLevelUpEvent { PlayerId = id });

SeparateTable is an advanced database persistence solution in the Fantasy Framework that allows you to store sub-components of a complex aggregate entity in independent database tables (collections) instead of nesting them within the parent entity's table.

Why use SeparateTable:

• Reduce Main Table Size: Prevents the main entity table from becoming bloated with large nested data (e.g., inventories, friend lists, or mail data), which speeds up basic queries.
• Improve Query Performance: Allows you to query basic entity information (like Name or Level) without the overhead of loading massive sub-components.
• Independent Index Management: You can create specific indexes for sub-tables (e.g., indexing an ItemId within a PlayerInventoryEntity table) without affecting the main table.
• Flexible Data Management: Enables independent backups, data cleanup, or different storage strategies for specific sub-components.

Overview

FantasyRuntime is an all-in-one network connection and framework initialization component for the Fantasy Unity client. It simplifies client-side code by automating Entry.Initialize() and Scene.Create() calls and providing visual configuration.

Usage Modes

Core Features

• Automatic Initialization: Handles framework and scene setup.
• Visual Configuration: Network parameters can be set in the Inspector.
• Multi-Protocol Support: Supports TCP, KCP, and WebSocket.
• Heartbeat Management: Automatic heartbeat enabling and real-time latency monitoring.
• Event Callbacks: UnityEvent support for connection success, failure, and disconnection.
• Multi-Instance Support: Ability to create multiple instances for different servers.
• Global Access: Fast access to Scene and Session via the Runtime class.