unit_three

@vmlibs/unit_three is a TypeScript library built on top of Three.js to help create game-like scenes, objects, managers, and visual effects with a reusable engine-style architecture.

What this library provides

• Three.js-based core runtime (GameCore) and high-level manager (GameManager)
• Scene composition helpers (Scenary, skybox/floor/background setup)
• Object and component system (GameObject, GameComponent, mesh/light/rigidbody/collider/skybox components)
• Editor-oriented interactions (TransformControls, selection, object manipulation hooks)
• Built-in managers for input, HUD, lighting, collisions, rigid body orchestration, scene state control
• Visual effects helpers (for example FireParticles)
• Typed API surface for scenary/game options and engine events

Installation

npm install @vmlibs/unit_three three

Peer ecosystem used by this library:

• three
• @dimforge/rapier3d-compat
• dat.gui
• rxjs

Quick start

import { GameManager } from '@vmlibs/unit_three';

const game = new GameManager({
  gameOptions: {
    showFps: true,
    isEditor: true,
  },
  initScene: {
    scenaryOptions: {
      skybox: {
        images: {
          front: '/assets/barren_ft.jpg',
          back: '/assets/barren_bk.jpg',
          left: '/assets/barren_lf.jpg',
          right: '/assets/barren_rt.jpg',
          up: '/assets/barren_up.jpg',
          down: '/assets/barren_dn.jpg',
        },
        size: 300,
      },
      floor: {
        primitiveType: 'plane',
        gameObjectName: 'floor',
        width: 200,
        height: 200,
      },
    },
    charactersOptions: [],
    objectsOptions: [],
  },
});

Main exports

From package root:

• THREE (re-exported Three.js namespace from shared constants)
• GameManager
• GameObject
• GameComponent
• All public types exports (GameOptions, IScenary, ISceneOptions, etc.)
• VFX exports (FireParticles)
• testIsFromPackage helper

Entry files:

• src/index.ts exports package root API
• src/scripts/index.ts exports managers/common engine primitives
• src/types/index.ts exports public type contracts
• src/vfx/index.ts exports effects

Core concepts

1. Engine core

GameCore handles renderer/camera setup, controls, input, resize lifecycle, and update loop infrastructure.

2. Manager layer

GameManager extends GameCore and centralizes scene states, game object selection, physics debug overlays, and editor actions.

3. Scene composition

Scenary composes:

• Skybox
• Floor mesh
• Directional background groups (north/south/east/west)

4. Components and objects

Objects are built and updated through component abstractions (GameMeshComponent, GameLightComponent, GameSkyboxComponent, GameRigidBodyComponent, GameColliderComponent, etc.).

Development

Build

npm run build

Build pipeline uses tsup and generates:

• CommonJS (dist/**/*.js)
• ESM (dist/**/*.mjs)
• Type declarations (dist/**/*.d.ts)
• Source maps

Test

npm test

Jest is configured with ts-jest and matches tests under:

• src/__tests__/**/*.test.ts
• **/?(*.)+(spec|test).ts

Repository structure (high level)

src/
  factory/        # mesh/box/skybox and primitive factories
  scripts/        # core runtime, managers, components, scenes, states
  types/          # public TypeScript contracts
  vfx/            # effects modules
  examples/       # example/demo implementations
  __tests__/      # unit tests

Package metadata

• Package: @vmlibs/unit_three
• Version: 1.0.0
• Author: Vitor Machado
• License: ISC

Notes

• The library is browser-focused (Three.js renderer + DOM integration).
• Some editor/debug behaviors depend on runtime scene setup and object metadata (gameObjectName in userData).