Merge pull request #261 from RSamaium/v4.1.0

V4.1.0

docs/.vitepress/config.js

@@ -125,16 +125,30 @@ const guideMenu = [{
   ]
 },
 {
-  text: 'GUI Creation',
+  text: 'GUI',
   collapsed: false,
   items: [
     { text: "Customizing Your Theme", link: "/gui/theme" },
     { text: "Reusing GUI Components", link: "/gui/reuse-gui" },
     { text: "Creating Notifications in Your GUI", link: "/gui/notification-gui" },
+  ]
+},
+{
+  text: 'Create GUI with VueJS',
+  collapsed: false,
+  items: [
     { text: "Creating Your Own GUI", link: "/guide/create-gui" },
     { text: "Adding Tooltips to Your GUI", link: "/gui/tooltip" }
   ]
 },
+{
+  text: 'Create GUI with React',
+  collapsed: false,
+  items: [
+    { text: "Create Gui with React", link: "/gui/react" },
+    { text: "Adding Tooltips to Your GUI", link: "/gui/react-tooltip" }
+  ]
+},
 {
   text: 'Technical',
   collapsed: false,
@@ -145,6 +159,7 @@ const guideMenu = [{
     { text: "Supporting Gamepad Input", link: "/guide/gamepad" },
     { text: "Creating Responsive Game Design", link: "/guide/responsive-design" },
     { text: "Create Progressive Web Apps (PWA)", link: "/guide/pwa" },
+    { text: "Add TailwindCSS", link: "/guide/tailwindcss" },
     { text: "Upgrade/Update RPGJS", link: "/guide/upgrade" }
   ]
 
@@ -172,6 +187,13 @@ const pluginMenu = [{
     { text: "Creating a Title Screen Plugin", link: "/plugins/title-screen" },
     { text: "Displaying Emotion Bubbles for Characters", link: "/plugins/emotion-bubble" }
   ]
+}, 
+{
+  text: 'Unofficial Plugins',
+  collapsed: false,
+  items: [
+    { text: "Character Select", link: "/plugins/character-select" },
+  ]
 }]
 
 const GA_ID = 'G-VCPFWQS1BJ'

docs/.vitepress/theme/components/PreferenceSwitch.vue

@@ -9,7 +9,7 @@ import {
 
 const route = useRoute()
 const show = computed(() =>
-  /^\/(guide|tutorial|examples|style-guide)\//.test(route.path)
+  /^\/(guide|tutorial|examples|style-guide|gui|advanced)\//.test(route.path)
 )
 
 let isOpen = ref(true)

docs/gui/_trigger-tooltip.md

@@ -0,0 +1,122 @@
+## Trigger the GUI
+
+You have either the client side solution or the server side solution. 
+
+- Advantage on the client side: instantaneous, no communication with the server
+- Disadvantage: the server does not have the authority and cannot trigger it for all players at once
+
+On the server side, it's the opposite :)
+
+### Client Side
+
+1. you must open the menu, as usual (here, named `my-tooltip`)
+
+```ts
+RpgGui.display('my-tooltip')
+```
+
+You can open it whenever you want, for example, after loading a map
+
+<div class="module-api">
+
+```ts
+import { RpgClient, RpgModule, RpgGui } from '@rpgjs/client'
+import myTooltip from './gui/tooltip.vue'
+import sprite from './sprite'
+
+@RpgModule<RpgClient>({ 
+    scenes: {
+        map: {
+            onAfterLoading() {
+                RpgGui.display('my-tooltip')
+            }
+        }
+    },
+	sprite,
+    gui: [
+        myTooltip
+    ]
+})
+export default class RpgClientModuleEngine {}
+```
+
+<PathTo to="baseModule" file="sprite.ts" />
+
+```ts
+import { RpgSprite, RpgSpriteHooks } from '@rpgjs/client'
+
+export const sprite: RpgSpriteHooks = {
+    onInit(sprite: RpgSprite) {
+        sprite.interactive = true
+        sprite.on('click', () => {
+            sprite.guiDisplay = !sprite.guiDisplay
+        })
+    }
+}
+```
+
+</div>
+
+<div class="autoload-api">
+
+<PathTo to="baseModule" file="scene-map.ts" />
+
+```ts
+import {RpgGui } from '@rpgjs/client'
+
+export default {
+	onAfterLoading() {
+		RpgGui.display('my-tooltip')
+	}
+}
+```
+
+2. Then you can trigger the opening on the sprite
+
+<PathTo to="baseModule" file="sprite.ts" />
+
+```ts
+import { RpgSprite, RpgSpriteHooks } from '@rpgjs/client'
+
+export const sprite: RpgSpriteHooks = {
+    onInit(sprite: RpgSprite) {
+        sprite.interactive = true
+        sprite.on('click', () => {
+            sprite.guiDisplay = !sprite.guiDisplay
+        })
+    }
+}
+```
+
+Clicking on the sprite opens (or closes) the tooltip
+
+</div>
+
+
+## Server Side
+
+> Even if we are on the server side, remember to add the GUI in the client side module
+
+<PathTo to="playerFile" />
+
+```ts
+import { RpgPlayer, RpgPlayerHooks } from '@rpgjs/server'
+
+export const player: RpgPlayerHooks = {
+    onJoinMap(player: RpgPlayer) {
+        player.gui('my-tooltip').open()
+        player.showAttachedGui()
+		// you can hide with player.hideAttachedGui()
+    }
+}
+```
+
+We open the `my-tooltip` GUI and display the player's tooltip 
+
+:::tip Tip 
+You can indicate which tooltips you want to display by specifying the events (or players) in parameter: 
+
+```ts
+player.showAttachedGui([otherEvent, otherPlayer])
+```
+:::

docs/gui/react-tooltip.md

@@ -0,0 +1,35 @@
+# Create a GUI attached to a sprite
+
+## Prerequisites
+
+- Know how to create a GUI and add it in the module
+- Be comfortable with React
+- Since v4.1.0
+
+::: warning
+**Experimental Feature**: This feature is still in its experimental stage and may not be stable.
+:::
+
+## Example
+
+This is very useful to make more advanced interactions on a sprite. For example, display a tooltip or additional interactive displays.
+
+<Video src="/assets/rpgjs_gui.mp4" /> 
+
+## Create Component
+
+<PathTo to="guiDir" file="tooltip.tsx" />
+
+```tsx
+export default function MyTooltip({ spriteData }) {
+    return (
+        <span className="tooltip">
+            {spriteData.position.x}, {spriteData.position.y}
+	    </span>
+    )
+}
+
+MyTooltip.rpgAttachToSprite = true
+```
+
+<!--@include: _trigger-tooltip.md-->

docs/gui/react.md

@@ -0,0 +1,87 @@
+# Building GUI with React
+
+## Prerequisites
+
+- You must be familiar with the [React](https://react.dev) library
+- Since v4.1.0
+
+::: warning
+**Experimental Feature**: This feature is still in its experimental stage and may not be stable.
+:::
+
+## Step 1: Installation
+
+Begin by installing the necessary dependencies:
+
+```bash
+npm install react react-dom
+```
+
+## Step 2: Set Up a Basic GUI
+
+In the file <PathTo to="guiDir" file="mygui.tsx" />, create a simple React component:
+
+```tsx
+export default function MyGUI() {
+  return (
+    <div>
+      <h1>Hello World</h1>
+    </div>
+  );
+}
+```
+Name function is used for identifying the GUI. Id is `my-gui`. 
+
+> Id is Kebab Case of the name function
+
+## Step 3: Incorporate Context
+
+For more dynamic data, you can utilize the context from the RPG client and some React hooks.
+
+```tsx
+import { RpgReactContext } from '@rpgjs/client/react';
+import { useContext, useEffect, useState } from 'react';
+
+export default function MyGUI({ foo }) {
+  const { rpgCurrentPlayer } = useContext(RpgReactContext);
+  const [hp, setHp] = useState(0);
+
+  console.log(foo);
+
+  useEffect(() => {
+    rpgCurrentPlayer.subscribe(({ object }) => {
+      setHp(object.hp);
+    });
+
+    return () => {
+      rpgCurrentPlayer.unsubscribe();
+    };
+  }, []);
+
+  return (
+    <div>
+      <h1>{hp}</h1>
+    </div>
+  );
+}
+```
+
+## Step 4: Interact with the Server Side
+
+On the server side, you have the capability to open the GUI for players. 
+
+In the file <PathTo to="serverDir" file="player.ts" />:
+
+```ts
+import { RpgPlayer, RpgPlayerHooks } from '@rpgjs/server';
+
+const player: RpgPlayerHooks = {
+  onJoinMap(player: RpgPlayer) {
+    player.gui('my-gui').open({
+      foo: 'bar' // You can send props to the GUI
+    }); 
+  }
+};
+
+export default player;
+```