@esengine/server 4.4.0 → 4.5.1

package/dist/index.d.ts

@@ -1,9 +1,11 @@
-import { S as ServerConfig, G as GameServer, A as ApiDefinition, M as MsgDefinition, H as HttpDefinition, a as HttpRoutes, b as HttpRouterOptions } from './index-lcuKuQsL.js';
-export { d as ApiContext, C as CorsOptions, i as HttpHandler, f as HttpMethod, g as HttpRequest, h as HttpResponse, e as MsgContext, c as ServerConnection } from './index-lcuKuQsL.js';
-export { I as IPlayer, P as Player, R as Room, a as RoomOptions } from './Room-BnKpl5Sj.js';
-export { o as onMessage } from './decorators-DY8nZ8Nh.js';
+import { a as ServerConfig, G as GameServer, b as ApiDefinition, c as MsgDefinition, H as HttpDefinition, d as HttpRoutes, e as HttpRouterOptions, I as IDistributedAdapter, f as ServerRegistration, R as RoomRegistration, g as RoomQuery, h as RoomSnapshot, D as DistributedEvent, i as DistributedEventType, j as DistributedEventHandler, U as Unsubscribe, k as DistributedRoomManagerConfig, l as RoutingRequest, m as RoutingResult } from './index-B1sr5YAl.js';
+export { A as ApiContext, C as CorsOptions, s as DistributedConfig, q as HttpHandler, n as HttpMethod, o as HttpRequest, p as HttpResponse, M as MsgContext, S as ServerConnection, r as ServerStatus } from './index-B1sr5YAl.js';
+import { R as Room, a as RoomOptions, P as Player } from './Room-5owFVIFR.js';
+export { I as IPlayer } from './Room-5owFVIFR.js';
+export { ECSRoom, ECSRoomConfig, onMessage } from './ecs/index.js';
 import { IncomingMessage, ServerResponse } from 'node:http';
 export { ErrorCode, RpcError } from '@esengine/rpc';
+import '@esengine/ecs-framework';
 
 /**
  * @zh 游戏服务器核心
@@ -31,11 +33,584 @@ export { ErrorCode, RpcError } from '@esengine/rpc';
  */
 declare function createServer(config?: ServerConfig): Promise<GameServer>;
 
