@rpgjs/client 5.0.0-beta.10 → 5.0.0-beta.12

package/src/Game/ProjectileManager.ts

@@ -0,0 +1,346 @@
+import { computed, signal } from "canvasengine";
+import { Hooks } from "@rpgjs/common";
+import { normalizeRoomMapId } from "../utils/mapId";
+
+export interface ClientProjectileSpawn {
+  id: string;
+  type: string;
+  ownerId?: string;
+  origin: { x: number; y: number };
+  direction: { x: number; y: number };
+  speed: number;
+  range: number;
+  ttl: number;
+  spawnTick: number;
+  delay?: number;
+  index?: number;
+  count?: number;
+  params?: Record<string, unknown>;
+  collisionMask?: number;
+  ignoreOwner?: boolean;
+  predictImpact?: boolean;
+}
+
+export interface ClientProjectileImpact {
+  id: string;
+  targetId?: string;
+  x: number;
+  y: number;
+  distance?: number;
+}
+
+export interface ClientProjectileDestroy {
+  id: string;
+  reason?: string;
+  targetId?: string;
+  x?: number;
+  y?: number;
+  distance?: number;
+}
+
+export interface RenderedProjectileProps extends ClientProjectileSpawn {
+  x: number;
+  y: number;
+  angle: number;
+  distance: number;
+  elapsed: number;
+  progress: number;
+  impact?: ClientProjectileImpact;
+  impactElapsed?: number;
+  impactProgress?: number;
+  destroyed?: boolean;
+}
+
+export interface RenderedProjectile {
+  id: string;
+  type: string;
+  component: any;
+  props: RenderedProjectileProps;
+}
+
+export type ProjectilePredictionResolver = (
+  projectile: ClientProjectileSpawn,
+) => ClientProjectileImpact | null | undefined;
+
+export interface ProjectileSpawnClock {
+  now?: number;
+  currentServerTick?: number;
+  tickDurationMs?: number;
+  mapId?: string;
+}
+
+interface RuntimeProjectile {
+  spawn: ClientProjectileSpawn;
+  component: any;
+  createdAt: number;
+  impact?: ClientProjectileImpact;
+  visualImpact?: ClientProjectileImpact;
+  predictedImpact?: ClientProjectileImpact;
+  impactStartedAt?: number;
+  destroyAt?: number;
+  destroyReason?: string;
+}
+
+export class ProjectileManager {
+  private readonly components = new Map<string, any>();
+  private readonly projectiles = new Map<string, RuntimeProjectile>();
+  private readonly version = signal(0);
+  private readonly impactDurationMs = 350;
+  private mapId?: string;
+
+  constructor(
+    private readonly hooks: Hooks,
+    private readonly predictionResolver?: ProjectilePredictionResolver,
+  ) {}
+
+  current = computed<RenderedProjectile[]>(() => {
+    this.version();
+    const now = Date.now();
+    const rendered: RenderedProjectile[] = [];
+    for (const projectile of this.projectiles.values()) {
+      const props = this.toProps(projectile, now);
+      if (!props) {
+        continue;
+      }
+      rendered.push({
+        id: projectile.spawn.id,
+        type: projectile.spawn.type,
+        component: projectile.component,
+        props,
+      });
+    }
+    return rendered;
+  });
+
+  register(type: string, component: any): any {
+    this.components.set(type, component);
+    return component;
+  }
+
+  get(type: string): any {
+    return this.components.get(type);
+  }
+
+  setMapId(mapId: string | undefined): void {
+    const normalizedMapId = normalizeRoomMapId(mapId);
+    if (this.mapId === normalizedMapId) return;
+    this.mapId = normalizedMapId;
+    this.clear();
+  }
+
+  getMapId(): string | undefined {
+    return this.mapId;
+  }
+
+  spawnBatch(projectiles: ClientProjectileSpawn[], clock: ProjectileSpawnClock = {}): void {
+    if (!this.acceptsMap(clock.mapId)) return;
+    const now = clock.now ?? Date.now();
+    for (const projectile of projectiles) {
+      const component = this.components.get(projectile.type);
+      if (!component) {
+        continue;
+      }
+      const runtime: RuntimeProjectile = {
+        spawn: {
+          ...projectile,
+          delay: projectile.delay ?? 0,
+          index: projectile.index ?? 0,
+          count: projectile.count ?? 1,
+        },
+        component,
+        createdAt: now,
+      };
+      this.setPredictedImpact(runtime);
+      this.projectiles.set(projectile.id, runtime);
+      this.hooks.callHooks("client-projectiles-onSpawn", runtime.spawn).subscribe();
+    }
+    this.touch();
+  }
+
+  impactBatch(impacts: ClientProjectileImpact[], context: { mapId?: string } = {}): void {
+    if (!this.acceptsMap(context.mapId)) return;
+    const now = Date.now();
+    for (const impact of impacts) {
+      const projectile = this.projectiles.get(impact.id);
+      if (!projectile) {
+        continue;
+      }
+      this.setImpact(projectile, impact, now);
+      this.hooks.callHooks("client-projectiles-onImpact", this.toProps(projectile, now)).subscribe();
+    }
+    this.touch();
+  }
+
+  destroyBatch(projectiles: ClientProjectileDestroy[], context: { mapId?: string } = {}): void {
+    if (!this.acceptsMap(context.mapId)) return;
+    const now = Date.now();
+    for (const destroyed of projectiles) {
+      const projectile = this.projectiles.get(destroyed.id);
+      if (!projectile) {
+        continue;
+      }
+      if (destroyed.reason === "hit") {
+        const current = this.toProps(projectile, now);
+        this.setImpact(projectile, {
+          id: destroyed.id,
+          targetId: destroyed.targetId ?? projectile.impact?.targetId,
+          x: destroyed.x ?? projectile.impact?.x ?? current?.x ?? projectile.spawn.origin.x,
+          y: destroyed.y ?? projectile.impact?.y ?? current?.y ?? projectile.spawn.origin.y,
+          distance: destroyed.distance ?? projectile.impact?.distance ?? current?.distance,
+        }, now);
+      }
+      projectile.destroyReason = destroyed.reason;
+      projectile.destroyAt = projectile.destroyAt ?? (
+        projectile.impact && projectile.impactStartedAt !== undefined
+          ? projectile.impactStartedAt + this.impactDurationMs
+          : now
+      );
+      this.hooks.callHooks("client-projectiles-onDestroy", this.toProps(projectile, now)).subscribe();
+    }
+    this.touch();
+  }
+
+  clear(): void {
+    this.projectiles.clear();
+    this.touch();
+  }
+
+  step(): void {
+    const now = Date.now();
+    let changed = false;
+    for (const [id, projectile] of this.projectiles) {
+      const props = this.toProps(projectile, now);
+      if (
+        (!props && !this.isWaitingForDelay(projectile, now)) ||
+        (projectile.destroyAt !== undefined && now >= projectile.destroyAt)
+      ) {
+        this.projectiles.delete(id);
+        changed = true;
+      }
+    }
+    this.touch(changed || this.projectiles.size > 0);
+  }
+
+  private toProps(projectile: RuntimeProjectile, now: number): RenderedProjectileProps | null {
+    const spawn = projectile.spawn;
+    const delayMs = (spawn.delay ?? 0) * 1000;
+    const elapsedMs = now - projectile.createdAt - delayMs;
+    if (elapsedMs < 0) {
+      return null;
+    }
+    const elapsed = elapsedMs / 1000;
+    const ttl = Math.max(0.001, spawn.ttl);
+    const rawDistance = Math.min(spawn.speed * elapsed, spawn.range);
+    const predictedImpact = this.getActivePredictedImpact(projectile, now, rawDistance);
+    const visualImpact = projectile.visualImpact ?? projectile.impact;
+    const distance = visualImpact?.distance ?? predictedImpact?.distance ?? rawDistance;
+    const progress = Math.min(1, distance / spawn.range);
+    const x = visualImpact?.x ?? predictedImpact?.x ?? spawn.origin.x + spawn.direction.x * distance;
+    const y = visualImpact?.y ?? predictedImpact?.y ?? spawn.origin.y + spawn.direction.y * distance;
+    const impactElapsedMs = projectile.impactStartedAt !== undefined
+      ? Math.max(0, now - projectile.impactStartedAt)
+      : undefined;
+    return {
+      ...spawn,
+      x,
+      y,
+      angle: Math.atan2(spawn.direction.y, spawn.direction.x),
+      distance,
+      elapsed,
+      progress,
+      impact: projectile.impact,
+      impactElapsed: impactElapsedMs === undefined ? undefined : impactElapsedMs / 1000,
+      impactProgress: impactElapsedMs === undefined
+        ? undefined
+        : Math.min(1, impactElapsedMs / this.impactDurationMs),
+      destroyed: projectile.destroyAt !== undefined,
+      ttl,
+    };
+  }
+
+  private acceptsMap(mapId: string | undefined): boolean {
+    const normalizedMapId = normalizeRoomMapId(mapId);
+    return !normalizedMapId || !this.mapId || normalizedMapId === this.mapId;
+  }
+
+  private isWaitingForDelay(projectile: RuntimeProjectile, now: number): boolean {
+    const delayMs = (projectile.spawn.delay ?? 0) * 1000;
+    return now - projectile.createdAt - delayMs < 0;
+  }
+
+  private setPredictedImpact(projectile: RuntimeProjectile): void {
+    if (projectile.spawn.predictImpact === false) {
+      return;
+    }
+    const impact = this.predictionResolver?.(projectile.spawn);
+    if (!impact || !Number.isFinite(impact.x) || !Number.isFinite(impact.y)) {
+      return;
+    }
+    const distance = typeof impact.distance === "number" && Number.isFinite(impact.distance)
+      ? impact.distance
+      : Math.hypot(impact.x - projectile.spawn.origin.x, impact.y - projectile.spawn.origin.y);
+    if (!Number.isFinite(distance) || distance < 0 || distance > projectile.spawn.range) {
+      return;
+    }
+    projectile.predictedImpact = {
+      ...impact,
+      distance,
+    };
+  }
+
+  private getActivePredictedImpact(
+    projectile: RuntimeProjectile,
+    now: number,
+    rawDistance: number,
+  ): ClientProjectileImpact | undefined {
+    if (!projectile.predictedImpact || projectile.impact) {
+      return undefined;
+    }
+    const distance = projectile.predictedImpact.distance;
+    if (distance === undefined || rawDistance < distance) {
+      return undefined;
+    }
+    return projectile.predictedImpact;
+  }
+
+  private setImpact(projectile: RuntimeProjectile, impact: ClientProjectileImpact, now: number): void {
+    projectile.visualImpact = this.resolveVisualImpact(projectile, impact, now);
+    projectile.impact = impact;
+    projectile.predictedImpact = undefined;
+    projectile.impactStartedAt = projectile.impactStartedAt ?? now;
+    const impactDestroyAt = projectile.impactStartedAt + this.impactDurationMs;
+    projectile.destroyAt = Math.max(projectile.destroyAt ?? 0, impactDestroyAt);
+  }
+
+  private resolveVisualImpact(
+    projectile: RuntimeProjectile,
+    impact: ClientProjectileImpact,
+    now: number,
+  ): ClientProjectileImpact {
+    const predicted = projectile.predictedImpact;
+    if (!predicted || !this.isSameTarget(predicted, impact)) {
+      return impact;
+    }
+    const distance = predicted.distance;
+    if (distance === undefined) {
+      return impact;
+    }
+    const delayMs = (projectile.spawn.delay ?? 0) * 1000;
+    const elapsedMs = now - projectile.createdAt - delayMs;
+    if (elapsedMs < 0) {
+      return impact;
+    }
+    const rawDistance = Math.min(projectile.spawn.speed * (elapsedMs / 1000), projectile.spawn.range);
+    return rawDistance >= distance ? predicted : impact;
+  }
+
+  private isSameTarget(a: ClientProjectileImpact, b: ClientProjectileImpact): boolean {
+    return a.targetId !== undefined && a.targetId === b.targetId;
+  }
+
+  private touch(force = true): void {
+    if (force) {
+      this.version.update((value) => value + 1);
+    }
+  }
+}

