Mini game engine built on top of three.js
npm install @gnsx/genesys.js
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.
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 systemsArchitecture Overview
mermaid
classDiagram
World --> InputManager
World --> Actor
Actor --> Component
Actor --> SceneComponent
SceneComponent --|> THREE.Object3D
SceneComponent --> SceneComponent
`Note that
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 devProduction 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 — 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 to compile.
2. In downstream project, update package.json:
`json
"genesys.js": "link:/path/to/genesys.js"
`
3. Run 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