Three64 Engine

A lightweight Three.js-based engine with Ammo.js physics and a Blender-driven authoring workflow.

Default engine settings are set to emulate the Nintendo64's constraints.

This README is a quick-start. Full docs live in src/docs/pages/ and render directly on GitHub.

Features

• Three.js renderer with scene/skybox management
• Ammo.js physics (rigidbodies, raycasts)
• AI navigation (navmesh + agent steering)
• Character controller and locomotion
• Event and input systems
• UI system (HUD, stat bars)
• Inventory and item framework
• Particles and projectile utilities
• Audio system
• Loading screen and main/settings menus
• Asset pipeline + Blender add-on/exporter
• Browser-based scene editor

Requirements

• Node.js 18+

Install

npm install

Develop (watch + live reload)

npm run dev
# open http://localhost:5173

Build (outputs to public/build)

npm run build

Serve static (no watch)

npm run serve
# then open http://localhost:5173/

Scene Editor

npm run editor
# open http://localhost:3664

A browser-based scene authoring tool for placing GLTF objects, assigning components, and configuring their properties. All data is written into GLTF userData so the engine loads it directly.

• Assets panel (left) lists models from src/assets/models/. Click one to enter placement mode, then click in the viewport to stamp it.
• Viewport (center) shows the 3D scene. Orbit with mouse drag, zoom with scroll. Click objects to select them. Transform gizmos appear on the selected object.
• Hierarchy (top-right) shows the scene tree. Right-click for duplicate/delete/rename.
• Inspector (bottom-right) shows the selected object's name, transform, and components. Use the dropdown to add components; each one expands into a property editor auto-generated from the engine's paramDescriptions.
• Toolbar shortcuts: W translate, E rotate, R scale, Delete remove, Ctrl+D duplicate, Ctrl+S save, F focus, Escape deselect.
• Save writes the GLB back to src/assets/models/ via the editor server. Export downloads the GLB to your browser.

To use a different port: npm run editor -- --port=3665

The editor is a dev-only tool. It is not included in npm run build output. See full editor documentation for details on the API, GLTF round-tripping, and file structure.

Start relay server

node server.js
# then open two browser windows http://localhost:5173/?lan=true (Connects to localhost:8080)

Notes:

• Production builds disable dev mode and do not include /public/docs.
• Entry: src/runtime/engine.js → Output: public/build/runtime.js.

In development, press F1 for the debug overlay. An “Open Docs” button appears there (dev-only). Production builds keep dev features disabled.

Documentation

• Getting Started
  • Intro
  • Setup & Build
  • Scene Conventions
  • Assets Folder Structure
• Asset Authoring
  • Asset Authoring (Blender)
  • Blender add-on README
  • Scene Editor
• API
  • Architecture Overview
  • Runtime Overview
  • Runtime Modules
    • Agent
    • Archetypes
    • Asset Loader
    • Audio System
    • Character Controller
    • Component
    • Debug
    • Engine
    • Event System
    • Healthbar Component
    • Input
    • Inventory
    • IO
    • Item
    • Loading Screen
    • Navmesh
    • Network
    • Particle System
    • Physics
    • Player
    • Pool
    • Projectile
    • Raycaster
    • Renderer
    • Rigidbody
    • Scene
    • Skybox
    • Statistic
    • Statistic Bar
    • UI System
    • Volume