@rpgjs/client 5.0.0-beta.7 → 5.0.0-beta.8

package/src/RpgClientEngine.ts

@@ -1,6 +1,6 @@
 import Canvas from "./components/scenes/canvas.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";
@@ -14,6 +14,10 @@ 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,
@@ -32,6 +36,17 @@ interface MovementTrajectoryPoint {
   direction?: Direction;
 }
 
+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;
@@ -44,10 +59,10 @@ export class RpgClientEngine<T = any> {
   stopProcessingInput = false;
   width = signal("100%");
   height = signal("100%");
-  spritesheets: Map<string, any> = new Map();
+  spritesheets: Map<string | number, any> = new Map();
   sounds: Map<string, any> = new Map();
   componentAnimations: any[] = [];
-  private spritesheetResolver?: (id: string) => any | Promise<any>;
+  private spritesheetResolver?: (id: string | number) => any | Promise<any>;
   private soundResolver?: (id: string) => any | Promise<any>;
   particleSettings: {
     emitters: any[]
@@ -61,10 +76,11 @@ export class RpgClientEngine<T = any> {
   playerIdSignal = signal<string | null>(null);
   spriteComponentsBehind = signal<any[]>([]);
   spriteComponentsInFront = signal<any[]>([]);
+  spriteComponents: Map<string, any> = new Map();
   /** 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);
@@ -123,6 +139,13 @@ 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.initializePredictionController();
   }
@@ -233,7 +256,7 @@ export class RpgClientEngine<T = any> {
 
     await this.webSocket.connection(() => {
       const saveClient = inject(SaveClientService);
-      saveClient.initialize(this.webSocket);
+      saveClient.initialize();
       this.initListeners()
       this.guiService._initialize()
       this.startPingPong();
@@ -425,7 +448,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,
@@ -574,7 +597,7 @@ export class RpgClientEngine<T = any> {
     })
     await this.webSocket.reconnect(() => {
       const saveClient = inject(SaveClientService);
-      saveClient.initialize(this.webSocket);
+      saveClient.initialize();
       this.initListeners()
       this.guiService._initialize()
     })
@@ -635,7 +658,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;
   }
 
@@ -646,7 +669,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
    * 
@@ -659,7 +682,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);
@@ -1093,6 +1116,37 @@ 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);
+  }
+
   /**
    * Add a component animation to the engine
    * 

package/src/components/character.ce

@@ -4,6 +4,8 @@
       <compConfig.component object ...compConfig.props />
     </Container>
   } 
+  <PlayerComponents object position="bottom" graphicBounds />
+  <PlayerComponents object position="left" graphicBounds />
   <Particle emit={emitParticleTrigger} settings={particleSettings} zIndex={1000} name={particleName} />
   <Container>
     @for (graphicObj of graphicsSignals) {
@@ -17,6 +19,9 @@
       />
     }
   </Container>
+  <PlayerComponents object position="center" graphicBounds />
+  <PlayerComponents object position="right" graphicBounds />
+  <PlayerComponents object position="top" graphicBounds />
   @for (compConfig of normalizedComponentsInFront) {
     <Container dependencies={compConfig.dependencies}>
       <compConfig.component object ...compConfig.props />
@@ -37,13 +42,14 @@
 
 <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 { RpgClientEngine } from "../RpgClientEngine";
   import { inject } from "../core/inject";  
-  import { Direction } from "@rpgjs/common";
+  import { Direction, Animation } from "@rpgjs/common";
   import Hit from "./effects/hit.ce";
   import PlayerComponents from "./player-components.ce";
   import { RpgGui } from "../Gui/Gui";
@@ -390,6 +396,280 @@
     return undefined;
   }
 
+  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 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
+    };
+  });
+
   // 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

package/src/components/dynamics/bar.ce

@@ -0,0 +1,87 @@
+<Container width={width} height={containerHeight} minWidth={width} minHeight={containerHeight}>
+  <Graphics width={width} height={containerHeight} draw={drawBar} />
+  @if (hasLabel) {
+    <Text text={labelText} x={labelPosition.x} y={labelPosition.y} size={labelSize} color={labelColor} />
+  }
+</Container>
+
+<script>
+import { computed } from "canvasengine";
+import { resolveDynamicValue } from "./parse-value";
+
+const { object, current, max, style, text } = defineProps();
+
+const read = (prop, fallback) => prop ? prop() : fallback;
+
+const toNumber = (value, fallback = 0) => {
+  const resolved = resolveDynamicValue(value, object);
+  const num = typeof resolved === 'number' ? resolved : parseFloat(resolved);
+  return Number.isFinite(num) ? num : fallback;
+};
+
+const toColor = (value, fallback) => {
+  const resolved = resolveDynamicValue(value, object);
+  if (typeof resolved === 'number') return resolved;
+  if (typeof resolved === 'string' && resolved.startsWith('#')) {
+    return parseInt(resolved.slice(1), 16);
+  }
+  return resolved ?? fallback;
+};
+
+const config = computed(() => read(style, {}) ?? {});
+const width = computed(() => toNumber(config().width, 50));
+const height = computed(() => toNumber(config().height, 8));
+const borderRadius = computed(() => toNumber(config().borderRadius, 3));
+const borderWidth = computed(() => toNumber(config().borderWidth, 1));
+const backgroundColor = computed(() => toColor(config().bgColor, 0x16213e));
+const fillColor = computed(() => toColor(config().fillColor, 0x4ade80));
+const borderColor = computed(() => toColor(config().borderColor, 0x4a5568));
+const opacity = computed(() => Math.max(0, Math.min(1, toNumber(config().opacity, 1))));
+
+const currentValue = computed(() => toNumber(read(current, 0), 0));
+const maxValue = computed(() => Math.max(0, toNumber(read(max, 0), 0)));
+const percent = computed(() => {
+  const max = maxValue();
+  if (max <= 0) return 0;
+  return Math.max(0, Math.min(1, currentValue() / max));
+});
+
+const fillWidth = computed(() => Math.max(0, width() * percent()));
+const labelTemplate = computed(() => read(text, null));
+const labelText = computed(() => {
+  const template = labelTemplate();
+  if (template == null || template === '') return '';
+
+  const value = String(template)
+    .replace(/\{\$current\}/g, String(currentValue()))
+    .replace(/\{\$max\}/g, String(maxValue()))
+    .replace(/\{\$percent\}/g, String(Math.round(percent() * 100)));
+
+  return String(resolveDynamicValue(value, object) ?? '');
+});
+const labelSize = computed(() => toNumber(config().fontSize, 10));
+const hasLabel = computed(() => labelText().length > 0);
+const labelOffset = computed(() => hasLabel() ? labelSize() + 2 : 0);
+const containerHeight = computed(() => labelOffset() + height());
+const labelColor = computed(() => toColor(config().textColor, 0xffffff));
+const labelPosition = computed(() => ({
+  x: 0,
+  y: 0
+}));
+
+const drawBar = (g) => {
+  g.roundRect(0, labelOffset(), width(), height(), borderRadius());
+  g.fill({ color: backgroundColor(), alpha: opacity() });
+
+  const currentWidth = fillWidth();
+  if (currentWidth > 0) {
+    g.roundRect(0, labelOffset(), currentWidth, height(), borderRadius());
+    g.fill({ color: fillColor(), alpha: opacity() });
+  }
+  
+  const strokeWidth = borderWidth();
+  if (strokeWidth <= 0) return;
+  g.roundRect(0, labelOffset(), width(), height(), borderRadius());
+  g.stroke({ color: borderColor(), width: strokeWidth, alpha: opacity() });
+};
+</script>

package/src/components/dynamics/image.ce

@@ -0,0 +1,20 @@
+<Sprite sheet={sheet} />
+
+<script>
+import { computed } from "canvasengine";
+import { RpgClientEngine } from "../../RpgClientEngine";
+import { inject } from "../../core/inject";
+import { resolveDynamicValue } from "./parse-value";
+
+const { object, value } = defineProps();
+const client = inject(RpgClientEngine);
+
+const sheet = computed(() => {
+  const id = resolveDynamicValue(value?.(), object);
+  if (!id) return null;
+  return {
+    definition: client.getSpriteSheet(id),
+    playing: 'default'
+  };
+});
+</script>

package/src/components/dynamics/parse-value.spec.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from "vitest";
+import { signal } from "canvasengine";
+import { resolveDynamicProps, resolveDynamicValue } from "./parse-value";
+
+describe("dynamic component values", () => {
+  test("resolves player properties and keeps bar placeholders for the bar renderer", () => {
+    const object = {
+      name: signal("Alex"),
+      hpSignal: signal(100),
+      _param: signal({ maxHp: 120 })
+    };
+
+    expect(resolveDynamicValue("HP: {hp}/{param.maxHp} {name} {$current}", object)).toBe("HP: 100/120 Alex {$current}");
+  });
+
+  test("keeps resolved props reactive", () => {
+    const object = {
+      name: signal("Alex"),
+      hpSignal: signal(100),
+      _param: signal({ maxHp: 120 })
+    };
+    const props: any = resolveDynamicProps({
+      value: "HP: {hp} {name}",
+      text: "{$current}/{$max} {name}",
+      style: {
+        width: "{hp}"
+      }
+    }, object);
+
+    expect(props.value()).toBe("HP: 100 Alex");
+    expect(props.text()).toBe("{$current}/{$max} Alex");
+    expect(props.style()).toEqual({ width: "100" });
+
+    object.hpSignal.set(10);
+    object.name.set("Sam");
+
+    expect(props.value()).toBe("HP: 10 Sam");
+    expect(props.text()).toBe("{$current}/{$max} Sam");
+    expect(props.style()).toEqual({ width: "10" });
+  });
+});