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

package/src/RpgClient.ts

@@ -2,11 +2,49 @@ 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 I18nMessages, type MapPhysicsEntityContext, type MapPhysicsInitContext, type RpgActionName } from '@rpgjs/common'
+import type {
+    ClientProjectileSpawn,
+    RenderedProjectileProps,
+} from './Game/ProjectileManager'
+import type { ClientVisualMap } from './Game/ClientVisuals'
+import type {
+    RpgInteractionBehavior,
+    RpgInteractionMatcher,
+} from './services/interactions'
 
 type RpgClass<T = any> = new (...args: any[]) => T
 type RpgComponent = RpgClientObject
 type SceneMap = Container
+export type SpriteComponentConfig = ComponentFunction | {
+    component: ComponentFunction
+    props?: Record<string, any> | ((object: RpgClientObject) => Record<string, any>)
+    data?: Record<string, any> | ((object: RpgClientObject) => Record<string, any>)
+    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
+    transition?: {
+        animation?: string
+        graphic?: string | string[]
+        duration?: number
+        effect?: string
+    }
+    timeoutMs?: number
+}
 
 export interface RpgClientEngineHooks {
     /**
@@ -28,13 +66,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
@@ -50,7 +89,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
@@ -81,7 +121,7 @@ export interface RpgSpriteHooks {
      * }
      * ```
      */
-    componentsBehind?: ComponentFunction[]
+    componentsBehind?: SpriteComponentConfig[]
     
     /**
      * Array of components to render in front of the sprite
@@ -96,7 +136,53 @@ export interface RpgSpriteHooks {
      * }
      * ```
      */
-    componentsInFront?: ComponentFunction[]
+    componentsInFront?: SpriteComponentConfig[]
+
+    /**
+     * Reusable sprite components addressable by server-side component definitions.
+     *
+     * The server sends only the component id and serializable props. The client
+     * registry maps that id to the CanvasEngine component that renders it.
+     *
+     * @prop {Record<string, ComponentFunction>} [components]
+     * @memberof RpgSpriteHooks
+     * @example
+     * ```ts
+     * import GuildBadge from './components/guild-badge.ce'
+     *
+     * const sprite: RpgSpriteHooks = {
+     *   components: {
+     *     guildBadge: GuildBadge
+     *   }
+     * }
+     * ```
+     */
+    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
@@ -114,6 +200,21 @@ export interface RpgSpriteHooks {
      */
     onDestroy?: (sprite: RpgComponent) => any
 
+    /**
+     * Called when a sprite removal is requested, before it disappears from the scene.
+     *
+     * Return a promise to keep the sprite visible while an animation, effect, or
+     * sound transition is running. The server still owns gameplay removal and
+     * uses the timeout carried by the remove request as a safety limit.
+     *
+     * @prop { (sprite: RpgSprite, context: RpgSpriteBeforeRemoveContext) => any } [onBeforeRemove]
+     * @memberof RpgSpriteHooks
+     */
+    onBeforeRemove?: (
+        sprite: RpgComponent,
+        context: RpgSpriteBeforeRemoveContext
+    ) => any
+
     /**
      * As soon as a data is changed on the server side (the name for example), you are able to know the new data but also the old data.
      * 
@@ -191,6 +292,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
      * 
@@ -235,7 +344,37 @@ 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 {
+    /**
+     * Default translations owned by this client module.
+     *
+     * Game-level translations provided with `provideI18n()` override module
+     * translations when they share the same locale and key.
+     */
+    i18n?: I18nMessages
+
     /**
      * Add hooks to the player or engine. All modules can listen to the hook
      * 
@@ -485,6 +624,13 @@ export interface RpgClient {
          * ```
          */
         attachToSprite?: boolean
+        /**
+         * Vue v4 compatibility alias for `attachToSprite`.
+         *
+         * Prefer `attachToSprite` in v5 projects. This is read by `@rpgjs/vue`
+         * for Vue GUI components migrated from the v4 GUI API.
+         */
+        rpgAttachToSprite?: boolean
     } | any)[],
 
     /** 
@@ -563,33 +709,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.
@@ -620,4 +769,58 @@ 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
+
+    /**
+     * Client-only pointer interactions attached to sprites.
+     *
+     * Use this for hover popovers, selection, drag previews, cursor changes, and
+     * explicit mouse-driven gameplay actions. Pointer feedback stays local unless
+     * the behavior calls `ctx.action(...)`.
+     */
+    interactions?:
+        | ((engine: RpgClientEngine) => void)
+        | {
+            setup?: (engine: RpgClientEngine) => void
+            load?: (engine: RpgClientEngine) => void
+            use?: Array<[RpgInteractionMatcher, RpgInteractionBehavior | ComponentFunction]>
+        }
 }