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
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
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.

File

When to Use

references/ecs/index.md

ECS entry: routes to Scene / SubScene / Entity definition / component operations / object pool / lifecycle; shared by server and Unity; read this first when Entity definition, component management, or ECS mechanism selection is involved

references/review.md

Fantasy code review entry: routes checks by ECS / Event / Timer / Protocol / Roaming / SphereEvent / HTTP / Database / Config; read this first when user wants review, code check, or Fantasy compliance verification

references/guidelines-examples.md

Development behavioral guidelines Fantasy scenario examples: Think Before Coding (clarify assumptions), Simplicity First (avoid over-engineering), Surgical Changes (precise modifications), Goal-Driven Execution (verifiable goals) with detailed comparison cases; read when understanding guideline application in Fantasy, or when code review reveals guideline violations

references/ecs/scene.md

Scene is the container and lifecycle boundary for all Entity/Component: cascade destruction when Scene disposes, OnCreateScene event, access system components via self.Scene (TimerComponent/EventComponent/NetworkMessagingComponent etc.); read when Scene concept, Scene initialization, OnCreateScene event, or Entity ownership is involved

references/ecs/ecs-check.md

ECS review checklist: Entity / Component / System / Scene / object pool / lifecycle common issues; read when user wants to check ECS code for Fantasy compliance

references/timer/index.md

Timer entry: routes to async wait / callback timers / event integration / best practices; read first when user needs delayed execution, repeated tasks, countdown, Wait, OnceTimer, RepeatedTimer

references/timer/implement.md

Timer implementation: FTask.Wait, WaitTill, WaitFrame, OnceTimer, RepeatedTimer, cancel timers; read only when directly writing Timer code

references/timer/event.md

Timer and Event integration: event-based timers, hot reload differences, when to use events instead of Action; read only when hot-reload-friendly Timer logic is needed

references/timer/best-practices.md

Timer best practices and troubleshooting: performance tips, common errors, Scene destruction, precision, cancel strategies; read only when optimizing or troubleshooting Timer code

references/ecs/subscene.md

SubScene dynamic child scenes: lightweight isolated spaces created at runtime from parent Scene, sharing parent Scene core components but with independent entity lists; Scene.CreateSubScene() API details (params, callback execution order), sending Address messages to SubScene, using Addressable on SubScene, destroying SubScene; read when needing instances, match rooms, instanced maps, dynamic battlefields, player private spaces, or on-demand scene creation/destruction

references/ecs/lifecycle.md

ECS lifecycle Systems: AwakeSystem, UpdateSystem, DestroySystem, DeserializeSystem, TransferOutSystem/TransferInSystem (cross-server transfer only) and trigger order; read when responding to Entity lifecycle events

references/event/index.md

Event entry: determine whether to use EventAwaiter or Event, then follow Workflow to corresponding doc; read first when requirement involves "wait for result" or "publish event" mechanism selection

references/event/event-awaiter.md

EventAwaiter entry: routes to implementation / modeling / troubleshooting; read first when user needs to wait for a condition, wait for player action, do request-response async flow, or explicitly mentions EventAwaiter/EventAwaiterComponent

references/event/struct-event.md

Struct event full workflow: Step 1 define event → Step 2 create listener → Step 3 publish event; recommended for most scenarios, read when creating Struct events

references/event/entity-event.md

Entity event full workflow: Step 1 create listener → Step 2 publish existing Entity (note isDisposed param); read only when passing existing Entity

references/event/check-event.md

Event system code review: Struct event checklist, Entity event checklist, listener checklist, common error comparisons; read when checking existing event code

references/server/setup-server.md

Create new Fantasy server project, integrate Fantasy into existing project (.NET/NuGet), three-layer structure setup, logging system quick config

references/unity/index.md

Unity client entry: routes to installation, connection, Session, receiving pushes; read first when Fantasy Unity client is involved

references/unity/unity-check.md

Unity review checklist: version consistency, compile macros, connection methods, Session usage, push Handler common issues; read when user wants to check Unity client code