+/**
+ * @zh Schema 验证类型定义
+ * @en Schema validation type definitions
+ */
+/**
+ * @zh 验证错误
+ * @en Validation error
+ */
+interface ValidationError {
+    /**
+     * @zh 错误路径（如 ['user', 'name']）
+     * @en Error path (e.g., ['user', 'name'])
+     */
+    path: string[];
+    /**
+     * @zh 错误消息
+     * @en Error message
+     */
+    message: string;
+    /**
+     * @zh 预期类型
+     * @en Expected type
+     */
+    expected?: string;
+    /**
+     * @zh 实际值
+     * @en Actual value
+     */
+    received?: unknown;
+}
+/**
+ * @zh 验证成功结果
+ * @en Validation success result
+ */
+interface ValidationSuccess<T> {
+    success: true;
+    data: T;
+}
+/**
+ * @zh 验证失败结果
+ * @en Validation failure result
+ */
+interface ValidationFailure {
+    success: false;
+    error: ValidationError;
+}
+/**
+ * @zh 验证结果
+ * @en Validation result
+ */
+type ValidationResult<T> = ValidationSuccess<T> | ValidationFailure;
+/**
+ * @zh 验证器接口
+ * @en Validator interface
+ */
+interface Validator<T> {
+    /**
+     * @zh 类型名称（用于错误消息）
+     * @en Type name (for error messages)
+     */
+    readonly typeName: string;
+    /**
+     * @zh 验证值
+     * @en Validate value
+     *
+     * @param value - @zh 待验证的值 @en Value to validate
+     * @param path - @zh 当前路径（用于错误报告）@en Current path (for error reporting)
+     * @returns @zh 验证结果 @en Validation result
+     */
+    validate(value: unknown, path?: string[]): ValidationResult<T>;
+    /**
+     * @zh 类型守卫检查
+     * @en Type guard check
+     *
+     * @param value - @zh 待检查的值 @en Value to check
+     * @returns @zh 是否为指定类型 @en Whether value is of specified type
+     */
+    is(value: unknown): value is T;
+    /**
+     * @zh 标记为可选
+     * @en Mark as optional
+     */
+    optional(): Validator<T | undefined>;
+    /**
+     * @zh 设置默认值
+     * @en Set default value
+     *
+     * @param defaultValue - @zh 默认值 @en Default value
+     */
+    default(defaultValue: T): Validator<T>;
+    /**
+     * @zh 允许 null
+     * @en Allow null
+     */
+    nullable(): Validator<T | null>;
+}
+/**
+ * @zh 从验证器推断类型
+ * @en Infer type from validator
+ */
+type Infer<V extends Validator<unknown>> = V extends Validator<infer T> ? T : never;
+/**
+ * @zh 对象 Schema 定义
+ * @en Object schema definition
+ */
+type ObjectShape = Record<string, Validator<unknown>>;
+/**
+ * @zh 从对象 Shape 推断类型
+ * @en Infer type from object shape
+ */
+type InferShape<T extends ObjectShape> = {
+    [K in keyof T]: Infer<T[K]>;
+};
+/**
+ * @zh 验证器选项
+ * @en Validator options
+ */
+interface ValidatorOptions {
+    /**
+     * @zh 是否可选
+     * @en Whether optional
+     */
+    isOptional?: boolean;
+    /**
+     * @zh 默认值
+     * @en Default value
+     */
+    defaultValue?: unknown;
+    /**
+     * @zh 是否允许 null
+     * @en Whether nullable
+     */
+    isNullable?: boolean;
+}
+
+/**
+ * @zh 基础验证器抽象类
+ * @en Base validator abstract class
+ *
+ * @zh 所有验证器的基类，提供通用的验证逻辑
+ * @en Base class for all validators, providing common validation logic
+ */
+
+/**
+ * @zh 基础验证器抽象类
+ * @en Base validator abstract class
+ */
+declare abstract class BaseValidator<T> implements Validator<T> {
+    abstract readonly typeName: string;
+    protected _options: ValidatorOptions;
+    /**
+     * @zh 核心验证逻辑（子类实现）
+     * @en Core validation logic (implemented by subclass)
+     */
+    protected abstract _validate(value: unknown, path: string[]): ValidationResult<T>;
+    validate(value: unknown, path?: string[]): ValidationResult<T>;
+    is(value: unknown): value is T;
+    optional(): Validator<T | undefined>;
+    default(defaultValue: T): Validator<T>;
+    nullable(): Validator<T | null>;
+    /**
+     * @zh 克隆验证器（用于链式调用）
+     * @en Clone validator (for chaining)
+     */
+    protected abstract _clone(): BaseValidator<T>;
+}
+
+/**
+ * @zh 基础类型验证器
+ * @en Primitive type validators
+ */
+
+/**
+ * @zh 字符串验证器
+ * @en String validator
+ */
+declare class StringValidator extends BaseValidator<string> {
+    readonly typeName = "string";
+    private _stringOptions;
+    protected _validate(value: unknown, path: string[]): ValidationResult<string>;
+    protected _clone(): StringValidator;
+    /**
+     * @zh 设置最小长度
+     * @en Set minimum length
+     */
+    min(length: number): StringValidator;
+    /**
+     * @zh 设置最大长度
+     * @en Set maximum length
+     */
+    max(length: number): StringValidator;
+    /**
+     * @zh 设置长度范围
+     * @en Set length range
+     */
+    length(min: number, max: number): StringValidator;
+    /**
+     * @zh 设置正则模式
+     * @en Set regex pattern
+     */
+    regex(pattern: RegExp): StringValidator;
+    /**
+     * @zh 邮箱格式验证
+     * @en Email format validation
+     */
+    email(): StringValidator;
+    /**
+     * @zh URL 格式验证
+     * @en URL format validation
+     */
+    url(): StringValidator;
+}
+/**
+ * @zh 数字验证器
+ * @en Number validator
+ */
+declare class NumberValidator extends BaseValidator<number> {
+    readonly typeName = "number";
+    private _numberOptions;
+    protected _validate(value: unknown, path: string[]): ValidationResult<number>;
+    protected _clone(): NumberValidator;
+    /**
+     * @zh 设置最小值
+     * @en Set minimum value
+     */
+    min(value: number): NumberValidator;
+    /**
+     * @zh 设置最大值
+     * @en Set maximum value
+     */
+    max(value: number): NumberValidator;
+    /**
+     * @zh 设置范围
+     * @en Set range
+     */
+    range(min: number, max: number): NumberValidator;
+    /**
+     * @zh 要求为整数
+     * @en Require integer
+     */
+    int(): NumberValidator;
+    /**
+     * @zh 要求为正数
+     * @en Require positive
+     */
+    positive(): NumberValidator;
+    /**
+     * @zh 要求为负数
+     * @en Require negative
+     */
+    negative(): NumberValidator;
+}
+/**
+ * @zh 布尔验证器
+ * @en Boolean validator
+ */
+declare class BooleanValidator extends BaseValidator<boolean> {
+    readonly typeName = "boolean";
+    protected _validate(value: unknown, path: string[]): ValidationResult<boolean>;
+    protected _clone(): BooleanValidator;
+}
+/**
+ * @zh 字面量验证器
+ * @en Literal validator
+ */
+declare class LiteralValidator<T extends string | number | boolean> extends BaseValidator<T> {
+    readonly typeName: string;
+    private readonly _literal;
+    constructor(literal: T);
+    protected _validate(value: unknown, path: string[]): ValidationResult<T>;
+    protected _clone(): LiteralValidator<T>;
+}
+/**
+ * @zh 任意类型验证器
+ * @en Any type validator
+ */
+declare class AnyValidator extends BaseValidator<unknown> {
+    readonly typeName = "any";
+    protected _validate(value: unknown): ValidationResult<unknown>;
+    protected _clone(): AnyValidator;
+}
+/**
+ * @zh 创建字符串验证器
+ * @en Create string validator
+ */
+declare function string(): StringValidator;
+/**
+ * @zh 创建数字验证器
+ * @en Create number validator
+ */
+declare function number(): NumberValidator;
+/**
+ * @zh 创建布尔验证器
+ * @en Create boolean validator
+ */
+declare function boolean(): BooleanValidator;
+/**
+ * @zh 创建字面量验证器
+ * @en Create literal validator
+ */
+declare function literal<T extends string | number | boolean>(value: T): LiteralValidator<T>;
+/**
+ * @zh 创建任意类型验证器
+ * @en Create any type validator
+ */
+declare function any(): AnyValidator;
+
+/**
+ * @zh 复合类型验证器
+ * @en Composite type validators
+ */
+
+/**
+ * @zh 对象验证器
+ * @en Object validator
+ */
+declare class ObjectValidator<T extends ObjectShape> extends BaseValidator<InferShape<T>> {
+    readonly typeName = "object";
+    private readonly _shape;
+    private _objectOptions;
+    constructor(shape: T);
+    protected _validate(value: unknown, path: string[]): ValidationResult<InferShape<T>>;
+    protected _clone(): ObjectValidator<T>;
+    /**
+     * @zh 严格模式（不允许额外字段）
+     * @en Strict mode (no extra fields allowed)
+     */
+    strict(): ObjectValidator<T>;
+    /**
+     * @zh 部分模式（所有字段可选）
+     * @en Partial mode (all fields optional)
+     */
+    partial(): ObjectValidator<{
+        [K in keyof T]: ReturnType<T[K]['optional']>;
+    }>;
+    /**
+     * @zh 选择部分字段
+     * @en Pick specific fields
+     */
+    pick<K extends keyof T>(...keys: K[]): ObjectValidator<Pick<T, K>>;
+    /**
+     * @zh 排除部分字段
+     * @en Omit specific fields
+     */
+    omit<K extends keyof T>(...keys: K[]): ObjectValidator<Omit<T, K>>;
+    /**
+     * @zh 扩展对象 Schema
+     * @en Extend object schema
+     */
+    extend<U extends ObjectShape>(shape: U): ObjectValidator<T & U>;
+}
+/**
+ * @zh 数组验证器
+ * @en Array validator
+ */
+declare class ArrayValidator<T> extends BaseValidator<T[]> {
+    readonly typeName = "array";
+    private readonly _element;
+    private _arrayOptions;
+    constructor(element: Validator<T>);
+    protected _validate(value: unknown, path: string[]): ValidationResult<T[]>;
+    protected _clone(): ArrayValidator<T>;
+    /**
+     * @zh 设置最小长度
+     * @en Set minimum length
+     */
+    min(length: number): ArrayValidator<T>;
+    /**
+     * @zh 设置最大长度
+     * @en Set maximum length
+     */
+    max(length: number): ArrayValidator<T>;
+    /**
+     * @zh 设置长度范围
+     * @en Set length range
+     */
+    length(min: number, max: number): ArrayValidator<T>;
+    /**
+     * @zh 要求非空数组
+     * @en Require non-empty array
+     */
+    nonempty(): ArrayValidator<T>;
+}
+/**
+ * @zh 元组验证器
+ * @en Tuple validator
+ */
+declare class TupleValidator<T extends readonly Validator<unknown>[]> extends BaseValidator<{
+    [K in keyof T]: T[K] extends Validator<infer U> ? U : never;
+}> {
+    readonly typeName = "tuple";
+    private readonly _elements;
+    constructor(elements: T);
+    protected _validate(value: unknown, path: string[]): ValidationResult<{
+        [K in keyof T]: T[K] extends Validator<infer U> ? U : never;
+    }>;
+    protected _clone(): TupleValidator<T>;
+}
+/**
+ * @zh 联合类型验证器
+ * @en Union type validator
+ */
+declare class UnionValidator<T extends readonly Validator<unknown>[]> extends BaseValidator<T[number] extends Validator<infer U> ? U : never> {
+    readonly typeName: string;
+    private readonly _variants;
+    constructor(variants: T);
+    protected _validate(value: unknown, path: string[]): ValidationResult<T[number] extends Validator<infer U> ? U : never>;
+    protected _clone(): UnionValidator<T>;
+}
+/**
+ * @zh 记录类型验证器
+ * @en Record type validator
+ */
+declare class RecordValidator<T> extends BaseValidator<Record<string, T>> {
+    readonly typeName = "record";
+    private readonly _valueValidator;
+    constructor(valueValidator: Validator<T>);
+    protected _validate(value: unknown, path: string[]): ValidationResult<Record<string, T>>;
+    protected _clone(): RecordValidator<T>;
+}
+/**
+ * @zh 枚举验证器
+ * @en Enum validator
+ */
+declare class EnumValidator<T extends readonly (string | number)[]> extends BaseValidator<T[number]> {
+    readonly typeName: string;
+    private readonly _values;
+    private readonly _valuesArray;
+    constructor(values: T);
+    protected _validate(value: unknown, path: string[]): ValidationResult<T[number]>;
+    protected _clone(): EnumValidator<T>;
+}
+/**
+ * @zh 创建对象验证器
+ * @en Create object validator
+ */
+declare function object<T extends ObjectShape>(shape: T): ObjectValidator<T>;
+/**
+ * @zh 创建数组验证器
+ * @en Create array validator
+ */
+declare function array<T>(element: Validator<T>): ArrayValidator<T>;
+/**
+ * @zh 创建元组验证器
+ * @en Create tuple validator
+ */
+declare function tuple<T extends readonly Validator<unknown>[]>(elements: T): TupleValidator<T>;
+/**
+ * @zh 创建联合类型验证器
+ * @en Create union type validator
+ */
+declare function union<T extends readonly Validator<unknown>[]>(variants: T): UnionValidator<T>;
+/**
+ * @zh 创建记录类型验证器
+ * @en Create record type validator
+ */
+declare function record<T>(valueValidator: Validator<T>): RecordValidator<T>;
+/**
+ * @zh 创建枚举验证器
+ * @en Create enum validator
+ */
+declare function nativeEnum<T extends readonly (string | number)[]>(values: T): EnumValidator<T>;
+
+/**
+ * @zh Schema 构建器命名空间
+ * @en Schema builder namespace
+ *
+ * @example
+ * ```typescript
+ * import { s } from '@esengine/server';
+ *
+ * const UserSchema = s.object({
+ *     id: s.string(),
+ *     name: s.string().min(1).max(50),
+ *     age: s.number().int().min(0).max(150),
+ *     email: s.string().email().optional(),
+ *     role: s.enum(['admin', 'user', 'guest'] as const),
+ *     tags: s.array(s.string()),
+ *     metadata: s.record(s.any()).optional()
+ * });
+ *
+ * type User = s.infer<typeof UserSchema>;
+ * ```
+ */
+declare const s: {
+    readonly string: typeof string;
+    readonly number: typeof number;
+    readonly boolean: typeof boolean;
+    readonly literal: typeof literal;
+    readonly any: typeof any;
+    readonly object: typeof object;
+    readonly array: typeof array;
+    readonly tuple: typeof tuple;
+    readonly union: typeof union;
+    readonly record: typeof record;
+    /**
+     * @zh 创建枚举验证器
+     * @en Create enum validator
+     *
+     * @example
+     * ```typescript
+     * const RoleSchema = s.enum(['admin', 'user', 'guest'] as const);
+     * type Role = s.infer<typeof RoleSchema>; // 'admin' | 'user' | 'guest'
+     * ```
+     */
+    readonly enum: typeof nativeEnum;
+    /**
+     * @zh 类型推断辅助（仅用于类型层面）
+     * @en Type inference helper (type-level only)
+     *
+     * @zh 这是一个类型辅助，用于从验证器推断类型
+     * @en This is a type helper to infer types from validators
+     */
+    readonly infer: <V extends Validator<unknown>>() => Infer<V>;
+};
+/**
+ * @zh 类型推断辅助类型
+ * @en Type inference helper type
+ */
+declare namespace s {
+    /**
+     * @zh 从验证器推断类型
+     * @en Infer type from validator
+     */
+    type infer<V extends Validator<unknown>> = Infer<V>;
+}
+/**
+ * @zh 验证数据并抛出错误
+ * @en Validate data and throw error
+ *
+ * @param validator - @zh 验证器 @en Validator
+ * @param value - @zh 待验证的值 @en Value to validate
+ * @returns @zh 验证通过的数据 @en Validated data
+ * @throws @zh 验证失败时抛出错误 @en Throws when validation fails
+ */
+declare function parse<T>(validator: Validator<T>, value: unknown): T;
+/**
+ * @zh 安全验证数据（不抛出错误）
+ * @en Safely validate data (no throw)
+ *
+ * @param validator - @zh 验证器 @en Validator
+ * @param value - @zh 待验证的值 @en Value to validate
+ * @returns @zh 验证结果 @en Validation result
+ */
+declare function safeParse<T>(validator: Validator<T>, value: unknown): ValidationResult<T>;
+/**
+ * @zh 创建类型守卫函数
+ * @en Create type guard function
+ *
+ * @param validator - @zh 验证器 @en Validator
+ * @returns @zh 类型守卫函数 @en Type guard function
+ *
+ * @example
+ * ```typescript
+ * const isUser = createGuard(UserSchema);
+ * if (isUser(data)) {
+ *     // data is User
+ * }
+ * ```
+ */
+declare function createGuard<T>(validator: Validator<T>): (value: unknown) => value is T;
+
 /**
  * @zh API、消息和 HTTP 定义助手
  * @en API, message, and HTTP definition helpers
  */
 
