@rpgjs/client 5.0.0-beta.25 → 5.0.0-beta.26

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @rpgjs/client
 
+## 5.0.0-beta.26
+
+### Minor Changes
+
+- 83fc2b7: Add production Signe room adapters for persistent Node servers and Cloudflare Durable Objects, plus remote Vite map publication for trusted editor workflows with transient-only retries. Resolve local TMX files and their external tilesets when publishing maps, recreate configured events safely during live map updates, and restore player and event graphics after clients reload the Tiled scene.
+
+  Add provider-neutral authoritative map streaming with progressive render/physics chunks, client prediction barriers, and spatial interest management for players, NPCs, events, and projectiles. Keep complete Tiled TMX/TSX sources server-side in MMORPG mode while sharing the same game module between Node.js, local Wrangler, and Cloudflare Durable Object hosts.
+
+  Use the physics broad-phase index when resolving synchronized entities in each player's retained chunks, avoiding full-room player and event scans on every sync packet.
+
+  Assign Tiled collision geometry to every streamed chunk it intersects, and preserve the generated client reference for action, dash, pointer, and interaction APIs with a dedicated interactions guide.
+
+  Preserve initial room synchronization on older local Workerd runtimes that expose an accepted Durable Object WebSocket with a transient `CONNECTING` ready state.
+
+  Prevent CanvasEngine rain layers from retaining tick subscriptions when an asynchronous mount overlaps destruction or another mount.
+
+  Keep component-ready standalone Studio maps intact when sharing the in-memory server, and select the Cloudflare publisher independently from the generic MMORPG entry so local Node.js development does not require a Worker secret.
+
+  Add Studio v2 authoritative map preparation and progressive chunk streaming, including server physics, nearby rendering data, and provider-neutral entity synchronization. Trusted Vite publishers can now resolve a complete Studio payload before sending it to Node or Cloudflare map rooms, while raw Studio map structure, events, database records, and global collision data stay server-side.
+
+  Make initial map streaming explicit and hibernation-safe: clients request a fresh manifest after joining, trusted map updates are durably stored before acknowledgement, and recreated Durable Object room instances rebuild their transient streaming runtime. Stream Studio terrain control masks per chunk so transition rendering and prediction physics work without disclosing the complete map, and reset spatial visibility on reconnect so existing clients receive newly joined players.
+
+  Preserve custom streaming providers when Studio's built-in streaming is disabled, refresh cached client controllers after Durable Object hibernation, and key terrain-control buffers by their complete streamed region content to prevent stale masks.
+
+  Suppress projectile lifecycle packets that fall outside a player's disclosed interest window, clear client prediction barriers after the final streamed chunk is evicted, and coalesce concurrent requests for the same map stream. Exercise these paths with server, client, and real Workerd WebSocket tests, and run the Cloudflare MMORPG and Studio runtime suites in CI.
+
+  Avoid dereferencing an empty Studio weather state while switching maps.
+
+  Publish authenticated world topology updates to every map room, persist them across Durable Object hibernation, and refresh automatic world-map transitions without restarting the MMORPG server.
+
+  Document the Durable Object room model, map-and-world publication flow, hibernation recovery, production deployment, and common Cloudflare diagnostics.
+
+  Correct the documented default runtime to standalone RPG and add a beginner deployment path that takes the v5 starter through explicit MMORPG development, private map bundling, authenticated map publication, a persistent Node Docker deployment, or a Cloudflare Durable Object deployment. Include an executable production map publisher in the Cloudflare sample and make the production pages discoverable from both documentation navigations.
+
+  Declare the RPGJS Durable Object binding explicitly in Wrangler staging and production environments so isolated deployments keep their room namespace.
+
+  Cover the previous Studio scene before unmounting it during World transfers, preserve recent directional movement into the destination room, then reveal the new map through a full-screen dark transition with a centered, delayed localized loader and a bounded asset wait so stale or white frames cannot flash while fast local transitions stay unobtrusive.
+
+### Patch Changes
+
+- b6ab003: Establish `defineModule()` as the canonical runtime module authoring API, export it from the client and server packages, keep `createModule()` for advanced provider composition, and align runtime-specific module installation documentation and examples.
+- Updated dependencies [b6ab003]
+- Updated dependencies [777541a]
+- Updated dependencies [48fcd25]
+- Updated dependencies [83fc2b7]
+  - @rpgjs/common@5.0.0-beta.25
+  - @rpgjs/server@5.0.0-beta.26
+
 ## 5.0.0-beta.25
 
 ### Minor Changes

