V5 compatibility with v4

docs/.vitepress/config.ts

@@ -1,5 +1,5 @@
 const guideMenu = [{
-  text: 'Quick Start',
+  text: 'Guide',
   collapsed: false,
   items: [
     { text: "Getting Started", link: "/guide/get-started" },
@@ -8,23 +8,33 @@ const guideMenu = [{
     { text: "Display Animations", link: "/guide/display-animations" },
     { text: "Create Movement", link: "/guide/create-movement" },
     { text: "Sprite Components", link: "/guide/sprite-components" },
-    { text: "Battle AI", link: "/guide/battle-ai" }
+    { text: "Spritesheets", link: "/guide/spritesheets" },
+    { text: "World Maps", link: "/guide/world-maps" },
+    { text: "Items", link: "/guide/items" },
+    { text: "Sounds", link: "/guide/sounds" },
+    { text: "Synchronization", link: "/guide/synchronization" },
+    { text: "Battle AI", link: "/guide/battle-ai" },
+    { text: "Attach GUI", link: "/guide/gui/attach-gui" }
   ]
 }]
 
 const guiMenu = [{
   text: 'GUI',
   collapsed: false,
   items: [
-    { text: "Engine Injection", link: "/gui/engine-injection" }
+    { text: "Engine Injection", link: "/gui/engine-injection" },
+    { text: "Dialog Box", link: "/gui/dialog-box" },
+    { text: "Vue Integration", link: "/gui/vue-integration" }
   ]
 }]
 
 const advancedMenu = [{
   text: 'Advanced',
   collapsed: false,
   items: [
-    { text: "Provide Load Map", link: "/advanced/provide-load-map" }
+    { text: "Provide Load Map", link: "/advanced/provide-load-map" },
+    { text: "Latency Simulation", link: "/advanced/latency-simulation" },
+    { text: "Packet Loss Simulation", link: "/advanced/packet-loss-simulation" }
   ]
 }]
 

docs/gui/dialog-box.md

@@ -201,7 +201,9 @@ export default {
 
 ### Customizing Sounds
 
-You can customize the sounds used by the dialog box. The sound IDs in `provideClientGlobalConfig()` must correspond to the sound IDs defined in `provideClientModules()`:
+You can customize the sounds used by the dialog box. The sound IDs in `provideClientGlobalConfig()` must correspond to the sound IDs defined in `provideClientModules()`.
+
+> **See also:** [Sounds Guide](/guide/sounds) for comprehensive information about sound configuration, dynamic sound resolution, and playing sounds from the server.
 
 ```typescript
 import { provideClientGlobalConfig } from "@rpgjs/client";
@@ -263,4 +265,9 @@ export default {
     ]),
   ],
 };
+```
+
+## See Also
+
+- [Sounds Guide](/guide/sounds) - Comprehensive guide on configuring and using sounds, including dynamic sound resolution
 ```

docs/guide/get-started.md

@@ -7,8 +7,8 @@ RPGJS was created several years ago, with the aim of creating an RPG on the brow
 ## Technology
 
 - Typescript v5
-- ViteJS v6+ (for compilation)
-- NodeJS v22+ (for server)
+- ViteJS v7+ (for compilation)
+- NodeJS v24+ (for server)
 - CanvasEngine v2 (for rendering, based on PixiJS)
 
 ## Compatibility

docs/guide/gui/attach-gui.md

@@ -0,0 +1,312 @@
+# Attach GUI to Sprites Guide
+
+This guide explains how to use the `attachToSprite` option to attach GUI components directly to sprites in the game world.
+
+## Overview
+
+By default, GUI components are displayed as fixed overlays on the screen. However, you can attach GUI components to sprites so they follow the sprite's position in the game world. This is useful for:
+
+- Tooltips that appear when hovering over a sprite
+- Name tags above characters
+- Interactive UI elements attached to specific sprites
+- Contextual menus that follow a sprite
+- Status indicators that move with the sprite
+
+## Basic Usage
+
+To attach a GUI component to sprites, set `attachToSprite: true` in your GUI configuration:
+
+```typescript
+import { defineModule, RpgClient } from '@rpgjs/client'
+import TooltipComponent from './components/tooltip.ce'
+
+defineModule<RpgClient>({
+    gui: [
+        {
+            id: "my-tooltip",
+            component: TooltipComponent,
+            attachToSprite: true
+        }
+    ]
+})
+```
+
+## Creating an Attached GUI Component
+
+Attached GUI components are Canvas Engine components (`.ce` files) that receive the sprite object as a prop. They are rendered within the sprite's container, so they automatically follow the sprite's position.
+
+### Example: Simple Tooltip Component
+
+```javascript
+<!-- tooltip.ce -->
+<DOMContainer>
+    <input type="text" placeholder="Enter text..." />
+</DOMContainer>
+```
+
+The component receives the sprite `object` as a prop automatically, allowing you to access sprite properties:
+
+```javascript
+<!-- tooltip.ce -->
+<DOMContainer>
+    <div style="background: rgba(0,0,0,0.8); color: white; padding: 8px; border-radius: 4px;">
+        <p>Player: {object.name()}</p>
+        <p>HP: {object.hp()} / {object.param.maxHp()}</p>
+    </div>
+</DOMContainer>
+
+<script>
+  const { object } = defineProps();
+</script>
+```
+
+> For more information about DOMContainer, see the [Canvas Engine documentation](https://canvasengine.net/components/dom-container.html)
+
+## Controlling Display from Server Side
+
+Attached GUIs are controlled from the server side using the `showAttachedGui()` and `hideAttachedGui()` methods on the player object.
+
+### Show Attached GUI
+
+Display the attached GUI for a player:
+
+```typescript
+// Show the attached GUI for this player
+player.showAttachedGui()
+
+// Show the attached GUI for other players
+player.showAttachedGui([otherPlayer1, otherPlayer2])
+
+// Show for multiple players
+player.showAttachedGui([player1, player2, player3])
+```
+
+### Hide Attached GUI
+
+Hide the attached GUI for a player:
+
+```typescript
+// Hide the attached GUI for this player
+player.hideAttachedGui()
+
+// Hide the attached GUI for other players
+player.hideAttachedGui([otherPlayer1, otherPlayer2])
+```
+
+### Example: Show Tooltip on Hover
+
+```typescript
+// server.ts
+import { RpgPlayer, RpgMap } from '@rpgjs/server'
+
+export default {
+    player: {
+        onJoinMap(player: RpgPlayer, map: RpgMap) {
+            // Show tooltip when player joins the map
+            player.gui('my-tooltip').open()
+            player.showAttachedGui()
+        },
+
+        onLeaveMap(player: RpgPlayer, map: RpgMap) {
+            // Hide tooltip when player leaves
+            player.hideAttachedGui()
+        }
+    }
+}
+```
+
+## Component Props
+
+Attached GUI components receive the following props:
+
+- `object`: The sprite object (RpgClientObject) - contains all sprite properties like position, health, name, etc.
+- `onFinish`: Callback function when the GUI finishes its action
+- `onInteraction`: Callback function for GUI interactions
+
+### Example: Using Component Props
+
+```javascript
+<!-- interactive-tooltip.ce -->
+<DOMContainer>
+    <div style="background: rgba(0,0,0,0.9); color: white; padding: 10px; border-radius: 4px;">
+        <button click={() => onInteraction('action', { type: 'heal' })}>
+            Heal
+        </button>
+        <button click={() => onFinish({ result: 'closed' })}>
+            Close
+        </button>
+    </div>
+</DOMContainer>
+
+<script>
+  const { object, onFinish, onInteraction } = defineProps();
+</script>
+```
+
+### Example: Using Reactive Signals with Form Elements
+
+DOMContainer supports reactive two-way data binding for form elements using signals:
+
+```javascript
+<!-- tooltip-with-input.ce -->
+<script>
+  import { signal } from 'canvasengine'
+
+  const { object } = defineProps();
+  const inputValue = signal('')
+</script>
+
+<DOMContainer>
+    <div style="background: rgba(0,0,0,0.8); color: white; padding: 8px; border-radius: 4px;">
+        <p>Player: {object.name()}</p>
+        <input 
+            type="text" 
+            placeholder="Enter message..." 
+            value={inputValue}
+        />
+        <p>You typed: {inputValue()}</p>
+    </div>
+</DOMContainer>
+```
+
+### Example: Using Event Handlers
+
+DOMContainer supports all standard DOM events. Use the event name directly (without "on" prefix):
+
+```javascript
+<!-- interactive-tooltip.ce -->
+<script>
+  const { object, onFinish, onInteraction } = defineProps();
+
+  const handleMouseOver = (event) => {
+    console.log('Mouse over tooltip', event)
+  }
+
+  const handleMouseOut = (event) => {
+    console.log('Mouse out of tooltip', event)
+  }
+</script>
+
+<DOMContainer>
+    <div 
+        style="background: rgba(0,0,0,0.8); color: white; padding: 8px; border-radius: 4px;"
+        mouseover={handleMouseOver}
+        mouseout={handleMouseOut}
+    >
+        <p>Player: {object.name()}</p>
+        <button click={() => onInteraction('action', { type: 'heal' })}>
+            Heal
+        </button>
+    </div>
+</DOMContainer>
+```
+
+### Example: Using CSS Classes
+
+You can apply CSS classes using different formats:
+
+```javascript
+<!-- styled-tooltip.ce -->
+<script>
+  import { signal } from 'canvasengine'
+
+  const { object } = defineProps();
+  const isActive = signal(false)
+</script>
+
+<DOMContainer>
+    <!-- String format -->
+    <div class="tooltip primary-theme">
+        <p>Player: {object.name()}</p>
+    </div>
+
+    <!-- Array format -->
+    <div class={['tooltip', 'primary-theme', 'active']}>
+        <p>Player: {object.name()}</p>
+    </div>
+
+    <!-- Object format (conditional classes) -->
+    <div class={{
+        'tooltip': true,
+        'active': isActive(),
+        'inactive': !isActive()
+    }}>
+        <p>Player: {object.name()}</p>
+    </div>
+</DOMContainer>
+```
+
+### Example: Using Inline Styles
+
+You can apply styles using string or object format:
+
+```javascript
+<!-- styled-tooltip.ce -->
+<DOMContainer>
+    <!-- String format -->
+    <div style="background-color: rgba(0,0,0,0.8); color: white; padding: 8px;">
+        <p>Player: {object.name()}</p>
+    </div>
+
+    <!-- Object format -->
+    <div style={{
+        backgroundColor: 'rgba(0,0,0,0.8)',
+        color: 'white',
+        padding: '8px',
+        borderRadius: '4px',
+        fontSize: '14px'
+    }}>
+        <p>Player: {object.name()}</p>
+    </div>
+</DOMContainer>
+
+<script>
+  const { object } = defineProps();
+</script>
+```
+
+### Example: Using Forms with Automatic Data Collection
+
+DOMContainer automatically collects form data when a form is submitted:
+
+```javascript
+<!-- form-tooltip.ce -->
+<script>
+  import { signal } from 'canvasengine'
+
+  const { object, onInteraction } = defineProps();
+
+  const handleSubmit = (event, formData) => {
+    console.log('Form submitted with data:', formData)
+    // Example formData: { message: 'Hello', priority: 'high' }
+    onInteraction('form-submit', formData)
+  }
+</script>
+
+<DOMContainer>
+    <div style="background: rgba(0,0,0,0.8); color: white; padding: 10px; border-radius: 4px;">
+        <p>Player: {object.name()}</p>
+        <form submit={handleSubmit}>
+            <input name="message" type="text" placeholder="Enter message..." />
+            <select name="priority">
+                <option value="low">Low</option>
+                <option value="high">High</option>
+            </select>
+            <button type="submit">Send</button>
+        </form>
+    </div>
+</DOMContainer>
+```
+
+## Supported Events
+
+DOMContainer supports all standard DOM events. Use the event name directly (without "on" prefix):
+
+- **Mouse events**: `click`, `mouseover`, `mouseout`, `mouseenter`, `mouseleave`, `mousemove`, `mouseup`, `mousedown`
+- **Touch events**: `touchstart`, `touchend`, `touchmove`, `touchcancel`
+- **Keyboard events**: `keydown`, `keyup`, `keypress`
+- **Form events**: `submit`, `reset`, `change`, `input`, `focus`, `blur`
+- **Drag events**: `drag`, `dragend`, `dragenter`, `dragleave`, `dragover`, `drop`, `dragstart`
+- **Other events**: `wheel`, `scroll`, `resize`, `contextmenu`, `select`
+
+For more details, see the [Canvas Engine DOMContainer documentation](https://canvasengine.net/components/dom-container.html#supported-events).