references/unity/setup-unity.md

Unity client install Fantasy.Unity, configure compile symbols, import protocols; read only during installation or initial integration

references/unity/unity-connection.md

Unity client connect to server: FantasyRuntime component, scene.Connect, Runtime.Connect, protocol selection; read only during connection initialization

references/unity/unity-session.md

Unity client Session usage: send messages, RPC, connection holding, disconnect; read only for how to send messages after connection

references/logging.md

Logging system details: Fantasy.NLog full config, Fantasy config or add logging, NLog.config explanation, custom ILog implementation (Serilog/file logging etc.)

references/logging-check.md

Logging review checklist: logging initialization, NLog rules, config copy, mode switching, custom ILog common issues; read when user wants to check logging integration

references/protocol/index.md

Protocol entry: define .proto, export C#, install export tool routing; read first when .proto, Outer/Inner, protocol export is involved

references/protocol/protocol-check.md

Protocol review checklist: Outer/Inner selection, interface matching, naming, export, Handler alignment; read when user wants to check protocol or Handler definitions

references/protocol/define.md

Protocol definition entry: locate protocol root directory and route to Outer/Inner; read when creating new protocol files or determining where to place protocols

references/protocol/define-outer.md

Outer protocol: client↔server messages, IMessage / IRequest / IResponse; read only when defining Outer protocols

references/protocol/define-inner.md

Inner protocol: server↔server messages, IAddressMessage / IAddressRequest / IAddressResponse; read only when defining Inner protocols

references/protocol/define-common.md

Protocol common features: fields, collections, Map, enums, serialization, code injection; read only when field or serialization details are needed

references/protocol/export.md

Protocol export: check tool, run export, verify results; read after protocol definition is complete or when user requests re-export

references/protocol/export-install.md

Export tool installation and ExporterSettings.json configuration; read when tool is not installed or paths are not configured

references/server/server-message-handler.md

Server-side Handler for client messages, only for messages implementing IMessage/IRequest/IResponse interfaces; Message<T>/MessageRPC<TReq,TRes> templates, reply() usage, error code patterns, Session push; see respective files for Addressable/Roaming

references/server/server-message-handler-check.md

Server message Handler review checklist: base class selection, error codes, reply(), Session lifecycle, duplicate Handler common issues; read when user wants to check client message Handlers

references/unity/unity-message-handler.md

Unity client Handler for server push messages: Message<Session,T>, file location conventions, compile verification; read when user needs to create a Handler in Unity to receive server messages

references/server/address.md

Server-to-server messaging based on Entity.Address (RuntimeId): only for messages implementing IAddressMessage/IAddressRequest/IAddressResponse interfaces; read when defining Address message Handlers

references/server/address-check.md

Address review checklist: message patterns, entry address retrieval, Handler types, first communication and cached address common errors; read when user wants to check Address code

references/server/sphere-event/index.md

SphereEvent entry: cross-server domain events, subscribe, publish, unsubscribe, choosing between Event/Roaming; read first when cross-server event notifications, SphereEventComponent, SphereEventArgs, SphereEventSystem are involved

references/server/sphere-event/implement.md

SphereEvent implementation: define event class, implement handler, subscribe to remote events, publish events, unsubscribe; read only when directly writing SphereEvent code

references/server/sphere-event/best-practices.md

SphereEvent best practices and troubleshooting: object pool, hot reload, event size, disconnect cleanup, differences from Event/Roaming; read only when optimizing or troubleshooting SphereEvent logic

references/server/roaming/index.md

Roaming concept entry: core concepts (SessionRoamingComponent/Terminus/RoamingType) and Workflow decision tree; read this first, then sub-files as needed

references/server/roaming/roaming-check.md

Roaming review checklist: protocol, link establishment, Terminus lifecycle, message flow, transfer common issues; read when user wants to check Roaming code

references/server/roaming/protocol.md

Define roaming protocols: RoamingType.Config configuration, IRoamingMessage/IRoamingRequest/IRoamingResponse format; read only when defining protocols and adding roaming types or servers

