voidcore 0.0.0

package/README.md

@@ -0,0 +1,303 @@
+# V1V2 Engine
+
+Engine in development for [Mana Blade](https://manablade.com/).
+
+A minimal, high-performance WebGPU/WebGL rendering engine with a Three.js-like API.
+
+## Quickstart
+
+```ts
+import { createScene, Mesh, OrbitControls, Scheduler, cubeVertices, cubeIndices } from '@v1v2/engine'
+
+const canvas = document.querySelector('canvas')!
+const scene = await createScene(canvas)
+
+// Register geometry
+const cubeGeo = scene.registerGeometry(cubeVertices, cubeIndices)
+
+// Add a mesh
+const cube = scene.add(
+  new Mesh({
+    geometry: cubeGeo,
+    position: [0, 0, 0],
+    color: [1, 0.3, 0.3],
+  }),
+)
+
+// Camera
+const orbit = new OrbitControls(canvas)
+scene.camera.fov = Math.PI / 3
+scene.camera.near = 0.1
+scene.camera.far = 1000
+
+// Lighting
+scene.setDirectionalLight([-1, -1, -2], [0.5, 0.5, 0.5])
+scene.setAmbientLight([0.8, 0.8, 0.8])
+
+// Shadows
+scene.shadow.enabled = true
+scene.shadow.target.set([0, 0, 0])
+
+// Scheduler
+const scheduler = new Scheduler(scene)
+scheduler.maxFps = 60
+
+scheduler.register(({ dt }) => {
+  cube.rotation[2]! += dt
+  scene.camera.eye.set(orbit.eye)
+  scene.camera.target.set(orbit.target)
+  scene.render()
+})
+
+scheduler.start()
+```
+
+## Features
+
+- WebGPU with automatic WebGL2 fallback
+- Structure-of-Arrays internals for cache-friendly rendering
+- Frustum culling with bounding spheres
+- Shadow mapping (directional light)
+- Bloom post-processing (5-mip downsample/upsample chain)
+- Outline rendering (MRT-based, configurable thickness/color)
+- GPU skinning with animation crossfade blending
+- Bone attachment system (parent meshes to skeleton bones)
+- BVH-accelerated raycasting (SAH-binned, zero allocation in hot path)
+- GLB/glTF loading with Draco mesh compression
+- KTX2/Basis Universal texture loading
+- HTML overlay (project DOM elements to 3D world positions)
+- Orbit controls (pan, rotate, zoom)
+- Transparent object sorting (back-to-front)
+- Priority-based rAF scheduler with global and per-callback FPS throttling
+- Zero per-frame allocations in the hot path
+
+## API
+
+### Scene
+
+```ts
+const scene = await createScene(canvas, { maxEntities: 10_000, backend: 'webgpu' })
+```
+
+### Geometry
+
+```ts
+const geo = scene.registerGeometry(vertices, indices)
+const skinnedGeo = scene.registerSkinnedGeometry(vertices, indices, joints, weights)
+const texturedGeo = scene.registerTexturedGeometry(vertices, indices, uvs)
+```
+
+### Built-in Primitives
+
+```ts
+import { createBoxGeometry, createSphereGeometry, mergeGeometries } from '@v1v2/engine'
+
+const box = createBoxGeometry(1, 1, 1)
+const sphere = createSphereGeometry(0.5, 32, 16)
+const merged = mergeGeometries([
+  { vertices: box.vertices, indices: box.indices, color: [1, 0, 0] },
+  { vertices: sphere.vertices, indices: sphere.indices, color: [0, 0, 1] },
+])
+```
+
+### Meshes
+
+```ts
+const mesh = scene.add(
+  new Mesh({
+    geometry: geo,
+    position: [0, 0, 0],
+    rotation: [0, 0, 0],
+    scale: [1, 1, 1],
+    color: [1, 1, 1],
+    alpha: 1,
+    unlit: false,
+  }),
+)
+
+mesh.position[0]! += 1 // direct mutation
+mesh.visible = false // hide
+mesh.bloom = 1.5 // emissive glow (0 = off)
+mesh.outline = 1 // outline group (0 = off)
+scene.remove(mesh) // remove from scene
+```
+
+### Camera
+
+```ts
+scene.camera.fov = Math.PI / 3
+scene.camera.near = 0.1
+scene.camera.far = 5000
+scene.camera.eye.set([0, -10, 5])
+scene.camera.target.set([0, 0, 0])
+scene.camera.up.set([0, 0, 1])
+```
+
+### Lighting
+
+```ts
+scene.setDirectionalLight([dx, dy, dz], [r, g, b])
+scene.setAmbientLight([r, g, b])
+```
+
+### Shadows
+
+```ts
+scene.shadow.enabled = true
+scene.shadow.target.set([0, 0, 0])
+scene.shadow.distance = 400
+scene.shadow.extent = 150
+scene.shadow.near = 1
+scene.shadow.far = 800
+scene.shadow.bias = 0.0001
+```
+
+### Bloom
+
+```ts
+scene.bloom.enabled = true
+scene.bloom.intensity = 1.0
+scene.bloom.threshold = 0.0
+scene.bloom.radius = 1.0
+scene.bloom.whiten = 0.0
+```
+
+### Outline
+
+```ts
+scene.outline.enabled = true
+scene.outline.thickness = 3
+scene.outline.color = [1, 0.5, 0]
+scene.outline.distanceFactor = 0 // distance-based scaling
+```
+
+### Raycasting
+
+```ts
+import { createRaycastHit } from '@v1v2/engine'
+
+const hit = createRaycastHit() // reusable receiver — no per-frame allocation
+scene.buildBVH(groundMesh.geometry) // optional pre-build (lazy-built on first raycast otherwise)
+
+if (scene.raycast(x, y, z + 50, 0, 0, -1, hit, [groundMesh])) {
+  player.position[2] = hit.pointZ
+  // hit.distance, hit.normalX/Y/Z, hit.faceIndex, hit.mesh
+}
+```
+
+### GLB/glTF Loading
+
+```ts
+import { loadGlb } from '@v1v2/engine'
+
+const glb = await loadGlb('/model.glb', '/draco-1.5.7/')
+// glb.meshes, glb.skins, glb.animations, glb.nodeTransforms
+```
+
+### Skinning & Animation
+
+```ts
+import { createSkeleton, createSkinInstance, updateSkinInstance, transitionTo } from '@v1v2/engine'
+
+const skeleton = createSkeleton(glb.skins[0], glb.nodeTransforms)
+const skin = createSkinInstance(skeleton, 0) // start with clip 0
+scene.skinInstances.push(skin)
+
+// In render loop:
+updateSkinInstance(skin, glb.animations, dt)
+
+// Crossfade to a new clip:
+transitionTo(skin, 2, 0.2) // blend to clip 2 over 0.2s
+```
+
+### Bone Attachment
+
+```ts
+scene.attachToBone(weaponMesh, characterMesh, 'Hand.R')
+scene.detachFromBone(weaponMesh)
+```
+
+### Textures
+
+```ts
+import { loadKTX2 } from '@v1v2/engine'
+
+const tex = await loadKTX2('/texture.ktx2', '/basis/')
+const texId = scene.registerTexture(tex.data, tex.width, tex.height)
+const geo = scene.registerTexturedGeometry(vertices, indices, uvs)
+const mesh = scene.add(new Mesh({ geometry: geo, aoMap: texId }))
+```
+
+### HTML Overlay
+
+```ts
+import { HtmlOverlay, HtmlElement } from '@v1v2/engine'
+
+const overlay = new HtmlOverlay(containerDiv)
+const label = overlay.add(new HtmlElement({ position: [0, 0, 5], element: myDiv, distanceFactor: 1 }))
+label.mesh = someMesh // track a mesh
+
+// In render loop:
+overlay.update(scene)
+```
+
+### Rendering
+
+```ts
+scene.render() // sync + draw in one call
+scene.resize(width, height) // resize canvas/backbuffer
+scene.drawCalls // frame draw call count
+```
+
+### Scheduler
+
+Priority-based rAF loop with optional per-callback and global FPS throttling.
+
+```ts
+import { Scheduler } from '@v1v2/engine'
+
+const scheduler = new Scheduler(scene)
+
+// Global FPS cap — throttles the entire loop (0 = uncapped)
+scheduler.maxFps = 60
+
+// Register callbacks with priority ordering (lower = earlier)
+const unsub = scheduler.register(
+  ({ scene, dt, elapsed, frame }) => {
+    // dt = seconds since last tick (capped at 0.1s)
+    player.position[1]! += speed * dt
+  },
+  { priority: -1 },
+)
+
+// Per-callback FPS throttle (independent of global cap)
+scheduler.register(({ scene }) => scene.render(), { priority: 0, fps: 30 })
+
+scheduler.start()
+scheduler.stop() // pause (resumable)
+unsub() // remove a callback
+scheduler.destroy() // stop + remove all
+```
+
+### Backend switching
+
+```ts
+await scene.switchBackend(newCanvas, 'webgl')
+```
+
+### Cleanup
+
+```ts
+scene.destroy()
+```
+
+## Coordinate system
+
+Right-handed Z-up (Blender convention): +X right, +Y forward, +Z up.
+
+## Development
+
+```bash
+bun install
+bun run dev
+```

package/dist/index.d.ts

@@ -0,0 +1,158 @@
+interface WasmExports {
+    memory: WebAssembly.Memory;
+    vc_init: (pages: number) => number;
+    vc_perspective: (offset: number, fov: number, aspect: number, near: number, far: number) => void;
+    vc_look_at: (offset: number, ex: number, ey: number, ez: number, tx: number, ty: number, tz: number, ux: number, uy: number, uz: number) => void;
+    vc_m4_multiply: (out: number, a: number, b: number) => void;
+    vc_frame_reset: () => void;
+    vc_compute_world_matrices: (count: number) => number;
+    vc_get_positions_ptr: () => number;
+    vc_get_euler_rotations_ptr: () => number;
+    vc_get_scales_ptr: () => number;
+    vc_get_world_matrices_ptr: () => number;
+    vc_get_colors_ptr: () => number;
+    vc_get_flags_ptr: () => number;
+    vc_get_bspheres_ptr: () => number;
+    vc_get_geometry_ids_ptr: () => number;
+    vc_get_sort_keys_ptr: () => number;
+    vc_get_visible_indices_ptr: () => number;
+    vc_extract_frustum_planes: (vpOffset: number, planesOffset: number) => void;
+    vc_frustum_cull: (count: number, planesOffset: number, bspheresOffset: number, flagsOffset: number, outOffset: number) => number;
+    vc_build_sort_keys: (count: number, visibleOffset: number, geoIdsOffset: number, keysOutOffset: number) => void;
+    vc_sort_draw_calls: (count: number, keysOffset: number, indicesOffset: number) => void;
+}
+interface WasmCore {
+    exports: WasmExports;
+    memory: WebAssembly.Memory;
+    f32: Float32Array;
+    u32: Uint32Array;
+    u8: Uint8Array;
+    scratchOffset: number;
+    positionsPtr: number;
+    eulerRotationsPtr: number;
+    scalesPtr: number;
+    worldMatricesPtr: number;
+    colorsPtr: number;
+    flagsPtr: number;
+    bspheresPtr: number;
+    geometryIdsPtr: number;
+    sortKeysPtr: number;
+    visibleIndicesPtr: number;
+}
+declare function loadWasm(): Promise<WasmCore>;
+
+interface DrawEntity {
+    worldMatrix: Float32Array;
+    color: Float32Array;
+    geometryId: number;
+    unlit: boolean;
+}
+interface Renderer {
+    backend: Backend;
+    registerGeometry(id: number, vertices: Float32Array, indices: Uint16Array | Uint32Array): void;
+    updateCamera(view: Float32Array, projection: Float32Array): void;
+    updateLighting(dir: Float32Array, dirColor: Float32Array, ambient: Float32Array): void;
+    draw(entities: DrawEntity[], count: number): void;
+    resize(width: number, height: number): void;
+    destroy(): void;
+}
+
+type Backend = 'webgpu' | 'webgl';
+declare function createRenderer(canvas: HTMLCanvasElement, backend?: Backend): Promise<Renderer>;
+
+declare class Camera {
+    eye: Float32Array<ArrayBuffer>;
+    target: Float32Array<ArrayBuffer>;
+    up: Float32Array<ArrayBuffer>;
+    fov: number;
+    near: number;
+    far: number;
+    view: Float32Array<ArrayBuffer>;
+    projection: Float32Array<ArrayBuffer>;
+    vp: Float32Array<ArrayBuffer>;
+    private viewOffset;
+    private projOffset;
+    private vpOffset;
+    constructor(scratchOffset: number);
+    update(wasm: WasmCore, aspect: number): void;
+}
+
+interface MeshOptions {
+    geometryId: number;
+    position?: [number, number, number];
+    rotation?: [number, number, number];
+    scale?: [number, number, number];
+    color?: [number, number, number, number];
+    visible?: boolean;
+    unlit?: boolean;
+}
+declare class Mesh {
+    entityId: number;
+    position: Float32Array;
+    rotation: Float32Array;
+    scale: Float32Array;
+    color: Float32Array;
+    worldMatrix: Float32Array;
+    private wasm;
+    private flags;
+    geometryId: number;
+    private initOptions;
+    bsphereRadius: number;
+    bsphereCenterOffset: Float32Array<ArrayBuffer>;
+    constructor(options: MeshOptions);
+    /** Called by Scene when entity is assigned */
+    _bind(wasm: WasmCore, entityId: number): void;
+    setDirty(): void;
+    get visible(): boolean;
+    set visible(v: boolean);
+    get unlit(): boolean;
+    set unlit(v: boolean);
+    /** Update bounding sphere in WASM memory */
+    updateBsphere(): void;
+}
+
+interface Geometry {
+    vertices: Float32Array;
+    indices: Uint16Array;
+}
+declare function createBoxGeometry(w?: number, h?: number, d?: number): Geometry;
+declare function createSphereGeometry(radius?: number, wSegs?: number, hSegs?: number): Geometry;
+
+interface SceneConfig {
+    backend?: Backend;
+}
+declare class Scene {
+    wasm: WasmCore;
+    renderer: Renderer;
+    camera: Camera;
+    canvas: HTMLCanvasElement;
+    private meshes;
+    private activeCount;
+    private geometryRegistry;
+    private nextGeometryId;
+    private config;
+    private lightDir;
+    private lightColor;
+    private ambientColor;
+    visibleCount: number;
+    drawCalls: number;
+    private planesOffset;
+    private constructor();
+    static create(canvas: HTMLCanvasElement, config?: SceneConfig): Promise<Scene>;
+    registerGeometry(geometry: Geometry): number;
+    add(mesh: Mesh): Mesh;
+    remove(mesh: Mesh): void;
+    setDirectionalLight(direction: [number, number, number], color: [number, number, number]): void;
+    setAmbientLight(color: [number, number, number]): void;
+    render(): void;
+    resize(width: number, height: number): void;
+    switchBackend(canvas: HTMLCanvasElement, backend: Backend): Promise<void>;
+    destroy(): void;
+}
+
+declare const shaderSource = "\nstruct CameraUniforms {\n  view: mat4x4f,\n  projection: mat4x4f,\n}\n\nstruct ModelUniforms {\n  world: mat4x4f,\n  color: vec4f,\n  flags: vec4f, // x = unlit\n}\n\nstruct LightUniforms {\n  direction: vec4f,\n  color: vec4f,\n  ambient: vec4f,\n}\n\n@group(0) @binding(0) var<uniform> camera: CameraUniforms;\n@group(1) @binding(0) var<uniform> model: ModelUniforms;\n@group(2) @binding(0) var<uniform> light: LightUniforms;\n\nstruct VertexInput {\n  @location(0) position: vec3f,\n  @location(1) normal: vec3f,\n}\n\nstruct VertexOutput {\n  @builtin(position) position: vec4f,\n  @location(0) worldNormal: vec3f,\n  @location(1) color: vec4f,\n  @location(2) unlit: f32,\n}\n\n@vertex\nfn vs_main(input: VertexInput) -> VertexOutput {\n  var output: VertexOutput;\n\n  let worldPos = model.world * vec4f(input.position, 1.0);\n  output.position = camera.projection * camera.view * worldPos;\n\n  // Transform normal by upper 3x3 of world matrix\n  let normalMat = mat3x3f(\n    model.world[0].xyz,\n    model.world[1].xyz,\n    model.world[2].xyz,\n  );\n  output.worldNormal = normalize(normalMat * input.normal);\n  output.color = model.color;\n  output.unlit = model.flags.x;\n\n  return output;\n}\n\n@fragment\nfn fs_main(input: VertexOutput) -> @location(0) vec4f {\n  let normal = normalize(input.worldNormal);\n  let lightDir = normalize(-light.direction.xyz);\n\n  // Lambert diffuse\n  let NdotL = max(dot(normal, lightDir), 0.0);\n  let diffuse = light.color.rgb * NdotL;\n  let ambient = light.ambient.rgb;\n\n  var finalColor: vec3f;\n  if (input.unlit > 0.5) {\n    finalColor = input.color.rgb;\n  } else {\n    finalColor = input.color.rgb * (diffuse + ambient);\n  }\n\n  return vec4f(finalColor, input.color.a);\n}\n";
+
+declare const vertexShaderGLSL = "#version 300 es\nprecision highp float;\n\nlayout(std140) uniform CameraUniforms {\n  mat4 view;\n  mat4 projection;\n} camera;\n\nlayout(std140) uniform ModelUniforms {\n  mat4 world;\n  vec4 color;\n  vec4 flags; // x = unlit\n} model;\n\nlayout(location = 0) in vec3 a_position;\nlayout(location = 1) in vec3 a_normal;\n\nout vec3 v_worldNormal;\nout vec4 v_color;\nout float v_unlit;\n\nvoid main() {\n  vec4 worldPos = model.world * vec4(a_position, 1.0);\n  gl_Position = camera.projection * camera.view * worldPos;\n\n  mat3 normalMat = mat3(model.world);\n  v_worldNormal = normalize(normalMat * a_normal);\n  v_color = model.color;\n  v_unlit = model.flags.x;\n}\n";
+declare const fragmentShaderGLSL = "#version 300 es\nprecision highp float;\n\nlayout(std140) uniform LightUniforms {\n  vec4 direction;\n  vec4 color;\n  vec4 ambient;\n} light;\n\nin vec3 v_worldNormal;\nin vec4 v_color;\nin float v_unlit;\n\nout vec4 fragColor;\n\nvoid main() {\n  vec3 normal = normalize(v_worldNormal);\n  vec3 lightDir = normalize(-light.direction.xyz);\n\n  float NdotL = max(dot(normal, lightDir), 0.0);\n  vec3 diffuse = light.color.rgb * NdotL;\n  vec3 ambient = light.ambient.rgb;\n\n  vec3 finalColor;\n  if (v_unlit > 0.5) {\n    finalColor = v_color.rgb;\n  } else {\n    finalColor = v_color.rgb * (diffuse + ambient);\n  }\n\n  fragColor = vec4(finalColor, v_color.a);\n}\n";
+
+export { type Backend, Camera, type Geometry, Mesh, type MeshOptions, type Renderer, Scene, type SceneConfig, type WasmCore, type WasmExports, createBoxGeometry, createRenderer, createSphereGeometry, fragmentShaderGLSL, loadWasm, shaderSource, vertexShaderGLSL };