@deathlegion/huy.js
v1.0.0
Published
A lightweight, easy-to-use 3D graphics library for the web — by Death Legion Team
Maintainers
deathlegionReadme
huy.js
A lightweight, easy-to-use 3D graphics library for the web — built from scratch by the Death Legion Team.
✨ Features
- Zero dependencies — every line written from scratch
- WebGL / WebGL2 — auto-detects the best available API
- Simple API — get a 3D scene running in 15 lines of code
- Scene graph — hierarchical parent/child object relationships
- Blinn-Phong shading — built-in lit material with ambient, diffuse, and specular
- Multiple light types — ambient, directional, and point lights (up to 4 of each)
- Geometry primitives — box, sphere, plane, cylinder, and cone
- VR/AR ready — forward-compatible WebXR hooks
- Lightweight — minimal footprint, fast startup
🚀 Quick Start
<!DOCTYPE html>
<html>
<body>
<canvas id="c"></canvas>
<script type="module">
import {
Scene, PerspectiveCamera, BoxGeometry, PhongMaterial,
Mesh, AmbientLight, DirectionalLight, WebGLRenderer,
AnimationLoop
} from './src/huy.js';
// 1. Scene + Camera
const scene = new Scene();
const camera = new PerspectiveCamera(60, innerWidth/innerHeight, 0.1, 100);
camera.position.set(0, 1.5, 4);
camera.lookAt(0, 0, 0);
// 2. A spinning cube
const cube = new Mesh(new BoxGeometry(), new PhongMaterial(0xff4466));
scene.add(cube);
// 3. Lights
scene.add(new AmbientLight(0x404040));
const sun = new DirectionalLight(0xffffff, 1);
sun.position.set(3, 5, 2);
scene.add(sun);
// 4. Renderer + Animation
const renderer = new WebGLRenderer(document.getElementById('c'));
renderer.setSize(innerWidth, innerHeight);
new AnimationLoop((t, dt) => {
cube.rotateY(dt);
renderer.render(scene, camera);
}).start();
window.onresize = () => {
renderer.setSize(innerWidth, innerHeight);
camera.aspect = innerWidth / innerHeight;
camera.updateProjectionMatrix();
};
</script>
</body>
</html>📁 Project Structure
huy.js/
├── src/
│ ├── huy.js ← Main entry point (import from here)
│ ├── math/
│ │ ├── Vec3.js 3D vector
│ │ ├── Vec4.js 4D vector
│ │ ├── Mat4.js 4×4 matrix (column-major)
│ │ ├── Quaternion.js Unit quaternion
│ │ └── Euler.js Euler angles
│ ├── core/
│ │ ├── Object3D.js Base scene object
│ │ ├── Scene.js Root scene container
│ │ ├── Camera.js Camera base
│ │ ├── PerspectiveCamera.js
│ │ └── OrthographicCamera.js
│ ├── geometry/
│ │ ├── Geometry.js Vertex buffer container
│ │ ├── BoxGeometry.js
│ │ ├── SphereGeometry.js
│ │ ├── PlaneGeometry.js
│ │ └── CylinderGeometry.js
│ ├── material/
│ │ ├── Material.js Base material
│ │ ├── BasicMaterial.js Unlit (flat color)
│ │ ├── PhongMaterial.js Blinn-Phong lit
│ │ └── WireframeMaterial.js
│ ├── objects/
│ │ ├── Mesh.js Geometry + Material
│ │ └── Lights.js Ambient, Directional, Point
│ ├── renderer/
│ │ ├── WebGLRenderer.js Core rendering engine
│ │ └── ShaderSource.js Built-in GLSL shaders
│ ├── animation/
│ │ ├── AnimationLoop.js requestAnimationFrame loop
│ │ └── Clock.js High-precision timer
│ ├── utils/
│ │ └── Color.js RGB color class
│ └── vr/
│ └── VRManager.js WebXR integration stubs
├── demos/
│ ├── quick-start.html Minimal 15-line example
│ ├── spinning-cube.html Animated cube with stats
│ └── multi-object.html Multiple objects + mouse orbit
├── docs/
│ └── index.html Full API documentation
└── package.json📖 API Overview
Scene Setup
| Class | Description |
|-------|-------------|
| Scene | Root container for objects and lights |
| PerspectiveCamera(fov, aspect, near, far) | Standard 3D camera |
| OrthographicCamera(l, r, t, b, n, f) | Parallel projection camera |
Geometry
| Class | Description |
|-------|-------------|
| BoxGeometry(w, h, d) | Cube / rectangular box |
| SphereGeometry(r, wSeg, hSeg) | UV sphere |
| PlaneGeometry(w, h) | Flat plane |
| CylinderGeometry(rTop, rBot, h) | Cylinder / cone |
Material
| Class | Description |
|-------|-------------|
| BasicMaterial(color) | Unlit solid color |
| PhongMaterial(color) | Blinn-Phong lit material |
| WireframeMaterial(color) | Wireframe-only rendering |
Lighting
| Class | Description |
|-------|-------------|
| AmbientLight(color, intensity) | Uniform omnidirectional light |
| DirectionalLight(color, intensity) | Parallel rays (sunlight) |
| PointLight(color, intensity, distance, decay) | Point source with falloff |
Rendering
| Class | Description |
|-------|-------------|
| WebGLRenderer(canvas, options) | WebGL rendering engine |
| AnimationLoop(callback) | Frame loop with delta time |
| Clock | High-precision timer |
Math
| Class | Description |
|-------|-------------|
| Vec3 | 3D vector with arithmetic & geometry ops |
| Vec4 | 4D vector |
| Mat4 | 4×4 column-major matrix |
| Quaternion | Unit quaternion for rotations |
| Euler | Euler angle representation |
| Color | RGB color (hex, CSS, float) |
🥽 VR / AR Support
huy.js includes forward-compatible WebXR integration:
import { VRManager } from './src/huy.js';
const vr = new VRManager(renderer);
// Check support
const vrOK = await vr.isVRSupported();
const arOK = await vr.isARSupported();
// Start immersive session
if (vrOK) await vr.startVR();
// End session
await vr.endSession();Current: API surface and capability detection
Planned: Stereo rendering, controller input, hand tracking, AR hit testing, anchors, and light estimation.
🎮 Demos
| Demo | Description |
|------|-------------|
| demos/quick-start.html | Minimal 15-line spinning cube |
| demos/spinning-cube.html | Animated cube with FPS stats |
| demos/multi-object.html | Box, sphere, cylinder + lights + mouse orbit |
Open any demo in a browser (use a local server for ES module support):
npx http-server . -p 8080 -c-1
# Then open http://localhost:8080/demos/quick-start.html🛠️ Building from Source
No build step required! huy.js uses native ES modules. Just serve the files with any HTTP server.
📄 License
MIT License — © Death Legion Team
huy.js — Lightweight 3D for the web. By Death Legion Team.