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

package/dist/RpgClientEngine.js

@@ -1,45 +1,125 @@
 import { inject } from "./core/inject.js";
 import { WebSocketToken } from "./services/AbstractSocket.js";
+import { normalizeActionInput } from "./services/actionInput.js";
+import { getCanMoveValue } from "./utils/readPropValue.js";
 import { SaveClientService } from "./services/save.js";
 import { RpgGui } from "./Gui/Gui.js";
-import component from "./components/scenes/canvas.ce.js";
+import __ce_component from "./components/scenes/canvas.ce.js";
+import __ce_component$1 from "./components/scenes/draw-map.ce.js";
 import { LoadMapToken } from "./services/loadMap.js";
 import { RpgSound } from "./Sound.js";
 import { RpgResource } from "./Resource.js";
-import { load } from "./node_modules/.pnpm/@signe_sync@2.9.0/node_modules/@signe/sync/dist/index.js";
+import { load } from "./node_modules/.pnpm/@signe_sync@3.1.0_react@19.2.7/node_modules/@signe/sync/dist/index.js";
 import { RpgClientMap } from "./Game/Map.js";
 import { AnimationManager } from "./Game/AnimationManager.js";
 import { GlobalConfigToken } from "./module.js";
 import { PrebuiltComponentAnimations } from "./components/animations/index.js";
+import __ce_component$2 from "./components/dynamics/text.ce.js";
+import __ce_component$3 from "./components/dynamics/bar.ce.js";
+import __ce_component$4 from "./components/dynamics/shape.ce.js";
+import __ce_component$5 from "./components/dynamics/image.ce.js";
 import { NotificationManager } from "./Gui/NotificationManager.js";
+import { normalizeRoomMapId } from "./utils/mapId.js";
+import { ProjectileManager } from "./Game/ProjectileManager.js";
+import { ClientVisualRegistry } from "./Game/ClientVisuals.js";
+import { createClientPointerContext } from "./services/pointerContext.js";
+import { RpgClientInteractions } from "./services/interactions.js";
+import { EventComponentResolverRegistry } from "./Game/EventComponentResolver.js";
+import { RpgClientBuiltinI18n } from "./i18n.js";
 import { Howl, bootstrapCanvas, signal, trigger } from "canvasengine";
-import { Direction, ModulesToken, PredictionController } from "@rpgjs/common";
+import { Direction, ModulesToken, PredictionController, Vector2, getOrCreateI18nService, normalizeLightingState } from "@rpgjs/common";
 import { BehaviorSubject, combineLatest, filter, lastValueFrom, switchMap, take } from "rxjs";
 import * as PIXI from "pixi.js";
 //#region src/RpgClientEngine.ts
