Rpg Client Engine
Reference for theRpgClientEngine class.
Members
- activeRoom
- activeRoomSceneComponent
- activeSceneKind
- addComponentAnimation
- addEventComponentResolver
- addSound
- addSpriteComponentBehind
- addSpriteComponentInFront
- cameraFollowRevision
- cameraFollowSmoothMove
- cameraFollowTargetId
- clear
- clearClientPredictionStates
- connect
- dashDefaults
- disconnect
- flash
- getAvailableLocales
- getComponentAnimation
- getCurrentRoom
- getLocale
- getLocalePreference
- getSound
- getSoundVolume
- getSpriteComponent
- getSpriteSheet
- interactions
- interruptCurrentPlayerMovement
- mapShakeTrigger
- music
- playClientVisual
- playSound
- pointer
- processAction
- processDash
- registerClientVisual
- registerClientVisuals
- registerSpriteComponent
- resolveEventComponent
- sceneRoom
- setCameraFollow
- setKeyboardControls
- setLocale
- setSoundResolver
- setSoundVolume
- setSpritesheetResolver
- startTransition
- stopAllSounds
- stopSound
- visualPause
activeRoom
Authoritative descriptor of the active room.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
property - Defined in:
RpgClientEngine
Signature
activeRoomSceneComponent
CanvasEngine component selected for a custom gameplay room.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
property - Defined in:
RpgClientEngine
Signature
activeSceneKind
Active room kind;map keeps the historical map pipeline enabled.
- Source:
packages/client/src/RpgClientEngine.ts - Kind:
property - Defined in:
RpgClientEngine
Signature
addComponentAnimation
Add a component animation to the engine Component animations are temporary visual effects that can be displayed on sprites or objects, such as hit indicators, spell effects, or status animations.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Parameters
componentAnimation:{ component: any, id: string }
Returns
The added component animation configurationExamples
addEventComponentResolver
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.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Parameters
resolver:EventComponentResolver
Returns
The registered resolveraddSound
Add a sound to the engine Adds a sound to the engine’s sound cache. The sound can be:- A simple object with
idandsrcproperties - A Howler instance
- An object with a
play()method
src property, a Howler instance will be created automatically.
- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Parameters
sound:anyid?:string
Returns
The added soundExamples
addSpriteComponentBehind
Add a component to render behind sprites Components added with this method will be displayed with a lower z-index than the sprite Supports multiple formats:- Direct component:
ShadowComponent - Configuration object:
{ component: LightHalo, props: {...} } - With dynamic props:
{ component: LightHalo, props: (object) => {...} } - With dependencies:
{ component: HealthBar, dependencies: (object) => [object.hp, object.param.maxHp] }
- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Parameters
component:any
Returns
The added component or configurationExamples
addSpriteComponentInFront
Add a component to render in front of sprites Components added with this method will be displayed with a higher z-index than the sprite Supports multiple formats:- Direct component:
HealthBarComponent - Configuration object:
{ component: StatusIndicator, props: {...} } - With dynamic props:
{ component: HealthBar, props: (object) => {...} } - With dependencies:
{ component: HealthBar, dependencies: (object) => [object.hp, object.param.maxHp] }
- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Parameters
component:any | { component: any, props: (object: any) => any, dependencies?: (object: any) => any[] }
Returns
The added component or configurationExamples
cameraFollowRevision
Incremented for each camera follow command so repeated commands on the same target are applied- Source:
packages/client/src/RpgClientEngine.ts - Kind:
property - Defined in:
RpgClientEngine
Signature
cameraFollowSmoothMove
Camera follow transition options used by character components when the target changes- Source:
packages/client/src/RpgClientEngine.ts - Kind:
property - Defined in:
RpgClientEngine
Signature
cameraFollowTargetId
ID of the sprite that the camera should follow. null means follow the current player- Source:
packages/client/src/RpgClientEngine.ts - Kind:
property - Defined in:
RpgClientEngine
Signature
clear
Clear all client resources and reset state This method should be called to clean up all client-side resources when shutting down or resetting the client engine. It:- Destroys the PIXI renderer
- Stops all sounds
- Cleans up subscriptions and event listeners
- Resets scene map
- Stops ping/pong interval
- Clears prediction states
Design
This method is used primarily in testing environments to ensure clean state between tests. In production, the client engine typically persists for the lifetime of the application.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Examples
clearClientPredictionStates
Clear client prediction states for cleanup Removes old prediction states and input history to prevent memory leaks. Should be called when changing maps or disconnecting.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Examples
connect
Open the initial MMORPG connection after a deferred account flow. Concurrent calls share the same attempt. Standalone and normal MMORPG starts call this automatically.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Member of:
RpgClientEngine - Defined in:
RpgClientEngine
Signature
Returns
A promise resolved after the RPGJS server accepts the connection.dashDefaults
Runtime defaults used by modules that specialize the built-in dash.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
property - Defined in:
RpgClientEngine
Signature
disconnect
Close the current physical connection without destroying the rendered client. Account modules can return to a pre-connection GUI and callconnect() again.
- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Member of:
RpgClientEngine - Defined in:
RpgClientEngine
Signature
Returns
Nothing.flash
Trigger a flash animation on a sprite This method allows you to trigger a flash effect on any sprite from client-side code. The flash can be configured with various options including type (alpha, tint, or both), duration, cycles, and color.Design
The flash is applied directly to the sprite object using its flash trigger. This is useful for client-side visual feedback, UI interactions, or local effects that don’t need to be synchronized with the server.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Parameters
spriteId?:stringoptions?:{ type?: 'alpha' | 'tint' | 'both'; duration?: number; cycles?: number; alpha?: number; tint?: number | string; }
Examples
getAvailableLocales
Game catalogue locales only, in both standalone and MMORPG mode.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Member of:
RpgClientEngine - Defined in:
RpgClientEngine
Signature
Returns
Registered game locales; defaultLocale if there are no catalogues.Examples
getComponentAnimation
Get a component animation by its ID Retrieves the EffectManager instance for a specific component animation, which can be used to display the animation on sprites or objects.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Parameters
id:string
Returns
The EffectManager instance for the animationExamples
getCurrentRoom
Return the active map scene or synchronized custom gameplay room.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
getLocale
Read the resolved client locale, reactively inside CanvasEngine computations. Works in standalone RPG and MMORPG modes.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Member of:
RpgClientEngine - Defined in:
RpgClientEngine
Signature
Returns
The resolved game locale, neverauto.
Examples
getLocalePreference
Current client preference in standalone RPG and MMORPG modes.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Member of:
RpgClientEngine - Defined in:
RpgClientEngine
Signature
Returns
Locale preference, reactive in client components.Examples
getSound
Get a sound by ID, using resolver if not found in cache This method first checks if the sound exists in the cache. If not found and a resolver is set, it calls the resolver to create the sound. The resolved sound is automatically cached for future use.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Parameters
id:string
Returns
The sound if found or created, or undefined if not found and no resolverExamples
getSoundVolume
Read the persisted volume of one sound channel for the current project. Calls made inside a CanvasEngine computed value remain reactive.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Member of:
RpgClientEngine - Defined in:
RpgClientEngine
Signature
Parameters
channel:RpgAudioChannel
Returns
Volume between 0 and 1.Examples
getSpriteComponent
Get a reusable sprite component by id.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Parameters
id:string
Returns
The CanvasEngine component, or undefined when missinggetSpriteSheet
Get a spritesheet by ID, using resolver if not found in cache This method first checks if the spritesheet exists in the cache. 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.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Parameters
id:string | number
Returns
The spritesheet if found or created, or undefined if not found and no resolverExamples
interactions
Register client-only pointer behaviors for map sprites. Interactions remain local unless a behavior explicitly sends an action to the server. See the client interactions guide for hover, selection, hit testing, drag-and-drop, overlays, and network rules.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
property - Member of:
RpgClientEngine - Defined in:
RpgClientEngine
Signature
Examples
interruptCurrentPlayerMovement
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.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Parameters
player?:any
Returns
true when a player was found and interrupted.
Examples
mapShakeTrigger
Trigger for map shake animation- Source:
packages/client/src/RpgClientEngine.ts - Kind:
property - Defined in:
RpgClientEngine
Signature
music
Client-only controller for temporary looping music and map BGM crossfades.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
property - Defined in:
RpgClientEngine
Signature
playClientVisual
Play a registered client visual locally. This is also used by the websocket listener when the server callsplayer.clientVisual() or map.clientVisual().
- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Parameters
packet:ClientVisualPacket
playSound
Play a sound by its ID This method retrieves a sound from the cache or resolver and plays it. If the sound is not found, it will attempt to resolve it using the soundResolver. Uses Howler.js for audio playback instead of native Audio elements. The existing API remains the single entry point for ordinary, channel-aware, and spatial sounds. Playback is client-owned in both standalone and MMORPG games; server calls only ask the receiving client to play a registered ID.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Member of:
RpgClientEngine - Defined in:
RpgClientEngine
Signature
Parameters
soundId:stringoptions?:RpgPlaySoundOptions
Returns
Resolves after the sound has been resolved and started when available.Examples
pointer
Read the latest pointer position tracked by the client canvas. World coordinates are suitable for action payloads and map interactions.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
property - Member of:
RpgClientEngine - Defined in:
RpgClientEngine
Signature
Examples
processAction
Send an action intent to the authoritative server. Client-provided data must be validated by the receiving player input handler or action.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Member of:
RpgClientEngine - Defined in:
RpgClientEngine
Signature
Parameters
action:RpgActionNamedata?:any
Returns
Nothing.Examples
processDash
Start a predicted dash for the current player and send it through the authoritative movement channel.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Member of:
RpgClientEngine - Defined in:
RpgClientEngine
Signature
Parameters
input?:Partial<RpgDashInput>
Returns
A promise resolved after the dash input has been processed locally.Examples
registerClientVisual
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.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Parameters
name:stringhandler:ClientVisualHandler
Returns
The registered handlerregisterClientVisuals
Register several named client visual macros.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Parameters
visuals:ClientVisualMap
registerSpriteComponent
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.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Parameters
id:stringcomponent:any
Returns
The registered componentExamples
resolveEventComponent
Resolve the custom CanvasEngine component for an event, if any.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Parameters
event:RpgClientEvent
Returns
The component/config returned by the last matching resolversceneRoom
Synchronized state for the active non-map gameplay room.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
property - Defined in:
RpgClientEngine
Signature
setCameraFollow
Set the camera to follow a specific sprite This method changes which sprite the camera viewport should follow. The camera can smoothly animate to the target sprite before continuous follow starts.Design
The camera follow target is stored in a signal that is read by sprite components. Each sprite checks if it should be followed by comparing its ID with the target ID. When smoothMove options are provided, the transition is handled by pixi-viewport’s animation plugin, then continuous follow is handled by CanvasEngine’s viewport system.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Parameters
targetId:string | nullsmoothMove?:CameraFollowSmoothMove
Examples
setKeyboardControls
Registers the current player’s live CanvasEngine controls on the client. Used automatically when the player component mounts in standalone RPG and MMORPG modes. Destroyed directives are ignored so a retiring component cannot overwrite replacement controls during streamed map updates. Input handling remains client-side; this does not change server movement authority.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Member of:
RpgClientEngine - Defined in:
RpgClientEngine
Signature
Parameters
controlInstance:ControlsDirective
Returns
Nothing.Examples
setLocale
Select and persist a game language, orauto for browser negotiation.
Updates client labels and the connected player’s future translations.
- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Member of:
RpgClientEngine - Defined in:
RpgClientEngine
Signature
Parameters
locale:string
Returns
Nothing.Examples
setSoundResolver
Set a resolver function for sounds The resolver is called when a sound is requested but not found in the cache. It can be synchronous (returns directly) or asynchronous (returns a Promise). The resolved sound is automatically cached for future use.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Parameters
resolver:(id: string) => any | Promise<any>
Examples
setSoundVolume
Set the persisted volume of one sound channel for the current project. Master volume is applied through Howler, including sounds controlled through the legacyRpgSound.global facade. This client-owned preference behaves the
same in standalone and MMORPG games and never changes server state.
- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Member of:
RpgClientEngine - Defined in:
RpgClientEngine
Signature
Parameters
channel:RpgAudioChannelvalue:number
Examples
setSpritesheetResolver
Set a resolver function for spritesheets The resolver is called when a spritesheet is requested but not found in the cache. It can be synchronous (returns directly) or asynchronous (returns a Promise). The resolved spritesheet is automatically cached for future use.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Parameters
resolver:(id: string | number) => any | Promise<any>
Examples
startTransition
Start a transition Convenience method to display a transition by its ID using the GUI system.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Parameters
id:stringprops?:any
Examples
stopAllSounds
Stop all currently playing sounds This method stops all sounds that are currently playing. Useful when changing maps to prevent sound overlap.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Examples
stopSound
Stop a sound that is currently playing This method stops a sound that was previously started withplaySound().
- Source:
packages/client/src/RpgClientEngine.ts - Kind:
method - Defined in:
RpgClientEngine
Signature
Parameters
soundId:string
Examples
visualPause
Freezes map rendering for short presentation-only beats such as combat hit-stop. It is deliberately separate from menu/gameplay pause ownership.- Source:
packages/client/src/RpgClientEngine.ts - Kind:
property - Defined in:
RpgClientEngine