+/**
+ * @zh 带 Schema 的 API 定义选项
+ * @en API definition options with schema
+ */
+interface ApiDefinitionWithSchema<TReq, TRes, TData = Record<string, unknown>> extends ApiDefinition<TReq, TRes, TData> {
+    /**
+     * @zh 请求数据 Schema（自动验证）
+     * @en Request data schema (auto validation)
+     */
+    schema?: Validator<TReq>;
+}
 /**
  * @zh 定义 API 处理器
  * @en Define API handler
@@ -52,8 +627,62 @@ declare function createServer(config?: ServerConfig): Promise<GameServer>;
  *     }
  * })
  * ```
+ *
+ * @example
+ * ```typescript
+ * // 使用 Schema 验证 | With schema validation
+ * import { defineApi, s } from '@esengine/server'
+ *
+ * const MoveSchema = s.object({
+ *     x: s.number(),
+ *     y: s.number()
+ * });
+ *
+ * export default defineApi({
+ *     schema: MoveSchema,
+ *     handler(req, ctx) {
+ *         // req 已验证，类型安全 | req is validated, type-safe
+ *         console.log(req.x, req.y);
+ *     }
+ * })
+ * ```
+ */
+declare function defineApi<TReq, TRes, TData = Record<string, unknown>>(definition: ApiDefinitionWithSchema<TReq, TRes, TData>): ApiDefinitionWithSchema<TReq, TRes, TData>;
+/**
+ * @zh 使用 Schema 定义 API 处理器（类型自动推断）
+ * @en Define API handler with schema (auto type inference)
+ *
+ * @example
+ * ```typescript
+ * import { defineApiWithSchema, s } from '@esengine/server'
+ *
+ * const MoveSchema = s.object({
+ *     x: s.number(),
+ *     y: s.number()
+ * });
+ *
+ * export default defineApiWithSchema(MoveSchema, {
+ *     handler(req, ctx) {
+ *         // req 类型自动推断为 { x: number, y: number }
+ *         // req type is auto-inferred as { x: number, y: number }
+ *         console.log(req.x, req.y);
+ *         return { success: true };
+ *     }
+ * })
+ * ```
  */