references/server/roaming/setup.md

Establish roaming routes: Gate-side TryCreateRoaming/Link, parameter passing; read only when establishing routes

references/server/roaming/on-create-terminus.md

OnCreateTerminus event: event parameters, LinkTerminusEntity API, Args memory management rules, independent Handler implementation per server; read only when handling Terminus creation/reconnection

references/server/roaming/on-dispose-terminus.md

OnDisposeTerminus event: trigger timing, DisposeTerminusType distinction, independent Handler implementation per server; read only when handling Terminus disposal

references/server/roaming/handler.md

Roaming Handler entry: routes to message handling / push / cross-server send / transfer; read first when user wants to write Roaming Handlers or do transfers

references/server/roaming/messaging.md

Roaming message handling: client send, Gate proactive send to backend, Roaming Handler, backend push to client, cross-server send; read only when implementing message flow

references/server/roaming/transfer.md

Terminus transfer: StartTransfer, TransferOutSystem, TransferInSystem, lifecycle and considerations; read only when implementing cross-server transfer

references/server/roaming/error-codes.md

Roaming error codes: meanings and troubleshooting methods; read only when encountering Roaming-related errors

references/http.md

HTTP entry: routes to server configuration events and Controller writing; read first when HTTP server, Controller, OnConfigureHttpServices, OnConfigureHttpApplication are involved

references/http-check.md

HTTP review checklist: service configuration phase, middleware order, SceneContextFilter, return patterns, route mapping common issues; read when user wants to check HTTP code

references/http-server.md

HTTP server configuration: OnConfigureHttpServices, OnConfigureHttpApplication, authentication, authorization, CORS, middleware; read only when configuring HTTP services and middleware

references/http-controller.md

HTTP Controller writing: SceneContextFilter, Scene injection, Action return values, thread switching, Controller examples; read only when writing or troubleshooting Controllers

references/database/index.md

Database entry: MongoDB configuration, getting database instance, persistence, queries, indexes, concurrent modification routing; read first when MongoDB, IDatabase, scene.World.Database, data persistence is involved

references/database/database-check.md

Database review checklist: scene.World access, ISupportedSerialize, isDeserialize, coroutine locks, SeparateTable applicability; read when user wants to check database code

references/database/mongodb.md

MongoDB usage: ISupportedSerialize, Save, Insert, Query, Remove, indexes, isDeserialize, concurrent modification; read only when directly writing database code

references/database/separate-table.md

SeparateTable separate storage: aggregate entity split storage, [SeparateTable], PersistAggregate, LoadWithSeparateTables; read only when aggregate entity child data is too large and needs table separation optimization

references/database/best-practices.md

MongoDB best practices and troubleshooting: config association, query optimization, save strategies, common issues; read only when optimizing or troubleshooting database logic

references/config.md

Fantasy.config entry: routes by "add machine / process / World / Scene / database / port"; read first when Fantasy.config is involved

references/config-check.md

Fantasy.config review checklist: machine/process/world/scene/database reference relationships, ports, World mode ID range common issues; read when user wants to check configuration correctness

references/config-scenarios.md

Fantasy.config common scenarios: new project, add/remove Scene, change database, change port, multi-zone; read when modifying config for specific scenarios

references/server/setup-server-check.md

Server project integration review checklist: three-layer structure, target framework, Fantasy-Net reference, compile macros, AssemblyHelper, Program entry common issues; read when user wants to check server project Fantasy integration

templates/Fantasy.config

Full annotated template: all nodes, attributes, possible values, and examples; read only when writing actual XML

Fantasy-net

Core Principles

Fantasy Technical Specifications

Development Behavioral Guidelines

Fantasy-net

Core Principles

Fantasy Technical Specifications

Development Behavioral Guidelines

1. Think Before Coding

2. Simplicity First

3. Surgical Changes

4. Goal-Driven Execution

Reference File Navigation

Prose

Golang Patterns

Audiocraft Audio Generation

Pokemon Player

Ideation

Storybook Upgrade