# Fantasy Net

This guide applies to development and code review for Fantasy / Fantasy.Net /...

- Repository: https://github.com/qq362946/Fantasy (1476 stars)
- Category: Data and ML
- License: see repository
- Last updated: 2026-10-19
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add qq362946/Fantasy --skill fantasy-net -g -a claude-code -y`
Codex: `npx skills add qq362946/Fantasy --skill fantasy-net -g -a codex -y`
Cursor: `npx skills add qq362946/Fantasy --skill fantasy-net -g -a cursor -y`
Gemini CLI: `npx skills add qq362946/Fantasy --skill fantasy-net -g -a gemini-cli -y`

## Description

This guide applies to development and code review for Fantasy / Fantasy.Net / Fantasy.Unity written in C#. Use it when a task involves Fantasy server code or Unity client code using Fantasy, ECS entities/components/systems, scenes and subscenes, FTask, network handlers/messages/protocols, Address or Roaming routing, Control Center and service discovery, Kubernetes deployment and Pod DNS binding, Namespace/WorldGroup/World isolation, dynamic Scene registration or routing, cross-server events and subscriptions, Fantasy.config, scene or database access, HTTP controllers/services, session or client connection logic, or distributed runtime architecture. It may also be used for Fantasy-related code review, troubleshooting, compliance checks, risk analysis, and best practices, even when the user does not explicitly mention Fantasy.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

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

The rest: https://github.com/qq362946/Fantasy/blob/HEAD/Skills/fantasy-net/SKILL.md