-declare function defineApi<TReq, TRes, TData = Record<string, unknown>>(definition: ApiDefinition<TReq, TRes, TData>): ApiDefinition<TReq, TRes, TData>;
+declare function defineApiWithSchema<TReq, TRes, TData = Record<string, unknown>>(schema: Validator<TReq>, definition: Omit<ApiDefinition<TReq, TRes, TData>, 'validate'>): ApiDefinitionWithSchema<TReq, TRes, TData>;
+/**
+ * @zh 带 Schema 的消息定义选项
+ * @en Message definition options with schema
+ */
+interface MsgDefinitionWithSchema<TMsg, TData = Record<string, unknown>> extends MsgDefinition<TMsg, TData> {
+    /**
+     * @zh 消息数据 Schema（自动验证）
+     * @en Message data schema (auto validation)
+     */
+    schema?: Validator<TMsg>;
+}
 /**
  * @zh 定义消息处理器
  * @en Define message handler
@@ -69,8 +698,50 @@ declare function defineApi<TReq, TRes, TData = Record<string, unknown>>(definiti
  *     }
  * })
  * ```
+ *
+ * @example
+ * ```typescript
+ * // 使用 Schema 验证 | With schema validation
+ * import { defineMsg, s } from '@esengine/server'
+ *
+ * const InputSchema = s.object({
+ *     keys: s.array(s.string()),
+ *     timestamp: s.number()
+ * });
+ *
+ * export default defineMsg({
+ *     schema: InputSchema,
+ *     handler(msg, ctx) {
+ *         // msg 已验证，类型安全 | msg is validated, type-safe
+ *         console.log(msg.keys, msg.timestamp);
+ *     }
+ * })
+ * ```
+ */
+declare function defineMsg<TMsg, TData = Record<string, unknown>>(definition: MsgDefinitionWithSchema<TMsg, TData>): MsgDefinitionWithSchema<TMsg, TData>;
+/**
+ * @zh 使用 Schema 定义消息处理器（类型自动推断）
+ * @en Define message handler with schema (auto type inference)
+ *
+ * @example
+ * ```typescript
+ * import { defineMsgWithSchema, s } from '@esengine/server'
+ *
+ * const InputSchema = s.object({
+ *     keys: s.array(s.string()),
+ *     timestamp: s.number()
+ * });
+ *
+ * export default defineMsgWithSchema(InputSchema, {
+ *     handler(msg, ctx) {
+ *         // msg 类型自动推断
+ *         // msg type is auto-inferred
+ *         console.log(msg.keys, msg.timestamp);
+ *     }
+ * })
+ * ```
  */
