feat(animation): add custom animation support

- Extend AnimationSet type to include custom actions
- Implement setCustomAnimation function for invoking custom animations

Author: DavideBruner

readme.md

@@ -13,6 +13,36 @@
 
 ## New Features
 
+### (2024-04-23) Custom AnimationSet actions:
+
+- Introduces support for defining custom actions in the animations set and invoking them using the setCustomAnimation function.
+
+#### Usage Example:
+
+```js
+import { useGame } from "ecctrl";
+
+const animationSet = {
+  idle: "Idle",
+  walk: "Walk",
+  run: "Run",
+  .....
+  // Custom action
+  custom: {
+    fly: "Fly"
+  }
+};
+
+// ...
+const setCustomAnimation = useGame((state) => state.setCustomAnimation);
+// ...
+setCustomAnimation("fly");
+```
+
+#### Note:
+
+Ensure to update your `animationSet` accordingly to include any custom animations you wish to use in your game.
+
 ### (2024-1-1) EcctrlMode:
 
 - Now you can seamlessly switch between different modes by adding "mode" inside Ecctrl.
@@ -170,8 +200,8 @@ EcctrlProps: {
   autoBalance: true, // Enable auto-balance
   autoBalanceSpringK: 0.3, // Auto-balance spring constant
   autoBalanceDampingC: 0.03, // Auto-balance damping coefficient
-  autoBalanceSpringOnY: 0.5, // Auto-balance spring on Y-axis 
-  autoBalanceDampingOnY: 0.015, // Auto-balance damping on Y-axis 
+  autoBalanceSpringOnY: 0.5, // Auto-balance spring on Y-axis
+  autoBalanceDampingOnY: 0.015, // Auto-balance damping on Y-axis
   // Animation temporary setups
   animated: false, // Enable animation
   // Mode setups
@@ -425,7 +455,7 @@ pressButton1();
 
 ### Ecctrl Mode
 
-Activate different modes in Ecctrl by including the desired mode inside Ecctrl component: 
+Activate different modes in Ecctrl by including the desired mode inside Ecctrl component:
 `<Ecctrl mode="PointToMove">`.
 
 #### 1. "PointToMove" Mode ([CodeSandbox Demo](https://codesandbox.io/p/sandbox/ecctrl-pointtomove-m9z6xh?file=%2Fsrc%2FMap.js%3A46%2C19))

src/stores/useGame.ts

@@ -47,6 +47,14 @@ export const useGame = /* @__PURE__ */ create(
             state.curAnimation !== state.animationSet.action3 &&
             state.curAnimation !== state.animationSet.action4
           ) {
+            if (
+              state.animationSet?.custom &&
+              Object.values(state.animationSet?.custom).includes(
+                state.curAnimation
+              )
+            ) {
+              return {};
+            }
             return { curAnimation: state.animationSet.idle };
           }
           return {};
@@ -144,11 +152,17 @@ export const useGame = /* @__PURE__ */ create(
       /**
        * Additional animations
        */
-      // triggerFunction: ()=>{
-      //    set((state) => {
-      //        return { curAnimation: state.animationSet.additionalAnimation };
-      //    });
-      // }
+      setCustomAnimation: (animation: string) => {
+        set((state) => {
+          if (
+            state.animationSet.custom[animation] &&
+            state.curAnimation === state.animationSet.idle
+          ) {
+            return { curAnimation: state.animationSet.custom[animation] };
+          }
+          return { curAnimation: state.animationSet.idle };
+        });
+      },
 
       /**
        * Set/get point to move point
@@ -196,6 +210,8 @@ export type AnimationSet = {
   action2?: string;
   action3?: string;
   action4?: string;
+  // Custom actions
+  custom?: Record<string, string>;
 };
 
 type State = {
@@ -208,11 +224,12 @@ type State = {
   setMoveToPoint: (point: THREE.Vector3) => void;
   getMoveToPoint: () => {
     moveToPoint: THREE.Vector3;
-  }
+  };
   setCameraBased: (isCameraBased: boolean) => void;
   getCameraBased: () => {
     isCameraBased: boolean;
-  }
+  };
+  setCustomAnimation: (animation: string) => void;
 } & {
-  [key in keyof AnimationSet]: () => void;
+  [key in keyof Omit<AnimationSet, "custom">]: () => void;
 };