+var DEFAULT_DASH_ADDITIONAL_SPEED = 8;
+var DEFAULT_DASH_DURATION_MS = 180;
+var DEFAULT_DASH_COOLDOWN_MS = 450;
+var isDashInput = (input) => typeof input === "object" && input !== null && input.type === "dash";
+var isMoveInput = (input) => typeof input === "object" && input !== null && input.type === "move";
+var resolveMoveDirection = (input) => {
+	if (isMoveInput(input)) return input.direction;
+	if (typeof input === "string" || typeof input === "number") return input;
+};
+var directionToVector = (direction) => {
+	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
+		};
+	}
+};
+var vectorToDirection = (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;
+};
+var normalizeDashInput = (input, fallbackDirection) => {
+	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, 1e3)) : DEFAULT_DASH_DURATION_MS;
+	const cooldown = typeof input.cooldown === "number" && Number.isFinite(input.cooldown) ? Math.max(0, Math.min(input.cooldown, 5e3)) : DEFAULT_DASH_COOLDOWN_MS;
+	return {
+		type: "dash",
+		direction: {
+			x: rawX / magnitude,
+			y: rawY / magnitude
+		},
+		additionalSpeed,
+		duration,
+		cooldown
+	};
+};
 var RpgClientEngine = class {
 	constructor(context) {
 		this.context = context;
+		this.sceneMapComponent = __ce_component$1;
 		this.stopProcessingInput = false;
 		this.width = signal("100%");
 		this.height = signal("100%");
 		this.spritesheets = /* @__PURE__ */ new Map();
+		this.spritesheetPromises = /* @__PURE__ */ new Map();
 		this.sounds = /* @__PURE__ */ new Map();
 		this.componentAnimations = [];
+		this.clientVisuals = new ClientVisualRegistry();
+		this.pointer = createClientPointerContext();
+		this.interactions = new RpgClientInteractions(this);
 		this.particleSettings = { emitters: [] };
 		this.playerIdSignal = signal(null);
 		this.spriteComponentsBehind = signal([]);
 		this.spriteComponentsInFront = signal([]);
+		this.spriteComponents = /* @__PURE__ */ new Map();
+		this.eventComponentResolvers = new EventComponentResolverRegistry();
 		this.cameraFollowTargetId = signal(null);
 		this.mapShakeTrigger = trigger();
 		this.controlsReady = signal(void 0);
 		this.gamePause = signal(false);
 		this.predictionEnabled = false;
 		this.SERVER_CORRECTION_THRESHOLD = 30;
+		this.localMovementAuthority = false;
+		this.lastLocalMovementInputAt = 0;
+		this.LOCAL_MOVEMENT_AUTHORITY_ACK_GRACE_MS = 250;
 		this.inputFrameCounter = 0;
 		this.pendingPredictionFrames = [];
 		this.lastClientPhysicsStepAt = 0;
 		this.frameOffset = 0;
+		this.latestServerTickAt = 0;
+		this.dashLockedUntil = 0;
 		this.rtt = 0;
 		this.pingInterval = null;
 		this.PING_INTERVAL_MS = 5e3;
@@ -53,12 +133,20 @@ var RpgClientEngine = class {
 		this.playersReceived$ = new BehaviorSubject(false);
 		this.eventsReceived$ = new BehaviorSubject(false);
 		this.sceneResetQueued = false;
+		this.mapTransitionInProgress = false;
+		this.socketListenersInitialized = false;
+		this.clientReadyForMapChanges = false;
+		this.pendingMapChanges = [];
 		this.tickSubscriptions = [];
+		this.pendingSyncPackets = [];
 		this.notificationManager = new NotificationManager();
 		this.webSocket = inject(WebSocketToken);
 		this.guiService = inject(RpgGui);
 		this.loadMapService = inject(LoadMapToken);
 		this.hooks = inject(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) this.globalConfig = {};
 		if (!this.globalConfig.box) this.globalConfig.box = {
@@ -72,9 +160,38 @@ var RpgClientEngine = class {
 			id: "animation",
 			component: PrebuiltComponentAnimations.Animation
 		});
+		this.registerSpriteComponent("rpg:text", __ce_component$2);
+		this.registerSpriteComponent("rpg:hpBar", __ce_component$3);
+		this.registerSpriteComponent("rpg:spBar", __ce_component$3);
+		this.registerSpriteComponent("rpg:bar", __ce_component$3);
+		this.registerSpriteComponent("rpg:shape", __ce_component$4);
+		this.registerSpriteComponent("rpg:image", __ce_component$5);
 		this.predictionEnabled = this.globalConfig?.prediction?.enabled !== false;
+		this.localMovementAuthority = this.resolveLocalMovementAuthority();
 		this.initializePredictionController();
 	}
+	resolveLocalMovementAuthority() {
+		const predictionConfig = this.globalConfig?.prediction;
+		const configured = this.globalConfig?.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) {
+		this.locale = locale;
+	}
+	getLocale() {
+		return this.locale || this.i18nService.defaultLocale;
+	}
+	t(key, params) {
+		return this.i18nService.t(key, params, this.getLocale());
+	}
+	i18n() {
+		return {
+			locale: this.getLocale(),
+			t: (key, params) => this.t(key, params)
+		};
+	}
 	/**
 	* Assigns a CanvasEngine KeyboardControls instance to the dependency injection context
 	* 
@@ -120,12 +237,25 @@ var RpgClientEngine = class {
 		this.sceneMap = new RpgClientMap();
 		this.sceneMap.configureClientPrediction(this.predictionEnabled);
 		this.sceneMap.loadPhysic();
+		this.resolveSceneMapComponent();
+		inject(SaveClientService).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");
 		const bootstrapOptions = this.globalConfig?.bootstrapCanvasOptions;
-		const { app, canvasElement } = await bootstrapCanvas(this.selector, component, bootstrapOptions);
+		const { app, canvasElement } = await bootstrapCanvas(this.selector, __ce_component, bootstrapOptions);
+		this.installCanvasResizeGuard(app);
 		this.canvasApp = app;
 		this.canvasElement = canvasElement;
 		this.renderer = app.renderer;
+		this.setupPointerTracking();
 		this.tick = canvasElement?.propObservables?.context["tick"].observable;
 		const inputCheckSubscription = this.tick.subscribe(() => {
 			if (Date.now() - this.lastInputTime > 100) {
@@ -137,6 +267,7 @@ var RpgClientEngine = class {
 		this.tickSubscriptions.push(inputCheckSubscription);
 		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);
@@ -144,14 +275,20 @@ var RpgClientEngine = class {
 		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();
 		this.resizeHandler = () => {
 			this.hooks.callHooks("client-engine-onWindowResize", this).subscribe();
 		};
 		window.addEventListener("resize", this.resizeHandler);
 		const tickSubscription = this.tick.subscribe((tick) => {
 			this.stepClientPhysicsTick();
+			this.projectiles.step();
 			this.flushPendingPredictedStates();
 			this.flushPendingMovePath();
 			this.hooks.callHooks("client-engine-onStep", this, tick).subscribe();
@@ -162,12 +299,133 @@ var RpgClientEngine = class {
 			}
 		});
 		this.tickSubscriptions.push(tickSubscription);
-		await this.webSocket.connection(() => {
-			inject(SaveClientService).initialize(this.webSocket);
-			this.initListeners();
-			this.guiService._initialize();
-			this.startPingPong();
-		});
+		this.startPingPong();
+	}
+	installCanvasResizeGuard(app) {
+		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();
+		};
+	}
+	readCanvasResizeTargetSize(app) {
+		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
+		};
+	}
+	readCanvasRendererSize(app) {
+		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
+		};
+	}
+	cancelCanvasResizeFrame(app) {
+		if (typeof app?._cancelResize === "function") app._cancelResize();
+	}
+	resolveSceneMapComponent() {
+		const components = this.hooks.getHookFunctions("client-sceneMap-component");
+		const component = components[components.length - 1];
+		if (component) this.sceneMapComponent = component;
+	}
+	setupPointerTracking() {
+		const renderer = this.renderer;
+		const canvas = renderer?.canvas ?? renderer?.view ?? this.canvasApp?.canvas;
+		if (!canvas || typeof canvas.addEventListener !== "function") return;
+		this.pointerCanvas = canvas;
+		const updatePointer = (event) => {
+			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) => {
+			updatePointer(event);
+			this.interactions.handlePointerMove(event);
+		};
+		this.pointerUpHandler = (event) => {
+			updatePointer(event);
+			this.interactions.handlePointerUp(event);
+		};
+		this.pointerCancelHandler = (event) => {
+			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) {
+		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);
+	}
+	findViewportInstance() {
+		const find = (node) => {
+			if (!node) return void 0;
+			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 find(this.canvasApp?.stage);
 	}
 	prepareSyncPayload(data) {
 		const payload = { ...data ?? {} };
@@ -175,7 +433,8 @@ var RpgClientEngine = class {
 		delete payload.timestamp;
 		const myId = this.playerIdSignal();
 		const players = payload.players;
-		if (this.predictionEnabled && !!this.prediction?.hasPendingInputs() && myId && players && players[myId]) {
+		const localPatch = myId && players ? players[myId] : void 0;
+		if (this.shouldPreserveLocalPlayerPosition(localPatch) && myId && players && players[myId]) {
 			const localPatch = { ...players[myId] };
 			delete localPatch.x;
 			delete localPatch.y;
@@ -188,6 +447,18 @@ var RpgClientEngine = class {
 		}
 		return payload;
 	}
+	shouldPreserveLocalPlayerPosition(localPatch) {
+		if (!localPatch) return false;
+		if (this.predictionEnabled && !!this.prediction?.hasPendingInputs()) return true;
+		return this.shouldKeepLocalPlayerMovement();
+	}
+	shouldKeepLocalPlayerMovement() {
+		if (!this.localMovementAuthority || this.mapTransitionInProgress) return false;
+		const myId = this.playerIdSignal();
+		if (!(myId ? this.sceneMap?.players?.()?.[myId] : void 0)) return false;
+		if (this.prediction?.hasPendingInputs()) return true;
+		return Date.now() - this.lastLocalMovementInputAt <= this.LOCAL_MOVEMENT_AUTHORITY_ACK_GRACE_MS;
+	}
 	normalizeAckWithSyncState(ack, syncData) {
 		const myId = this.playerIdSignal();
 		if (!myId) return ack;
@@ -201,43 +472,30 @@ var RpgClientEngine = class {
 		};
 	}
 	initListeners() {
+		if (this.socketListenersInitialized) return;
+		this.socketListenersInitialized = true;
 		this.webSocket.on("sync", (data) => {
-			if (data.pId) {
-				this.playerIdSignal.set(data.pId);
-				this.playerIdReceived$.next(true);
-			}
-			if (this.sceneResetQueued) {
-				this.sceneMap.reset();
-				this.sceneMap.loadPhysic();
-				this.sceneResetQueued = false;
-			}
-			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) : void 0;
-			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];
+			if (!this.tick) {
+				this.pendingSyncPackets.push(data);
+				return;
 			}
-			const players = payload.players || this.sceneMap.players();
-			if (players && Object.keys(players).length > 0) this.playersReceived$.next(true);
-			if ((payload.events || this.sceneMap.events()) !== void 0) this.eventsReceived$.next(true);
+			this.applySyncPacket(data);
 		});
 		this.webSocket.on("pong", (data) => {
-			this.rtt = Date.now() - data.clientTime;
+			const now = Date.now();
+			this.rtt = now - data.clientTime;
 			const estimatedTicksInFlight = Math.floor(this.rtt / 2 / (1e3 / 60));
 			const estimatedServerTickNow = data.serverTick + estimatedTicksInFlight;
+			this.updateServerTickEstimate(estimatedServerTickNow, now);
 			if (this.inputFrameCounter > 0) this.frameOffset = estimatedServerTickNow - data.clientFrame;
 			console.debug(`[Ping/Pong] RTT: ${this.rtt}ms, ServerTick: ${data.serverTick}, FrameOffset: ${this.frameOffset}`);
 		});
 		this.webSocket.on("changeMap", (data) => {
-			this.sceneResetQueued = true;
-			this.cameraFollowTargetId.set(null);
-			const transferToken = typeof data?.transferToken === "string" ? data.transferToken : void 0;
-			this.loadScene(data.mapId, transferToken);
+			if (!this.clientReadyForMapChanges) {
+				this.pendingMapChanges.push(data);
+				return;
+			}
+			this.handleChangeMap(data);
 		});
 		this.webSocket.on("showComponentAnimation", (data) => {
 			const { params, object, position, id } = data;
@@ -245,14 +503,42 @@ var RpgClientEngine = class {
 			const player = object ? this.sceneMap.getObjectById(object) : void 0;
 			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 !== void 0) player.setAnimation(animationName, graphic, nbTimes);
-			else player.setAnimation(animationName, nbTimes);
+			const { animationName, nbTimes, object, graphic, restoreAnimationName, restoreGraphics } = data;
+			const player = object ? this.sceneMap.getObjectById(object) : void 0;
+			if (!player) return;
+			const restoreOptions = {
+				restoreAnimationName,
+				restoreGraphics
+			};
+			if (graphic !== void 0) player.setAnimation(animationName, graphic, nbTimes, restoreOptions);
+			else player.setAnimation(animationName, nbTimes, restoreOptions);
 		});
 		this.webSocket.on("playSound", (data) => {
 			const { soundId, volume, loop } = data;
@@ -314,6 +600,10 @@ var RpgClientEngine = class {
 				seed: raw.seed
 			});
 		});
+		this.webSocket.on("lightingState", (data) => {
+			const raw = data && typeof data === "object" && "value" in data ? data.value : data;
+			this.sceneMap.lightingState.set(normalizeLightingState(raw));
+		});
 		this.webSocket.on("open", () => {
 			this.hooks.callHooks("client-engine-onConnected", this, this.socket).subscribe();
 			this.startPingPong();
@@ -323,9 +613,82 @@ var RpgClientEngine = class {
 			this.stopPingPong();
 		});
 		this.webSocket.on("error", (error) => {
-			this.hooks.callHooks("client-engine-onConnectError", this, error, this.socket).subscribe();
+			this.callConnectError(error);
+		});
+	}
+	beginMapTransfer(nextMapId) {
+		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();
+	}
+	clearComponentAnimations() {
+		this.componentAnimations.forEach((componentAnimation) => {
+			componentAnimation.instance?.clear?.();
 		});
 	}
+	shouldProcessProjectilePacket(data) {
+		if (this.mapTransitionInProgress) return false;
+		const packetMapId = normalizeRoomMapId(typeof data?.mapId === "string" ? data.mapId : void 0);
+		const currentMapId = normalizeRoomMapId(this.currentMapRoomId);
+		return !packetMapId || !currentMapId || packetMapId === currentMapId;
+	}
+	async callConnectError(error) {
+		await lastValueFrom(this.hooks.callHooks("client-engine-onConnectError", this, error, this.socket));
+	}
+	flushPendingSyncPackets() {
+		const packets = this.pendingSyncPackets;
+		this.pendingSyncPackets = [];
+		packets.forEach((packet) => this.applySyncPacket(packet));
+	}
+	flushPendingMapChanges() {
+		const packets = this.pendingMapChanges;
+		this.pendingMapChanges = [];
+		packets.forEach((packet) => this.handleChangeMap(packet));
+	}
+	handleChangeMap(data) {
+		const nextMapId = typeof data?.mapId === "string" ? data.mapId : void 0;
+		this.beginMapTransfer(nextMapId);
+		const transferToken = typeof data?.transferToken === "string" ? data.transferToken : void 0;
+		this.loadScene(data.mapId, transferToken);
+	}
+	applySyncPacket(data) {
+		if (data.pId) {
+			this.playerIdSignal.set(data.pId);
+			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;
+		}
+		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) : void 0;
+		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];
+		}
+		const players = payload.players || this.sceneMap.players();
+		if (players && Object.keys(players).length > 0) this.playersReceived$.next(true);
+		if ((payload.events || this.sceneMap.events()) !== void 0) this.eventsReceived$.next(true);
+	}
 	/**
 	* Start periodic ping/pong for client-server synchronization
 	* 
@@ -402,18 +765,25 @@ var RpgClientEngine = class {
 			room: mapId,
 			query: transferToken ? { transferToken } : void 0
 		});
-		await this.webSocket.reconnect(() => {
-			inject(SaveClientService).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);
 		if (this.playerIdSignal()) this.playerIdReceived$.next(true);
 		const players = this.sceneMap.players();
 		if (players && Object.keys(players).length > 0) this.playersReceived$.next(true);
 		if (this.sceneMap.events() !== void 0) this.eventsReceived$.next(true);
 		this.mapLoadCompleted$.next(true);
+		this.currentMapRoomId = mapId;
+		this.mapTransitionInProgress = false;
 		this.sceneMap.configureClientPrediction(this.predictionEnabled);
 		this.sceneMap.loadPhysic();
 	}
@@ -458,7 +828,7 @@ var RpgClientEngine = class {
 	* 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
 	* 
@@ -474,12 +844,20 @@ var RpgClientEngine = class {
 	getSpriteSheet(id) {
 		if (this.spritesheets.has(id)) return this.spritesheets.get(id);
 		if (this.spritesheetResolver) {
+			if (this.spritesheetPromises.has(id)) return this.spritesheetPromises.get(id);
 			const result = this.spritesheetResolver(id);
-			if (result instanceof Promise) return result.then((spritesheet) => {
-				if (spritesheet) this.spritesheets.set(id, spritesheet);
-				return spritesheet;
-			});
-			else {
+			if (result instanceof Promise) {
+				const promise = result.then((spritesheet) => {
+					if (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 {
 				if (result) this.spritesheets.set(id, result);
 				return result;
 			}
@@ -807,6 +1185,95 @@ var RpgClientEngine = class {
 		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, component) {
+		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) {
+		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) {
+		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) {
+		return this.eventComponentResolvers.resolve(event);
+	}
+	registerProjectileComponent(type, component) {
+		return this.projectiles.register(type, component);
+	}
+	getProjectileComponent(type) {
+		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, handler) {
+		return this.clientVisuals.register(name, handler);
+	}
+	/**
+	* Register several named client visual macros.
+	*
+	* @param visuals - Map of visual names to client-side handlers
+	*/
+	registerClientVisuals(visuals) {
+		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) {
+		return this.clientVisuals.play(packet, this);
+	}
+	/**
 	* Add a component animation to the engine
 	* 
 	* Component animations are temporary visual effects that can be displayed
@@ -882,18 +1349,47 @@ var RpgClientEngine = class {
 	*   duration: 1000,
 	*   onFinish: () => console.log('Fade complete')
 	* });
+	*
+	* // Wait until the transition component calls onFinish
+	* await engine.startTransition('fade', { duration: 1000 });
 	* ```
 	*/
 	startTransition(id, props = {}) {
 		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((resolve) => {
+			let finished = false;
+			const finish = (data) => {
+				if (finished) return;
+				finished = true;
+				props?.onFinish?.(data);
+				resolve();
+			};
+			this.guiService.display(id, {
+				...props,
+				onFinish: finish
+			});
+		});
 	}
 	async processInput({ input }) {
+		if (this.stopProcessingInput) return;
+		const currentPlayer = this.sceneMap.getCurrentPlayer();
+		if (!(!currentPlayer || getCanMoveValue(currentPlayer))) {
+			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;
 		let tick;
 		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 {
@@ -902,29 +1398,38 @@ var RpgClientEngine = class {
 		}
 		this.inputFrameCounter = frame;
 		this.hooks.callHooks("client-engine-onInput", this, {
-			input,
+			input: movementInput,
 			playerId: this.playerId
 		}).subscribe();
-		const currentPlayer = this.sceneMap.getCurrentPlayer();
 		const bodyReady = this.ensureCurrentPlayerBody();
 		if (currentPlayer && bodyReady) {
-			currentPlayer.changeDirection(input);
-			this.sceneMap.moveBody(currentPlayer, input);
+			this.applyPredictedMovementInput(currentPlayer, movementInput);
 			if (this.predictionEnabled && this.prediction) {
 				this.pendingPredictionFrames.push(frame);
 				if (this.pendingPredictionFrames.length > 240) this.pendingPredictionFrames = this.pendingPredictionFrames.slice(-240);
 			}
 		}
-		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();
 	}
-	processAction({ action }) {
+	async processDash(input = {}) {
+		const currentPlayer = this.sceneMap.getCurrentPlayer();
+		const dashInput = normalizeDashInput(input, typeof currentPlayer?.direction === "function" ? currentPlayer.direction() : currentPlayer?.direction);
+		if (!dashInput) return;
+		await this.processInput({ input: dashInput });
+	}
+	processAction(action, data) {
 		if (this.stopProcessingInput) return;
+		const currentPlayer = this.sceneMap.getCurrentPlayer();
+		if (!(!currentPlayer || getCanMoveValue(currentPlayer))) return;
+		const payload = normalizeActionInput(action, data);
 		this.hooks.callHooks("client-engine-onInput", this, {
-			input: "action",
+			input: payload.action,
+			action: payload.action,
+			data: payload.data,
 			playerId: this.playerId
 		}).subscribe();
-		this.webSocket.emit("action", { action });
+		this.webSocket.emit("action", payload);
 	}
 	get PIXI() {
 		return PIXI;
@@ -938,9 +1443,43 @@ var RpgClientEngine = class {
 	get scene() {
 		return this.sceneMap;
 	}
+	getObjectById(id) {
+		return this.sceneMap?.getObjectById(id);
+	}
 	getPhysicsTick() {
 		return this.sceneMap?.getTick?.() ?? 0;
 	}
+	getPhysicsTickDurationMs() {
+		const timeStep = this.sceneMap?.physic?.getWorld?.()?.getTimeStep?.();
+		return typeof timeStep === "number" && Number.isFinite(timeStep) && timeStep > 0 ? timeStep * 1e3 : 1e3 / 60;
+	}
+	updateServerTickEstimate(serverTick, now = Date.now()) {
+		if (typeof serverTick !== "number" || !Number.isFinite(serverTick)) return;
+		this.latestServerTick = serverTick;
+		this.latestServerTickAt = now;
+	}
+	estimateServerTick(now = Date.now()) {
+		if (typeof this.latestServerTick !== "number" || this.latestServerTickAt <= 0) return;
+		const elapsedTicks = Math.max(0, (now - this.latestServerTickAt) / this.getPhysicsTickDurationMs());
+		return this.latestServerTick + elapsedTicks;
+	}
+	predictProjectileImpact(projectile) {
+		if (projectile.predictImpact === false) return null;
+		const sceneMap = this.sceneMap;
+		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
+		};
+	}
 	ensureCurrentPlayerBody() {
 		const player = this.sceneMap?.getCurrentPlayer();
 		const myId = this.playerIdSignal();
@@ -986,7 +1525,7 @@ var RpgClientEngine = class {
 				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) return trajectory.slice(-this.MAX_MOVE_TRAJECTORY_POINTS);
@@ -1008,6 +1547,11 @@ var RpgClientEngine = class {
 	}
 	flushPendingMovePath() {
 		if (!this.predictionEnabled || !this.prediction) return;
+		const player = this.sceneMap?.getCurrentPlayer?.();
+		if (player && !getCanMoveValue(player)) {
+			this.interruptCurrentPlayerMovement(player);
+			return;
+		}
 		const pendingInputs = this.prediction.getPendingInputs();
 		if (pendingInputs.length === 0) return;
 		const latest = pendingInputs[pendingInputs.length - 1];
@@ -1016,6 +1560,17 @@ var RpgClientEngine = class {
 		if (now - this.lastMovePathSentAt < this.MOVE_PATH_RESEND_INTERVAL_MS) return;
 		this.emitMovePacket(latest.direction, latest.frame, latest.tick, now, false);
 	}
+	applyPredictedMovementInput(player, input) {
+		if (isDashInput(input)) {
+			const direction = vectorToDirection(input.direction);
+			player.changeDirection(direction);
+			return Boolean(this.sceneMap.dashBody?.(player, input));
+		}
+		const direction = resolveMoveDirection(input);
+		if (!direction) return false;
+		player.changeDirection(direction);
+		return Boolean(this.sceneMap.moveBody?.(player, direction));
+	}
 	getLocalPlayerState() {
 		const currentPlayer = this.sceneMap?.getCurrentPlayer();
 		if (!currentPlayer) return {
@@ -1124,6 +1679,31 @@ var RpgClientEngine = class {
 		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 = this.sceneMap?.getCurrentPlayer?.()) {
+		if (!player) return false;
+		this.sceneMap?.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
 	* 
 	* This method allows you to trigger a flash effect on any sprite from client-side code.
@@ -1177,11 +1757,13 @@ var RpgClientEngine = class {
 		if (sprite && typeof sprite.flash === "function") sprite.flash(options);
 	}
 	applyServerAck(ack) {
+		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" ? {
+				state: !keepLocalMovement && typeof ack.x === "number" && typeof ack.y === "number" ? {
 					x: ack.x,
 					y: ack.y,
 					direction: ack.direction
@@ -1191,6 +1773,7 @@ var RpgClientEngine = class {
 			return;
 		}
 		if (typeof ack.x !== "number" || typeof ack.y !== "number") return;
+		if (keepLocalMovement) return;
 		const player = this.getCurrentPlayer();
 		const myId = this.playerIdSignal();
 		if (!player || !myId) return;
@@ -1205,13 +1788,17 @@ var RpgClientEngine = class {
 	reconcilePrediction(authoritativeState, pendingInputs) {
 		const player = this.getCurrentPlayer();
 		if (!player) return;
+		if (!getCanMoveValue(player)) {
+			this.interruptCurrentPlayerMovement(player);
+			return;
+		}
 		this.sceneMap.stopMovement(player);
 		this.applyAuthoritativeState(authoritativeState);
 		if (!pendingInputs.length) return;
 		const replayInputs = pendingInputs.slice(-600);
 		for (const entry of replayInputs) {
 			if (!entry?.direction) continue;
-			this.sceneMap.moveBody(player, entry.direction);
+			this.applyPredictedMovementInput(player, entry.direction);
 			this.sceneMap.stepPredictionTick();
 			this.prediction?.attachPredictedState(entry.frame, this.getLocalPlayerState());
 		}
@@ -1277,6 +1864,19 @@ var RpgClientEngine = class {
 				window.removeEventListener("resize", this.resizeHandler);
 				this.resizeHandler = void 0;
 			}
+			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 = void 0;
+				this.pointerUpHandler = void 0;
+				this.pointerCancelHandler = void 0;
+				this.pointerCanvas = void 0;
+			}
 			const rendererStillExists = this.renderer && typeof this.renderer.destroy === "function";
 			if (this.canvasApp && typeof this.canvasApp.destroy === "function") {
 				try {
@@ -1308,6 +1908,7 @@ var RpgClientEngine = class {
 			this.cameraFollowTargetId.set(null);
 			this.spriteComponentsBehind.set([]);
 			this.spriteComponentsInFront.set([]);
+			this.eventComponentResolvers.clear();
 			this.spritesheets.clear();
 			this.sounds.clear();
 			this.componentAnimations = [];