-declare function defineMsg<TMsg, TData = Record<string, unknown>>(definition: MsgDefinition<TMsg, TData>): MsgDefinition<TMsg, TData>;
+declare function defineMsgWithSchema<TMsg, TData = Record<string, unknown>>(schema: Validator<TMsg>, definition: MsgDefinition<TMsg, TData>): MsgDefinitionWithSchema<TMsg, TData>;
 /**
  * @zh 定义 HTTP 路由处理器
  * @en Define HTTP route handler
@@ -133,4 +804,779 @@ declare function defineHttp<TBody = unknown>(definition: HttpDefinition<TBody>):
  */
 declare function createHttpRouter(routes: HttpRoutes, options?: HttpRouterOptions): (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
 
-export { ApiDefinition, GameServer, HttpDefinition, HttpRoutes, MsgDefinition, ServerConfig, createHttpRouter, createServer, defineApi, defineHttp, defineMsg };
+/**
+ * @zh 内存分布式适配器
+ * @en Memory distributed adapter
+ *
+ * @zh 用于单机模式和测试的内存实现。所有数据存储在进程内存中。
+ * @en In-memory implementation for single-server mode and testing. All data stored in process memory.
+ */
+
+/**
+ * @zh 内存适配器配置
+ * @en Memory adapter configuration
+ */
+interface MemoryAdapterConfig {
+    /**
+     * @zh 服务器 TTL（毫秒），超时后视为离线
+     * @en Server TTL (ms), considered offline after timeout
+     * @default 15000
+     */
+    serverTtl?: number;
+    /**
+     * @zh 是否启用 TTL 检查
+     * @en Whether to enable TTL check
+     * @default true
+     */
+    enableTtlCheck?: boolean;
+    /**
+     * @zh TTL 检查间隔（毫秒）
+     * @en TTL check interval (ms)
+     * @default 5000
+     */
+    ttlCheckInterval?: number;
+}
+/**
+ * @zh 内存分布式适配器
+ * @en Memory distributed adapter
+ */
+declare class MemoryAdapter implements IDistributedAdapter {
+    private readonly _config;
+    private _connected;
+    private readonly _servers;
+    private readonly _rooms;
+    private readonly _snapshots;
+    private readonly _locks;
+    private readonly _subscribers;
+    private _subscriberId;
+    private _ttlCheckTimer;
+    constructor(config?: MemoryAdapterConfig);
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    registerServer(server: ServerRegistration): Promise<void>;
+    unregisterServer(serverId: string): Promise<void>;
+    heartbeat(serverId: string): Promise<void>;
+    getServers(): Promise<ServerRegistration[]>;
+    getServer(serverId: string): Promise<ServerRegistration | null>;
+    updateServer(serverId: string, updates: Partial<ServerRegistration>): Promise<void>;
+    registerRoom(room: RoomRegistration): Promise<void>;
+    unregisterRoom(roomId: string): Promise<void>;
+    updateRoom(roomId: string, updates: Partial<RoomRegistration>): Promise<void>;
+    getRoom(roomId: string): Promise<RoomRegistration | null>;
+    queryRooms(query: RoomQuery): Promise<RoomRegistration[]>;
+    findAvailableRoom(roomType: string): Promise<RoomRegistration | null>;
+    getRoomsByServer(serverId: string): Promise<RoomRegistration[]>;
+    saveSnapshot(snapshot: RoomSnapshot): Promise<void>;
+    loadSnapshot(roomId: string): Promise<RoomSnapshot | null>;
+    deleteSnapshot(roomId: string): Promise<void>;
+    publish(event: DistributedEvent): Promise<void>;
+    subscribe(pattern: DistributedEventType | '*', handler: DistributedEventHandler): Promise<Unsubscribe>;
+    sendToRoom(roomId: string, messageType: string, data: unknown, playerId?: string): Promise<void>;
+    acquireLock(key: string, ttlMs: number): Promise<boolean>;
+    releaseLock(key: string): Promise<void>;
+    extendLock(key: string, ttlMs: number): Promise<boolean>;
+    private _ensureConnected;
+    private _countRoomsByServer;
+    private _checkServerTtl;
+    /**
+     * @zh 清除所有数据（仅用于测试）
+     * @en Clear all data (for testing only)
+     */
+    _clear(): void;
+    /**
+     * @zh 获取内部状态（仅用于测试）
+     * @en Get internal state (for testing only)
+     */
+    _getState(): {
+        servers: Map<string, ServerRegistration>;
+        rooms: Map<string, RoomRegistration>;
+        snapshots: Map<string, RoomSnapshot>;
+    };
+}
+
+/**
+ * @zh Redis 分布式适配器
+ * @en Redis distributed adapter
+ *
+ * @zh 基于 Redis 的分布式房间适配器，支持 Pub/Sub、分布式锁和状态持久化
+ * @en Redis-based distributed room adapter with Pub/Sub, distributed lock and state persistence
+ */
+
+/**
+ * @zh Redis 客户端接口（兼容 ioredis）
+ * @en Redis client interface (compatible with ioredis)
+ */
+interface RedisClient {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ...args: (string | number)[]): Promise<string | null>;
+    del(...keys: string[]): Promise<number>;
+    expire(key: string, seconds: number): Promise<number>;
+    ttl(key: string): Promise<number>;
+    hget(key: string, field: string): Promise<string | null>;
+    hset(key: string, ...args: (string | number | Buffer)[]): Promise<number>;
+    hdel(key: string, ...fields: string[]): Promise<number>;
+    hgetall(key: string): Promise<Record<string, string>>;
+    hmset(key: string, ...args: (string | number | Buffer)[]): Promise<'OK'>;
+    sadd(key: string, ...members: string[]): Promise<number>;
+    srem(key: string, ...members: string[]): Promise<number>;
+    smembers(key: string): Promise<string[]>;
+    publish(channel: string, message: string): Promise<number>;
+    subscribe(channel: string): Promise<number>;
+    psubscribe(pattern: string): Promise<number>;
+    unsubscribe(...channels: string[]): Promise<number>;
+    punsubscribe(...patterns: string[]): Promise<number>;
+    on(event: 'message', callback: (channel: string, message: string) => void): void;
+    on(event: 'pmessage', callback: (pattern: string, channel: string, message: string) => void): void;
+    on(event: string, callback: (...args: unknown[]) => void): void;
+    off(event: 'message', callback: (channel: string, message: string) => void): void;
+    off(event: 'pmessage', callback: (pattern: string, channel: string, message: string) => void): void;
+    off(event: string, callback: (...args: unknown[]) => void): void;
+    eval(script: string, numkeys: number, ...args: (string | number)[]): Promise<unknown>;
+    duplicate(): RedisClient;
+    quit(): Promise<'OK'>;
+    disconnect(): void;
+}
+/**
+ * @zh Redis 连接工厂
+ * @en Redis connection factory
+ */
+type RedisClientFactory = () => RedisClient | Promise<RedisClient>;
+/**
+ * @zh Redis 适配器配置
+ * @en Redis adapter configuration
+ */
+interface RedisAdapterConfig {
+    /**
+     * @zh Redis 客户端工厂（惰性连接）
+     * @en Redis client factory (lazy connection)
+     *
+     * @example
+     * ```typescript
+     * import Redis from 'ioredis'
+     * const adapter = new RedisAdapter({
+     *     factory: () => new Redis('redis://localhost:6379')
+     * })
+     * ```
+     */
+    factory: RedisClientFactory;
+    /**
+     * @zh 键前缀
+     * @en Key prefix
+     * @default 'dist:'
+     */
+    prefix?: string;
+    /**
+     * @zh 服务器 TTL（秒）
+     * @en Server TTL (seconds)
+     * @default 30
+     */
+    serverTtl?: number;
+    /**
+     * @zh 房间 TTL（秒），0 = 永不过期
+     * @en Room TTL (seconds), 0 = never expire
+     * @default 0
+     */
+    roomTtl?: number;
+    /**
+     * @zh 快照 TTL（秒）
+     * @en Snapshot TTL (seconds)
+     * @default 86400 (24 hours)
+     */
+    snapshotTtl?: number;
+    /**
+     * @zh Pub/Sub 频道名
+     * @en Pub/Sub channel name
+     * @default 'distributed:events'
+     */
+    channel?: string;
+}
+/**
+ * @zh Redis 分布式适配器
+ * @en Redis distributed adapter
+ *
+ * @example
+ * ```typescript
+ * import Redis from 'ioredis'
+ * import { RedisAdapter, DistributedRoomManager } from '@esengine/server'
+ *
+ * const adapter = new RedisAdapter({
+ *     factory: () => new Redis('redis://localhost:6379'),
+ *     prefix: 'game:'
+ * })
+ *
+ * const manager = new DistributedRoomManager(adapter, {
+ *     serverId: 'server-1',
+ *     serverAddress: 'localhost',
+ *     serverPort: 3000
+ * }, sendFn)
+ *
+ * await manager.start()
+ * ```
+ */
+declare class RedisAdapter implements IDistributedAdapter {
+    private readonly _config;
+    private _client;
+    private _subscriber;
+    private _connected;
+    private readonly _lockTokens;
+    private readonly _handlers;
+    private _messageHandler;
+    constructor(config: RedisAdapterConfig);
+    private _key;
+    private _serverKey;
+    private _roomKey;
+    private _snapshotKey;
+    private _lockKey;
+    private _serversSetKey;
+    private _roomsSetKey;
+    private _serverRoomsKey;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    private _ensureConnected;
+    registerServer(server: ServerRegistration): Promise<void>;
+    unregisterServer(serverId: string): Promise<void>;
+    heartbeat(serverId: string): Promise<void>;
+    getServers(): Promise<ServerRegistration[]>;
+    getServer(serverId: string): Promise<ServerRegistration | null>;
+    updateServer(serverId: string, updates: Partial<ServerRegistration>): Promise<void>;
+    registerRoom(room: RoomRegistration): Promise<void>;
+    unregisterRoom(roomId: string): Promise<void>;
+    updateRoom(roomId: string, updates: Partial<RoomRegistration>): Promise<void>;
+    getRoom(roomId: string): Promise<RoomRegistration | null>;
+    queryRooms(query: RoomQuery): Promise<RoomRegistration[]>;
+    findAvailableRoom(roomType: string): Promise<RoomRegistration | null>;
+    getRoomsByServer(serverId: string): Promise<RoomRegistration[]>;
+    saveSnapshot(snapshot: RoomSnapshot): Promise<void>;
+    loadSnapshot(roomId: string): Promise<RoomSnapshot | null>;
+    deleteSnapshot(roomId: string): Promise<void>;
+    publish(event: DistributedEvent): Promise<void>;
+    subscribe(pattern: DistributedEventType | '*', handler: DistributedEventHandler): Promise<Unsubscribe>;
+    sendToRoom(roomId: string, messageType: string, data: unknown, playerId?: string): Promise<void>;
+    private _dispatchEvent;
+    acquireLock(key: string, ttlMs: number): Promise<boolean>;
+    releaseLock(key: string): Promise<void>;
+    extendLock(key: string, ttlMs: number): Promise<boolean>;
+}
+/**
+ * @zh 创建 Redis 适配器
+ * @en Create Redis adapter
+ */
+declare function createRedisAdapter(config: RedisAdapterConfig): RedisAdapter;
+
+/**
+ * @zh 负载均衡路由器
+ * @en Load-balanced router for server selection
+ */
+
+/**
+ * @zh 负载均衡策略
+ * @en Load balancing strategy
+ */
+type LoadBalanceStrategy = 'round-robin' | 'least-rooms' | 'least-players' | 'random' | 'weighted';
+/**
+ * @zh 负载均衡路由器配置
+ * @en Load-balanced router configuration
+ */
+interface LoadBalancedRouterConfig {
+    /**
+     * @zh 负载均衡策略
+     * @en Load balancing strategy
+     * @default 'least-rooms'
+     */
+    strategy?: LoadBalanceStrategy;
+    /**
+     * @zh 本地服务器优先
+     * @en Prefer local server
+     * @default true
+     */
+    preferLocal?: boolean;
+    /**
+     * @zh 本地服务器优先阈值（0-1之间，表示本地服务器负载低于此比例时优先使用本地）
+     * @en Local server preference threshold (0-1, prefer local if load is below this ratio)
+     * @default 0.8
+     */
+    localPreferenceThreshold?: number;
+}
+/**
+ * @zh 负载均衡路由器
+ * @en Load-balanced router for selecting optimal server
+ *
+ * @example
+ * ```typescript
+ * const router = new LoadBalancedRouter({
+ *     strategy: 'least-rooms',
+ *     preferLocal: true
+ * });
+ *
+ * const bestServer = router.selectServer(servers, 'server-1');
+ * ```
+ */
+declare class LoadBalancedRouter {
+    private readonly _config;
+    private _roundRobinIndex;
+    constructor(config?: LoadBalancedRouterConfig);
+    /**
+     * @zh 选择最优服务器
+     * @en Select optimal server
+     *
+     * @param servers - 可用服务器列表 | Available servers
+     * @param localServerId - 本地服务器 ID | Local server ID
+     * @returns 最优服务器，如果没有可用服务器返回 null | Optimal server, or null if none available
+     */
+    selectServer(servers: ServerRegistration[], localServerId?: string): ServerRegistration | null;
+    /**
+     * @zh 选择创建房间的最优服务器
+     * @en Select optimal server for room creation
+     */
+    selectServerForCreation(servers: ServerRegistration[], localServerId?: string): ServerRegistration | null;
+    /**
+     * @zh 重置轮询索引
+     * @en Reset round-robin index
+     */
+    resetRoundRobin(): void;
+    private _selectRoundRobin;
+    private _selectLeastRooms;
+    private _selectLeastPlayers;
+    private _selectRandom;
+    private _selectWeighted;
+}
+/**
+ * @zh 创建负载均衡路由器
+ * @en Create load-balanced router
+ */
+declare function createLoadBalancedRouter(config?: LoadBalancedRouterConfig): LoadBalancedRouter;
+
+/**
+ * @zh 房间管理器
+ * @en Room manager
+ */
+
+/**
+ * @zh 房间类型
+ * @en Room class type
+ */
+type RoomClass<T extends Room = Room> = new () => T;
+/**
+ * @zh 房间定义
+ * @en Room definition
+ */
+interface RoomDefinition {
+    roomClass: RoomClass;
+}
+/**
+ * @zh 房间管理器
+ * @en Room manager
+ *
+ * @zh 管理房间的创建、加入、离开等操作。可被 DistributedRoomManager 继承以支持分布式功能。
+ * @en Manages room creation, joining, leaving, etc. Can be extended by DistributedRoomManager for distributed features.
+ */
+declare class RoomManager {
+    /**
+     * @zh 房间类型定义映射
+     * @en Room type definitions map
+     */
+    protected _definitions: Map<string, RoomDefinition>;
+    /**
+     * @zh 房间实例映射
+     * @en Room instances map
+     */
+    protected _rooms: Map<string, Room>;
+    /**
+     * @zh 玩家到房间的映射
+     * @en Player to room mapping
+     */
+    protected _playerToRoom: Map<string, string>;
+    /**
+     * @zh 下一个房间 ID 计数器
+     * @en Next room ID counter
+     */
+    protected _nextRoomId: number;
+    /**
+     * @zh 消息发送函数
+     * @en Message send function
+     */
+    protected _sendFn: (conn: any, type: string, data: unknown) => void;
+    /**
+     * @zh 二进制发送函数
+     * @en Binary send function
+     */
+    protected _sendBinaryFn?: (conn: any, data: Uint8Array) => void;
+    constructor(sendFn: (conn: any, type: string, data: unknown) => void, sendBinaryFn?: (conn: any, data: Uint8Array) => void);
+    /**
+     * @zh 注册房间类型
+     * @en Define room type
+     */
+    define<T extends Room>(name: string, roomClass: RoomClass<T>): void;
+    /**
+     * @zh 创建房间
+     * @en Create room
+     *
+     * @param name - 房间类型名称 | Room type name
+     * @param options - 房间配置 | Room options
+     * @returns 房间实例或 null | Room instance or null
+     */
+    create(name: string, options?: RoomOptions): Promise<Room | null>;
+    /**
+     * @zh 房间创建后的回调
+     * @en Callback after room is created
+     *
+     * @param _name - 房间类型名称 | Room type name
+     * @param _room - 房间实例 | Room instance
+     */
+    protected _onRoomCreated(_name: string, _room: Room): Promise<void>;
+    /**
+     * @zh 加入或创建房间
+     * @en Join or create room
+     *
+     * @param name - 房间类型名称 | Room type name
+     * @param playerId - 玩家 ID | Player ID
+     * @param conn - 玩家连接 | Player connection
+     * @param options - 房间配置 | Room options
+     * @returns 房间和玩家实例或 null | Room and player instance or null
+     */
+    joinOrCreate(name: string, playerId: string, conn: any, options?: RoomOptions): Promise<{
+        room: Room;
+        player: Player;
+    } | null>;
+    /**
+     * @zh 加入指定房间
+     * @en Join specific room
+     *
+     * @param roomId - 房间 ID | Room ID
+     * @param playerId - 玩家 ID | Player ID
+     * @param conn - 玩家连接 | Player connection
+     * @returns 房间和玩家实例或 null | Room and player instance or null
+     */
+    joinById(roomId: string, playerId: string, conn: any): Promise<{
+        room: Room;
+        player: Player;
+    } | null>;
+    /**
+     * @zh 玩家离开
+     * @en Player leave
+     *
+     * @param playerId - 玩家 ID | Player ID
+     * @param reason - 离开原因 | Leave reason
+     */
+    leave(playerId: string, reason?: string): Promise<void>;
+    /**
+     * @zh 处理消息
+     * @en Handle message
+     */
+    handleMessage(playerId: string, type: string, data: unknown): void;
+    /**
+     * @zh 获取房间
+     * @en Get room
+     */
+    getRoom(roomId: string): Room | undefined;
+    /**
+     * @zh 获取玩家所在房间
+     * @en Get player's room
+     */
+    getPlayerRoom(playerId: string): Room | undefined;
+    /**
+     * @zh 获取所有房间
+     * @en Get all rooms
+     */
+    getRooms(): ReadonlyArray<Room>;
+    /**
+     * @zh 获取指定类型的所有房间
+     * @en Get all rooms of a type
+     */
+    getRoomsByType(name: string): Room[];
+    /**
+     * @zh 查找可用房间
+     * @en Find available room
+     *
+     * @param name - 房间类型名称 | Room type name
+     * @returns 可用房间或 null | Available room or null
+     */
+    protected _findAvailableRoom(name: string): Room | null;
+    /**
+     * @zh 生成房间 ID
+     * @en Generate room ID
+     *
+     * @returns 新的房间 ID | New room ID
+     */
+    protected _generateRoomId(): string;
+    /**
+     * @zh 获取房间定义
+     * @en Get room definition
+     *
+     * @param name - 房间类型名称 | Room type name
+     * @returns 房间定义或 undefined | Room definition or undefined
+     */
+    protected _getDefinition(name: string): RoomDefinition | undefined;
+    /**
+     * @zh 内部创建房间实例
+     * @en Internal create room instance
+     *
+     * @param name - 房间类型名称 | Room type name
+     * @param options - 房间配置 | Room options
+     * @param roomId - 可选的房间 ID（用于分布式恢复） | Optional room ID (for distributed recovery)
+     * @returns 房间实例或 null | Room instance or null
+     */
+    protected _createRoomInstance(name: string, options?: RoomOptions, roomId?: string): Promise<Room | null>;
+    /**
+     * @zh 房间销毁回调
+     * @en Room disposed callback
+     *
+     * @param roomId - 房间 ID | Room ID
+     */
+    protected _onRoomDisposed(roomId: string): void;
+    /**
+     * @zh 玩家加入房间后的回调
+     * @en Callback after player joins room
+     *
+     * @param playerId - 玩家 ID | Player ID
+     * @param roomId - 房间 ID | Room ID
+     * @param player - 玩家实例 | Player instance
+     */
+    protected _onPlayerJoined(playerId: string, roomId: string, _player: Player): void;
+    /**
+     * @zh 玩家离开房间后的回调
+     * @en Callback after player leaves room
+     *
+     * @param playerId - 玩家 ID | Player ID
+     * @param _roomId - 房间 ID | Room ID
+     */
+    protected _onPlayerLeft(playerId: string, _roomId: string): void;
+}
+
+/**
+ * @zh 分布式房间管理器
+ * @en Distributed room manager
+ *
+ * @zh 继承 RoomManager，添加分布式功能支持。包括跨服务器房间注册、
+ * 玩家路由、状态同步和故障转移。
+ * @en Extends RoomManager with distributed features. Includes cross-server room
+ * registration, player routing, state synchronization, and failover.
+ */
+
+/**
+ * @zh 分布式房间管理器配置（内部使用）
+ * @en Distributed room manager configuration (internal use)
+ */
+interface InternalConfig extends Required<Omit<DistributedRoomManagerConfig, 'metadata'>> {
+    metadata: Record<string, unknown>;
+}
+/**
+ * @zh 分布式房间管理器
+ * @en Distributed room manager
+ *
+ * @zh 扩展基础 RoomManager，添加以下功能：
+ * - 服务器注册和心跳
+ * - 跨服务器房间注册
+ * - 玩家路由和重定向
+ * - 状态快照和恢复
+ * - 分布式锁防止竞态
+ * @en Extends base RoomManager with:
+ * - Server registration and heartbeat
+ * - Cross-server room registration
+ * - Player routing and redirection
+ * - State snapshots and recovery
+ * - Distributed locks to prevent race conditions
+ */
+declare class DistributedRoomManager extends RoomManager {
+    private readonly _adapter;
+    private readonly _config;
+    private readonly _serverId;
+    private _heartbeatTimer;
+    private _snapshotTimer;
+    private _subscriptions;
+    private _isShuttingDown;
+    /**
+     * @zh 创建分布式房间管理器
+     * @en Create distributed room manager
+     *
+     * @param adapter - 分布式适配器 | Distributed adapter
+     * @param config - 配置 | Configuration
+     * @param sendFn - 消息发送函数 | Message send function
+     * @param sendBinaryFn - 二进制发送函数 | Binary send function
+     */
+    constructor(adapter: IDistributedAdapter, config: DistributedRoomManagerConfig, sendFn: (conn: any, type: string, data: unknown) => void, sendBinaryFn?: (conn: any, data: Uint8Array) => void);
+    /**
+     * @zh 获取服务器 ID
+     * @en Get server ID
+     */
+    get serverId(): string;
+    /**
+     * @zh 获取分布式适配器
+     * @en Get distributed adapter
+     */
+    get adapter(): IDistributedAdapter;
+    /**
+     * @zh 获取配置
+     * @en Get configuration
+     */
+    get config(): Readonly<InternalConfig>;
+    /**
+     * @zh 启动分布式房间管理器
+     * @en Start distributed room manager
+     */
+    start(): Promise<void>;
+    /**
+     * @zh 停止分布式房间管理器
+     * @en Stop distributed room manager
+     *
+     * @param graceful - 是否优雅关闭（等待玩家退出）| Whether to gracefully shutdown (wait for players)
+     */
+    stop(graceful?: boolean): Promise<void>;
+    /**
+     * @zh 房间创建后注册到分布式系统
+     * @en Register room to distributed system after creation
+     */
+    protected _onRoomCreated(name: string, room: Room): Promise<void>;
+    /**
+     * @zh 房间销毁时从分布式系统注销
+     * @en Unregister room from distributed system when disposed
+     */
+    protected _onRoomDisposed(roomId: string): void;
+    /**
+     * @zh 玩家加入后更新分布式房间信息
+     * @en Update distributed room info after player joins
+     */
+    protected _onPlayerJoined(playerId: string, roomId: string, player: Player): void;
+    /**
+     * @zh 玩家离开后更新分布式房间信息
+     * @en Update distributed room info after player leaves
+     */
+    protected _onPlayerLeft(playerId: string, roomId: string): void;
+    /**
+     * @zh 路由玩家到合适的房间/服务器
+     * @en Route player to appropriate room/server
+     *
+     * @param request - 路由请求 | Routing request
+     * @returns 路由结果 | Routing result
+     */
+    route(request: RoutingRequest): Promise<RoutingResult>;
+    /**
+     * @zh 加入或创建房间（分布式版本）
+     * @en Join or create room (distributed version)
+     *
+     * @zh 此方法会：
+     * 1. 先在分布式注册表中查找可用房间
+     * 2. 如果找到其他服务器的房间，返回重定向
+     * 3. 如果找到本地房间或需要创建，在本地处理
+     * @en This method will:
+     * 1. First search for available room in distributed registry
+     * 2. If room found on another server, return redirect
+     * 3. If local room found or creation needed, handle locally
+     */
+    joinOrCreateDistributed(name: string, playerId: string, conn: any, options?: RoomOptions): Promise<{
+        room: Room;
+        player: Player;
+    } | {
+        redirect: string;
+    } | null>;
+    /**
+     * @zh 保存房间状态快照
+     * @en Save room state snapshot
+     *
+     * @param roomId - 房间 ID | Room ID
+     */
+    saveSnapshot(roomId: string): Promise<void>;
+    /**
+     * @zh 从快照恢复房间
+     * @en Restore room from snapshot
+     *
+     * @param roomId - 房间 ID | Room ID
+     * @returns 是否成功恢复 | Whether restore was successful
+     */
+    restoreFromSnapshot(roomId: string): Promise<boolean>;
+    /**
+     * @zh 注册服务器到分布式系统
+     * @en Register server to distributed system
+     */
+    private _registerServer;
+    /**
+     * @zh 订阅分布式事件
+     * @en Subscribe to distributed events
+     */
+    private _subscribeToEvents;
+    /**
+     * @zh 启动心跳定时器
+     * @en Start heartbeat timer
+     */
+    private _startHeartbeat;
+    /**
+     * @zh 启动快照定时器
+     * @en Start snapshot timer
+     */
+    private _startSnapshotTimer;
+    /**
+     * @zh 保存所有房间快照
+     * @en Save all room snapshots
+     */
+    private _saveAllSnapshots;
+    /**
+     * @zh 路由到指定房间
+     * @en Route to specific room
+     */
+    private _routeToRoom;
+    /**
+     * @zh 按类型路由
+     * @en Route by type
+     */
+    private _routeByType;
+    /**
+     * @zh 处理服务器离线事件
+     * @en Handle server offline event
+     */
+    private _handleServerOffline;
+    /**
+     * @zh 尝试从离线服务器恢复房间
+     * @en Try to recover rooms from offline server
+     */
+    private _tryRecoverRoomsFromServer;
+    /**
+     * @zh 处理跨服务器房间消息
+     * @en Handle cross-server room message
+     */
+    private _handleRoomMessage;
+    /**
+     * @zh 统计总玩家数
+     * @en Count total players
+     */
+    private _countTotalPlayers;
+    /**
+     * @zh 根据房间实例获取定义
+     * @en Get definition by room instance
+     */
+    private _getDefinitionByRoom;
+    /**
+     * @zh 休眠指定时间
+     * @en Sleep for specified time
+     */
+    private _sleep;
+    /**
+     * @zh 向其他服务器的房间发送消息
+     * @en Send message to room on another server
+     *
+     * @param roomId - 房间 ID | Room ID
+     * @param messageType - 消息类型 | Message type
+     * @param data - 消息数据 | Message data
+     * @param playerId - 发送者玩家 ID（可选）| Sender player ID (optional)
+     */
+    sendToRemoteRoom(roomId: string, messageType: string, data: unknown, playerId?: string): Promise<void>;
+    /**
+     * @zh 获取所有在线服务器
+     * @en Get all online servers
+     */
+    getServers(): Promise<ServerRegistration[]>;
+    /**
+     * @zh 查询分布式房间
+     * @en Query distributed rooms
+     */
+    queryDistributedRooms(query: {
+        roomType?: string;
+        hasSpace?: boolean;
+        notLocked?: boolean;
+        metadata?: Record<string, unknown>;
+        limit?: number;
+    }): Promise<RoomRegistration[]>;
+}
+
+export { AnyValidator, ApiDefinition, type ApiDefinitionWithSchema, ArrayValidator, BooleanValidator, DistributedEvent, DistributedEventHandler, DistributedEventType, DistributedRoomManager, DistributedRoomManagerConfig, EnumValidator, GameServer, HttpDefinition, HttpRoutes, IDistributedAdapter, type Infer, type InferShape, LiteralValidator, type LoadBalanceStrategy, LoadBalancedRouter, type LoadBalancedRouterConfig, MemoryAdapter, type MemoryAdapterConfig, MsgDefinition, type MsgDefinitionWithSchema, NumberValidator, type ObjectShape, ObjectValidator, Player, RecordValidator, RedisAdapter, type RedisAdapterConfig, type RedisClient, type RedisClientFactory, Room, type RoomClass, RoomManager, RoomOptions, RoomQuery, RoomRegistration, RoomSnapshot, RoutingRequest, RoutingResult, ServerConfig, ServerRegistration, StringValidator, TupleValidator, UnionValidator, type ValidationError, type ValidationFailure, type ValidationResult, type ValidationSuccess, type Validator, any, array, boolean, createGuard, createHttpRouter, createLoadBalancedRouter, createRedisAdapter, createServer, defineApi, defineApiWithSchema, defineHttp, defineMsg, defineMsgWithSchema, literal, nativeEnum, number, object, parse, record, s, safeParse, string, tuple, union };