$36
Fantasy is a high-performance C# distributed game server framework based on ECS architecture, using FTask for async operations.
FTask for all async operations, not Task.g.cssealed class; all classes except structs must be created via Entitynamespace Fantasy;)Log.Debug/Info/Error() for logging; return error codes via response.ErrorCode; business logic should not throw exceptionsTradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment.
See references/guidelines-examples.md for detailed Fantasy scenario examples.
Don't assume. Don't hide confusion. Surface tradeoffs.
Before implementing:
Fantasy Key Points: Before implementing, clarify: architecture pattern (single-server/distributed), Entity ownership (which Scene), communication method (Roaming/Address/SphereEvent), configuration state (whether Fantasy.config has relevant nodes configured). When uncertain, ask; don't assume.
Minimum code that solves the problem. Nothing speculative.
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
Fantasy Key Points: Avoid premature abstraction of Entity/Component structures; don't design factory/strategy patterns for single scenarios. When users only need basic functionality, write Component + necessary AwakeSystem directly; refactor when extension is needed.
Touch only what you must. Clean up only your own mess.
When editing existing code:
When your changes create orphans:
The test: Every changed line should trace directly to the user's request.
Fantasy Key Points: Never modify .g.cs generated files (if you find issues, modify source files and regenerate). Don't manually adjust source generator registration code. Don't "optimize" existing Entity/Component structures unless user explicitly requests refactoring.
Define success criteria. Loop until verified.
Transform tasks into verifiable goals:
For multi-step tasks, state a brief plan:
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
Fantasy Key Points: Define verifiable steps and criteria: protocol export (dotnet fantasy-export successfully generates .g.cs), compilation passes (dotnet build with no errors), Handler registration (check generated registration code), message flow (Log.Debug outputs key nodes, confirm request/response correctness).
Read the corresponding file based on the requirement; for complex tasks, read multiple files.
| 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 |