@rpgjs/client 5.0.0-beta.2 → 5.0.0-beta.20

package/src/RpgClientEngine.ts

@@ -1,11 +1,14 @@
 import Canvas from "./components/scenes/canvas.ce";
+import BuiltinSceneMap from "./components/scenes/draw-map.ce";
 import { inject } from './core/inject'
-import { signal, bootstrapCanvas, Howl, trigger } from "canvasengine";
+import { signal, bootstrapCanvas, Howl, trigger, type Trigger } from "canvasengine";
 import { AbstractWebsocket, WebSocketToken } from "./services/AbstractSocket";
 import { LoadMapService, LoadMapToken } from "./services/loadMap";
 import { RpgSound } from "./Sound";
 import { RpgResource } from "./Resource";
-import { Hooks, ModulesToken, Direction } from "@rpgjs/common";
+import { getOrCreateI18nService, Hooks, ModulesToken, Direction, normalizeLightingState, Vector2, type I18nParams, type I18nService } from "@rpgjs/common";
+import type { EventComponentConfig } from "./RpgClient";
+import type { RpgClientEvent } from "./Game/Event";
 import { load } from "@signe/sync";
 import { RpgClientMap } from "./Game/Map"
 import { RpgGui } from "./Gui/Gui";
@@ -14,24 +17,133 @@ import { lastValueFrom, Observable, combineLatest, BehaviorSubject, filter, swit
 import { GlobalConfigToken } from "./module";
 import * as PIXI from "pixi.js";
 import { PrebuiltComponentAnimations } from "./components/animations";
+import TextComponent from "./components/dynamics/text.ce";
+import BarComponent from "./components/dynamics/bar.ce";
+import ShapeComponent from "./components/dynamics/shape.ce";
+import ImageComponent from "./components/dynamics/image.ce";
 import {
   PredictionController,
   type PredictionHistoryEntry,
   type PredictionState,
+  type RpgActionInput,
+  type RpgActionName,
+  type RpgDashInput,
+  type RpgMovementInput,
 } from "@rpgjs/common";
 import { NotificationManager } from "./Gui/NotificationManager";
 import { SaveClientService } from "./services/save";
+import { getCanMoveValue } from "./utils/readPropValue";
+import { ProjectileManager, type ClientProjectileImpact, type ClientProjectileSpawn } from "./Game/ProjectileManager";
+import { ClientVisualRegistry, type ClientVisualHandler, type ClientVisualMap, type ClientVisualPacket } from "./Game/ClientVisuals";
+import { normalizeActionInput } from "./services/actionInput";
+import { createClientPointerContext, type ClientPointerContext } from "./services/pointerContext";
+import { RpgClientInteractions } from "./services/interactions";
+import { normalizeRoomMapId } from "./utils/mapId";
+import { EventComponentResolverRegistry, type EventComponentResolver } from "./Game/EventComponentResolver";
+import { RpgClientBuiltinI18n } from "./i18n";
 
 interface MovementTrajectoryPoint {
   frame: number;
   tick: number;
   timestamp: number;
-  input: Direction;
+  input: RpgMovementInput;
   x: number;
   y: number;
   direction?: Direction;
 }
 
+interface CanvasResizeSize {
+  width: number;
+  height: number;
+}
+
+const DEFAULT_DASH_ADDITIONAL_SPEED = 8;
+const DEFAULT_DASH_DURATION_MS = 180;
+const DEFAULT_DASH_COOLDOWN_MS = 450;
+
+const isDashInput = (input: RpgMovementInput): input is RpgDashInput =>
+  typeof input === "object" && input !== null && input.type === "dash";
+
+const isMoveInput = (
+  input: RpgMovementInput
+): input is { type: "move"; direction: Direction } =>
+  typeof input === "object" && input !== null && input.type === "move";
+
+const resolveMoveDirection = (input: RpgMovementInput): Direction | undefined => {
+  if (isMoveInput(input)) return input.direction;
+  if (typeof input === "string" || typeof input === "number") {
+    return input as Direction;
+  }
+  return undefined;
+};
+
+const directionToVector = (direction: Direction | undefined) => {
+  switch (direction) {
+    case Direction.Left:
+      return { x: -1, y: 0 };
+    case Direction.Right:
+      return { x: 1, y: 0 };
+    case Direction.Up:
+      return { x: 0, y: -1 };
+    case Direction.Down:
+    default:
+      return { x: 0, y: 1 };
+  }
+};
+
+const vectorToDirection = (direction: { x: number; y: number }): Direction => {
+  if (Math.abs(direction.x) > Math.abs(direction.y)) {
+    return direction.x < 0 ? Direction.Left : Direction.Right;
+  }
+  return direction.y < 0 ? Direction.Up : Direction.Down;
+};
+
+const normalizeDashInput = (
+  input: Partial<RpgDashInput>,
+  fallbackDirection: Direction | undefined
+): RpgDashInput | null => {
+  const rawDirection = input.direction ?? directionToVector(fallbackDirection);
+  const rawX = Number(rawDirection?.x ?? 0);
+  const rawY = Number(rawDirection?.y ?? 0);
+  const magnitude = Math.hypot(rawX, rawY);
+  if (!Number.isFinite(magnitude) || magnitude <= 0) return null;
+
+  const additionalSpeed =
+    typeof input.additionalSpeed === "number" && Number.isFinite(input.additionalSpeed)
+      ? Math.max(0, Math.min(input.additionalSpeed, 64))
+      : DEFAULT_DASH_ADDITIONAL_SPEED;
+  const duration =
+    typeof input.duration === "number" && Number.isFinite(input.duration)
+      ? Math.max(1, Math.min(input.duration, 1000))
+      : DEFAULT_DASH_DURATION_MS;
+  const cooldown =
+    typeof input.cooldown === "number" && Number.isFinite(input.cooldown)
+      ? Math.max(0, Math.min(input.cooldown, 5000))
+      : DEFAULT_DASH_COOLDOWN_MS;
+
+  return {
+    type: "dash",
+    direction: {
+      x: rawX / magnitude,
+      y: rawY / magnitude,
+    },
+    additionalSpeed,
+    duration,
+    cooldown,
+  };
+};
+
+type ConfigurableTrigger<T> = Omit<Trigger<T>, "start"> & {
+  start(config?: T): Promise<void>;
+};
+
+type MapShakeOptions = {
+  intensity?: number;
+  duration?: number;
+  frequency?: number;
+  direction?: string;
+};
+
 export class RpgClientEngine<T = any> {
   private guiService: RpgGui;
   private webSocket: AbstractWebsocket;
@@ -41,13 +153,19 @@ export class RpgClientEngine<T = any> {
   private selector: HTMLElement;
   public globalConfig: T;
   public sceneComponent: any;
+  public sceneMapComponent: any = BuiltinSceneMap;
   stopProcessingInput = false;
   width = signal("100%");
   height = signal("100%");
-  spritesheets: Map<string, any> = new Map();
+  spritesheets: Map<string | number, any> = new Map();
+  private spritesheetPromises: Map<string | number, Promise<any>> = new Map();
   sounds: Map<string, any> = new Map();
   componentAnimations: any[] = [];
-  private spritesheetResolver?: (id: string) => any | Promise<any>;
+  clientVisuals = new ClientVisualRegistry();
+  projectiles: ProjectileManager;
+  pointer: ClientPointerContext = createClientPointerContext();
+  interactions: RpgClientInteractions = new RpgClientInteractions(this);
+  private spritesheetResolver?: (id: string | number) => any | Promise<any>;
   private soundResolver?: (id: string) => any | Promise<any>;
   particleSettings: {
     emitters: any[]
@@ -61,21 +179,29 @@ export class RpgClientEngine<T = any> {
   playerIdSignal = signal<string | null>(null);
   spriteComponentsBehind = signal<any[]>([]);
   spriteComponentsInFront = signal<any[]>([]);
+  spriteComponents: Map<string, any> = new Map();
+  private eventComponentResolvers = new EventComponentResolverRegistry();
   /** ID of the sprite that the camera should follow. null means follow the current player */
   cameraFollowTargetId = signal<string | null>(null);
   /** Trigger for map shake animation */
-  mapShakeTrigger = trigger();
+  mapShakeTrigger: ConfigurableTrigger<MapShakeOptions> = trigger<MapShakeOptions>();
 
   controlsReady = signal(undefined); 
   gamePause = signal(false);
 
   private predictionEnabled = false;
-  private prediction?: PredictionController<Direction>;
+  private prediction?: PredictionController<RpgMovementInput, Direction>;
   private readonly SERVER_CORRECTION_THRESHOLD = 30;
+  private localMovementAuthority = false;
+  private lastLocalMovementInputAt = 0;
+  private readonly LOCAL_MOVEMENT_AUTHORITY_ACK_GRACE_MS = 250;
   private inputFrameCounter = 0;
   private pendingPredictionFrames: number[] = [];
   private lastClientPhysicsStepAt = 0;
   private frameOffset = 0;
+  private latestServerTick?: number;
+  private latestServerTickAt = 0;
+  private dashLockedUntil = 0;
   // Ping/Pong for RTT measurement
   private rtt: number = 0; // Round-trip time in ms
   private pingInterval: any = null;
@@ -92,17 +218,35 @@ export class RpgClientEngine<T = any> {
   private eventsReceived$ = new BehaviorSubject<boolean>(false);
   private onAfterLoadingSubscription?: any;
   private sceneResetQueued = false;
+  private mapTransitionInProgress = false;
+  private currentMapRoomId?: string;
+  private socketListenersInitialized = false;
+  private clientReadyForMapChanges = false;
+  private pendingMapChanges: any[] = [];
   
   // Store subscriptions and event listeners for cleanup
   private tickSubscriptions: any[] = [];
   private resizeHandler?: () => void;
+  private pointerMoveHandler?: (event: PointerEvent) => void;
+  private pointerUpHandler?: (event: PointerEvent) => void;
+  private pointerCancelHandler?: (event: PointerEvent) => void;
+  private pointerCanvas?: HTMLCanvasElement;
+  private pendingSyncPackets: any[] = [];
   private notificationManager: NotificationManager = new NotificationManager();
+  private i18nService: I18nService;
+  private locale?: string;
 
   constructor(public context) {
     this.webSocket = inject(WebSocketToken);
     this.guiService = inject(RpgGui);
     this.loadMapService = inject(LoadMapToken);
     this.hooks = inject<Hooks>(ModulesToken);
+    this.i18nService = getOrCreateI18nService(context);
+    this.i18nService.addMessages(RpgClientBuiltinI18n, "rpgjs-client", 0);
+    this.projectiles = new ProjectileManager(
+      this.hooks,
+      (projectile) => this.predictProjectileImpact(projectile),
+    );
     this.globalConfig = inject(GlobalConfigToken)
 
     if (!this.globalConfig) {
@@ -123,10 +267,63 @@ export class RpgClientEngine<T = any> {
       component: PrebuiltComponentAnimations.Animation
     })
 
+    this.registerSpriteComponent("rpg:text", TextComponent);
+    this.registerSpriteComponent("rpg:hpBar", BarComponent);
+    this.registerSpriteComponent("rpg:spBar", BarComponent);
+    this.registerSpriteComponent("rpg:bar", BarComponent);
+    this.registerSpriteComponent("rpg:shape", ShapeComponent);
+    this.registerSpriteComponent("rpg:image", ImageComponent);
+
     this.predictionEnabled = (this.globalConfig as any)?.prediction?.enabled !== false;
+    this.localMovementAuthority = this.resolveLocalMovementAuthority();
     this.initializePredictionController();
   }
 
+  private resolveLocalMovementAuthority(): boolean {
+    const predictionConfig = (this.globalConfig as any)?.prediction;
+    const configured =
+      (this.globalConfig as any)?.movementAuthority ??
+      predictionConfig?.movementAuthority ??
+      predictionConfig?.authority ??
+      predictionConfig?.mode;
+
+    if (
+      configured === "server" ||
+      configured === "network" ||
+      configured === false
+    ) {
+      return false;
+    }
+    if (
+      configured === "client" ||
+      configured === "local" ||
+      configured === true
+    ) {
+      return true;
+    }
+
+    return this.webSocket.mode === "standalone";
+  }
+
+  setLocale(locale: string) {
+    this.locale = locale;
+  }
+
+  getLocale(): string {
+    return this.locale || this.i18nService.defaultLocale;
+  }
+
+  t(key: string, params?: I18nParams): string {
+    return this.i18nService.t(key, params, this.getLocale());
+  }
+
+  i18n() {
+    return {
+      locale: this.getLocale(),
+      t: (key: string, params?: I18nParams) => this.t(key, params),
+    };
+  }
+
   /**
    * Assigns a CanvasEngine KeyboardControls instance to the dependency injection context
    * 
@@ -173,6 +370,22 @@ export class RpgClientEngine<T = any> {
     this.sceneMap = new RpgClientMap()
     this.sceneMap.configureClientPrediction(this.predictionEnabled);
     this.sceneMap.loadPhysic();
+    this.resolveSceneMapComponent();
+
+    const saveClient = inject(SaveClientService);
+    saveClient.initialize();
+    this.initListeners();
+    this.guiService._initialize();
+
+    try {
+      await this.webSocket.connection();
+    }
+    catch (error) {
+      this.stopPingPong();
+      await this.callConnectError(error);
+      throw error;
+    }
+
     this.selector = document.body.querySelector("#rpg") as HTMLElement;
 
     const bootstrapOptions = (this.globalConfig as any)?.bootstrapCanvasOptions;
@@ -181,9 +394,11 @@ export class RpgClientEngine<T = any> {
       Canvas,
       bootstrapOptions
     );
+    this.installCanvasResizeGuard(app);
     this.canvasApp = app;
     this.canvasElement = canvasElement;
-    this.renderer = app.renderer as PIXI.Renderer;
+    this.renderer = app.renderer as unknown as PIXI.Renderer;
+    this.setupPointerTracking();
     this.tick = canvasElement?.propObservables?.context['tick'].observable
 
     const inputCheckSubscription = this.tick.subscribe(() => {
@@ -198,17 +413,23 @@ export class RpgClientEngine<T = any> {
 
     this.hooks.callHooks("client-spritesheets-load", this).subscribe();
     this.hooks.callHooks("client-spritesheetResolver-load", this).subscribe();
+    this.flushPendingSyncPackets();
     this.hooks.callHooks("client-sounds-load", this).subscribe();
     this.hooks.callHooks("client-soundResolver-load", this).subscribe();
-    
+
     RpgSound.init(this);
     RpgResource.init(this);
     this.hooks.callHooks("client-gui-load", this).subscribe();
     this.hooks.callHooks("client-particles-load", this).subscribe();
     this.hooks.callHooks("client-componentAnimations-load", this).subscribe();
+    this.hooks.callHooks("client-clientVisuals-load", this).subscribe();
+    this.hooks.callHooks("client-projectiles-load", this).subscribe();
+    this.hooks.callHooks("client-interactions-load", this).subscribe();
     this.hooks.callHooks("client-sprite-load", this).subscribe();
 
     await lastValueFrom(this.hooks.callHooks("client-engine-onStart", this));
+    this.clientReadyForMapChanges = true;
+    this.flushPendingMapChanges();
 
     // wondow is resize
     this.resizeHandler = () => {
@@ -218,6 +439,7 @@ export class RpgClientEngine<T = any> {
 
     const tickSubscription = this.tick.subscribe((tick) => {
       this.stepClientPhysicsTick();
+      this.projectiles.step();
       this.flushPendingPredictedStates();
       this.flushPendingMovePath();
       this.hooks.callHooks("client-engine-onStep", this, tick).subscribe();
@@ -231,13 +453,157 @@ export class RpgClientEngine<T = any> {
     });
     this.tickSubscriptions.push(tickSubscription);
 
-    await this.webSocket.connection(() => {
-      const saveClient = inject(SaveClientService);
-      saveClient.initialize(this.webSocket);
-      this.initListeners()
-      this.guiService._initialize()
-      this.startPingPong();
-    });
+    this.startPingPong();
+  }
+
+  private installCanvasResizeGuard(app: any) {
+    if (!app || typeof app.resize !== "function") return;
+
+    const originalResize = app.resize.bind(app);
+    app.resize = () => {
+      const targetSize = this.readCanvasResizeTargetSize(app);
+      const rendererSize = this.readCanvasRendererSize(app);
+
+      if (
+        targetSize &&
+        rendererSize &&
+        targetSize.width === rendererSize.width &&
+        targetSize.height === rendererSize.height
+      ) {
+        this.cancelCanvasResizeFrame(app);
+        return;
+      }
+
+      originalResize();
+    };
+  }
+
+  private readCanvasResizeTargetSize(app: any): CanvasResizeSize | null {
+    const resizeTarget = app?.resizeTo;
+    if (!resizeTarget || typeof window === "undefined") return null;
+
+    const rawWidth = resizeTarget === window ? window.innerWidth : resizeTarget.clientWidth;
+    const rawHeight = resizeTarget === window ? window.innerHeight : resizeTarget.clientHeight;
+    const width = Math.round(Number(rawWidth));
+    const height = Math.round(Number(rawHeight));
+
+    if (!Number.isFinite(width) || !Number.isFinite(height) || width < 0 || height < 0) return null;
+    return { width, height };
+  }
+
+  private readCanvasRendererSize(app: any): CanvasResizeSize | null {
+    const screen = app?.renderer?.screen;
+    const width = Math.round(Number(screen?.width));
+    const height = Math.round(Number(screen?.height));
+
+    if (!Number.isFinite(width) || !Number.isFinite(height)) return null;
+    return { width, height };
+  }
+
+  private cancelCanvasResizeFrame(app: any) {
+    if (typeof app?._cancelResize === "function") {
+      app._cancelResize();
+    }
+  }
+
+  private resolveSceneMapComponent() {
+    const components = this.hooks.getHookFunctions("client-sceneMap-component");
+    const component = components[components.length - 1];
+    if (component) {
+      this.sceneMapComponent = component;
+    }
+  }
+
+  private setupPointerTracking() {
+    const renderer = this.renderer as any;
+    const canvas = renderer?.canvas ?? renderer?.view ?? (this.canvasApp as any)?.canvas;
+
+    if (!canvas || typeof canvas.addEventListener !== "function") {
+      return;
+    }
+
+    this.pointerCanvas = canvas;
+    const updatePointer = (event: PointerEvent) => {
+      const rect = canvas.getBoundingClientRect();
+      const screen = {
+        x: event.clientX - rect.left,
+        y: event.clientY - rect.top,
+      };
+      const viewport = this.findViewportInstance();
+      let world = screen;
+
+      if (viewport && typeof viewport.toWorld === "function") {
+        const point = viewport.toWorld(screen.x, screen.y);
+        world = { x: Number(point.x), y: Number(point.y) };
+      } else if (viewport && typeof viewport.toLocal === "function") {
+        const point = viewport.toLocal(screen);
+        world = { x: Number(point.x), y: Number(point.y) };
+      }
+
+      this.pointer.update(screen, world);
+    };
+
+    this.pointerMoveHandler = (event: PointerEvent) => {
+      updatePointer(event);
+      this.interactions.handlePointerMove(event);
+    };
+    this.pointerUpHandler = (event: PointerEvent) => {
+      updatePointer(event);
+      this.interactions.handlePointerUp(event);
+    };
+    this.pointerCancelHandler = (event: PointerEvent) => {
+      updatePointer(event);
+      this.interactions.cancelDrag(event);
+    };
+
+    canvas.addEventListener("pointermove", this.pointerMoveHandler);
+    canvas.addEventListener("pointerdown", this.pointerMoveHandler);
+    canvas.addEventListener("pointerup", this.pointerUpHandler);
+    canvas.addEventListener("pointercancel", this.pointerCancelHandler);
+    canvas.addEventListener("pointerleave", this.pointerCancelHandler);
+  }
+
+  updatePointerFromInteractionEvent(event: any): void {
+    const global = event?.global ?? event?.data?.global;
+
+    if (!global) {
+      this.pointer.updateFromEvent(event);
+      return;
+    }
+
+    const screen = {
+      x: Number(global.x),
+      y: Number(global.y),
+    };
+    if (!Number.isFinite(screen.x) || !Number.isFinite(screen.y)) {
+      this.pointer.updateFromEvent(event);
+      return;
+    }
+
+    const viewport = this.findViewportInstance();
+    if (viewport && typeof viewport.toWorld === "function") {
+      const point = viewport.toWorld(screen.x, screen.y);
+      this.pointer.update(screen, { x: Number(point.x), y: Number(point.y) });
+      return;
+    }
+
+    this.pointer.update(screen);
+  }
+
+  private findViewportInstance(): any {
+    const find = (node: any): any => {
+      if (!node) return undefined;
+      if (typeof node?.toWorld === "function" || node?.constructor?.name === "Viewport") {
+        return node;
+      }
+      for (const child of node.children ?? []) {
+        const viewport = find(child);
+        if (viewport) return viewport;
+      }
+      return undefined;
+    };
+
+    return find((this.canvasApp as any)?.stage);
   }
 
   private prepareSyncPayload(data: any): any {
@@ -247,8 +613,8 @@ export class RpgClientEngine<T = any> {
 
     const myId = this.playerIdSignal();
     const players = payload.players;
-    const shouldMaskLocalPosition =
-      this.predictionEnabled && !!this.prediction?.hasPendingInputs();
+    const localPatch = myId && players ? players[myId] : undefined;
+    const shouldMaskLocalPosition = this.shouldPreserveLocalPlayerPosition(localPatch);
     if (shouldMaskLocalPosition && myId && players && players[myId]) {
       const localPatch = { ...players[myId] };
       delete localPatch.x;
@@ -264,6 +630,31 @@ export class RpgClientEngine<T = any> {
     return payload;
   }
 
+  private shouldPreserveLocalPlayerPosition(localPatch?: any): boolean {
+    if (!localPatch) {
+      return false;
+    }
+    if (this.predictionEnabled && !!this.prediction?.hasPendingInputs()) {
+      return true;
+    }
+    return this.shouldKeepLocalPlayerMovement();
+  }
+
+  private shouldKeepLocalPlayerMovement(): boolean {
+    if (!this.localMovementAuthority || this.mapTransitionInProgress) {
+      return false;
+    }
+    const myId = this.playerIdSignal();
+    const player = myId ? this.sceneMap?.players?.()?.[myId] : undefined;
+    if (!player) {
+      return false;
+    }
+    if (this.prediction?.hasPendingInputs()) {
+      return true;
+    }
+    return Date.now() - this.lastLocalMovementInputAt <= this.LOCAL_MOVEMENT_AUTHORITY_ACK_GRACE_MS;
+  }
+
   private normalizeAckWithSyncState(
     ack: { frame: number; serverTick?: number; x?: number; y?: number; direction?: Direction },
     syncData: any,
@@ -287,52 +678,15 @@ export class RpgClientEngine<T = any> {
   }
 
   private initListeners() {
-    this.webSocket.on("sync", (data) => {
-      if (data.pId) {
-        this.playerIdSignal.set(data.pId);
-        // Signal that player ID was received
-        this.playerIdReceived$.next(true);
-      }
+    if (this.socketListenersInitialized) return;
+    this.socketListenersInitialized = true;
 
-      if (this.sceneResetQueued) {
-        this.sceneMap.reset();
-        this.sceneMap.loadPhysic();
-        this.sceneResetQueued = false;
-      }
-
-      // Apply client-side prediction filtering and server reconciliation
-      this.hooks.callHooks("client-sceneMap-onChanges", this.sceneMap, { partial: data }).subscribe();
-
-      const ack = data?.ack;
-      const normalizedAck =
-        ack && typeof ack.frame === "number"
-          ? this.normalizeAckWithSyncState(ack, data)
-          : undefined;
-      const payload = this.prepareSyncPayload(data);
-      load(this.sceneMap, payload, true);
-
-      if (normalizedAck) {
-        this.applyServerAck(normalizedAck);
-      }
-
-      for (const playerId in payload.players ?? {}) {
-        const player = payload.players[playerId]
-        if (!player._param) continue
-        for (const param in player._param) {
-         this.sceneMap.players()[playerId]._param()[param] = player._param[param]
-        }
-      }
-      
-      // Check if players and events are present in sync data
-      const players = payload.players || this.sceneMap.players();
-      if (players && Object.keys(players).length > 0) {
-        this.playersReceived$.next(true);
-      }
-      
-      const events = payload.events || this.sceneMap.events();
-      if (events !== undefined) {
-        this.eventsReceived$.next(true);
+    this.webSocket.on("sync", (data) => {
+      if (!this.tick) {
+        this.pendingSyncPackets.push(data);
+        return;
       }
+      this.applySyncPacket(data);
     });
 
     // Handle pong responses for RTT measurement
@@ -344,6 +698,7 @@ export class RpgClientEngine<T = any> {
       // This helps us estimate which server tick corresponds to each client input frame
       const estimatedTicksInFlight = Math.floor(this.rtt / 2 / (1000 / 60)); // Estimate ticks during half RTT
       const estimatedServerTickNow = data.serverTick + estimatedTicksInFlight;
+      this.updateServerTickEstimate(estimatedServerTickNow, now);
 
       // Update frame offset (only if we have inputs to calibrate with)
       if (this.inputFrameCounter > 0) {
@@ -354,11 +709,11 @@ export class RpgClientEngine<T = any> {
     });
 
     this.webSocket.on("changeMap", (data) => {
-      this.sceneResetQueued = true;
-      // Reset camera follow to default (follow current player) when changing maps
-      this.cameraFollowTargetId.set(null);
-      const transferToken = typeof data?.transferToken === "string" ? data.transferToken : undefined;
-      this.loadScene(data.mapId, transferToken);
+      if (!this.clientReadyForMapChanges) {
+        this.pendingMapChanges.push(data);
+        return;
+      }
+      this.handleChangeMap(data);
     });
 
     this.webSocket.on("showComponentAnimation", (data) => {
@@ -370,19 +725,63 @@ export class RpgClientEngine<T = any> {
       this.getComponentAnimation(id).displayEffect(params, player || position)
     });
 
+    this.webSocket.on("clientVisual", (data) => {
+      this.playClientVisual(data);
+    });
+
+    this.webSocket.on("projectile:spawnBatch", (data) => {
+      if (!this.shouldProcessProjectilePacket(data)) return;
+      this.projectiles.spawnBatch(data?.projectiles ?? [], {
+        mapId: data?.mapId,
+        currentServerTick: this.estimateServerTick(),
+        tickDurationMs: this.getPhysicsTickDurationMs(),
+      });
+    });
+
+    this.webSocket.on("projectile:impactBatch", (data) => {
+      if (!this.shouldProcessProjectilePacket(data)) return;
+      this.projectiles.impactBatch(data?.impacts ?? [], {
+        mapId: data?.mapId,
+      });
+    });
+
+    this.webSocket.on("projectile:destroyBatch", (data) => {
+      if (!this.shouldProcessProjectilePacket(data)) return;
+      this.projectiles.destroyBatch(data?.projectiles ?? [], {
+        mapId: data?.mapId,
+      });
+    });
+
+    this.webSocket.on("projectile:clear", (data) => {
+      if (!this.shouldProcessProjectilePacket(data)) return;
+      this.projectiles.clear();
+    });
+
     this.webSocket.on("notification", (data) => {
       this.notificationManager.add(data);
     });
 
-     this.webSocket.on("setAnimation", (data) => {    
-      const { animationName, nbTimes, object, graphic } = data;
-       const player = this.sceneMap.getObjectById(object);
-       if (graphic !== undefined) {
-         player.setAnimation(animationName, graphic, nbTimes);
-       } else {
-         player.setAnimation(animationName, nbTimes);
-       }
-     })
+    this.webSocket.on("setAnimation", (data) => {
+      const {
+        animationName,
+        nbTimes,
+        object,
+        graphic,
+        restoreAnimationName,
+        restoreGraphics,
+      } = data;
+      const player = object ? this.sceneMap.getObjectById(object) : undefined;
+      if (!player) return;
+      const restoreOptions = {
+        restoreAnimationName,
+        restoreGraphics,
+      };
+      if (graphic !== undefined) {
+        player.setAnimation(animationName, graphic, nbTimes, restoreOptions);
+      } else {
+        player.setAnimation(animationName, nbTimes, restoreOptions);
+      }
+    })
 
     this.webSocket.on("playSound", (data) => {
       const { soundId, volume, loop } = data;
@@ -413,7 +812,7 @@ export class RpgClientEngine<T = any> {
 
     this.webSocket.on("shakeMap", (data) => {
       const { intensity, duration, frequency, direction } = data || {};
-      (this.mapShakeTrigger as any).start({
+      this.mapShakeTrigger.start({
         intensity,
         duration,
         frequency,
@@ -447,6 +846,14 @@ export class RpgClientEngine<T = any> {
       });
     });
 
+    this.webSocket.on("lightingState", (data) => {
+      const raw = (data && typeof data === "object" && "value" in data)
+        ? (data as any).value
+        : data;
+
+      this.sceneMap.lightingState.set(normalizeLightingState(raw));
+    });
+
     this.webSocket.on('open', () => {
       this.hooks.callHooks("client-engine-onConnected", this, this.socket).subscribe();
       // Start ping/pong for synchronization
@@ -460,10 +867,115 @@ export class RpgClientEngine<T = any> {
     })
 
     this.webSocket.on('error', (error) => {
-      this.hooks.callHooks("client-engine-onConnectError", this, error, this.socket).subscribe();
+      void this.callConnectError(error);
     })
   }
 
+  private beginMapTransfer(nextMapId?: string) {
+    this.mapTransitionInProgress = true;
+    this.currentMapRoomId = nextMapId;
+    this.sceneResetQueued = false;
+    this.clearClientPredictionStates();
+    this.sceneMap.weatherState.set(null);
+    this.sceneMap.lightingState.set(null);
+    this.sceneMap.clearLightSpots();
+    this.clearComponentAnimations();
+    this.projectiles.setMapId(nextMapId);
+    this.cameraFollowTargetId.set(null);
+    this.sceneMap.reset();
+    this.sceneMap.loadPhysic();
+  }
+
+  private clearComponentAnimations() {
+    this.componentAnimations.forEach((componentAnimation) => {
+      componentAnimation.instance?.clear?.();
+    });
+  }
+
+  private shouldProcessProjectilePacket(data: any): boolean {
+    if (this.mapTransitionInProgress) return false;
+    const packetMapId = normalizeRoomMapId(
+      typeof data?.mapId === "string" ? data.mapId : undefined,
+    );
+    const currentMapId = normalizeRoomMapId(this.currentMapRoomId);
+    return !packetMapId || !currentMapId || packetMapId === currentMapId;
+  }
+
+  private async callConnectError(error: any) {
+    await lastValueFrom(this.hooks.callHooks("client-engine-onConnectError", this, error, this.socket));
+  }
+
+  private flushPendingSyncPackets() {
+    const packets = this.pendingSyncPackets;
+    this.pendingSyncPackets = [];
+    packets.forEach((packet) => this.applySyncPacket(packet));
+  }
+
+  private flushPendingMapChanges() {
+    const packets = this.pendingMapChanges;
+    this.pendingMapChanges = [];
+    packets.forEach((packet) => this.handleChangeMap(packet));
+  }
+
+  private handleChangeMap(data: any) {
+    const nextMapId = typeof data?.mapId === "string" ? data.mapId : undefined;
+    this.beginMapTransfer(nextMapId);
+    const transferToken = typeof data?.transferToken === "string" ? data.transferToken : undefined;
+    this.loadScene(data.mapId, transferToken);
+  }
+
+  private applySyncPacket(data: any) {
+    if (data.pId) {
+      this.playerIdSignal.set(data.pId);
+      // Signal that player ID was received
+      this.playerIdReceived$.next(true);
+    }
+
+    if (this.sceneResetQueued) {
+      const weatherState = this.sceneMap.weatherState();
+      const lightingState = this.sceneMap.lightingState();
+      this.sceneMap.reset();
+      this.sceneMap.weatherState.set(weatherState);
+      this.sceneMap.lightingState.set(lightingState);
+      this.sceneMap.loadPhysic();
+      this.sceneResetQueued = false;
+    }
+
+    // Apply client-side prediction filtering and server reconciliation
+    this.hooks.callHooks("client-sceneMap-onChanges", this.sceneMap, { partial: data }).subscribe();
+
+    const ack = data?.ack;
+    const normalizedAck =
+      ack && typeof ack.frame === "number"
+        ? this.normalizeAckWithSyncState(ack, data)
+        : undefined;
+    const payload = this.prepareSyncPayload(data);
+    load(this.sceneMap, payload, true);
+
+    if (normalizedAck) {
+      this.applyServerAck(normalizedAck);
+    }
+
+    for (const playerId in payload.players ?? {}) {
+      const player = payload.players[playerId]
+      if (!player._param) continue
+      for (const param in player._param) {
+       this.sceneMap.players()[playerId]._param()[param] = player._param[param]
+      }
+    }
+
+    // Check if players and events are present in sync data
+    const players = payload.players || this.sceneMap.players();
+    if (players && Object.keys(players).length > 0) {
+      this.playersReceived$.next(true);
+    }
+
+    const events = payload.events || this.sceneMap.events();
+    if (events !== undefined) {
+      this.eventsReceived$.next(true);
+    }
+  }
+
   /**
    * Start periodic ping/pong for client-server synchronization
    * 
@@ -560,13 +1072,22 @@ export class RpgClientEngine<T = any> {
       room: mapId,
       query: transferToken ? { transferToken } : undefined,
     })
-    await this.webSocket.reconnect(() => {
-      const saveClient = inject(SaveClientService);
-      saveClient.initialize(this.webSocket);
-      this.initListeners()
-      this.guiService._initialize()
-    })
+    try {
+      await this.webSocket.reconnect()
+    }
+    catch (error) {
+      this.mapTransitionInProgress = false;
+      this.stopPingPong();
+      await this.callConnectError(error);
+      throw error;
+    }
     const res = await this.loadMapService.load(mapId)
+    const loadedLighting = typeof res?.lighting !== "undefined"
+      ? res.lighting
+      : res?.data?.lighting;
+    if (typeof loadedLighting !== "undefined") {
+      this.sceneMap.lightingState.set(normalizeLightingState(loadedLighting));
+    }
     this.sceneMap.data.set(res)
     
     // Check if playerId is already present
@@ -587,6 +1108,8 @@ export class RpgClientEngine<T = any> {
     
     // Signal that map loading is completed (this should be last to ensure other checks are done)
     this.mapLoadCompleted$.next(true);
+    this.currentMapRoomId = mapId;
+    this.mapTransitionInProgress = false;
     this.sceneMap.configureClientPrediction(this.predictionEnabled);
     this.sceneMap.loadPhysic()
   }
@@ -623,7 +1146,7 @@ export class RpgClientEngine<T = any> {
    * });
    * ```
    */
-  setSpritesheetResolver(resolver: (id: string) => any | Promise<any>): void {
+  setSpritesheetResolver(resolver: (id: string | number) => any | Promise<any>): void {
     this.spritesheetResolver = resolver;
   }
 
@@ -634,7 +1157,7 @@ export class RpgClientEngine<T = any> {
    * If not found and a resolver is set, it calls the resolver to create the spritesheet.
    * The resolved spritesheet is automatically cached for future use.
    * 
-   * @param id - The spritesheet ID to retrieve
+   * @param id - The spritesheet ID or legacy tile ID to retrieve
    * @returns The spritesheet if found or created, or undefined if not found and no resolver
    * @returns Promise<any> if the resolver is asynchronous
    * 
@@ -647,7 +1170,7 @@ export class RpgClientEngine<T = any> {
    * const spritesheet = await engine.getSpriteSheet('dynamic-sprite');
    * ```
    */
-  getSpriteSheet(id: string): any | Promise<any> {
+  getSpriteSheet(id: string | number): any | Promise<any> {
     // Check cache first
     if (this.spritesheets.has(id)) {
       return this.spritesheets.get(id);
@@ -655,17 +1178,29 @@ export class RpgClientEngine<T = any> {
 
     // If not in cache and resolver exists, use it
     if (this.spritesheetResolver) {
+      if (this.spritesheetPromises.has(id)) {
+        return this.spritesheetPromises.get(id);
+      }
+
       const result = this.spritesheetResolver(id);
 
       // Check if result is a Promise
       if (result instanceof Promise) {
-        return result.then((spritesheet) => {
-          if (spritesheet) {
-            // Cache the resolved spritesheet
-            this.spritesheets.set(id, spritesheet);
-          }
-          return spritesheet;
-        });
+        const promise = result
+          .then((spritesheet) => {
+            if (spritesheet) {
+              // Cache the resolved spritesheet
+              this.spritesheets.set(id, spritesheet);
+            }
+            this.spritesheetPromises.delete(id);
+            return spritesheet;
+          })
+          .catch((error) => {
+            this.spritesheetPromises.delete(id);
+            throw error;
+          });
+        this.spritesheetPromises.set(id, promise);
+        return promise;
       } else {
         // Synchronous result
         if (result) {
@@ -1081,6 +1616,104 @@ export class RpgClientEngine<T = any> {
     return component
   }
 
+  /**
+   * Register a reusable sprite component that can be addressed by the server.
+   *
+   * Server-side component definitions only carry the component id and
+   * serializable props. The client registry maps that id to the CanvasEngine
+   * component that performs the actual rendering.
+   *
+   * @param id - Stable component id used by server component definitions
+   * @param component - CanvasEngine component to render for this id
+   * @returns The registered component
+   *
+   * @example
+   * ```ts
+   * engine.registerSpriteComponent('guildBadge', GuildBadgeComponent);
+   * ```
+   */
+  registerSpriteComponent(id: string, component: any) {
+    this.spriteComponents.set(id, component);
+    return component;
+  }
+
+  /**
+   * Get a reusable sprite component by id.
+   *
+   * @param id - Component id registered on the client
+   * @returns The CanvasEngine component, or undefined when missing
+   */
+  getSpriteComponent(id: string) {
+    return this.spriteComponents.get(id);
+  }
+
+  /**
+   * Register a custom event component resolver.
+   *
+   * The last resolver returning a component wins. This lets later modules
+   * override earlier defaults without replacing the whole map scene.
+   *
+   * @param resolver - Function receiving the synced event object
+   * @returns The registered resolver
+   */
+  addEventComponentResolver(resolver: EventComponentResolver) {
+    return this.eventComponentResolvers.add(resolver);
+  }
+
+  /**
+   * Resolve the custom CanvasEngine component for an event, if any.
+   *
+   * @param event - Synced client event object
+   * @returns The component/config returned by the last matching resolver
+   */
+  resolveEventComponent(event: RpgClientEvent): EventComponentConfig | null {
+    return this.eventComponentResolvers.resolve(event);
+  }
+
+  registerProjectileComponent(type: string, component: any) {
+    return this.projectiles.register(type, component);
+  }
+
+  getProjectileComponent(type: string) {
+    return this.projectiles.get(type);
+  }
+
+  /**
+   * Register a named client visual macro.
+   *
+   * Client visuals are small client-side functions that group existing visual
+   * primitives such as flash, sound, component animations, sprite animation, or
+   * map shake. The server sends only the visual name and a serializable payload.
+   *
+   * @param name - Stable visual name sent by the server
+   * @param handler - Client-side visual handler
+   * @returns The registered handler
+   */
+  registerClientVisual(name: string, handler: ClientVisualHandler) {
+    return this.clientVisuals.register(name, handler);
+  }
+
+  /**
+   * Register several named client visual macros.
+   *
+   * @param visuals - Map of visual names to client-side handlers
+   */
+  registerClientVisuals(visuals: ClientVisualMap) {
+    this.clientVisuals.registerMany(visuals);
+  }
+
+  /**
+   * Play a registered client visual locally.
+   *
+   * This is also used by the websocket listener when the server calls
+   * `player.clientVisual()` or `map.clientVisual()`.
+   *
+   * @param packet - Visual name and serializable payload
+   */
+  playClientVisual(packet: ClientVisualPacket) {
+    return this.clientVisuals.play(packet, this);
+  }
+
   /**
    * Add a component animation to the engine
    * 
@@ -1164,21 +1797,59 @@ export class RpgClientEngine<T = any> {
    *   duration: 1000,
    *   onFinish: () => console.log('Fade complete')
    * });
+   *
+   * // Wait until the transition component calls onFinish
+   * await engine.startTransition('fade', { duration: 1000 });
    * ```
    */
-  startTransition(id: string, props: any = {}) {
+  startTransition(id: string, props: any = {}): Promise<void> {
     if (!this.guiService.exists(id)) {
       throw new Error(`Transition with id ${id} not found. Make sure to add it using engine.addTransition() or in your module's transitions property.`);
     }
-    this.guiService.display(id, props);
+    return new Promise<void>((resolve) => {
+      let finished = false;
+      const finish = (data?: any) => {
+        if (finished) return;
+        finished = true;
+        props?.onFinish?.(data);
+        resolve();
+      };
+
+      this.guiService.display(id, {
+        ...props,
+        onFinish: finish,
+      });
+    });
   }
 
-  async processInput({ input }: { input: Direction }) {
+  async processInput({ input }: { input: RpgMovementInput }) {
+    if (this.stopProcessingInput) return;
+
+    const currentPlayer = this.sceneMap.getCurrentPlayer() as any;
+    const canMove =
+      !currentPlayer ||
+      getCanMoveValue(currentPlayer);
+    if (!canMove) {
+      this.interruptCurrentPlayerMovement(currentPlayer);
+      return;
+    }
+
     const timestamp = Date.now();
+    const movementInput = isDashInput(input)
+      ? normalizeDashInput(input, currentPlayer?.direction?.())
+      : input;
+    if (!movementInput) return;
+    if (isDashInput(movementInput)) {
+      const cooldown = movementInput.cooldown ?? DEFAULT_DASH_COOLDOWN_MS;
+      if (timestamp < this.dashLockedUntil) return;
+      this.dashLockedUntil = timestamp + cooldown;
+    }
+    this.lastLocalMovementInputAt = timestamp;
+
     let frame: number;
     let tick: number;
     if (this.predictionEnabled && this.prediction) {
-      const meta = this.prediction.recordInput(input, timestamp);
+      const meta = this.prediction.recordInput(movementInput, timestamp);
       frame = meta.frame;
       tick = meta.tick;
     } else {
@@ -1186,13 +1857,11 @@ export class RpgClientEngine<T = any> {
       tick = this.getPhysicsTick();
     }
     this.inputFrameCounter = frame;
-    this.hooks.callHooks("client-engine-onInput", this, { input, playerId: this.playerId }).subscribe();
+    this.hooks.callHooks("client-engine-onInput", this, { input: movementInput, playerId: this.playerId }).subscribe();
 
-    const currentPlayer = this.sceneMap.getCurrentPlayer();
     const bodyReady = this.ensureCurrentPlayerBody();
     if (currentPlayer && bodyReady) {
-      currentPlayer.changeDirection(input);
-      (this.sceneMap as any).moveBody(currentPlayer, input);
+      this.applyPredictedMovementInput(currentPlayer, movementInput);
       if (this.predictionEnabled && this.prediction) {
         this.pendingPredictionFrames.push(frame);
         if (this.pendingPredictionFrames.length > 240) {
@@ -1201,14 +1870,42 @@ export class RpgClientEngine<T = any> {
       }
     }
 
-    this.emitMovePacket(input, frame, tick, timestamp, true);
-    this.lastInputTime = Date.now();
+    this.emitMovePacket(movementInput, frame, tick, timestamp, true);
+    this.lastInputTime = isDashInput(movementInput)
+      ? Date.now() + (movementInput.duration ?? DEFAULT_DASH_DURATION_MS)
+      : Date.now();
+  }
+
+  async processDash(input: Partial<RpgDashInput> = {}) {
+    const currentPlayer = this.sceneMap.getCurrentPlayer() as any;
+    const fallbackDirection =
+      typeof currentPlayer?.direction === "function"
+        ? currentPlayer.direction()
+        : currentPlayer?.direction;
+    const dashInput = normalizeDashInput(input, fallbackDirection);
+    if (!dashInput) return;
+    await this.processInput({ input: dashInput });
   }
 
-  processAction({ action }: { action: number }) {
+  processAction(action: RpgActionName, data?: any): void;
+  processAction(action: RpgActionInput): void;
+  processAction(action: RpgActionName | RpgActionInput, data?: any): void {
     if (this.stopProcessingInput) return;
-    this.hooks.callHooks("client-engine-onInput", this, { input: 'action', playerId: this.playerId }).subscribe();
-    this.webSocket.emit('action', { action })
+    const currentPlayer = this.sceneMap.getCurrentPlayer() as any;
+    const canMove =
+      !currentPlayer ||
+      getCanMoveValue(currentPlayer);
+    if (!canMove) return;
+
+    const payload = normalizeActionInput(action as any, data);
+
+    this.hooks.callHooks("client-engine-onInput", this, {
+      input: payload.action,
+      action: payload.action,
+      data: payload.data,
+      playerId: this.playerId,
+    }).subscribe();
+    this.webSocket.emit('action', payload)
   }
 
   get PIXI() {
@@ -1227,8 +1924,76 @@ export class RpgClientEngine<T = any> {
     return this.sceneMap
   }
 
+  getObjectById(id: string) {
+    return this.sceneMap?.getObjectById(id);
+  }
+
   private getPhysicsTick(): number {
-    return this.sceneMap?.getTick?.() ?? 0;
+    return (this.sceneMap as any)?.getTick?.() ?? 0;
+  }
+
+  private getPhysicsTickDurationMs(): number {
+    const timeStep = (this.sceneMap as any)?.physic?.getWorld?.()?.getTimeStep?.();
+    return typeof timeStep === "number" && Number.isFinite(timeStep) && timeStep > 0
+      ? timeStep * 1000
+      : 1000 / 60;
+  }
+
+  private updateServerTickEstimate(serverTick: number | undefined, now = Date.now()): void {
+    if (typeof serverTick !== "number" || !Number.isFinite(serverTick)) {
+      return;
+    }
+    this.latestServerTick = serverTick;
+    this.latestServerTickAt = now;
+  }
+
+  private estimateServerTick(now = Date.now()): number | undefined {
+    if (typeof this.latestServerTick !== "number" || this.latestServerTickAt <= 0) {
+      return undefined;
+    }
+    const elapsedTicks = Math.max(0, (now - this.latestServerTickAt) / this.getPhysicsTickDurationMs());
+    return this.latestServerTick + elapsedTicks;
+  }
+
+  private predictProjectileImpact(projectile: ClientProjectileSpawn): ClientProjectileImpact | null {
+    if (projectile.predictImpact === false) {
+      return null;
+    }
+    const sceneMap = this.sceneMap as any;
+    if (!sceneMap?.physic || !Number.isFinite(projectile.range) || projectile.range <= 0) {
+      return null;
+    }
+    const origin = projectile.origin;
+    const direction = projectile.direction;
+    if (
+      !origin ||
+      !direction ||
+      !Number.isFinite(origin.x) ||
+      !Number.isFinite(origin.y) ||
+      !Number.isFinite(direction.x) ||
+      !Number.isFinite(direction.y) ||
+      (direction.x === 0 && direction.y === 0)
+    ) {
+      return null;
+    }
+
+    const hit = sceneMap.physic.raycast(
+      new Vector2(origin.x, origin.y),
+      new Vector2(direction.x, direction.y),
+      projectile.range,
+      projectile.collisionMask,
+      (entity) => projectile.ignoreOwner === false || !projectile.ownerId || entity.uuid !== projectile.ownerId,
+    );
+    if (!hit) {
+      return null;
+    }
+    return {
+      id: projectile.id,
+      targetId: hit.entity.uuid,
+      x: hit.point.x,
+      y: hit.point.y,
+      distance: hit.distance,
+    };
   }
 
   private ensureCurrentPlayerBody(): boolean {
@@ -1295,7 +2060,7 @@ export class RpgClientEngine<T = any> {
         input: entry.direction,
         x: state.x,
         y: state.y,
-        direction: state.direction ?? entry.direction,
+        direction: state.direction ?? resolveMoveDirection(entry.direction),
       });
     }
     if (trajectory.length > this.MAX_MOVE_TRAJECTORY_POINTS) {
@@ -1305,7 +2070,7 @@ export class RpgClientEngine<T = any> {
   }
 
   private emitMovePacket(
-    input: Direction,
+    input: RpgMovementInput,
     frame: number,
     tick: number,
     timestamp: number,
@@ -1337,6 +2102,14 @@ export class RpgClientEngine<T = any> {
     if (!this.predictionEnabled || !this.prediction) {
       return;
     }
+    const player = this.sceneMap?.getCurrentPlayer?.() as any;
+    if (
+      player &&
+      !getCanMoveValue(player)
+    ) {
+      this.interruptCurrentPlayerMovement(player);
+      return;
+    }
     const pendingInputs = this.prediction.getPendingInputs();
     if (pendingInputs.length === 0) {
       return;
@@ -1352,6 +2125,22 @@ export class RpgClientEngine<T = any> {
     this.emitMovePacket(latest.direction, latest.frame, latest.tick, now, false);
   }
 
+  private applyPredictedMovementInput(
+    player: any,
+    input: RpgMovementInput
+  ): boolean {
+    if (isDashInput(input)) {
+      const direction = vectorToDirection(input.direction);
+      player.changeDirection(direction);
+      return Boolean((this.sceneMap as any).dashBody?.(player, input));
+    }
+
+    const direction = resolveMoveDirection(input);
+    if (!direction) return false;
+    player.changeDirection(direction);
+    return Boolean((this.sceneMap as any).moveBody?.(player, direction));
+  }
+
   private getLocalPlayerState(): PredictionState<Direction> {
     const currentPlayer = this.sceneMap?.getCurrentPlayer();
     if (!currentPlayer) {
@@ -1395,7 +2184,7 @@ export class RpgClientEngine<T = any> {
         ? configuredMaxEntries
         : Math.max(600, Math.ceil(historyTtlMs / 16) + 120);
     this.sceneMap?.configureClientPrediction?.(true);
-    this.prediction = new PredictionController<Direction>({
+    this.prediction = new PredictionController<RpgMovementInput, Direction>({
       correctionThreshold: (this.globalConfig as any)?.prediction?.correctionThreshold ?? this.SERVER_CORRECTION_THRESHOLD,
       historyTtlMs,
       maxHistoryEntries,
@@ -1475,6 +2264,34 @@ export class RpgClientEngine<T = any> {
     this.lastMovePathSentFrame = 0;
   }
 
+  /**
+   * Stop local movement immediately and discard pending predicted movement.
+   *
+   * Use this before a blocking action such as an A-RPG attack, dialog, dash
+   * startup, or any client-side state where already buffered movement inputs
+   * must not be replayed after server reconciliation.
+   *
+   * @param player - Player object to stop. Defaults to the current player.
+   * @returns `true` when a player was found and interrupted.
+   *
+   * @example
+   * ```ts
+   * engine.interruptCurrentPlayerMovement();
+   * ```
+   */
+  interruptCurrentPlayerMovement(player: any = this.sceneMap?.getCurrentPlayer?.()): boolean {
+    if (!player) {
+      return false;
+    }
+    (this.sceneMap as any)?.stopMovement?.(player);
+    this.prediction?.clearPendingInputs();
+    this.pendingPredictionFrames = [];
+    this.lastInputTime = 0;
+    this.lastMovePathSentAt = Date.now();
+    this.lastMovePathSentFrame = this.inputFrameCounter;
+    return true;
+  }
+
   /**
    * Trigger a flash animation on a sprite
    * 
@@ -1542,12 +2359,14 @@ export class RpgClientEngine<T = any> {
   }
 
   private applyServerAck(ack: { frame: number; serverTick?: number; x?: number; y?: number; direction?: Direction }) {
+    this.updateServerTickEstimate(ack.serverTick);
+    const keepLocalMovement = this.shouldKeepLocalPlayerMovement();
     if (this.predictionEnabled && this.prediction) {
       const result = this.prediction.applyServerAck({
         frame: ack.frame,
         serverTick: ack.serverTick,
         state:
-          typeof ack.x === "number" && typeof ack.y === "number"
+          !keepLocalMovement && typeof ack.x === "number" && typeof ack.y === "number"
             ? { x: ack.x, y: ack.y, direction: ack.direction }
             : undefined,
       });
@@ -1560,7 +2379,10 @@ export class RpgClientEngine<T = any> {
     if (typeof ack.x !== "number" || typeof ack.y !== "number") {
       return;
     }
-    const player = this.getCurrentPlayer();
+    if (keepLocalMovement) {
+      return;
+    }
+    const player = this.getCurrentPlayer() as any;
     const myId = this.playerIdSignal();
     if (!player || !myId) {
       return;
@@ -1581,12 +2403,16 @@ export class RpgClientEngine<T = any> {
 
   private reconcilePrediction(
     authoritativeState: PredictionState<Direction>,
-    pendingInputs: PredictionHistoryEntry<Direction>[],
+    pendingInputs: PredictionHistoryEntry<RpgMovementInput, Direction>[],
   ): void {
-    const player = this.getCurrentPlayer();
+    const player = this.getCurrentPlayer() as any;
     if (!player) {
       return;
     }
+    if (!getCanMoveValue(player)) {
+      this.interruptCurrentPlayerMovement(player);
+      return;
+    }
 
     (this.sceneMap as any).stopMovement(player);
     this.applyAuthoritativeState(authoritativeState);
@@ -1599,7 +2425,7 @@ export class RpgClientEngine<T = any> {
     const replayInputs = pendingInputs.slice(-600);
     for (const entry of replayInputs) {
       if (!entry?.direction) continue;
-      (this.sceneMap as any).moveBody(player, entry.direction);
+      this.applyPredictedMovementInput(player, entry.direction);
       this.sceneMap.stepPredictionTick();
       this.prediction?.attachPredictedState(entry.frame, this.getLocalPlayerState());
     }
@@ -1699,6 +2525,22 @@ export class RpgClientEngine<T = any> {
         this.resizeHandler = undefined;
       }
 
+      if (this.pointerMoveHandler && this.pointerCanvas) {
+        this.pointerCanvas.removeEventListener('pointermove', this.pointerMoveHandler);
+        this.pointerCanvas.removeEventListener('pointerdown', this.pointerMoveHandler);
+        if (this.pointerUpHandler) {
+          this.pointerCanvas.removeEventListener('pointerup', this.pointerUpHandler);
+        }
+        if (this.pointerCancelHandler) {
+          this.pointerCanvas.removeEventListener('pointercancel', this.pointerCancelHandler);
+          this.pointerCanvas.removeEventListener('pointerleave', this.pointerCancelHandler);
+        }
+        this.pointerMoveHandler = undefined;
+        this.pointerUpHandler = undefined;
+        this.pointerCancelHandler = undefined;
+        this.pointerCanvas = undefined;
+      }
+
       // Destroy PIXI app and renderer if they exist
       // Destroy the app first, which will destroy the renderer
       // Store renderer reference before destroying app (since app.destroy() will destroy the renderer)
@@ -1772,6 +2614,7 @@ export class RpgClientEngine<T = any> {
       this.cameraFollowTargetId.set(null);
       this.spriteComponentsBehind.set([]);
       this.spriteComponentsInFront.set([]);
+      this.eventComponentResolvers.clear();
       
       // Clear maps and arrays
       this.spritesheets.clear();