package/dist/Game/Map.d.ts

@@ -9,6 +9,7 @@ export declare class RpgClientMap extends RpgCommonMap<any> {
     currentPlayer: import('canvasengine').ComputedSignal<RpgClientPlayer>;
     weatherState: import('canvasengine').WritableSignal<WeatherState | null>;
     localWeatherOverride: import('canvasengine').WritableSignal<WeatherState | null>;
+    private localWeatherValue;
     lightingState: import('canvasengine').WritableSignal<LightingState | null>;
     localLightSpots: import('canvasengine').WritableObjectSignal<Record<string, LightSpot>>;
     weather: import('canvasengine').ComputedSignal<WeatherState | null>;

package/dist/Game/Map.js

@@ -25,6 +25,7 @@ var RpgClientMap = class extends RpgCommonMap {
 		this.currentPlayer = computed(() => this.players()[this.engine.playerIdSignal()]);
 		this.weatherState = signal(null);
 		this.localWeatherOverride = signal(null);
+		this.localWeatherValue = null;
 		this.lightingState = signal(null);
 		this.localLightSpots = signal({});
 		this.weather = computed(() => {
@@ -72,6 +73,7 @@ var RpgClientMap = class extends RpgCommonMap {
 		this.players.set(currentPlayerId && currentPlayer ? { [currentPlayerId]: currentPlayer } : {});
 		this.events.set({});
 		this.weatherState.set(null);
+		this.localWeatherValue = null;
 		this.localWeatherOverride.set(null);
 		this.lightingState.set(null);
 		this.localLightSpots.set({});
@@ -81,9 +83,12 @@ var RpgClientMap = class extends RpgCommonMap {
 		return this.weather();
 	}
 	setLocalWeather(next) {
+		if (this.localWeatherValue === next) return;
+		this.localWeatherValue = next;
 		this.localWeatherOverride.set(next);
 	}
 	clearLocalWeather() {
+		this.localWeatherValue = null;
 		this.localWeatherOverride.set(null);
 	}
 	getLighting() {

package/dist/Game/Map.js.map

@@ -1 +1 @@
-{"version":3,"file":"Map.js","names":[],"sources":["../../src/Game/Map.ts"],"sourcesContent":["import {\n  RpgCommonMap,\n  cloneLightingState,\n  normalizeLightingState,\n  type LightSpot,\n  type LightingState,\n  type WeatherState,\n  type MapPhysicsInitContext,\n  type MapPhysicsEntityContext,\n} from \"@rpgjs/common\";\nimport { sync, users } from \"@signe/sync\";\nimport { RpgClientPlayer } from \"./Player\";\nimport { Signal, signal, computed, effect } from \"canvasengine\";\nimport { RpgClientEvent } from \"./Event\";\nimport { RpgClientEngine } from \"../RpgClientEngine\";\nimport { inject } from \"../core/inject\";\n\ntype TestGlobalScope = typeof globalThis & {\n  process?: {\n    env?: {\n      TEST?: string;\n    };\n  };\n  __RPGJS_TEST__?: boolean;\n};\n\nconst lightingColorsEqual = (\n  left: LightSpot[\"color\"],\n  right: LightSpot[\"color\"],\n): boolean => {\n  if (Array.isArray(left) || Array.isArray(right)) {\n    return Array.isArray(left)\n      && Array.isArray(right)\n      && left.length === right.length\n      && left.every((value, index) => value === right[index]);\n  }\n  return left === right;\n};\n\nconst lightSpotsEqual = (left: LightSpot | undefined, right: LightSpot): boolean => {\n  if (!left) return false;\n  return left.id === right.id\n    && left.x === right.x\n    && left.y === right.y\n    && left.radius === right.radius\n    && left.intensity === right.intensity\n    && lightingColorsEqual(left.color, right.color)\n    && left.flicker === right.flicker\n    && left.flickerSpeed === right.flickerSpeed\n    && left.pulse === right.pulse\n    && left.pulseSpeed === right.pulseSpeed\n    && left.phase === right.phase;\n};\n\nexport class RpgClientMap extends RpgCommonMap<any> {\n  engine: RpgClientEngine = inject(RpgClientEngine)\n  @users(RpgClientPlayer) players = signal<Record<string, RpgClientPlayer>>({});\n  @sync(RpgClientEvent) events = signal<Record<string, RpgClientEvent>>({});\n  currentPlayer = computed(() => this.players()[this.engine.playerIdSignal()!])\n  weatherState = signal<WeatherState | null>(null);\n  localWeatherOverride = signal<WeatherState | null>(null);\n  lightingState = signal<LightingState | null>(null);\n  localLightSpots = signal<Record<string, LightSpot>>({});\n  weather = computed<WeatherState | null>(() => {\n    const local = this.localWeatherOverride() \n    const state = this.weatherState()\n    return local ?? state\n  });\n  lighting = computed<LightingState | null>(() => {\n    const state = cloneLightingState(this.lightingState());\n    const localSpots = Object.entries(this.localLightSpots()).map(([id, spot]) => ({\n      ...spot,\n      id: spot.id ?? id,\n    }));\n\n    if (!state && localSpots.length === 0) {\n      return null;\n    }\n\n    const next: LightingState = { ...(state ?? {}) };\n    if (!state?.ambient) {\n      delete next.ambient;\n    }\n    next.spots = [\n      ...(state?.spots ?? []),\n      ...localSpots,\n    ];\n    return next;\n  });\n  private manualClientPhysicsTick = false;\n  private readonly isTestEnvironment: boolean;\n\n  constructor() {\n    super();\n    // Détecter l'environnement de test\n    const testGlobal = globalThis as TestGlobalScope;\n    const isTest = testGlobal.process?.env?.TEST === 'true'\n      || testGlobal.__RPGJS_TEST__ === true;\n    this.isTestEnvironment = isTest;\n    if (isTest) {\n      this.autoTickEnabled = false;\n    }\n  }\n\n  configureClientPrediction(enabled: boolean): void {\n    this.manualClientPhysicsTick = enabled;\n    this.autoTickEnabled = enabled ? false : !this.isTestEnvironment;\n  }\n\n  getCurrentPlayer() {\n    return this.currentPlayer()\n  }\n\n  reset(force = false) {\n    const currentPlayerId = this.engine.playerIdSignal();\n    const currentPlayer = !force && currentPlayerId\n      ? this.players()[currentPlayerId]\n      : undefined;\n    const players = this.players();\n    const events = this.events();\n\n    Object.entries(players).forEach(([id, player]) => {\n      if (!player || (!force && id === currentPlayerId)) return;\n      (player as any).resetAnimationState?.();\n    });\n    Object.values(events).forEach((event) => {\n      (event as any)?.resetAnimationState?.();\n    });\n\n    this.players.set(\n      currentPlayerId && currentPlayer ? { [currentPlayerId]: currentPlayer } : {}\n    );\n    this.events.set({})\n    this.weatherState.set(null);\n    this.localWeatherOverride.set(null);\n    this.lightingState.set(null);\n    this.localLightSpots.set({});\n    this.clearPhysic()\n  }\n\n  getWeather(): WeatherState | null {\n    return this.weather();\n  }\n\n  setLocalWeather(next: WeatherState | null): void {\n    this.localWeatherOverride.set(next);\n  }\n\n  clearLocalWeather(): void {\n    this.localWeatherOverride.set(null);\n  }\n\n  getLighting(): LightingState | null {\n    return this.lighting();\n  }\n\n  addLightSpot(id: string, spot: LightSpot): void {\n    const normalized = normalizeLightingState({ spots: [{ ...spot, id }] });\n    const nextSpot = normalized?.spots?.[0];\n    if (!nextSpot) {\n      return;\n    }\n    this.localLightSpots.update((spots) => {\n      if (lightSpotsEqual(spots[id], nextSpot)) {\n        return spots;\n      }\n      return {\n        ...spots,\n        [id]: nextSpot,\n      };\n    });\n  }\n\n  patchLightSpot(id: string, patch: Partial<LightSpot>): void {\n    this.localLightSpots.update((spots) => {\n      const current = spots[id];\n      if (!current) {\n        return spots;\n      }\n      return {\n        ...spots,\n        [id]: {\n          ...current,\n          ...patch,\n          id,\n          x: patch.x ?? current.x,\n          y: patch.y ?? current.y,\n        },\n      };\n    });\n  }\n\n  removeLightSpot(id: string): void {\n    this.localLightSpots.update((spots) => {\n      if (!(id in spots)) {\n        return spots;\n      }\n      const next = { ...spots };\n      delete next[id];\n      return next;\n    });\n  }\n\n  clearLightSpots(): void {\n    this.localLightSpots.set({});\n  }\n\n  stepClientPhysics(deltaMs: number): number {\n    if (!this.manualClientPhysicsTick) {\n      return 0;\n    }\n    return this.nextTick(deltaMs);\n  }\n\n  stepPredictionTick(): void {\n    this.forceSingleTick();\n  }\n\n  protected emitPhysicsInit(context: MapPhysicsInitContext): void {\n    this.engine?.emitSceneMapHook?.(\"onPhysicsInit\", this, context);\n  }\n\n  protected emitPhysicsEntityAdd(context: MapPhysicsEntityContext): void {\n    this.engine?.emitSceneMapHook?.(\"onPhysicsEntityAdd\", this, context);\n  }\n\n  protected emitPhysicsEntityRemove(context: MapPhysicsEntityContext): void {\n    this.engine?.emitSceneMapHook?.(\"onPhysicsEntityRemove\", this, context);\n  }\n\n  protected emitPhysicsReset(): void {\n    this.engine?.emitSceneMapHook?.(\"onPhysicsReset\", this);\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"Map.js","names":[],"sources":["../../src/Game/Map.ts"],"sourcesContent":["import {\n  RpgCommonMap,\n  cloneLightingState,\n  normalizeLightingState,\n  type LightSpot,\n  type LightingState,\n  type WeatherState,\n  type MapPhysicsInitContext,\n  type MapPhysicsEntityContext,\n} from \"@rpgjs/common\";\nimport { sync, users } from \"@signe/sync\";\nimport { RpgClientPlayer } from \"./Player\";\nimport { Signal, signal, computed, effect } from \"canvasengine\";\nimport { RpgClientEvent } from \"./Event\";\nimport { RpgClientEngine } from \"../RpgClientEngine\";\nimport { inject } from \"../core/inject\";\n\ntype TestGlobalScope = typeof globalThis & {\n  process?: {\n    env?: {\n      TEST?: string;\n    };\n  };\n  __RPGJS_TEST__?: boolean;\n};\n\nconst lightingColorsEqual = (\n  left: LightSpot[\"color\"],\n  right: LightSpot[\"color\"],\n): boolean => {\n  if (Array.isArray(left) || Array.isArray(right)) {\n    return Array.isArray(left)\n      && Array.isArray(right)\n      && left.length === right.length\n      && left.every((value, index) => value === right[index]);\n  }\n  return left === right;\n};\n\nconst lightSpotsEqual = (left: LightSpot | undefined, right: LightSpot): boolean => {\n  if (!left) return false;\n  return left.id === right.id\n    && left.x === right.x\n    && left.y === right.y\n    && left.radius === right.radius\n    && left.intensity === right.intensity\n    && lightingColorsEqual(left.color, right.color)\n    && left.flicker === right.flicker\n    && left.flickerSpeed === right.flickerSpeed\n    && left.pulse === right.pulse\n    && left.pulseSpeed === right.pulseSpeed\n    && left.phase === right.phase;\n};\n\nexport class RpgClientMap extends RpgCommonMap<any> {\n  engine: RpgClientEngine = inject(RpgClientEngine)\n  @users(RpgClientPlayer) players = signal<Record<string, RpgClientPlayer>>({});\n  @sync(RpgClientEvent) events = signal<Record<string, RpgClientEvent>>({});\n  currentPlayer = computed(() => this.players()[this.engine.playerIdSignal()!])\n  weatherState = signal<WeatherState | null>(null);\n  localWeatherOverride = signal<WeatherState | null>(null);\n  private localWeatherValue: WeatherState | null = null;\n  lightingState = signal<LightingState | null>(null);\n  localLightSpots = signal<Record<string, LightSpot>>({});\n  weather = computed<WeatherState | null>(() => {\n    const local = this.localWeatherOverride() \n    const state = this.weatherState()\n    return local ?? state\n  });\n  lighting = computed<LightingState | null>(() => {\n    const state = cloneLightingState(this.lightingState());\n    const localSpots = Object.entries(this.localLightSpots()).map(([id, spot]) => ({\n      ...spot,\n      id: spot.id ?? id,\n    }));\n\n    if (!state && localSpots.length === 0) {\n      return null;\n    }\n\n    const next: LightingState = { ...(state ?? {}) };\n    if (!state?.ambient) {\n      delete next.ambient;\n    }\n    next.spots = [\n      ...(state?.spots ?? []),\n      ...localSpots,\n    ];\n    return next;\n  });\n  private manualClientPhysicsTick = false;\n  private readonly isTestEnvironment: boolean;\n\n  constructor() {\n    super();\n    // Détecter l'environnement de test\n    const testGlobal = globalThis as TestGlobalScope;\n    const isTest = testGlobal.process?.env?.TEST === 'true'\n      || testGlobal.__RPGJS_TEST__ === true;\n    this.isTestEnvironment = isTest;\n    if (isTest) {\n      this.autoTickEnabled = false;\n    }\n  }\n\n  configureClientPrediction(enabled: boolean): void {\n    this.manualClientPhysicsTick = enabled;\n    this.autoTickEnabled = enabled ? false : !this.isTestEnvironment;\n  }\n\n  getCurrentPlayer() {\n    return this.currentPlayer()\n  }\n\n  reset(force = false) {\n    const currentPlayerId = this.engine.playerIdSignal();\n    const currentPlayer = !force && currentPlayerId\n      ? this.players()[currentPlayerId]\n      : undefined;\n    const players = this.players();\n    const events = this.events();\n\n    Object.entries(players).forEach(([id, player]) => {\n      if (!player || (!force && id === currentPlayerId)) return;\n      (player as any).resetAnimationState?.();\n    });\n    Object.values(events).forEach((event) => {\n      (event as any)?.resetAnimationState?.();\n    });\n\n    this.players.set(\n      currentPlayerId && currentPlayer ? { [currentPlayerId]: currentPlayer } : {}\n    );\n    this.events.set({})\n    this.weatherState.set(null);\n    this.localWeatherValue = null;\n    this.localWeatherOverride.set(null);\n    this.lightingState.set(null);\n    this.localLightSpots.set({});\n    this.clearPhysic()\n  }\n\n  getWeather(): WeatherState | null {\n    return this.weather();\n  }\n\n  setLocalWeather(next: WeatherState | null): void {\n    if (this.localWeatherValue === next) {\n      return;\n    }\n    this.localWeatherValue = next;\n    this.localWeatherOverride.set(next);\n  }\n\n  clearLocalWeather(): void {\n    this.localWeatherValue = null;\n    this.localWeatherOverride.set(null);\n  }\n\n  getLighting(): LightingState | null {\n    return this.lighting();\n  }\n\n  addLightSpot(id: string, spot: LightSpot): void {\n    const normalized = normalizeLightingState({ spots: [{ ...spot, id }] });\n    const nextSpot = normalized?.spots?.[0];\n    if (!nextSpot) {\n      return;\n    }\n    this.localLightSpots.update((spots) => {\n      if (lightSpotsEqual(spots[id], nextSpot)) {\n        return spots;\n      }\n      return {\n        ...spots,\n        [id]: nextSpot,\n      };\n    });\n  }\n\n  patchLightSpot(id: string, patch: Partial<LightSpot>): void {\n    this.localLightSpots.update((spots) => {\n      const current = spots[id];\n      if (!current) {\n        return spots;\n      }\n      return {\n        ...spots,\n        [id]: {\n          ...current,\n          ...patch,\n          id,\n          x: patch.x ?? current.x,\n          y: patch.y ?? current.y,\n        },\n      };\n    });\n  }\n\n  removeLightSpot(id: string): void {\n    this.localLightSpots.update((spots) => {\n      if (!(id in spots)) {\n        return spots;\n      }\n      const next = { ...spots };\n      delete next[id];\n      return next;\n    });\n  }\n\n  clearLightSpots(): void {\n    this.localLightSpots.set({});\n  }\n\n  stepClientPhysics(deltaMs: number): number {\n    if (!this.manualClientPhysicsTick) {\n      return 0;\n    }\n    return this.nextTick(deltaMs);\n  }\n\n  stepPredictionTick(): void {\n    this.forceSingleTick();\n  }\n\n  protected emitPhysicsInit(context: MapPhysicsInitContext): void {\n    this.engine?.emitSceneMapHook?.(\"onPhysicsInit\", this, context);\n  }\n\n  protected emitPhysicsEntityAdd(context: MapPhysicsEntityContext): void {\n    this.engine?.emitSceneMapHook?.(\"onPhysicsEntityAdd\", this, context);\n  }\n\n  protected emitPhysicsEntityRemove(context: MapPhysicsEntityContext): void {\n    this.engine?.emitSceneMapHook?.(\"onPhysicsEntityRemove\", this, context);\n  }\n\n  protected emitPhysicsReset(): void {\n    this.engine?.emitSceneMapHook?.(\"onPhysicsReset\", this);\n  }\n}\n"],"mappings":"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"}

package/dist/RpgClient.d.ts

@@ -230,7 +230,8 @@ export interface RpgSceneHooks<Scene> {
     */
     onRemoveSprite?: (scene: Scene, sprite: RpgComponent) => any;
     /**
-    * Before the scene is loaded
+    * Before the scene is loaded. Async hooks are awaited while the previous
+    * scene is still mounted, allowing transition UI to cover it before teardown.
     *
     * @prop { (scene: RpgScene) => any } [onBeforeLoading]
     * @memberof RpgSceneHooks

package/dist/RpgClientEngine.d.ts

@@ -43,7 +43,40 @@ export declare class RpgClientEngine<T = any> {
     componentAnimations: any[];
     clientVisuals: ClientVisualRegistry;
     projectiles: ProjectileManager;
+    /**
+     * Read the latest pointer position tracked by the client canvas. World
+     * coordinates are suitable for action payloads and map interactions.
+     *
+     * @title pointer
+     * @prop pointer: ClientPointerContext
+     * @memberof RpgClientEngine
+     * @example
+     * ```ts
+     * const target = engine.pointer.world()
+     * if (target) engine.processAction('projectile:shoot', { target })
+     * ```
+     */
     pointer: ClientPointerContext;
+    /**
+     * Register client-only pointer behaviors for map sprites. Interactions remain
+     * local unless a behavior explicitly sends an action to the server.
+     *
+     * See the [client interactions guide](../../guide/interactions.md) for hover,
+     * selection, hit testing, drag-and-drop, overlays, and network rules.
+     *
+     * @title interactions
+     * @prop interactions: RpgClientInteractions
+     * @memberof RpgClientEngine
+     * @example
+     * ```ts
+     * engine.interactions.use('Guard', {
+     *   cursor: 'pointer',
+     *   click(ctx) {
+     *     ctx.action('guard:talk', { eventId: ctx.target.id })
+     *   }
+     * })
+     * ```
+     */
     interactions: RpgClientInteractions;
     private spritesheetResolver?;
     private soundResolver?;
@@ -86,6 +119,8 @@ export declare class RpgClientEngine<T = any> {
     private pingInterval;
     private readonly PING_INTERVAL_MS;
     private lastInputTime;
+    private latestDirectionalInput?;
+    private pendingMapTransferInput?;
     private readonly MOVE_PATH_RESEND_INTERVAL_MS;
     private readonly MAX_MOVE_TRAJECTORY_POINTS;
     private lastMovePathSentAt;
@@ -98,6 +133,7 @@ export declare class RpgClientEngine<T = any> {
     private sceneResetQueued;
     private mapTransitionInProgress;
     private currentMapRoomId?;
+    private activeMapStreamController?;
     private socketListenersInitialized;
     private clientReadyForMapChanges;
     private pendingMapChanges;
@@ -170,6 +206,7 @@ export declare class RpgClientEngine<T = any> {
     private normalizeAckWithSyncState;
     private initListeners;
     private beginMapTransfer;
+    private resetSceneForMapTransfer;
     private clearComponentAnimations;
     private shouldProcessProjectilePacket;
     private callConnectError;
@@ -223,6 +260,7 @@ export declare class RpgClientEngine<T = any> {
      */
     private sendPing;
     private loadScene;
+    private resumeMapTransferMovement;
     addSpriteSheet<T = any>(spritesheetClass: any, id?: string): any;
     /**
      * Set a resolver function for spritesheets
@@ -676,7 +714,44 @@ export declare class RpgClientEngine<T = any> {
     processInput({ input }: {
         input: RpgMovementInput;
     }): Promise<void>;
+    /**
+     * Start a predicted dash for the current player and send it through the
+     * authoritative movement channel.
+     *
+     * @title processDash
+     * @method processDash(input?: Partial<RpgDashInput>): Promise<void>
+     * @param input - Optional direction, speed, duration, and cooldown overrides.
+     * @returns A promise resolved after the dash input has been processed locally.
+     * @memberof RpgClientEngine
+     * @example
+     * ```ts
+     * await engine.processDash({
+     *   direction: { x: 1, y: 0 },
+     *   additionalSpeed: 10,
+     *   duration: 220,
+     *   cooldown: 600,
+     * })
+     * ```
+     */
     processDash(input?: Partial<RpgDashInput>): Promise<void>;
+    /**
+     * Send an action intent to the authoritative server. Client-provided data
+     * must be validated by the receiving player input handler or action.
+     *
+     * @title processAction
+     * @method processAction(action: RpgActionName | RpgActionInput, data?: any): void
+     * @param action - Action name/control value, or a normalized action object.
+     * @param data - Optional serializable context sent with an action name.
+     * @returns Nothing.
+     * @memberof RpgClientEngine
+     * @example
+     * ```ts
+     * engine.processAction('projectile:shoot', {
+     *   target: engine.pointer.world(),
+     *   source: 'map-click',
+     * })
+     * ```
+     */
     processAction(action: RpgActionName, data?: any): void;
     processAction(action: RpgActionInput): void;
     get PIXI(): typeof PIXI;
@@ -742,6 +817,7 @@ export declare class RpgClientEngine<T = any> {
      * ```
      */
     clearClientPredictionStates(): void;
+    private clearMapTransferPredictionStates;
     /**
      * Stop local movement immediately and discard pending predicted movement.
      *

package/dist/RpgClientEngine.js

@@ -241,6 +241,7 @@ var RpgClientEngine = class {
 		this.sceneMap.configureClientPrediction(this.predictionEnabled);
 		this.sceneMap.loadPhysic();
 		this.resolveSceneMapComponent();
+		this.loadMapService.initialize?.();
 		inject(SaveClientService).initialize();
 		this.initListeners();
 		this.guiService._initialize();
@@ -624,11 +625,15 @@ var RpgClientEngine = class {
 			this.callConnectError(error);
 		});
 	}
-	beginMapTransfer(nextMapId) {
+	beginMapTransfer(nextMapId, continueMovement = false) {
+		this.pendingMapTransferInput = continueMovement ? this.latestDirectionalInput : void 0;
 		this.mapTransitionInProgress = true;
 		this.currentMapRoomId = nextMapId;
 		this.sceneResetQueued = false;
-		this.clearClientPredictionStates();
+		this.clearMapTransferPredictionStates();
+	}
+	resetSceneForMapTransfer(nextMapId) {
+		this.sceneMap.data.set(null);
 		this.sceneMap.weatherState.set(null);
 		this.sceneMap.lightingState.set(null);
 		this.sceneMap.clearLightSpots();
@@ -664,7 +669,7 @@ var RpgClientEngine = class {
 	}
 	handleChangeMap(data) {
 		const nextMapId = typeof data?.mapId === "string" ? data.mapId : void 0;
-		this.beginMapTransfer(nextMapId);
+		this.beginMapTransfer(nextMapId, data?.continueMovement === true);
 		const transferToken = typeof data?.transferToken === "string" ? data.transferToken : void 0;
 		this.loadScene(data.mapId, transferToken);
 	}
@@ -763,7 +768,11 @@ var RpgClientEngine = class {
 	}
 	async loadScene(mapId, transferToken) {
 		await lastValueFrom(this.hooks.callHooks("client-sceneMap-onBeforeLoading", this.sceneMap));
-		this.clearClientPredictionStates();
+		this.activeMapStreamController?.detach();
+		this.activeMapStreamController = void 0;
+		if (this.mapTransitionInProgress) this.resetSceneForMapTransfer(mapId);
+		if (this.mapTransitionInProgress) this.clearMapTransferPredictionStates();
+		else this.clearClientPredictionStates();
 		this.mapLoadCompleted$.next(false);
 		this.playerIdReceived$.next(false);
 		this.playersReceived$.next(false);
@@ -778,6 +787,7 @@ var RpgClientEngine = class {
 			await this.webSocket.reconnect();
 		} catch (error) {
 			this.mapTransitionInProgress = false;
+			this.pendingMapTransferInput = void 0;
 			this.stopPingPong();
 			await this.callConnectError(error);
 			throw error;
@@ -795,6 +805,23 @@ var RpgClientEngine = class {
 		this.mapTransitionInProgress = false;
 		this.sceneMap.configureClientPrediction(this.predictionEnabled);
 		this.sceneMap.loadPhysic();
+		if (res?.streamController) {
+			const controller = res.streamController;
+			this.activeMapStreamController = controller;
+			controller.attach(this.sceneMap);
+		}
+		const transferInput = this.pendingMapTransferInput;
+		this.pendingMapTransferInput = void 0;
+		if (transferInput !== void 0) this.resumeMapTransferMovement(transferInput, mapId);
+	}
+	async resumeMapTransferMovement(input, mapId) {
+		const repeatCount = 4;
+		const repeatIntervalMs = 50;
+		for (let index = 0; index < repeatCount; index += 1) {
+			if (this.mapTransitionInProgress || this.currentMapRoomId !== mapId) return;
+			await this.processInput({ input });
+			if (index < repeatCount - 1) await new Promise((resolve) => setTimeout(resolve, repeatIntervalMs));
+		}
 	}
 	addSpriteSheet(spritesheetClass, id) {
 		this.spritesheets.set(id || spritesheetClass.id, spritesheetClass);
@@ -1400,6 +1427,7 @@ var RpgClientEngine = class {
 		const timestamp = Date.now();
 		const movementInput = isDashInput(input) ? normalizeDashInput(input, currentPlayer?.direction?.()) : input;
 		if (!movementInput) return;
+		if (!isDashInput(movementInput)) this.latestDirectionalInput = movementInput;
 		if (isDashInput(movementInput)) {
 			const cooldown = movementInput.cooldown ?? DEFAULT_DASH_COOLDOWN_MS;
 			if (timestamp < this.dashLockedUntil) return;
@@ -1432,6 +1460,25 @@ var RpgClientEngine = class {
 		this.emitMovePacket(movementInput, frame, tick, timestamp, true);
 		this.lastInputTime = isDashInput(movementInput) ? Date.now() + (movementInput.duration ?? DEFAULT_DASH_DURATION_MS) : Date.now();
 	}
+	/**
+	* Start a predicted dash for the current player and send it through the
+	* authoritative movement channel.
+	*
+	* @title processDash
+	* @method processDash(input?: Partial<RpgDashInput>): Promise<void>
+	* @param input - Optional direction, speed, duration, and cooldown overrides.
+	* @returns A promise resolved after the dash input has been processed locally.
+	* @memberof RpgClientEngine
+	* @example
+	* ```ts
+	* await engine.processDash({
+	*   direction: { x: 1, y: 0 },
+	*   additionalSpeed: 10,
+	*   duration: 220,
+	*   cooldown: 600,
+	* })
+	* ```
+	*/
 	async processDash(input = {}) {
 		const currentPlayer = this.sceneMap.getCurrentPlayer();
 		const dashInput = normalizeDashInput(input, typeof currentPlayer?.direction === "function" ? currentPlayer.direction() : currentPlayer?.direction);
@@ -1707,6 +1754,14 @@ var RpgClientEngine = class {
 		this.lastMovePathSentAt = 0;
 		this.lastMovePathSentFrame = 0;
 	}
+	clearMapTransferPredictionStates() {
+		this.prediction?.clearPendingInputs();
+		this.frameOffset = 0;
+		this.pendingPredictionFrames = [];
+		this.lastClientPhysicsStepAt = 0;
+		this.lastMovePathSentAt = 0;
+		this.lastMovePathSentFrame = this.inputFrameCounter;
+	}
 	/**
 	* Stop local movement immediately and discard pending predicted movement.
 	*