genesys.js is a lightweight game engine built on top of three.js 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

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

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

pnpm install

Running the Project

# 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, 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, 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:

   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:

   "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/