npm - orbix-engine - Versions diffs - 1.0.0 → 1.0.1 - Mend

orbix-engine 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Orbix Engine Contributors
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,961 @@
+# Orbix Engine
+**GPU-accelerated WebGL engine** — fluid simulations, particle systems, post-processing, physics, audio, VR/AR, and more. One script tag, zero dependencies, works on desktop and mobile.
+```html
+<script src="https://unpkg.com/orbix-engine@1.0.1/dist/orbix.min.js"></script>
+```
+```html
+<script src="https://cdn.jsdelivr.net/npm/orbix-engine@1.0.1/dist/orbix.min.js"></script>
+```
+---
+## Hello World
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <style>* { margin: 0 } body { background: #000; overflow: hidden }</style>
+</head>
+<body>
+<script src="https://unpkg.com/orbix-engine@1.0.1/dist/orbix.min.js"></script>
+<script>
+Orbix.ready().then(function() {
+  var cube = new Mesh(
+    new BoxGeometry(2, 2, 2),
+    new Shader('ColorMaterial', {
+      unique: true,
+      color: { value: new Color(0.2, 0.5, 1.0) },
+      alpha: { value: 1.0 }
+    })
+  );
+  World.SCENE.add(cube);
+  World.CAMERA.position.z = 6;
+  Render.start(function() {
+    cube.rotation.x += 0.01;
+    cube.rotation.y += 0.02;
+  });
+});
+</script>
+</body>
+</html>
+```
+---
+## Install
+| Method | URL |
+|--------|-----|
+| unpkg CDN | `https://unpkg.com/orbix-engine@1.0.1/dist/orbix.min.js` |
+| jsDelivr CDN | `https://cdn.jsdelivr.net/npm/orbix-engine@1.0.1/dist/orbix.min.js` |
+| npm | `npm install orbix-engine` |
+### npm / bundler
+```js
+import Orbix, { Mesh, BoxGeometry, Shader, Color, Render, World } from 'orbix-engine';
+Orbix.ready().then(() => { /* ... */ });
+```
+---
+## Core Concepts
+### `Orbix.ready()`
+All engine use must happen inside the `.ready()` promise. The engine boots asynchronously (WebGL context, shader compilation, internal asset loading). Calling it multiple times is safe — each call gets its own Promise.
+```js
+Orbix.ready().then(function() {
+  // safe to use any Orbix class here
+});
+// or async/await
+async function main() {
+  await Orbix.ready();
+  // ...
+}
+```
+### `Orbix.check()`
+Returns support information before loading the full bundle:
+```js
+var info = Orbix.check();
+// { supported: true, webgl: true, mobile: false, gpu: 'Apple M2', tier: 'high' }
+```
+---
+## API Reference
+### Globals available after `ready()`
+All classes and constants listed below are also available directly on `window` (or the `Orbix` namespace). You can use `new Mesh(...)` or `new Orbix.Mesh(...)` interchangeably.
+---
+### Boot
+| Symbol | Description |
+|--------|-------------|
+| `Orbix.ready()` | Returns `Promise` — resolves when engine is fully booted |
+| `Orbix.check()` | Returns `{ supported, webgl, mobile, gpu, tier }` — safe to call before load |
+| `Orbix.VERSION` | Semver string |
+| `Orbix.supported` | Boolean — `false` if WebGL unavailable |
+---
+### World & Rendering
+| Symbol | Description |
+|--------|-------------|
+| `World.SCENE` | The root `Scene` — add your objects here |
+| `World.CAMERA` | Default `PerspectiveCamera` |
+| `World.RENDERER` | The `Renderer` instance |
+| `World.NUKE` | Post-processing pipeline |
+| `World.ELEMENT` | The `<canvas>` DOM element |
+| `Render.start(fn)` | Register a per-frame callback `(time, dt) => void` |
+| `Render.stop(fn)` | Remove a callback |
+| `Render.fps` | Current frames per second |
+```js
+Render.start(function(time, dt) {
+  mesh.rotation.y += dt * 2;
+});
+```
+---
+### 3D Objects
+| Class | Constructor | Description |
+|-------|-------------|-------------|
+| `Mesh` | `(geometry, shader)` | A visible 3D object |
+| `Group` | `()` | Container to transform multiple objects together |
+| `Scene` | `()` | Root container (use `World.SCENE` by default) |
+| `Points` | `(geometry, shader)` | Point cloud |
+| `Line3D` | `(geometry, shader)` | Line strip |
+| `Object3D` | `()` | Base class — position, rotation, scale, matrix |
+Every 3D object has:
+```js
+mesh.position.set(x, y, z)
+mesh.rotation.x = Math.PI / 4
+mesh.scale.setScalar(2)
+mesh.visible = false
+mesh.add(child)
+mesh.remove(child)
+mesh.traverse(fn)
+mesh.dispose()
+```
+---
+### Geometry
+| Class | Constructor |
+|-------|-------------|
+| `PlaneGeometry` | `(width, height, widthSegs, heightSegs)` |
+| `BoxGeometry` | `(width, height, depth, wSegs, hSegs, dSegs)` |
+| `SphereGeometry` | `(radius, widthSegs, heightSegs)` |
+| `CylinderGeometry` | `(radiusTop, radiusBottom, height, radialSegs)` |
+| `IcosahedronGeometry` | `(radius, detail)` |
+| `Geometry` | Base — set `attributes` and `index` manually |
+```js
+// Custom geometry
+var geo = new Geometry();
+geo.addAttribute('position', new GeometryAttribute(new Float32Array([...]), 3));
+geo.setIndex([0, 1, 2]);
+geo.computeVertexNormals();
+```
+**Loaders:**
+```js
+// Load from web worker thread (non-blocking)
+GeomThread.loadGeometry('/model.bin').then(function(geo) { ... });
+// Draco-compressed
+DracoThread.decode(buffer).then(function(geo) { ... });
+// GLTF
+var loader = new GLTFLoader();
+loader.load('/scene.glb', function(gltf) {
+  World.SCENE.add(gltf.scene);
+});
+// Spline paths
+var spline = new SplineGen(points, closed);
+var pt = spline.getPoint(0.5); // Vector3 at t=0.5
+```
+---
+### Shaders & Materials
+#### Built-in: `ColorMaterial`
+The simplest shader — a flat color with optional transparency.
+```js
+new Shader('ColorMaterial', {
+  unique: true,                          // each mesh gets its own uniform copy
+  color: { value: new Color(1, 0, 0) }, // RGB 0–1
+  alpha: { value: 1.0 }
+})
+```
+#### Custom GLSL via `Shaders.parse()`
+Register a custom shader at runtime from a JavaScript string and use it like any built-in:
+```js
+Shaders.parse(`
+{@}MyShader.glsl{@}
+#!ATTRIBUTES
+#!UNIFORMS
+uniform float uTime;
+uniform vec3 uColor;
+#!VARYINGS
+varying vec2 vUv;
+#!SHADER: MyShader.Vertex
+void main() {
+    vUv = uv;
+    gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}
+#!SHADER: MyShader.Fragment
+void main() {
+    gl_FragColor = vec4(uColor, 1.0);
+}
+`, 'MyShader.glsl');
+var mesh = new Mesh(
+  new SphereGeometry(1, 32, 32),
+  new Shader('MyShader', {
+    unique: true,
+    uTime:  { value: 0 },
+    uColor: { value: new Color(0.2, 0.8, 1.0) }
+  })
+);
+World.SCENE.add(mesh);
+Render.start(function(time) {
+  mesh.shader.uniforms.uTime.value = time;
+});
+```
+#### `PBRShader` — physically based
+```js
+new PBRShader({
+  roughness: 0.4,
+  metalness: 0.8,
+  envMapIntensity: 1.0
+})
+```
+#### `ShaderVariants` — switch between presets
+```js
+var variants = new ShaderVariants('ColorMaterial', {
+  hot:  { color: { value: new Color(1, 0.2, 0) } },
+  cool: { color: { value: new Color(0, 0.5, 1) } }
+});
+mesh.shader = variants.use('cool');
+```
+---
+### Math
+#### Vectors
+```js
+var v = new Vector3(1, 2, 3);
+v.add(new Vector3(0, 1, 0));   // chainable
+v.normalize();
+v.length();
+v.dot(other);
+v.cross(other);
+v.lerp(target, 0.5);
+v.applyMatrix4(matrix);
+v.clone();
+```
+`Vector2`, `Vector3`, `Vector4` all follow the same pattern.
+#### Color
+```js
+var c = new Color(1, 0.5, 0);   // RGB 0–1
+c.setHex(0xff8800);
+c.setHSL(0.05, 1.0, 0.5);
+c.lerp(other, t);
+```
+#### Quaternion / Euler / Matrix
+```js
+var q = new Quaternion();
+q.setFromEuler(new Euler(0, Math.PI, 0));
+q.slerp(target, 0.1);
+var m = new Matrix4();
+m.makeRotationFromQuaternion(q);
+m.makeTranslation(x, y, z);
+```
+#### `MathUtils`
+```js
+MathUtils.radians(90)          // 1.5707...
+MathUtils.lerp(0, 10, 0.5)    // 5
+MathUtils.clamp(val, 0, 1)
+MathUtils.range(val, 0, 1, -100, 100)
+MathUtils.smoothStep(0, 1, val)
+MathUtils.randFloat(0, 1)
+MathUtils.randInt(0, 10)
+```
+---
+### Textures
+```js
+// From URL (cached)
+var tex = Utils3D.getTexture('/path/to/image.jpg');
+// Repeat-wrap texture
+var rep = Utils3D.getRepeatTexture('/tile.jpg');
+// Cubemap
+var env = Utils3D.loadCubemap(['+x.jpg', '-x.jpg', '+y.jpg', '-y.jpg', '+z.jpg', '-z.jpg']);
+// Data texture (Float32 data → GPU)
+var data = Utils3D.createDataTexture(float32Array, width, height);
+// RenderTarget (render-to-texture)
+var rt = new RenderTarget(512, 512, { type: 'float' });
+// Pooled RenderTargets (saves GC pressure)
+var rt = RTPool.get(512, 512);
+RTPool.release(rt);
+```
+---
+### Camera
+```js
+// Default perspective camera
+World.CAMERA.fov = 60;
+World.CAMERA.position.z = 10;
+World.CAMERA.lookAt(new Vector3(0, 0, 0));
+World.CAMERA.updateProjectionMatrix();
+// Orthographic
+var ortho = new OrthographicCamera(-1, 1, 1, -1, 0.1, 100);
+// VR / XR
+var vrCam = new VRCamera();
+vrCam.setFromXRFrame(frame, refSpace);
+// Screen ↔ World projection
+var screen = ScreenProjection.toScreen(worldPos, camera); // Vector2
+var world  = ScreenProjection.toWorld(screenPos, z, camera); // Vector3
+```
+---
+### Lighting
+```js
+Lighting.setAmbient(new Color(0.1, 0.1, 0.1), 1.0);
+var sun = new ShadowLight({
+  color: new Color(1, 0.95, 0.8),
+  intensity: 2.0,
+  shadow: { mapSize: new Vector2(2048, 2048) }
+});
+sun.castShadow = true;
+World.SCENE.add(sun);
+```
+---
+### Post-Processing (Nuke)
+```js
+// Bloom
+var bloom = new HydraBloom({ strength: 1.5, radius: 0.4, threshold: 0.7 });
+World.NUKE.add(bloom);
+// Unreal-style bloom
+var unrealBloom = new UnrealBloom({ strength: 2.0, radius: 0.3 });
+World.NUKE.add(unrealBloom);
+// Anti-aliasing
+var fxaa = new FXAA();
+World.NUKE.add(fxaa);
+// Lens streaks
+var streak = new HydraLensStreak();
+World.NUKE.add(streak);
+// Volumetric light shafts
+var vol = new VolumetricLight({ density: 0.96, decay: 0.94, weight: 0.4, samples: 100 });
+World.NUKE.add(vol);
+// Custom fullscreen shader pass
+var pass = new NukePass('MyShader', {
+  uTexture: { value: someTexture },
+  uIntensity: { value: 0.5 }
+});
+World.NUKE.add(pass);
+// Mirror reflection
+var mirror = new Mirror({ clipBias: 0.003 });
+World.SCENE.add(mirror);
+```
+---
+### Fluid Simulation
+```js
+// Standalone fluid (manage yourself)
+var fluid = new Fluid(128, 512);  // simSize, dyeSize
+Render.start(function(t, dt) {
+  fluid.splat(Mouse.nX * 0.5 + 0.5, 0.5 - Mouse.nY * 0.5,
+              Mouse.vX * 20, -Mouse.vY * 20,
+              new Color(1, 0.5, 0));
+  fluid.update(dt);
+  mesh.shader.uniforms.uFluid.value = fluid.texture;
+});
+// Mouse-driven fluid (automatic)
+var mouseFluid = new MouseFluid();
+mouseFluid.applyTo(mesh); // links fluid texture to mesh's shader
+Render.start(function() { mouseFluid.update(); });
+// Full fluid scene (mesh + sim pre-wired)
+var scene = new FluidScene({ simSize: 128, dyeSize: 512 });
+World.SCENE.add(scene.mesh);
+Render.start(function(t, dt) { scene.update(dt); });
+```
+---
+### Particles — Antimatter
+GPU-based particle system simulated on the graphics card.
+```js
+var particles = new Antimatter({
+  count: 100000,
+  size: 2.0,
+  blending: 'additive',
+  spawner: new AntimatterSpawn({ rate: 1000, burst: false }),
+  behavior: 'default'
+});
+World.SCENE.add(particles.mesh);
+// Manual spawn
+particles.spawn(
+  new Vector3(0, 0, 0),      // position
+  new Vector3(0, 1, 0)       // velocity
+);
+Render.start(function() { /* Antimatter auto-updates via Render loop */ });
+```
+**Spline particles** — particles that travel along a path:
+```js
+var path   = new SplineGen([p0, p1, p2, p3], false);
+var ribbon = new SplineParticles(path, { count: 500, size: 1.5 });
+World.SCENE.add(ribbon.mesh);
+Render.start(function(t, dt) { ribbon.update(dt); });
+```
+---
+### Instancing & Batching
+Draw thousands of meshes in a single draw call:
+```js
+// InstanceMesh — each instance can have its own matrix + color
+var inst = new InstanceMesh(
+  new BoxGeometry(0.5, 0.5, 0.5),
+  new Shader('ColorMaterial', { color: { value: new Color(1, 1, 1) } }),
+  10000
+);
+var m = new Matrix4();
+for (var i = 0; i < 10000; i++) {
+  m.makeTranslation(
+    MathUtils.randFloat(-10, 10),
+    MathUtils.randFloat(-10, 10),
+    MathUtils.randFloat(-10, 10)
+  );
+  inst.setMatrixAt(i, m);
+  inst.setColorAt(i, new Color(Math.random(), Math.random(), Math.random()));
+}
+inst.update();
+World.SCENE.add(inst.mesh);
+// MeshBatch — add/remove at runtime
+var batch = new MeshBatch(geo, shader, 500);
+var id = batch.add(new Matrix4(), new Color(1, 0, 0));
+batch.remove(id);
+batch.update();
+```
+---
+### Mouse & Interaction
+```js
+// Normalized mouse position (-1 to +1)
+Mouse.nX  // horizontal
+Mouse.nY  // vertical
+// Raw pixel position
+Mouse.x
+Mouse.y
+// Velocity (per frame delta)
+Mouse.vX
+Mouse.vY
+// Is mouse/finger down
+Mouse.down
+// Events
+Mouse.on('down', function() { ... });
+Mouse.on('up',   function() { ... });
+Mouse.on('move', function() { ... });
+// Pointer-events-style (touch + mouse unified)
+Interaction.on('down', handler);
+Interaction.on('up',   handler);
+Interaction.on('move', handler);
+```
+**3D raycasting:**
+```js
+var i3d = new Interaction3D(World.CAMERA, World.SCENE);
+i3d.add(mesh);
+i3d.on('click', function(obj) { console.log('clicked', obj); });
+i3d.on('over',  function(obj) { ... });
+i3d.on('out',   function(obj) { ... });
+// Manual raycasting
+var raycaster = new Raycaster();
+raycaster.setFromCamera(new Vector2(Mouse.nX, -Mouse.nY), World.CAMERA);
+var hits = raycaster.intersectObjects(World.SCENE.children, true);
+```
+**Scroll:**
+```js
+Scroll.y      // current scroll Y
+Scroll.delta  // delta this frame
+Scroll.on('scroll', function() { ... });
+```
+**Keyboard:**
+```js
+Keyboard.on('down', function(key, code) { ... });
+Keyboard.isDown('Space');   // true/false
+Keyboard.isDown(32);        // by key code
+```
+---
+### Animation & Tweening
+```js
+// TweenManager
+TweenManager.to(mesh.position, { y: 5 }, 1.0, 'easeOutCubic');
+TweenManager.to(shader.uniforms.uColor, { value: new Color(1, 0, 0) }, 0.5);
+TweenManager.kill(mesh.position);  // cancel
+// One-liner shortcut
+tween(mesh.rotation, { y: Math.PI * 2 }, 2.0, 'easeInOutQuad');
+// TweenTimeline — sequence / overlap animations
+var tl = new TweenTimeline({ loop: false });
+tl.add(TweenManager.to(mesh.position, { y: 3 }, 0.5), 0.0);
+tl.add(TweenManager.to(mesh.scale,    { x: 2 }, 0.5), 0.3);
+tl.play();
+// CSS transitions
+var css = new CSSTransition(element, { duration: 0.4, ease: 'easeOutQuad' });
+css.to({ opacity: 0, transform: 'translateY(-20px)' });
+```
+Ease names: `linear`, `easeInQuad`, `easeOutQuad`, `easeInOutQuad`, `easeInCubic`, `easeOutCubic`, `easeInOutCubic`, `easeInQuart`, `easeOutQuart`, `easeInOutQuart`, `easeOutBack`, `easeInOutElastic`, `easeOutExpo`, `easeInOutBounce`
+---
+### Audio
+```js
+// Spatial audio (WebAudio API)
+var sfx = new Audio3D('/click.mp3', { volume: 0.8, loop: false });
+sfx.position.copy(mesh.position);
+sfx.play();
+// Sound effects controller (named sound bank)
+var sfxCtrl = new SFXController({
+  click:  '/sounds/click.mp3',
+  whoosh: '/sounds/whoosh.mp3'
+});
+sfxCtrl.play('click', { volume: 0.5, pitch: 1.2 });
+// Master volume
+GlobalAudio3D.setVolume(0.5);
+GlobalAudio3D.mute();
+GlobalAudio3D.unmute();
+// Raw Web Audio access
+var ctx       = WebAudio.context;
+var analyser  = WebAudio.createAnalyser();
+var freqData  = WebAudio.getFrequencyData(analyser); // Uint8Array
+```
+---
+### Video
+```js
+var video = new Video('/clip.mp4', { autoplay: true, loop: true, muted: true, playsInline: true });
+video.play();
+var vtex = new VideoTexture(video);
+// Use as shader texture
+var mesh = new Mesh(
+  new PlaneGeometry(16, 9),
+  new Shader('MyVideoShader', {
+    unique: true,
+    uVideo: { value: vtex }
+  })
+);
+Render.start(function() {
+  vtex.update();  // push new frame to GPU
+});
+// Webcam
+var cam = new Webcam({ facingMode: 'user', width: 1280, height: 720 });
+cam.start().then(function() {
+  var tex = cam.texture;
+});
+```
+---
+### Text (WebGL)
+```js
+var label = new Text3D('Hello World', {
+  font: '/fonts/Inter.json',
+  size: 0.5,
+  color: new Color(1, 1, 1),
+  align: 'center'
+});
+World.SCENE.add(label);
+label.setText('New Text');
+var { width, height } = label.measure();
+```
+---
+### Post — Scene Fragments (`Frag3D`)
+Frag3D is a composable scene unit — encapsulate a sub-scene with its own lifecycle:
+```js
+class MyFragment extends Frag3D {
+  init() {
+    this.mesh = new Mesh(new BoxGeometry(1, 1, 1), new Shader('ColorMaterial', {
+      unique: true, color: { value: new Color(1, 0, 0) }, alpha: { value: 1 }
+    }));
+    this.add(this.mesh);
+  }
+  update(dt) {
+    this.mesh.rotation.y += dt;
+  }
+}
+var frag = new MyFragment();
+SceneLayout.add(frag);
+World.SCENE.add(frag);
+Render.start(function(t, dt) { SceneLayout.update(dt); });
+frag.show(0.5);   // fade in over 0.5s
+frag.hide(0.5);   // fade out
+```
+---
+### Loading Assets
+```js
+// Non-blocking asset preload
+AssetLoader.on('progress', function(pct) { console.log(pct * 100 + '%'); });
+AssetLoader.on('complete', function()    { /* all done */ });
+AssetLoader.loadAssets({
+  textures: ['/diffuse.jpg', '/normal.jpg'],
+  audio:    ['/music.mp3'],
+  json:     ['/data.json']
+});
+// Individual loads
+Assets.loadJSON('/config.json').then(function(data) { ... });
+Assets.loadText('/shader.glsl').then(function(src)  { ... });
+// KTX2 compressed textures (GPU-native, fastest load)
+var ktx = new Ktx2Transcoder();
+ktx.transcode(buffer).then(function(texture) { ... });
+```
+---
+### Multiplayer / Networking
+```js
+var conn = Multiplayer.connect('wss://yourserver.com');
+conn.on('connect', function() { conn.send('hello', { id: 'player1' }); });
+conn.on('message', function(data) { ... });
+// Synchronized object positions
+var sync = new SynchronizedObjects();
+sync.add(mesh, 'object-id');
+Render.start(function(t, dt) { sync.update(dt); });
+```
+---
+### VR / AR
+```js
+// Check support
+XRDeviceManager.isSupported('immersive-vr').then(function(ok) {
+  if (ok) {
+    var btn = document.createElement('button');
+    btn.textContent = 'Enter VR';
+    btn.onclick = function() {
+      XRDeviceManager.requestSession('immersive-vr').then(function(session) {
+        var vrCam      = new VRCamera();
+        var vrRenderer = new VRRenderer(World.RENDERER, session);
+        var vrInput    = new VRInput(session);
+        session.requestAnimationFrame(function frame(t, xrFrame) {
+          vrCam.setFromXRFrame(xrFrame, refSpace);
+          vrInput.update(xrFrame);
+          vrRenderer.render(World.SCENE, vrCam, xrFrame);
+          session.requestAnimationFrame(frame);
+        });
+      });
+    };
+    document.body.appendChild(btn);
+  }
+});
+// AR: place object at tap position
+XRDeviceManager.isSupported('immersive-ar').then(function(ok) {
+  ARUtils.createSession().then(function(session) { ... });
+});
+```
+---
+### GPU & Performance
+```js
+// GPU info (before anything renders)
+console.log(GPU.vendor);   // 'Apple'
+console.log(GPU.tier);     // 0 = low, 1 = mid, 2 = high
+console.log(GPU.webgl2);   // true/false
+console.log(GPU.isMobile); // true/false
+// Adaptive quality
+if (GPU.tier < 1) {
+  World.RENDERER.setPixelRatio(1);
+  bloom.enabled = false;
+}
+// Frame timing
+Performance.on('low-fps', function(fps) {
+  console.warn('FPS dropped to', fps);
+});
+```
+---
+### Device Detection
+```js
+Device.mobile          // false | { phone, tablet, pwa, native }
+Device.system.os       // 'ios' | 'android' | 'windows' | 'macos' | 'linux'
+Device.system.browser  // 'chrome' | 'safari' | 'firefox' | ...
+Device.system.retina   // true/false
+Device.pixelRatio      // 1 | 2 | 3
+Device.touchCapable    // true/false
+```
+---
+### Threading
+Off-main-thread work via Web Workers:
+```js
+var worker = Thread.create(function() {
+  self.onmessage = function(e) {
+    // do heavy computation
+    var result = e.data.map(function(n) { return n * n; });
+    self.postMessage(result);
+  };
+});
+Thread.post(worker, bigArray, [bigArray.buffer]);
+worker.onmessage = function(e) {
+  console.log('result:', e.data);
+};
+```
+---
+### Debug
+```js
+Dev.enabled = true;
+// Helpers
+World.SCENE.add(Dev.grid(World.SCENE, 10, 10)); // grid floor
+World.SCENE.add(Dev.axes(2));                    // XYZ axes
+document.body.appendChild(Dev.stats());          // FPS/MS/MB panel
+Dev.log('mesh', mesh);
+Dev.warn('shader missing uniform');
+Dev.error('fatal:', err);
+```
+---
+### State Management (App)
+```js
+AppState.set('score', 0);
+AppState.get('score');        // 0
+// Reactive — callback fires whenever value changes
+AppState.on('score', function(val) {
+  console.log('score changed to', val);
+});
+// Scoped local state (component-level)
+var state = AppState.createLocal({ count: 0, active: true });
+state.count++;
+// Storage (localStorage wrapper)
+Storage.set('prefs', { volume: 0.8 });
+Storage.get('prefs'); // { volume: 0.8 }
+```
+---
+### Helper Factories
+Convenience shortcuts on the `Orbix` namespace:
+```js
+// Full scene setup in one call
+var { scene, camera, nuke, renderer, element } = Orbix.createScene();
+// Fluid simulation
+var fluid = Orbix.createFluid({ simSize: 128, dyeSize: 512 });
+// MouseFluid
+var mf = Orbix.createMouseFluid();
+// Particle system
+var particles = Orbix.createAntimatter({ count: 50000 });
+// Post-processing pass
+var pass = Orbix.createNukePass('ChromaticAberration', { uAmount: { value: 0.005 } });
+// Texture
+var tex = Orbix.getTexture('/img.jpg');
+```
+---
+## TypeScript
+Full type definitions are included (`dist/orbix.d.ts`):
+```ts
+import Orbix, {
+  Mesh, BoxGeometry, Shader, Color,
+  Render, World, Mouse,
+  Fluid, Antimatter, HydraBloom
+} from 'orbix-engine';
+Orbix.ready().then(() => {
+  const mesh = new Mesh(
+    new BoxGeometry(1, 1, 1),
+    new Shader('ColorMaterial', {
+      unique: true,
+      color: { value: new Color(0.2, 0.5, 1) },
+      alpha: { value: 1 }
+    })
+  );
+  World.SCENE.add(mesh);
+});
+```
+---
+## Files
+| File | Size | Description |
+|------|------|-------------|
+| `dist/orbix.min.js` | ~1.9 MB | **Production CDN build** — use this |
+| `dist/orbix.js` | ~3.0 MB | Development build (unminified) |
+| `dist/orbix.esm.js` | 11 KB | ESM loader / named exports |
+| `dist/orbix.d.ts` | 60 KB | Full TypeScript definitions |
+---
+## License
+MIT

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "orbix-engine",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Orbix — GPU-accelerated WebGL engine with fluid simulations, particle systems, and post-processing. Works on desktop & mobile.",
   "main": "dist/orbix.js",
   "module": "dist/orbix.esm.js",
@@ -9,7 +9,8 @@
   "types": "dist/orbix.d.ts",
   "files": [
     "dist/",
-    "LICENSE"
+    "LICENSE",
+    "README.md"
   ],
   "scripts": {
     "build": "python build.py",