@directivegames/genesys.js 3.1.24

package/README.md

@@ -0,0 +1,123 @@
+[![CI](https://github.com/directivegames/genesys.js/actions/workflows/ci.yml/badge.svg)](https://github.com/directivegames/genesys.js/actions/workflows/ci.yml)
+[![Publish](https://github.com/directivegames/genesys.js/actions/workflows/publish.yml/badge.svg)](https://github.com/directivegames/genesys.js/actions/workflows/publish.yml)
+
+![Version](https://gist.githubusercontent.com/haowang1013/d024d16ac57a7bfd7038ae32bf239d07/raw/genesys.js.svg)
+
+genesys.js is a lightweight game engine built on top of [three.js](https://threejs.org/) with an architecture inspired by Unreal Engine. It provides familiar classes like World, Actor, Component, Pawn, and PlayerController for easy game development.
+
+Documentation for this repo is generated by AI and typedoc, check the `docs` folder.
+
+# Folder Structure
+Mirrored in [folder-structure.mdc](.cursor/rules/folder-structure.mdc)
+```
+project/                    # Root folder
+├── src/                    # Core engine source code
+│   ├── actors/             # Actor classes (e.g. characters, entities)
+│   ├── components/         # Reusable component classes
+│   ├── game/               # Gameplay logic (e.g. world, game loop)
+│   ├── physics/            # Physics API and implementations
+│   ├── systems/            # Individual service-like systems
+│   ├── utils/              # Utility and helper classes
+│   └── index.ts            # Main entry point for the engine module
+├── games/                  # Internal mini-games for engine feature testing
+├── scripts/                # Development and build helper scripts
+└── launcher.ts             # Web launcher entry – links to each mini-game
+```
+
+# Features
+- 🏗️ Entity-Component system architecture
+- 🎮 Built-in input management
+- ⚡ Physics simulation (Havok and Rapier)
+- 🕹️ Player controller system
+- 🏃 Character movement components
+- 🧊 Scene graph management
+- **Ragdoll Physics**: Realistic physics-based character simulation with seamless transitions between animation and physics control
+- **Integration Ready**: Works seamlessly with existing character actors and animation systems
+
+# Architecture Overview
+
+```mermaid
+classDiagram
+    World --> InputManager
+    World --> Actor
+    Actor --> Component
+    Actor --> SceneComponent
+    SceneComponent --|> THREE.Object3D
+    SceneComponent --> SceneComponent
+```
+
+Note that `SceneComponent` is also a `THREE.Object3D` so we can reuse their scene graph implementation.
+
+# Getting Started
+## Prerequisites
+- Node.js (v18+ recommended)
+- pnpm (v9+ recommended)
+## Installation
+```bash
+pnpm install
+ ```
+
+## Running the Project
+```bash
+# Development mode
+pnpm dev
+
+# Production build
+pnpm build
+ ```
+
+# Engine Versioning
+We support making backward incompatible changes in the engine but you need to follow the steps below exactly:
+- When making breaking changes (those causing existing published games fail to run without fixes), you **MUST** bump up the major version.
+- After the new major version is published to npm, create an aliased import of the previous version in [genesys.ai](https://github.com/directivegames/genesys.ai/blob/develop/package.json), example:
+  ```
+  "genesys.js": "^1.0.0",
+  "genesys.js-0": "npm:genesys.js@^0.22.40",
+  ```
+  Note that the non-aliased version is assumed to be the latest.
+- Modify [GameRuntime.ts](https://github.com/directivegames/genesys.ai/blob/develop/src/lib/games/GameRuntime.ts), add new import for the just-deprecated major version and return it, etc.
+
+As a side note, the compatible engine version is saved in the genesys project file and it's being updated by the sdk app when the project is created/opened.
+
+# How to use local genesys.js build
+There are 2 ways to use a local genesys.js build in downstream projects:
+
+| Method | Best for | Workflow overhead |
+|--------|----------|-------------------|
+| Tarball | Testing release-like builds, CI | Re-pack + re-install on each change |
+| Symlink | Active development | Build engine only, no downstream changes |
+
+## Local tarball
+1. In genesys.js, run `pnpm run pack` — builds and generates `genesys.js-{version}.tgz` in the root.
+2. In downstream project, run:
+   ```bash
+   pnpm add file:/path/to/genesys.js-{version}.tgz --force
+   ```
+3. Repeat both steps whenever the engine code changes.
+
+## Local symlink (recommended for development)
+1. In genesys.js, run `pnpm build` to compile.
+2. In downstream project, update `package.json`:
+   ```json
+   "genesys.js": "link:/path/to/genesys.js"
+   ```
+3. Run `pnpm install` to create the symlink.
+4. On subsequent engine changes, only `pnpm build` in genesys.js is needed — the downstream project picks up changes automatically via the symlink.
+
+## Workflow for testing a genesys game WITHOUT the editor
+1. Install genesys sdk CLI: `pnpm add -g genesys.sdk`
+2. In the game project, run `genesys-sdk build && pnpm dev`
+   This builds the game in the same way as the sdk launcher and run a local dev server to serve the game content via https.
+   You can incorporate the local tarball/symlink engine into this flow to test engine changes.
+3. This workflow is suitable for those focusing on the game/engine code without too much dependency on the editor features.
+
+# Roadmap
+See https://www.notion.so/TODO-LIST-1d6bf732b9bf8050a7acc1707dbf4c5e
+
+# References
+- https://fly.pieter.com/
+- https://x.com/levelsio/status/1893385114496766155
+- https://dev.hytopia.com/
+- https://playcanvas.com/
+- https://www.meshy.ai/
+- https://www.tripo3d.ai/

package/assets/animation-profiles/mixamo.skeleton-profile.json

@@ -0,0 +1,63 @@
+{
+  "name": "Mixamo",
+  "description": "Mixamo auto-rigged characters (mixamorig prefix)",
+  "hipBoneName": "mixamorigHips",
+  "scale": 0.01,
+  "positionAxisFlips": { "y": true, "z": true },
+  "hipsPositionAxisFlips": { "z": true, "y": true },
+  "boneToRole": {
+    "mixamorigHips": "Hips",
+    "mixamorigSpine": "Spine",
+    "mixamorigSpine1": "Chest",
+    "mixamorigSpine2": "UpperChest",
+    "mixamorigNeck": "Neck",
+    "mixamorigHead": "Head",
+    "mixamorigLeftShoulder": "LeftShoulder",
+    "mixamorigLeftArm": "LeftUpperArm",
+    "mixamorigLeftForeArm": "LeftLowerArm",
+    "mixamorigLeftHand": "LeftHand",
+    "mixamorigRightShoulder": "RightShoulder",
+    "mixamorigRightArm": "RightUpperArm",
+    "mixamorigRightForeArm": "RightLowerArm",
+    "mixamorigRightHand": "RightHand",
+    "mixamorigLeftUpLeg": "LeftUpperLeg",
+    "mixamorigLeftLeg": "LeftLowerLeg",
+    "mixamorigLeftFoot": "LeftFoot",
+    "mixamorigLeftToeBase": "LeftToeBase",
+    "mixamorigRightUpLeg": "RightUpperLeg",
+    "mixamorigRightLeg": "RightLowerLeg",
+    "mixamorigRightFoot": "RightFoot",
+    "mixamorigRightToeBase": "RightToeBase",
+    "mixamorigLeftHandThumb1": "LeftHandThumb1",
+    "mixamorigLeftHandThumb2": "LeftHandThumb2",
+    "mixamorigLeftHandThumb3": "LeftHandThumb3",
+    "mixamorigLeftHandIndex1": "LeftHandIndex1",
+    "mixamorigLeftHandIndex2": "LeftHandIndex2",
+    "mixamorigLeftHandIndex3": "LeftHandIndex3",
+    "mixamorigLeftHandMiddle1": "LeftHandMiddle1",
+    "mixamorigLeftHandMiddle2": "LeftHandMiddle2",
+    "mixamorigLeftHandMiddle3": "LeftHandMiddle3",
+    "mixamorigLeftHandRing1": "LeftHandRing1",
+    "mixamorigLeftHandRing2": "LeftHandRing2",
+    "mixamorigLeftHandRing3": "LeftHandRing3",
+    "mixamorigLeftHandPinky1": "LeftHandPinky1",
+    "mixamorigLeftHandPinky2": "LeftHandPinky2",
+    "mixamorigLeftHandPinky3": "LeftHandPinky3",
+    "mixamorigRightHandThumb1": "RightHandThumb1",
+    "mixamorigRightHandThumb2": "RightHandThumb2",
+    "mixamorigRightHandThumb3": "RightHandThumb3",
+    "mixamorigRightHandIndex1": "RightHandIndex1",
+    "mixamorigRightHandIndex2": "RightHandIndex2",
+    "mixamorigRightHandIndex3": "RightHandIndex3",
+    "mixamorigRightHandMiddle1": "RightHandMiddle1",
+    "mixamorigRightHandMiddle2": "RightHandMiddle2",
+    "mixamorigRightHandMiddle3": "RightHandMiddle3",
+    "mixamorigRightHandRing1": "RightHandRing1",
+    "mixamorigRightHandRing2": "RightHandRing2",
+    "mixamorigRightHandRing3": "RightHandRing3",
+    "mixamorigRightHandPinky1": "RightHandPinky1",
+    "mixamorigRightHandPinky2": "RightHandPinky2",
+    "mixamorigRightHandPinky3": "RightHandPinky3"
+  }
+}
+

package/assets/animation-profiles/rigify.skeleton-profile.json

@@ -0,0 +1,61 @@
+{
+  "name": "Rigify",
+  "description": "Blender Rigify deformation bones (DEF- prefix)",
+  "hipBoneName": "DEF-hips",
+  "boneToRole": {
+    "root": "Root",
+    "DEF-hips": "Hips",
+    "DEF-spine001": "Spine",
+    "DEF-spine002": "Chest",
+    "DEF-spine003": "UpperChest",
+    "DEF-neck": "Neck",
+    "DEF-head": "Head",
+    "DEF-shoulderL": "LeftShoulder",
+    "DEF-upper_armL": "LeftUpperArm",
+    "DEF-forearmL": "LeftLowerArm",
+    "DEF-handL": "LeftHand",
+    "DEF-shoulderR": "RightShoulder",
+    "DEF-upper_armR": "RightUpperArm",
+    "DEF-forearmR": "RightLowerArm",
+    "DEF-handR": "RightHand",
+    "DEF-thighL": "LeftUpperLeg",
+    "DEF-shinL": "LeftLowerLeg",
+    "DEF-footL": "LeftFoot",
+    "DEF-toeL": "LeftToeBase",
+    "DEF-thighR": "RightUpperLeg",
+    "DEF-shinR": "RightLowerLeg",
+    "DEF-footR": "RightFoot",
+    "DEF-toeR": "RightToeBase",
+    "DEF-thumb01L": "LeftHandThumb1",
+    "DEF-thumb02L": "LeftHandThumb2",
+    "DEF-thumb03L": "LeftHandThumb3",
+    "DEF-f_index01L": "LeftHandIndex1",
+    "DEF-f_index02L": "LeftHandIndex2",
+    "DEF-f_index03L": "LeftHandIndex3",
+    "DEF-f_middle01L": "LeftHandMiddle1",
+    "DEF-f_middle02L": "LeftHandMiddle2",
+    "DEF-f_middle03L": "LeftHandMiddle3",
+    "DEF-f_ring01L": "LeftHandRing1",
+    "DEF-f_ring02L": "LeftHandRing2",
+    "DEF-f_ring03L": "LeftHandRing3",
+    "DEF-f_pinky01L": "LeftHandPinky1",
+    "DEF-f_pinky02L": "LeftHandPinky2",
+    "DEF-f_pinky03L": "LeftHandPinky3",
+    "DEF-thumb01R": "RightHandThumb1",
+    "DEF-thumb02R": "RightHandThumb2",
+    "DEF-thumb03R": "RightHandThumb3",
+    "DEF-f_index01R": "RightHandIndex1",
+    "DEF-f_index02R": "RightHandIndex2",
+    "DEF-f_index03R": "RightHandIndex3",
+    "DEF-f_middle01R": "RightHandMiddle1",
+    "DEF-f_middle02R": "RightHandMiddle2",
+    "DEF-f_middle03R": "RightHandMiddle3",
+    "DEF-f_ring01R": "RightHandRing1",
+    "DEF-f_ring02R": "RightHandRing2",
+    "DEF-f_ring03R": "RightHandRing3",
+    "DEF-f_pinky01R": "RightHandPinky1",
+    "DEF-f_pinky02R": "RightHandPinky2",
+    "DEF-f_pinky03R": "RightHandPinky3"
+  }
+}
+

package/assets/character/config/AnimationStateMachineComponent.md

@@ -0,0 +1,107 @@
+# Animation State Machine Configuration
+
+## AnimationStateMachineOptions
+
+- **autoPlay**: (boolean) Determines if the default animation should start playing automatically when the component begins play.
+
+- **parameters**: (object) A key-value map where keys are parameter names and values are their initial states. These parameters control state transitions and animation blending.
+  - Example: 
+    ```json
+    {
+      "isRunning": false,
+      "isJumping": false,
+      "forward": 0,
+      "back": 0,
+      "left": 0,
+      "right": 0
+    }
+    ```
+
+- **states**: (object) A collection of animation states, each defined by a unique state name.
+  - **State Properties**:
+    - **clip**: (string or array of strings) The name of the animation clip to play in this state, or an array of clip names. If an array, a random clip is selected each time the state is entered.
+    - **blend**: (array) A list of objects defining multiple clips to blend, each with:
+      - **clip**: (string) The name of the clip.
+      - **weight**: (number, optional) A static weight for the clip.
+      - **weightParam**: (string, optional) A parameter name whose value determines the clip's weight.
+    - **transitions**: (array) A list of transitions to other states, each with:
+      - **to**: (string) The target state name.
+      - **condition**: (object) A set of conditions that must be met for the transition, using parameter values.
+        - Special: `{ "clipFinished": true }` triggers the transition when the current state's animation clip finishes playing (useful for one-shot or non-looping clips).
+      - **blendDuration**: (number, optional) The duration of the blend transition in seconds.
+
+- **initialState**: (string) The name of the state to start in when the component begins play.
+
+- **clipOptions**: (object) Configuration for individual animation clips, with each clip name as a key.
+  - **Clip Option Properties**:
+    - **loop**: (string) The loop type for the clip, such as 'LoopOnce', 'LoopRepeat', or 'LoopPingPong'.
+    - **clampWhenFinished**: (boolean, optional) Whether the animation should stop at the last frame when finished.
+    - **blendMode**: (string, optional) The blend mode for the clip, such as 'NormalAnimationBlendMode' or 'AdditiveAnimationBlendMode'.
+
+---
+
+## One-Shot Clips
+
+- **oneShotClips**: (array of strings) List of animation clip names that can be triggered as one-shots.
+  - When a one-shot is triggered (via the `playOneShot(clipName)` method), the state machine is paused, the one-shot animation plays, and then the state machine resumes from where it left off.
+  - Example:
+    ```json
+    "oneShotClips": ["Wave_01", "Victory_01"]
+    ```
+
+---
+
+## Global Transitions (from Any State)
+
+- You can define transitions that apply from any state using the reserved state key `"__any__"` in your `states` object.
+- Transitions under `"__any__"` are checked before the current state's transitions.
+- Example:
+  ```json
+  "states": {
+    "__any__": {
+      "transitions": [
+        { "to": "Jump", "condition": { "inAir": true }, "blendDuration": 0.5 }
+      ]
+    },
+    "Idle": { ... },
+    ...
+  }
+  ```
+- **Note:** `"__any__"` is not a real state and cannot have a clip or blend. It is only for defining global transitions.
+
+---
+
+## Transition Evaluation Order
+
+1. **Global transitions** (from `"__any__"`) are checked first.
+2. If no global transition matches, the current state's transitions are checked.
+3. If a transition matches, the state machine transitions to the target state and plays/blends the new state's animation(s).
+
+---
+
+## Clip Finished Transition Condition
+
+- You can trigger a transition when the current state's animation clip finishes playing by using the special condition `{ "clipFinished": true }` in a transition.
+- This is especially useful for one-shot or non-looping clips (e.g., attacks, emotes, jumps) where you want to automatically return to Idle or another state after the animation completes.
+- Example:
+  ```json
+  "transitions": [
+    { "to": "Idle", "condition": { "clipFinished": true }, "blendDuration": 0.3 }
+  ]
+  ```
+- The state machine will detect when the current state's animation finishes and immediately trigger any transition with this condition.
+
+---
+
+## Advanced Usage & Best Practices
+
+- Use arrays for `clip` to add variety to idle, attack, or emote states.
+- Use one-shot clips for emotes, gestures, or actions that should temporarily interrupt the state machine.
+- Use `"__any__"` transitions for global interrupts (e.g., jumping, dying, or reacting to a global event).
+- Avoid naming real states `__any__` to prevent confusion.
+- For complex blends, use the `blend` property with parameter-driven weights.
+- Always ensure your state names in transitions match the actual state keys.
+
+---
+
+This setup allows you to define a comprehensive animation state machine, where each state can have its own animation logic, transitions based on parameter conditions, and specific clip behaviors. This flexibility supports complex animation sequences and dynamic character behaviors. 

package/assets/character/config/mannequin-anim.json

@@ -0,0 +1,53 @@
+{
+  "parameters": {
+    "isRunning": false,
+    "isJumping": false,
+    "forward": 0,
+    "back": 0,
+    "left": 0,
+    "right": 0
+  },
+  "initialState": "idle",
+  "externalAnimationSources": [
+    "/assets/character/mannequin.glb"
+  ],
+  "oneShotClips": [
+    "Jump", "StrafeRight"
+  ],
+  "states": {
+    "idle": {
+      "clip": "Idle",
+      "transitions": [
+        { "to": "run", "condition": { "isRunning": true, "isJumping": false }, "blendDuration": 0.2 },
+        { "to": "jump", "condition": { "isJumping": true }, "blendDuration": 0.2 }
+      ]
+    },
+    "run": {
+      "blend": [
+        { "clip": "Run", "weightParam": "forward" },
+        { "clip": "RunBackward", "weightParam": "back" },
+        { "clip": "StrafeRight", "weightParam": "right" },
+        { "clip": "StrafeLeft", "weightParam": "left" }
+      ],
+      "transitions": [
+        { "to": "idle", "condition": { "isRunning": false, "isJumping": false }, "blendDuration": 0.2 },
+        { "to": "jump", "condition": { "isJumping": true }, "blendDuration": 0.2 }
+      ]
+    },
+    "jump": {
+      "clip": "Jump",
+      "transitions": [
+        { "to": "idle", "condition": { "isJumping": false, "isRunning": false }, "blendDuration": 0.2 },
+        { "to": "run", "condition": { "isJumping": false, "isRunning": true }, "blendDuration": 0.2 }
+      ]
+    }
+  },
+  "clipOptions": {
+    "Run": { "loop": "LoopRepeat" },
+    "RunBackward": { "loop": "LoopRepeat" },
+    "StrafeLeft": { "loop": "LoopRepeat" },
+    "StrafeRight": { "loop": "LoopRepeat" },
+    "Idle": { "loop": "LoopRepeat" },
+    "Jump": { "loop": "LoopOnce" }
+  }
+} 

package/assets/default.genesys-scene

@@ -0,0 +1,194 @@
+{
+  "$version": 0,
+  "class": "ENGINE.World",
+  "uuid": "c0ae85792bc3b946",
+  "ctor": {
+    "backgroundColor": "#2E2E2E",
+    "navigationOptions": {
+      "engine": "recast-navigation",
+      "debug": false,
+      "generateOnStartUp": false
+    },
+    "physicsOptions": {
+      "gravity": [
+        0,
+        -9.81,
+        0,
+        "v"
+      ],
+      "engine": "rapier"
+    },
+    "useManifold": true
+  },
+  "actors": [
+    {
+      "uuid": "9a86d389088b361c",
+      "class": "ENGINE.Actor",
+      "properties": {
+        "editorData": {
+          "displayName": "Directional Light",
+          "hidden": false
+        }
+      },
+      "ctor": {
+        "rootComponent": {
+          "class": "ENGINE.DirectionalLightComponent",
+          "uuid": "cfe05433-9edc-4dfe-a535-c71f33e92d78",
+          "ctor": {
+            "color": 16777215,
+            "intensity": 1,
+            "castShadow": true,
+            "shadowMapSize": 2048,
+            "shadowBias": 0,
+            "shadowNormalBias": 0,
+            "shadowNear": 0.1,
+            "shadowFar": 100
+          },
+          "properties": {
+            "position": [
+              10,
+              50,
+              -10,
+              "v"
+            ],
+            "castShadow": true
+          }
+        }
+      }
+    },
+    {
+      "uuid": "9d428f2a16e5374a",
+      "class": "ENGINE.Actor",
+      "properties": {
+        "editorData": {
+          "displayName": "Ground",
+          "hidden": false
+        }
+      },
+      "ctor": {
+        "rootComponent": {
+          "class": "ENGINE.MeshComponent",
+          "uuid": "71caea24-62d7-4e45-a76e-4c7519de2c3c",
+          "ctor": {
+            "geometry": {
+              "class": "THREE.BoxGeometry",
+              "ctor": [
+                500,
+                0.1,
+                500
+              ]
+            },
+            "material": {
+              "@external": "DefaultMaterial"
+            },
+            "uvScaleTilesPerUnit": 0.2
+          },
+          "properties": {
+            "position": [
+              0,
+              -0.9,
+              0,
+              "v"
+            ],
+            "receiveShadow": true,
+            "name": "MeshComponent"
+          }
+        }
+      }
+    },
+    {
+      "uuid": "b87cbc5e60a2e54c",
+      "class": "ENGINE.PlayerStart",
+      "properties": {
+        "editorData": {
+          "displayName": "Player Start",
+          "hidden": false
+        }
+      },
+      "ctor": {
+        "rootComponent": {
+          "class": "ENGINE.SceneComponent",
+          "uuid": "b4d5f8f7-2512-45e1-9157-c7ff6772402d",
+          "properties": {
+            "position": [
+              -69.7,
+              41.4,
+              46.3,
+              "v"
+            ]
+          }
+        }
+      }
+    },
+    {
+      "uuid": "0ba1f4677e8370d1",
+      "class": "ENGINE.Actor",
+      "properties": {
+        "editorData": {
+          "displayName": "Skybox",
+          "hidden": false
+        }
+      },
+      "ctor": {
+        "rootComponent": {
+          "class": "ENGINE.SceneComponent",
+          "uuid": "195e88df-73ff-4f4b-82ae-7fb58671463d",
+          "children": [
+            {
+              "class": "ENGINE.SkyboxComponent",
+              "uuid": "f7e33ae7d5ac74f9",
+              "ctor": {
+                "textureUrl": "@engine/assets/textures/skybox/citrus_orchard_road_puresky_2k.hdr",
+                "width": 2048,
+                "height": 1024,
+                "bottomColor": "#E6F3FF",
+                "middleColor": "#4A90E2",
+                "topColor": "#0F1B3C",
+                "envMapIntensity": 1,
+                "backgroundIntensity": 1,
+                "backgroundBlurriness": 0,
+                "envMapRotation": [
+                  0,
+                  0,
+                  0,
+                  "e"
+                ]
+              }
+            }
+          ]
+        }
+      }
+    }
+  ],
+  "properties": {
+    "editorData": {
+      "sceneTree": {
+        "id": "c0ae85792bc3b946",
+        "nodeType": "scene",
+        "children": [
+          {
+            "id": "9a86d389088b361c",
+            "nodeType": "actor"
+          },
+          {
+            "id": "9d428f2a16e5374a",
+            "nodeType": "actor"
+          },
+          {
+            "id": "b87cbc5e60a2e54c",
+            "nodeType": "actor"
+          },
+          {
+            "id": "0ba1f4677e8370d1",
+            "nodeType": "actor"
+          },
+          {
+            "id": "fb83cb0e01ffbb8f",
+            "nodeType": "actor"
+          }
+        ]
+      }
+    },
+    "postProcessConfiguration": null
+  }
+}