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

package/src/components/character.ce

@@ -1,31 +1,65 @@
-<Container x={smoothX} y={smoothY} zIndex={z} viewportFollow={shouldFollowCamera} controls onBeforeDestroy  visible>
+<Container
+  x={smoothX}
+  y={smoothY}
+  zIndex={z}
+  viewportFollow={shouldFollowCamera}
+  controls
+  onBeforeDestroy
+  visible
+  cursor={interactionCursor}
+  pointerover={interactionPointerOver}
+  pointerout={interactionPointerOut}
+  pointerdown={interactionPointerDown}
+  pointerup={interactionPointerUp}
+  pointermove={interactionPointerMove}
+  click={interactionClick}
+>
   @for (compConfig of normalizedComponentsBehind) {
     <Container>
-      <compConfig.component object ...compConfig.props />
+      <compConfig.component object={sprite} ...compConfig.props />
     </Container>
   } 
+  <PlayerComponents object={sprite} position="bottom" graphicBounds />
+  <PlayerComponents object={sprite} position="left" graphicBounds />
   <Particle emit={emitParticleTrigger} settings={particleSettings} zIndex={1000} name={particleName} />
   <Container>
-    @for (graphicObj of graphicsSignals) {
-      <Sprite 
-        sheet={sheet(graphicObj)} 
-        direction 
-        tint 
-        hitbox
-        flash={flashConfig}
-      />
+    @for (graphicObj of renderedGraphics) {
+      <Container scale={graphicScale(graphicObj)}>
+        <Sprite 
+          sheet={sheet(graphicObj)} 
+          direction 
+          tint 
+          hitbox
+          shadowCaster={shadowCaster(graphicObj)}
+          flash={flashConfig}
+        />
+      </Container>
+    }
+    @for (eventComponent of resolvedEventComponents) {
+      <Container dependencies={eventComponent.dependencies}>
+        <eventComponent.component ...eventComponent.props />
+      </Container>
     }
   </Container>
+  <PlayerComponents object={sprite} position="center" graphicBounds />
+  <PlayerComponents object={sprite} position="right" graphicBounds />
+  <PlayerComponents object={sprite} position="top" graphicBounds />
   @for (compConfig of normalizedComponentsInFront) {
     <Container dependencies={compConfig.dependencies}>
-      <compConfig.component object ...compConfig.props />
+      <compConfig.component object={sprite} ...compConfig.props />
     </Container>
   }
+  <InteractionComponents
+    object={sprite}
+    bounds={graphicBounds}
+    hitboxBounds={hitboxBounds}
+    graphicBounds={graphicBounds}
+  />
   @for (attachedGui of attachedGuis) {
     @if (shouldDisplayAttachedGui) {
       <Container>
-        <attachedGui.component ...attachedGui.data() dependencies={attachedGui.dependencies} object={object} onFinish={(data) => {
-          onAttachedGuiFinish(attachedGui, data)
+        <attachedGui.component ...attachedGui.data() dependencies={attachedGui.dependencies} object={sprite} guiOpenId={attachedGui.openId} onFinish={(data, guiOpenId) => {
+          onAttachedGuiFinish(attachedGui, data, guiOpenId)
         }} onInteraction={(name, data) => {
           onAttachedGuiInteraction(attachedGui, name, data)
         }} />
@@ -36,28 +70,51 @@
 
 <script>
   import { signal, effect, mount, computed, tick, animatedSignal, on } from "canvasengine";
+  import { Assets } from "pixi.js";
 
   import { lastValueFrom, combineLatest, pairwise, filter, map, startWith } from "rxjs";
   import { Particle } from "@canvasengine/presets";
-  import { GameEngineToken, ModulesToken } from "@rpgjs/common";
+  import { GameEngineToken, ModulesToken, shouldRenderLightingShadows } from "@rpgjs/common";
   import { RpgClientEngine } from "../RpgClientEngine";
   import { inject } from "../core/inject";  
-  import { Direction } from "@rpgjs/common";
+  import { Direction, Animation } from "@rpgjs/common";
+  import { normalizeEventComponent } from "../Game/EventComponentResolver";
   import Hit from "./effects/hit.ce";
   import PlayerComponents from "./player-components.ce";
+  import InteractionComponents from "./interaction-components.ce";
   import { RpgGui } from "../Gui/Gui";
+  import { getCanMoveValue } from "../utils/readPropValue";
+  import {
+    getKeyboardControlBind,
+    keyboardEventMatchesBind,
+    resolveKeyboardActionInput,
+    resolveKeyboardDirectionInput,
+  } from "../services/actionInput";
 
   const { object, id } = defineProps();
+  const sprite = object();
 
   const client = inject(RpgClientEngine);
   const hooks = inject(ModulesToken);
   const guiService = inject(RpgGui);
 
   const spritesheets = client.spritesheets;
-  const playerId = client.playerId;
   const componentsBehind = client.spriteComponentsBehind;
   const componentsInFront = client.spriteComponentsInFront;
-  const isMe = computed(() => id() === playerId);
+  const readProp = (value) => typeof value === 'function' ? value() : value;
+  const isCurrentPlayer = () => {
+    const playerId = client.playerIdSignal();
+    const currentPlayer = playerId ? client.sceneMap?.players?.()?.[playerId] : undefined;
+    return readProp(id) === playerId
+      || readProp(sprite?.id) === playerId
+      || sprite === currentPlayer
+      || sprite === client.sceneMap?.getCurrentPlayer?.();
+  };
+  const isMe = computed(isCurrentPlayer);
+  const shadowsEnabled = computed(() => {
+    const lighting = client.sceneMap?.lighting?.();
+    return shouldRenderLightingShadows(lighting);
+  });
 
   /**
    * Normalize a single sprite component configuration
@@ -128,8 +185,8 @@
     // The computed will be created in the template when needed
     return {
       component: componentRef,
-      props: typeof propsValue === 'function' ? propsValue(object) : propsValue || {},
-      dependencies: dependenciesFn ? dependenciesFn(object) : []
+      props: typeof propsValue === 'function' ? propsValue(sprite) : propsValue || {},
+      dependencies: dependenciesFn ? dependenciesFn(sprite) : []
     };
   };
 
@@ -189,6 +246,18 @@
   const normalizedComponentsInFront = computed(() => {
     return normalizeComponents(componentsInFront());
   });
+
+  const isEventSprite = () => {
+    return typeof sprite?.isEvent === 'function'
+      ? sprite.isEvent()
+      : sprite?._type === 'event';
+  };
+
+  const resolvedEventComponents = computed(() => {
+    if (!isEventSprite()) return [];
+    const eventComponent = normalizeEventComponent(client.resolveEventComponent(sprite), sprite);
+    return eventComponent ? [eventComponent] : [];
+  });
   
   /**
    * Determine if the camera should follow this sprite
@@ -237,7 +306,13 @@
     isConnected,
     graphicsSignals,
     flashTrigger
-  } = object;
+  } = sprite;
+
+  const renderedGraphics = computed(() => {
+    const eventComponent = resolvedEventComponents()[0];
+    if (eventComponent && !eventComponent.renderGraphic) return [];
+    return graphicsSignals();
+  });
 
   /**
    * Flash configuration signals for dynamic options
@@ -282,53 +357,161 @@
 
   const particleSettings = client.particleSettings;
 
-  const canControls = () => isMe() && object.canMove()
+  const canControls = () => isMe() && getCanMoveValue(sprite)
   const keyboardControls = client.globalConfig.keyboardControls;
+  const activeDirectionKeys = new Map();
+
+  const resolveHeldDirection = () => {
+    const directions = Array.from(activeDirectionKeys.values());
+    return directions[directions.length - 1];
+  };
+
+  const resolveSpriteDirection = () => {
+    const heldDirection = resolveHeldDirection();
+    if (heldDirection) return heldDirection;
+    if (typeof sprite.getDirection === 'function') return sprite.getDirection();
+    if (typeof sprite.direction === 'function') return sprite.direction();
+    return direction();
+  };
+
+  const directionToDashVector = (currentDirection) => {
+    switch (currentDirection) {
+      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 withCurrentDirection = (payload) => {
+    if (payload.action !== 'action') return payload;
+    const data = payload.data && typeof payload.data === 'object'
+      ? { ...payload.data }
+      : {};
+    return {
+      ...payload,
+      data: {
+        ...data,
+        direction: data.direction ?? resolveSpriteDirection(),
+      },
+    };
+  };
+
+  const resolveCurrentActionInput = () =>
+    withCurrentDirection(
+      resolveKeyboardActionInput(keyboardControls.action, client, sprite)
+    );
+
+  const playPredictedWalkAnimation = () => {
+    if (sprite.animationFixed) return;
+    if (sprite.animationIsPlaying && sprite.animationIsPlaying()) return;
+    realAnimationName.set('walk');
+  };
+
+  const resumeHeldDirectionWalkAnimation = () => {
+    if (!isCurrentPlayer()) return false;
+    if (activeDirectionKeys.size === 0) return false;
+    if (!canControls()) return false;
+    if (sprite.animationFixed) return false;
+    if (sprite.animationIsPlaying && sprite.animationIsPlaying()) return false;
+    realAnimationName.set('walk');
+    return true;
+  };
+
+  const processMovementInput = (input) => {
+    if (!canControls()) return;
+    client.processInput({ input });
+    playPredictedWalkAnimation();
+  };
+
+  const processDashInput = () => {
+    if (!canControls()) return;
+    client.processDash({
+      direction: directionToDashVector(resolveSpriteDirection()),
+    });
+  };
+
+  const actionBind = () => getKeyboardControlBind(keyboardControls.action);
+  const keyboardEventId = (event) => `${event.keyCode}:${event.code}:${event.key}`;
+
+  const handleNativeActionWhileMoving = (event) => {
+    const inputDirection = resolveKeyboardDirectionInput(event, keyboardControls);
+    if (inputDirection) {
+      const keyId = keyboardEventId(event);
+      if (event.type === 'keydown') {
+        activeDirectionKeys.delete(keyId);
+        activeDirectionKeys.set(keyId, inputDirection);
+        resumeHeldDirectionWalkAnimation();
+      }
+      else {
+        activeDirectionKeys.delete(keyId);
+      }
+    }
+
+    if (!isCurrentPlayer()) return;
+    if (event.type !== 'keydown' || event.repeat) return;
+    if (activeDirectionKeys.size === 0) return;
+    if (!keyboardEventMatchesBind(event, actionBind())) return;
+    if (!canControls()) return;
+
+    client.processAction(resolveCurrentActionInput());
+  };
 
   const visible = computed(() => {
-    if (object.isEvent()) {
+    if (sprite.isEvent()) {
       return true
     }
     return isConnected()
   });
 
-  const controls = signal({
+  const controls = {
     down: {
       repeat: true,
       bind: keyboardControls.down,
       keyDown() {
-        if (canControls()) client.processInput({ input: Direction.Down })
+        processMovementInput(Direction.Down)
       },
     },
     up: {
       repeat: true,
       bind: keyboardControls.up,
       keyDown() {
-        if (canControls()) client.processInput({ input: Direction.Up })
+        processMovementInput(Direction.Up)
       },
     },
     left: {
       repeat: true,
       bind: keyboardControls.left,
       keyDown() {
-        if (canControls()) client.processInput({ input: Direction.Left })
+        processMovementInput(Direction.Left)
       },
     },
     right: {
       repeat: true,
       bind: keyboardControls.right,
       keyDown() {
-        if (canControls()) client.processInput({ input: Direction.Right })
+        processMovementInput(Direction.Right)
       },
     },
     action: {
-      bind: keyboardControls.action,
+      bind: getKeyboardControlBind(keyboardControls.action),
       keyDown() {
         if (canControls()) {
-          client.processAction({ action: 'action' })
+          client.processAction(resolveCurrentActionInput())
         }
       },
     },
+    dash: {
+      bind: keyboardControls.dash,
+      keyDown() {
+        processDashInput()
+      },
+    },
     escape: {
       bind: keyboardControls.escape,
       keyDown() {
@@ -340,7 +523,7 @@
     gamepad: {
       enabled: true
     }
-  });
+  };
 
   const smoothX = animatedSignal(x(), {
     duration: isMe() ? 0 : 0
@@ -351,7 +534,8 @@
   });
 
   const z = computed(() => {
-    return object.y() + object.z()
+    const box = hitbox?.()
+    return sprite.y() + (box?.h ?? 0) + sprite.z()
   });
 
   const realAnimationName = signal(animationName());
@@ -377,6 +561,344 @@
     };
   }
 
+  const graphicScale = (graphicObject) => {
+    const scale = graphicObject?.displayScale ?? graphicObject?.scale;
+    if (Array.isArray(scale)) return scale;
+    if (typeof scale === 'number') return [scale, scale];
+    if (scale && typeof scale === 'object') {
+      const x = typeof scale.x === 'number' ? scale.x : 1;
+      const y = typeof scale.y === 'number' ? scale.y : x;
+      return [x, y];
+    }
+    return undefined;
+  }
+
+  const shadowCaster = (graphicObject) => {
+    const box = hitbox();
+    const bounds = graphicBounds();
+    const scale = graphicScale(graphicObject);
+    const scaleY = Array.isArray(scale) && typeof scale[1] === 'number' ? Math.abs(scale[1]) : 1;
+    const height = Math.max(bounds?.height ?? box?.h ?? 32, box?.h ?? 32) * scaleY;
+
+    return {
+      enabled: shadowsEnabled,
+      height,
+      footAnchor: { x: 0.5, y: 1 },
+      footOffset: { x: 0, y: 2 },
+      alpha: 0.5,
+      blur: 3.5,
+      gradientPower: 2,
+      hardness: 0.42,
+      minLength: Math.max(6, (box?.h ?? 32) * 0.25),
+      maxLength: Math.max(90, height * 1.8),
+      contactAlpha: 0.3,
+      contactScale: 0.3,
+    };
+  }
+
+  const imageDimensions = signal({});
+  const loadingImageDimensions = new Set();
+
+  const toPositiveNumber = (value) => {
+    const number = typeof value === 'number' ? value : parseFloat(value);
+    return Number.isFinite(number) && number > 0 ? number : undefined;
+  };
+
+  const toFiniteNumber = (value, fallback = 0) => {
+    const number = typeof value === 'number' ? value : parseFloat(value);
+    return Number.isFinite(number) ? number : fallback;
+  };
+
+  const clampRatio = (value) => Math.min(1, Math.max(0, value));
+
+  const normalizePair = (value, fallback = [1, 1]) => {
+    if (Array.isArray(value)) {
+      const x = toFiniteNumber(value[0], fallback[0]);
+      const y = toFiniteNumber(value[1] ?? value[0], x);
+      return [x, y];
+    }
+    if (typeof value === 'number') {
+      return [value, value];
+    }
+    if (value && typeof value === 'object') {
+      const x = toFiniteNumber(value.x, fallback[0]);
+      const y = toFiniteNumber(value.y ?? value.x, x);
+      return [x, y];
+    }
+    return fallback;
+  };
+
+  const normalizeAnchor = (value) => {
+    if (!Array.isArray(value)) return undefined;
+    const [x, y] = normalizePair(value, [0, 0]);
+    return [clampRatio(x), clampRatio(y)];
+  };
+
+  const resolveImageSource = (image) => {
+    if (typeof image === 'string') return image;
+    if (typeof image?.default === 'string') return image.default;
+    return undefined;
+  };
+
+  const parentTextureOptions = (graphicObject) => {
+    const props = [
+      'width',
+      'height',
+      'framesHeight',
+      'framesWidth',
+      'rectWidth',
+      'rectHeight',
+      'offset',
+      'image',
+      'sound',
+      'spriteRealSize',
+      'scale',
+      'anchor',
+      'pivot',
+      'x',
+      'y',
+      'opacity'
+    ];
+
+    return props.reduce((options, prop) => {
+      if (graphicObject?.[prop] !== undefined) {
+        options[prop] = graphicObject[prop];
+      }
+      return options;
+    }, {});
+  };
+
+  const resolveTextureOptions = (graphicObject) => {
+    const textures = graphicObject?.textures ?? {};
+    const texture =
+      textures[realAnimationName()] ??
+      textures[Animation.Stand] ??
+      Object.values(textures)[0] ??
+      {};
+
+    return {
+      ...parentTextureOptions(graphicObject),
+      ...texture
+    };
+  };
+
+  const resolveFirstAnimationFrame = (textureOptions) => {
+    const animations = textureOptions?.animations;
+    if (!animations) return {};
+
+    try {
+      const frames = typeof animations === 'function'
+        ? animations({ direction: direction() })
+        : animations;
+      if (!Array.isArray(frames)) return {};
+      const firstGroup = frames[0];
+      return Array.isArray(firstGroup) ? firstGroup[0] ?? {} : firstGroup ?? {};
+    }
+    catch {
+      return {};
+    }
+  };
+
+  const optionValue = (prop, frame, textureOptions, graphicObject) => {
+    return frame?.[prop] ?? textureOptions?.[prop] ?? graphicObject?.[prop];
+  };
+
+  const resolveFrameSize = (textureOptions, dimensions) => {
+    const framesWidth = toPositiveNumber(textureOptions?.framesWidth) ?? 1;
+    const framesHeight = toPositiveNumber(textureOptions?.framesHeight) ?? 1;
+    const imageSource = resolveImageSource(textureOptions?.image);
+    const loadedSize = imageSource ? dimensions[imageSource] : undefined;
+    const fullWidth = toPositiveNumber(textureOptions?.width) ?? loadedSize?.width;
+    const fullHeight = toPositiveNumber(textureOptions?.height) ?? loadedSize?.height;
+    const width = toPositiveNumber(textureOptions?.rectWidth) ??
+      toPositiveNumber(textureOptions?.spriteWidth) ??
+      (fullWidth ? fullWidth / framesWidth : undefined);
+    const height = toPositiveNumber(textureOptions?.rectHeight) ??
+      toPositiveNumber(textureOptions?.spriteHeight) ??
+      (fullHeight ? fullHeight / framesHeight : undefined);
+
+    return {
+      width,
+      height
+    };
+  };
+
+  const resolveHitboxAnchor = (spriteWidth, spriteHeight, realSize, box) => {
+    if (!spriteWidth || !spriteHeight || !box) {
+      return [0, 0];
+    }
+
+    const heightOfSprite = typeof realSize === 'number' ? realSize : realSize?.height;
+    const resolvedHeight = toPositiveNumber(heightOfSprite) ?? spriteHeight;
+    const gap = Math.max(0, (spriteHeight - resolvedHeight) / 2);
+    const hitboxTopLeftX = clampRatio((spriteWidth - box.w) / 2 / spriteWidth);
+    const hitboxTopLeftY = clampRatio((spriteHeight - box.h - gap) / spriteHeight);
+    const hitboxCenterX = clampRatio(hitboxTopLeftX + box.w / 2 / spriteWidth);
+    const hitboxCenterY = clampRatio(hitboxTopLeftY + box.h / 2 / spriteHeight);
+    const footY = clampRatio((spriteHeight - gap) / spriteHeight);
+
+    switch (box.anchorMode ?? 'top-left') {
+      case 'center':
+        return [hitboxCenterX, hitboxCenterY];
+      case 'foot':
+        return [hitboxCenterX, footY];
+      case 'top-left':
+      default:
+        return [hitboxTopLeftX, hitboxTopLeftY];
+    }
+  };
+
+  const loadImageDimensions = (image) => {
+    const source = resolveImageSource(image);
+    if (!source || imageDimensions()[source] || loadingImageDimensions.has(source)) {
+      return;
+    }
+
+    loadingImageDimensions.add(source);
+    Assets.load(source)
+      .then((texture) => {
+        const width = toPositiveNumber(texture?.width);
+        const height = toPositiveNumber(texture?.height);
+        if (!width || !height) return;
+
+        imageDimensions.update((dimensions) => ({
+          ...dimensions,
+          [source]: { width, height }
+        }));
+      })
+      .catch(() => {})
+      .finally(() => {
+        loadingImageDimensions.delete(source);
+      });
+  };
+
+  effect(() => {
+    const sources = new Set();
+
+    graphicsSignals().forEach((graphicObject) => {
+      const baseImage = resolveImageSource(graphicObject?.image);
+      if (baseImage) sources.add(baseImage);
+
+      Object.values(graphicObject?.textures ?? {}).forEach((textureOptions) => {
+        const image = resolveImageSource(textureOptions?.image ?? graphicObject?.image);
+        if (image) sources.add(image);
+      });
+    });
+
+    sources.forEach((source) => loadImageDimensions(source));
+  });
+
+  const hitboxBounds = computed(() => {
+    const box = hitbox();
+    const width = box?.w ?? 0;
+    const height = box?.h ?? 0;
+
+    return {
+      left: 0,
+      top: 0,
+      right: width,
+      bottom: height,
+      width,
+      height,
+      centerX: width / 2,
+      centerY: height / 2
+    };
+  });
+
+  const graphicBounds = computed(() => {
+    const box = hitbox();
+    const fallback = hitboxBounds();
+    const customEventComponent = resolvedEventComponents()[0];
+    if (customEventComponent && !customEventComponent.renderGraphic) {
+      return fallback;
+    }
+    const dimensions = imageDimensions();
+    const graphics = graphicsSignals();
+    let bounds = null;
+
+    graphics.forEach((graphicObject) => {
+      const textureOptions = resolveTextureOptions(graphicObject);
+      const frame = resolveFirstAnimationFrame(textureOptions);
+      const size = resolveFrameSize(textureOptions, dimensions);
+      const spriteWidth = size.width ?? box?.w;
+      const spriteHeight = size.height ?? box?.h;
+
+      if (!spriteWidth || !spriteHeight) {
+        return;
+      }
+
+      const explicitAnchor = normalizeAnchor(optionValue('anchor', frame, textureOptions, graphicObject));
+      const anchor = explicitAnchor ?? resolveHitboxAnchor(
+        spriteWidth,
+        spriteHeight,
+        optionValue('spriteRealSize', frame, textureOptions, graphicObject),
+        box
+      );
+      const scale = normalizePair(optionValue('scale', frame, textureOptions, graphicObject) ?? graphicScale(graphicObject));
+      const x = toFiniteNumber(optionValue('x', frame, textureOptions, graphicObject), 0);
+      const y = toFiniteNumber(optionValue('y', frame, textureOptions, graphicObject), 0);
+      const leftEdge = -anchor[0] * spriteWidth * scale[0];
+      const rightEdge = (1 - anchor[0]) * spriteWidth * scale[0];
+      const topEdge = -anchor[1] * spriteHeight * scale[1];
+      const bottomEdge = (1 - anchor[1]) * spriteHeight * scale[1];
+      const graphic = {
+        left: x + Math.min(leftEdge, rightEdge),
+        top: y + Math.min(topEdge, bottomEdge),
+        right: x + Math.max(leftEdge, rightEdge),
+        bottom: y + Math.max(topEdge, bottomEdge)
+      };
+
+      bounds = bounds
+        ? {
+            left: Math.min(bounds.left, graphic.left),
+            top: Math.min(bounds.top, graphic.top),
+            right: Math.max(bounds.right, graphic.right),
+            bottom: Math.max(bounds.bottom, graphic.bottom)
+          }
+        : graphic;
+    });
+
+    if (!bounds) {
+      return fallback;
+    }
+
+    const width = bounds.right - bounds.left;
+    const height = bounds.bottom - bounds.top;
+
+    return {
+      ...bounds,
+      width,
+      height,
+      centerX: bounds.left + width / 2,
+      centerY: bounds.top + height / 2
+    };
+  });
+
+  const interactionBounds = () => ({
+    bounds: graphicBounds(),
+    hitbox: hitboxBounds(),
+    graphic: graphicBounds()
+  });
+
+  const interactionCursor = computed(() =>
+    client.interactions.cursorFor(sprite, interactionBounds())
+  );
+
+  const handleInteraction = (type) => (event) => {
+    client.updatePointerFromInteractionEvent(event);
+    client.interactions.handle(sprite, type, {
+      event,
+      bounds: interactionBounds()
+    });
+  };
+
+  const interactionPointerOver = handleInteraction('pointerover');
+  const interactionPointerOut = handleInteraction('pointerout');
+  const interactionPointerDown = handleInteraction('pointerdown');
+  const interactionPointerUp = handleInteraction('pointerup');
+  const interactionPointerMove = handleInteraction('pointermove');
+  const interactionClick = handleInteraction('click');
+
   // Combine animation change detection with movement state from smoothX/smoothY
   const movementAnimations = ['walk', 'stand'];
   const epsilon = 0; // movement threshold to consider the easing still running
@@ -400,25 +922,91 @@
     filter(([prev, curr]) => prev !== curr)
   );
 
+  let beforeRemovePromise = null;
+  let beforeRemoveTransitionValue = null;
+  const resolveRemoveContext = () => {
+    if (!sprite._removeTransition) return null;
+    const value = sprite._removeTransition();
+    if (!value || typeof value !== 'string') return null;
+    try {
+      const context = JSON.parse(value);
+      if (!context || typeof context !== 'object' || !context.active) return null;
+      context.__transitionValue = value;
+      return context;
+    }
+    catch {
+      return null;
+    }
+  };
+
+  const withTimeout = (promise, timeoutMs = 0) => {
+    if (!timeoutMs || timeoutMs <= 0) return promise;
+    return Promise.race([
+      promise,
+      new Promise((resolve) => setTimeout(resolve, timeoutMs)),
+    ]);
+  };
+
+  const runBeforeRemove = () => {
+    const context = resolveRemoveContext();
+    if (!context) return Promise.resolve();
+    if (beforeRemovePromise && beforeRemoveTransitionValue === context.__transitionValue) {
+      return beforeRemovePromise;
+    }
+    beforeRemoveTransitionValue = context.__transitionValue;
+    beforeRemovePromise = withTimeout(
+      lastValueFrom(hooks.callHooks("client-sprite-onBeforeRemove", sprite, context)),
+      context.timeoutMs
+    );
+    return beforeRemovePromise;
+  };
+
+  const removeTransitionSubscription = sprite._removeTransition?.observable?.subscribe(() => {
+    if (resolveRemoveContext()) {
+      runBeforeRemove();
+    }
+  });
+
   const animationMovementSubscription = combineLatest([animationChange$, moving$]).subscribe(([[prev, curr], isMoving]) => {
-    if (curr == 'stand' && !isMoving) {
+    const isMovementAnimation = movementAnimations.includes(curr);
+    const isTemporaryAnimationPlaying =
+      sprite.animationIsPlaying && sprite.animationIsPlaying();
+
+    if (sprite.animationFixed && isMovementAnimation) {
       realAnimationName.set(curr);
+      return;
+    }
+
+    if (curr == 'stand' && !isMoving) {
+      if (!resumeHeldDirectionWalkAnimation()) {
+        realAnimationName.set(curr);
+      }
     }
     else if (curr == 'walk' && isMoving) {
       realAnimationName.set(curr);
     }
-    else if (!movementAnimations.includes(curr)) {
+    else if (!isMovementAnimation) {
       realAnimationName.set(curr);
     }
-    if (!isMoving && object.animationIsPlaying && object.animationIsPlaying()) {
-      if (movementAnimations.includes(curr)) {
-        if (typeof object.resetAnimationState === 'function') {
-          object.resetAnimationState();
+    if (!isMoving && isTemporaryAnimationPlaying) {
+      if (isMovementAnimation) {
+        if (typeof sprite.resetAnimationState === 'function') {
+          sprite.resetAnimationState();
         }
       }
     }
   });
 
+  const resumeWalkSubscriptions = [
+    sprite._canMove,
+    sprite._animationFixed,
+    sprite.animationIsPlaying,
+  ]
+    .filter(signal => signal?.observable)
+    .map(signal => signal.observable.subscribe(() => {
+      resumeHeldDirectionWalkAnimation();
+    }));
+
   /**
    * Cleanup subscriptions and call hooks before sprite destruction.
    *
@@ -429,18 +1017,58 @@
    * @example
    * await onBeforeDestroy();
    */
+  const waitForTemporaryAnimationEnd = (maxDuration = 1200) => {
+    if (!sprite.animationIsPlaying || !sprite.animationIsPlaying()) {
+      return Promise.resolve();
+    }
+
+    return new Promise((resolve) => {
+      let finished = false;
+      let timeout;
+      let subscription;
+      const finish = () => {
+        if (finished) return;
+        finished = true;
+        clearTimeout(timeout);
+        subscription?.unsubscribe();
+        resolve();
+      };
+      timeout = setTimeout(finish, maxDuration);
+      subscription = sprite.animationIsPlaying.observable.subscribe((isPlaying) => {
+        if (!isPlaying) finish();
+      });
+      if (finished) subscription.unsubscribe();
+    });
+  };
+
   const onBeforeDestroy = async () => {
+    await runBeforeRemove();
+    await waitForTemporaryAnimationEnd();
+    if (typeof document !== 'undefined') {
+      document.removeEventListener('keydown', handleNativeActionWhileMoving);
+      document.removeEventListener('keyup', handleNativeActionWhileMoving);
+    }
+    removeTransitionSubscription?.unsubscribe();
     animationMovementSubscription.unsubscribe();
+    resumeWalkSubscriptions.forEach(subscription => subscription.unsubscribe());
     xSubscription.unsubscribe();
     ySubscription.unsubscribe();
-    await lastValueFrom(hooks.callHooks("client-sprite-onDestroy", object)) 
-    await lastValueFrom(hooks.callHooks("client-sceneMap-onRemoveSprite", client.sceneMap, object))
+    await lastValueFrom(hooks.callHooks("client-sprite-onDestroy", sprite)) 
+    await lastValueFrom(hooks.callHooks("client-sceneMap-onRemoveSprite", client.sceneMap, sprite))
   }
 
   mount((element) => {
-    hooks.callHooks("client-sprite-onAdd", object).subscribe()
-    hooks.callHooks("client-sceneMap-onAddSprite", client.sceneMap, object).subscribe()
-    if (isMe()) client.setKeyboardControls(element.directives.controls)
+    if (typeof document !== 'undefined') {
+      document.addEventListener('keydown', handleNativeActionWhileMoving);
+      document.addEventListener('keyup', handleNativeActionWhileMoving);
+    }
+    hooks.callHooks("client-sprite-onAdd", sprite).subscribe()
+    hooks.callHooks("client-sceneMap-onAddSprite", client.sceneMap, sprite).subscribe()
+    effect(() => {
+      if (isCurrentPlayer()) {
+        client.setKeyboardControls(element.directives.controls)
+      }
+    })
   })
 
   /**
@@ -449,8 +1077,16 @@
    * @param gui - The GUI instance
    * @param data - Data passed from the GUI component
    */
-  const onAttachedGuiFinish = (gui, data) => {
-    guiService.guiClose(gui.name, data);
+  const normalizeOpenId = (value) => {
+    const resolved = typeof value === "function" ? value() : value;
+    return typeof resolved === "string" && resolved.length > 0 ? resolved : undefined;
+  };
+
+  const onAttachedGuiFinish = (gui, data, guiOpenId) => {
+    const completedOpenId = normalizeOpenId(guiOpenId);
+    const currentOpenId = normalizeOpenId(gui.openId);
+    if (completedOpenId && currentOpenId && completedOpenId !== currentOpenId) return;
+    guiService.guiClose(gui.name, data, completedOpenId ?? currentOpenId);
   };
 
   /**
@@ -467,4 +1103,4 @@
   tick(() => {
     hooks.callHooks("client-sprite-onUpdate").subscribe()
   })
-</script>
+</script>