package/src/RpgClient.ts

@@ -2,7 +2,13 @@ import { ComponentFunction, Signal } from 'canvasengine'
 import { RpgClientEngine } from './RpgClientEngine'
 import { Loader, Container } from 'pixi.js'
 import { RpgClientObject } from './Game/Object'
-import { type MapPhysicsEntityContext, type MapPhysicsInitContext } from '@rpgjs/common'
+import type { RpgClientEvent } from './Game/Event'
+import { type MapPhysicsEntityContext, type MapPhysicsInitContext, type RpgActionName } from '@rpgjs/common'
+import type {
+    ClientProjectileSpawn,
+    RenderedProjectileProps,
+} from './Game/ProjectileManager'
+import type { ClientVisualMap } from './Game/ClientVisuals'
 
 type RpgClass<T = any> = new (...args: any[]) => T
 type RpgComponent = RpgClientObject
@@ -14,6 +20,16 @@ export type SpriteComponentConfig = ComponentFunction | {
     dependencies?: (object: RpgClientObject) => any[]
 }
 
+export type EventComponentSprite = RpgClientEvent & Record<string, any>
+
+export type EventComponentConfig = ComponentFunction | {
+    component: ComponentFunction
+    props?: Record<string, any> | ((event: EventComponentSprite) => Record<string, any>)
+    data?: Record<string, any> | ((event: EventComponentSprite) => Record<string, any>)
+    dependencies?: (event: EventComponentSprite) => any[]
+    renderGraphic?: boolean
+}
+
 export interface RpgSpriteBeforeRemoveContext {
     reason?: string
     data?: any
@@ -46,13 +62,14 @@ export interface RpgClientEngineHooks {
     /**
      * Recover keys from the pressed keyboard
      * 
-     * @prop { (engine: RpgClientEngine, obj: { input: string, playerId: number }) => any } [onInput]
+     * @prop { (engine: RpgClientEngine, obj: { input: string | number, action?: string | number, data?: any, playerId: number }) => any } [onInput]
      * @memberof RpgEngineHooks
      */
-    onInput?: (engine: RpgClientEngine, obj: { input: string, playerId: number }) => any
+    onInput?: (engine: RpgClientEngine, obj: { input: RpgActionName, action?: RpgActionName, data?: any, playerId: number }) => any
 
     /**
-     * Called when the user is connected to the server
+     * Called when the user is connected to the server. In MMORPG mode, this
+     * runs after the server sends the RPGJS connection acceptance packet.
      * 
      * @prop { (engine: RpgClientEngine, socket: any) => any } [onConnected]
      * @memberof RpgEngineHooks
@@ -68,7 +85,8 @@ export interface RpgClientEngineHooks {
     onDisconnect?: (engine: RpgClientEngine, reason: any, socket: any) => any
 
     /**
-     * Called when there was a connection error
+     * Called when there was a connection error. In MMORPG mode, this also runs
+     * when server-side auth refuses the connection.
      * 
      * @prop { (engine: RpgClientEngine, err: any, socket: any) => any } [onConnectError]
      * @memberof RpgEngineHooks
@@ -136,6 +154,31 @@ export interface RpgSpriteHooks {
      * ```
      */
     components?: Record<string, ComponentFunction>
+
+    /**
+     * Resolve a custom CanvasEngine component for a specific event.
+     *
+     * The component always receives the synced event object as the `sprite` prop.
+     * Custom props are merged in addition to `sprite`, but cannot replace it.
+     * Return `null` or `undefined` to keep the default graphic renderer.
+     *
+     * @prop { (event: EventComponentSprite) => EventComponentConfig | null | undefined } [eventComponent]
+     * @memberof RpgSpriteHooks
+     * @example
+     * ```ts
+     * import ChestEvent from './components/chest-event.ce'
+     *
+     * const sprite: RpgSpriteHooks = {
+     *   eventComponent(sprite) {
+     *     if (sprite.name === 'CHEST') {
+     *       return ChestEvent
+     *     }
+     *     return null
+     *   }
+     * }
+     * ```
+     */
+    eventComponent?: (event: EventComponentSprite) => EventComponentConfig | null | undefined
     
     /**
      * As soon as the sprite is initialized
@@ -245,6 +288,14 @@ export interface RpgSceneHooks<Scene> {
 }
 
 export interface RpgSceneMapHooks extends RpgSceneHooks<SceneMap> {
+    /**
+     * Root CanvasEngine component used to render the RPG scene map.
+     *
+     * Use the exported `SceneMap` component inside your custom component to
+     * keep the default map rendering and compose additional scene children.
+     */
+    component?: ComponentFunction
+
     /**
      * The map and resources are being loaded
      * 
@@ -289,6 +340,28 @@ export interface RpgSceneMapHooks extends RpgSceneHooks<SceneMap> {
     onPhysicsReset?: (scene: SceneMap) => any
 }
 
+export interface RpgProjectileHooks {
+    /**
+     * CanvasEngine components used to render server-authoritative projectiles.
+     */
+    components?: Record<string, ComponentFunction>
+
+    /**
+     * Called when a projectile spawn batch is received from the server.
+     */
+    onSpawn?: (projectile: ClientProjectileSpawn) => any
+
+    /**
+     * Called when the server confirms a projectile impact.
+     */
+    onImpact?: (projectile: RenderedProjectileProps | null) => any
+
+    /**
+     * Called when the server destroys a projectile.
+     */
+    onDestroy?: (projectile: RenderedProjectileProps | null) => any
+}
+
 export interface RpgClient {
     /**
      * Add hooks to the player or engine. All modules can listen to the hook
@@ -624,33 +697,36 @@ export interface RpgClient {
      * */
     sprite?: RpgSpriteHooks
 
-    /** 
-     * Reference the scenes of the game. Here you can put your own class that inherits RpgSceneMap
+    /**
+     * Reference the scenes of the game.
      * 
      * ```ts
      * import { RpgSceneMapHooks, RpgClient, defineModule } from '@rpgjs/client'
+     * import MyScene from './my-scene.ce'
      * 
      * export const sceneMap: RpgSceneMapHooks = {
-     *     
+     *     component: MyScene
      * }
      * 
      * defineModule<RpgClient>({
-     *      scenes: {
-     *          // If you put the RpgSceneMap scene, Thhe key is called mandatory `map`
-     *          map: sceneMap
-     *      }
+     *      sceneMap
      * })
      * ``` 
      * 
-     * @prop { [sceneName: string]: RpgSceneMapHooks } [scenes]
+     * @prop {RpgSceneMapHooks} [sceneMap]
      * @memberof RpgClient
      * */
+    sceneMap?: RpgSceneMapHooks
+
+    /**
+     * Legacy scene map hook container.
+     *
+     * Prefer `sceneMap` for new code.
+     */
     scenes?: {
         map: RpgSceneMapHooks
     }
 
-    sceneMap?: RpgSceneMapHooks
-
     /** 
      * Array containing the list of component animations
      * Each element defines a temporary component to display for animations like hits, effects, etc.
@@ -681,4 +757,43 @@ export interface RpgClient {
         id: string,
         component: ComponentFunction
     }[]
+
+    /**
+     * Named client-side visual macros.
+     *
+     * Use client visuals when the server needs to trigger a group of existing
+     * client visual primitives at once, such as a flash, damage text, sound,
+     * component animation, and camera shake. The server sends only the visual
+     * name and a serializable payload; the rendering details live on the client.
+     *
+     * For a single sound, flash, or component animation, prefer the direct
+     * server APIs (`playSound`, `flash`, `showComponentAnimation`). Client
+     * visuals are meant to group several visual operations and reduce bandwidth.
+     *
+     * ```ts
+     * import { defineModule, RpgClient } from '@rpgjs/client'
+     *
+     * export default defineModule<RpgClient>({
+     *   clientVisuals: {
+     *     hit({ target, data }, helpers) {
+     *       helpers.flash(target, { type: 'tint', tint: 'red' })
+     *       helpers.showHit(target, `-${data.damage}`)
+     *       helpers.sound('hit')
+     *     }
+     *   }
+     * })
+     * ```
+     *
+     * @prop {Record<string, ClientVisualHandler>} [clientVisuals]
+     * @memberof RpgClient
+     */
+    clientVisuals?: ClientVisualMap
+
+    /**
+     * Client-side projectile rendering configuration.
+     *
+     * Register a CanvasEngine component per projectile type. The server sends
+     * compact spawn/impact/destroy events and the client predicts x/y locally.
+     */
+    projectiles?: RpgProjectileHooks
 }