Fantasy-net

Fantasy is a high-performance C# distributed game server framework based on ECS architecture, using FTask for async operations.

Core Principles

Fantasy Technical Specifications

• Use FTask for all async operations, not Task
• Separate Entity data from logic (Handler/System); multi-assembly projects must separate to support hot reload
• Name Component business extension classes {ComponentFullName}System; add a static {Domain}Helper only when other systems need a shared business entry point
• All registration is done at compile-time by source generators; don't manually register, don't modify .g.cs
• Entities, components, and Handlers use sealed class; all classes except structs must be created via Entity
• Use file-scoped namespaces (namespace Fantasy;)
• Use Log.Debug/Info/Error() for logging; return error codes via response.ErrorCode; business logic should not throw exceptions
• Use Event system for module decoupling: publish events instead of direct calls; prefer Struct events (zero GC), use Entity events for complex logic; use EventSystem for sync, AsyncEventSystem for async
• Name Event listeners {EventName}_{BusinessAction}, such as OnHpChange_ExitGame; never suffix them with System, Async, or Handler
• When Control Center is enabled, use ServiceDiscovery for dynamic Root Scene and SubScene routing; keep strict account-to-node affinity in business storage rather than the service registry
• Before planned Scene shutdown, call ServiceDiscovery.SetSceneOfflineAsync, reject new business allocations, wait one discovery cache cycle, then drain and close the Scene
• Strictly follow SOLID principles

Development Behavioral Guidelines

Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment.

See references/guidelines-examples.md for detailed Fantasy scenario examples.

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.