@autarkis/chitin-web 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { parsePhys, selectLodHulls } from "./phys-parser.js";
+export type { PhysFile, PhysHull, PhysBone, PhysLodTier, } from "./phys-parser.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+// Format-only entry point: parses/validates .phys with no physics-engine or
+// Three.js dependency. Import the Rapier bindings from "@autarkis/chitin-web/rapier"
+// and the Three.js debug meshes from "@autarkis/chitin-web/three".
+export { parsePhys, selectLodHulls } from "./phys-parser.js";

package/dist/phys-parser.d.ts

@@ -0,0 +1,27 @@
+export interface PhysHull {
+    vertices: Float32Array;
+    indices: Uint16Array;
+    aabbMin: [number, number, number];
+    aabbMax: [number, number, number];
+    boneIndex: number | null;
+}
+export interface PhysBone {
+    name: string;
+    bindTransform: Float32Array;
+}
+export interface PhysLodTier {
+    concavity: number;
+    hulls: PhysHull[];
+}
+export interface PhysFile {
+    version: number;
+    flags: number;
+    hulls: PhysHull[];
+    bones: PhysBone[];
+    lodTiers: PhysLodTier[];
+    hasBones: boolean;
+    hasBindPoses: boolean;
+    hasLod: boolean;
+}
+export declare function selectLodHulls(phys: PhysFile, concavity: number): PhysHull[];
+export declare function parsePhys(buffer: ArrayBuffer): PhysFile;

package/dist/phys-parser.js

@@ -0,0 +1,241 @@
+const MAGIC = 0x53594850; // "PHYS" little-endian
+const HEADER_SIZE = 32;
+const FLAG_HAS_BONES = 0x01;
+const FLAG_HAS_BIND_POSES = 0x02;
+const FLAG_HAS_LOD = 0x04;
+const KNOWN_FLAGS = FLAG_HAS_BONES | FLAG_HAS_BIND_POSES | FLAG_HAS_LOD;
+const LOD_TIER_HEADER_SIZE = 24;
+const SUPPORTED_VERSIONS = new Set([2, 3]);
+// Shared hull-table reader for both the LOD0 block and each LOD tier, so the
+// same structural invariants (range, contiguity, finite AABB, bone bounds) hold
+// everywhere.
+function readHulls(blk) {
+    const { view, byteLength, hullTableOff, descSize, hasBones, hullCount, vertexDataOff, indexDataOff, totalVerts, totalIdx, boneTableCount, prefix, } = blk;
+    const hulls = [];
+    let expectedVOff = 0;
+    let expectedIOff = 0;
+    for (let i = 0; i < hullCount; i++) {
+        const off = hullTableOff + i * descSize;
+        requireBytes(byteLength, off, descSize, `${prefix} ${i} descriptor`);
+        const vOff = view.getUint32(off, true);
+        const vCount = view.getUint32(off + 4, true);
+        const iOff = view.getUint32(off + 8, true);
+        const iCount = view.getUint32(off + 12, true);
+        if (vOff + vCount > totalVerts) {
+            throw new Error(`${prefix} ${i}: vertex range [${vOff}, ${vOff + vCount}) exceeds total_vertices ${totalVerts}`);
+        }
+        if (iOff + iCount > totalIdx) {
+            throw new Error(`${prefix} ${i}: index range [${iOff}, ${iOff + iCount}) exceeds total_indices ${totalIdx}`);
+        }
+        if (vOff !== expectedVOff) {
+            throw new Error(`${prefix} ${i}: vertex_offset ${vOff} != expected ${expectedVOff} (non-contiguous or overlapping range)`);
+        }
+        if (iOff !== expectedIOff) {
+            throw new Error(`${prefix} ${i}: index_offset ${iOff} != expected ${expectedIOff} (non-contiguous or overlapping range)`);
+        }
+        const aabbMin = [
+            view.getFloat32(off + 16, true),
+            view.getFloat32(off + 20, true),
+            view.getFloat32(off + 24, true),
+        ];
+        const aabbMax = [
+            view.getFloat32(off + 28, true),
+            view.getFloat32(off + 32, true),
+            view.getFloat32(off + 36, true),
+        ];
+        if (![...aabbMin, ...aabbMax].every(Number.isFinite)) {
+            throw new Error(`${prefix} ${i}: non-finite aabb`);
+        }
+        let boneIndex = null;
+        if (hasBones) {
+            const raw = view.getInt32(off + 40, true);
+            if (raw < -1) {
+                throw new Error(`${prefix} ${i}: invalid bone_index ${raw}`);
+            }
+            if (boneTableCount !== null && raw >= boneTableCount) {
+                throw new Error(`${prefix} ${i}: bone_index ${raw} >= bone_count ${boneTableCount}`);
+            }
+            boneIndex = raw === -1 ? null : raw;
+        }
+        const vertices = new Float32Array(vCount * 3);
+        const qOff = vertexDataOff + vOff * 6;
+        requireBytes(byteLength, qOff, vCount * 6, `${prefix} ${i} vertices`);
+        for (let v = 0; v < vCount; v++) {
+            for (let c = 0; c < 3; c++) {
+                const q = view.getInt16(qOff + (v * 3 + c) * 2, true);
+                const extent = aabbMax[c] - aabbMin[c];
+                const e = extent === 0 ? 1.0 : extent;
+                vertices[v * 3 + c] = ((q + 32768) / 65535) * e + aabbMin[c];
+            }
+        }
+        const idxOff = indexDataOff + iOff * 2;
+        requireBytes(byteLength, idxOff, iCount * 2, `${prefix} ${i} indices`);
+        const indices = new Uint16Array(iCount);
+        for (let t = 0; t < iCount; t++) {
+            indices[t] = view.getUint16(idxOff + t * 2, true);
+        }
+        hulls.push({ vertices, indices, aabbMin, aabbMax, boneIndex });
+        expectedVOff += vCount;
+        expectedIOff += iCount;
+    }
+    return hulls;
+}
+// Pick the tier whose concavity is nearest the target; falls back to LOD0
+// (phys.hulls) when the file carries no additional tiers. Mirrors Python's
+// PhysFile.lod_tier().
+export function selectLodHulls(phys, concavity) {
+    if (phys.lodTiers.length === 0)
+        return phys.hulls;
+    let best = phys.lodTiers[0];
+    for (const tier of phys.lodTiers) {
+        if (Math.abs(tier.concavity - concavity) < Math.abs(best.concavity - concavity)) {
+            best = tier;
+        }
+    }
+    return best.hulls;
+}
+export function parsePhys(buffer) {
+    const view = new DataView(buffer);
+    const byteLength = buffer.byteLength;
+    if (byteLength < HEADER_SIZE) {
+        throw new Error(`file too small: ${byteLength} bytes`);
+    }
+    const magic = view.getUint32(0, true);
+    if (magic !== MAGIC) {
+        throw new Error(`bad magic: 0x${magic.toString(16)}`);
+    }
+    const version = view.getUint16(4, true);
+    const flags = view.getUint16(6, true);
+    const hullCount = view.getUint32(8, true);
+    const totalVerts = view.getUint32(12, true);
+    const totalIdx = view.getUint32(16, true);
+    const hullTableOff = view.getUint32(20, true);
+    const vertexDataOff = view.getUint32(24, true);
+    const indexDataOff = view.getUint32(28, true);
+    if (!SUPPORTED_VERSIONS.has(version)) {
+        throw new Error(`unsupported .phys version ${version}`);
+    }
+    const unknownFlags = flags & ~KNOWN_FLAGS;
+    if (unknownFlags !== 0) {
+        throw new Error(`unknown flags 0x${unknownFlags.toString(16)}`);
+    }
+    const hasBones = (flags & FLAG_HAS_BONES) !== 0;
+    const hasBindPoses = (flags & FLAG_HAS_BIND_POSES) !== 0;
+    const hasLod = (flags & FLAG_HAS_LOD) !== 0;
+    const descSize = hasBones ? 44 : 40;
+    const expectedVertexOff = hullTableOff + hullCount * descSize;
+    const expectedIndexOff = vertexDataOff + totalVerts * 6;
+    if (hullTableOff !== HEADER_SIZE) {
+        throw new Error(`bad hull table offset: ${hullTableOff}`);
+    }
+    if (vertexDataOff !== expectedVertexOff) {
+        throw new Error(`bad vertex data offset: ${vertexDataOff}`);
+    }
+    if (indexDataOff !== expectedIndexOff) {
+        throw new Error(`bad index data offset: ${indexDataOff}`);
+    }
+    // Peek the bone count (the bind-pose block trails the index data) so each
+    // hull's boneIndex can be range-checked in the loop below.
+    let boneTableCount = null;
+    if (hasBindPoses) {
+        const boneBlockOff = indexDataOff + totalIdx * 2;
+        if (boneBlockOff + 4 <= byteLength) {
+            boneTableCount = view.getUint32(boneBlockOff, true);
+        }
+    }
+    const hulls = readHulls({
+        view,
+        byteLength,
+        hullTableOff,
+        descSize,
+        hasBones,
+        hullCount,
+        vertexDataOff,
+        indexDataOff,
+        totalVerts,
+        totalIdx,
+        boneTableCount,
+        prefix: "hull",
+    });
+    const bones = [];
+    let nextBlockOff = indexDataOff + totalIdx * 2;
+    if (hasBindPoses) {
+        let bOff = nextBlockOff;
+        requireBytes(byteLength, bOff, 4, "bone count");
+        const boneCount = view.getUint32(bOff, true);
+        bOff += 4;
+        const decoder = new TextDecoder("utf-8");
+        for (let b = 0; b < boneCount; b++) {
+            requireBytes(byteLength, bOff, 64, `bone ${b} bind transform`);
+            const bindTransform = new Float32Array(16);
+            for (let f = 0; f < 16; f++) {
+                bindTransform[f] = view.getFloat32(bOff + f * 4, true);
+            }
+            if (!bindTransform.every(Number.isFinite)) {
+                throw new Error(`bone ${b}: non-finite bind_transform`);
+            }
+            bOff += 64;
+            requireBytes(byteLength, bOff, 2, `bone ${b} name length`);
+            const nameLen = view.getUint16(bOff, true);
+            bOff += 2;
+            requireBytes(byteLength, bOff, nameLen, `bone ${b} name`);
+            const name = decoder.decode(new Uint8Array(buffer, bOff, nameLen));
+            bOff += nameLen;
+            bones.push({ name, bindTransform });
+        }
+        nextBlockOff = bOff;
+    }
+    const lodTiers = [];
+    if (hasLod) {
+        requireBytes(byteLength, nextBlockOff, 4, "LOD tier count");
+        const tierCount = view.getUint32(nextBlockOff, true);
+        nextBlockOff += 4;
+        for (let tier = 0; tier < tierCount; tier++) {
+            requireBytes(byteLength, nextBlockOff, LOD_TIER_HEADER_SIZE, `LOD tier ${tier} header`);
+            const concavity = view.getFloat32(nextBlockOff, true);
+            const tHullCount = view.getUint32(nextBlockOff + 4, true);
+            const tTotalVerts = view.getUint32(nextBlockOff + 8, true);
+            const tTotalIdx = view.getUint32(nextBlockOff + 12, true);
+            const dataSize = view.getUint32(nextBlockOff + 16, true);
+            nextBlockOff += LOD_TIER_HEADER_SIZE;
+            requireBytes(byteLength, nextBlockOff, dataSize, `LOD tier ${tier} data`);
+            const tHullTableOff = nextBlockOff;
+            const tVertexDataOff = tHullTableOff + tHullCount * descSize;
+            const tIndexDataOff = tVertexDataOff + tTotalVerts * 6;
+            const tierHulls = readHulls({
+                view,
+                byteLength,
+                hullTableOff: tHullTableOff,
+                descSize,
+                hasBones,
+                hullCount: tHullCount,
+                vertexDataOff: tVertexDataOff,
+                indexDataOff: tIndexDataOff,
+                totalVerts: tTotalVerts,
+                totalIdx: tTotalIdx,
+                boneTableCount,
+                prefix: `LOD tier ${tier} hull`,
+            });
+            lodTiers.push({ concavity, hulls: tierHulls });
+            nextBlockOff += dataSize;
+        }
+    }
+    if (byteLength !== nextBlockOff) {
+        throw new Error(`${byteLength - nextBlockOff} trailing bytes after end of data`);
+    }
+    return {
+        version,
+        flags,
+        hulls,
+        bones,
+        lodTiers,
+        hasBones,
+        hasBindPoses,
+        hasLod,
+    };
+}
+function requireBytes(byteLength, offset, size, label) {
+    if (offset < 0 || size < 0 || offset + size > byteLength) {
+        throw new Error(`${label} truncated`);
+    }
+}

package/dist/rapier.d.ts

@@ -0,0 +1,15 @@
+import type RAPIER from "@dimforge/rapier3d-compat";
+import type { PhysFile } from "./phys-parser.js";
+export interface ColliderResult {
+    colliders: RAPIER.ColliderDesc[];
+    boneMap: Map<number, RAPIER.ColliderDesc[]>;
+}
+export interface ColliderOptions {
+    lodConcavity?: number;
+}
+export declare function createColliders(rapier: typeof RAPIER, phys: PhysFile, opts?: ColliderOptions): ColliderResult;
+export declare function addToWorld(rapier: typeof RAPIER, world: RAPIER.World, phys: PhysFile, position?: {
+    x: number;
+    y: number;
+    z: number;
+}, opts?: ColliderOptions): RAPIER.RigidBody;

package/dist/rapier.js

@@ -0,0 +1,35 @@
+import { selectLodHulls } from "./phys-parser.js";
+export function createColliders(rapier, phys, opts) {
+    const colliders = [];
+    const boneMap = new Map();
+    const hulls = opts?.lodConcavity !== undefined
+        ? selectLodHulls(phys, opts.lodConcavity)
+        : phys.hulls;
+    for (const hull of hulls) {
+        const desc = colliderFromHull(rapier, hull);
+        if (!desc)
+            continue;
+        colliders.push(desc);
+        if (hull.boneIndex !== null) {
+            const arr = boneMap.get(hull.boneIndex) ?? [];
+            arr.push(desc);
+            boneMap.set(hull.boneIndex, arr);
+        }
+    }
+    return { colliders, boneMap };
+}
+export function addToWorld(rapier, world, phys, position, opts) {
+    const pos = position ?? { x: 0, y: 0, z: 0 };
+    const bodyDesc = rapier.RigidBodyDesc.fixed().setTranslation(pos.x, pos.y, pos.z);
+    const body = world.createRigidBody(bodyDesc);
+    const { colliders } = createColliders(rapier, phys, opts);
+    for (const desc of colliders) {
+        world.createCollider(desc, body);
+    }
+    return body;
+}
+function colliderFromHull(rapier, hull) {
+    if (hull.vertices.length < 12 || hull.indices.length < 3)
+        return null;
+    return rapier.ColliderDesc.convexHull(hull.vertices);
+}

package/dist/three.d.ts

@@ -0,0 +1,8 @@
+import { Group } from "three";
+import type { PhysFile } from "./phys-parser.js";
+export interface DebugOptions {
+    color?: number;
+    opacity?: number;
+    wireframe?: boolean;
+}
+export declare function createDebugMeshes(phys: PhysFile, options?: DebugOptions): Group;

package/dist/three.js

@@ -0,0 +1,57 @@
+import { BufferGeometry, Float32BufferAttribute, Group, LineBasicMaterial, LineSegments, Matrix4, Mesh, MeshBasicMaterial, Uint16BufferAttribute, } from "three";
+export function createDebugMeshes(phys, options) {
+    const color = options?.color ?? 0x00ff88;
+    const opacity = options?.opacity ?? 0.3;
+    const wireframe = options?.wireframe ?? true;
+    const group = new Group();
+    group.name = "chitin_colliders";
+    const boneTransforms = new Map();
+    if (phys.bones.length > 0) {
+        for (let i = 0; i < phys.bones.length; i++) {
+            const m = new Matrix4();
+            m.fromArray(phys.bones[i].bindTransform);
+            boneTransforms.set(i, m);
+        }
+    }
+    for (let i = 0; i < phys.hulls.length; i++) {
+        const hull = phys.hulls[i];
+        const geo = new BufferGeometry();
+        geo.setAttribute("position", new Float32BufferAttribute(hull.vertices, 3));
+        geo.setIndex(new Uint16BufferAttribute(hull.indices, 1));
+        geo.computeVertexNormals();
+        if (wireframe) {
+            const edges = extractEdges(hull.indices);
+            const edgeGeo = new BufferGeometry();
+            edgeGeo.setAttribute("position", new Float32BufferAttribute(hull.vertices, 3));
+            edgeGeo.setIndex(edges);
+            const line = new LineSegments(edgeGeo, new LineBasicMaterial({ color }));
+            line.name = `hull_${i}_wire`;
+            if (hull.boneIndex !== null && boneTransforms.has(hull.boneIndex)) {
+                line.applyMatrix4(boneTransforms.get(hull.boneIndex));
+            }
+            group.add(line);
+        }
+        const mat = new MeshBasicMaterial({
+            color,
+            transparent: true,
+            opacity,
+            depthWrite: false,
+        });
+        const mesh = new Mesh(geo, mat);
+        mesh.name = `hull_${i}`;
+        if (hull.boneIndex !== null && boneTransforms.has(hull.boneIndex)) {
+            mesh.applyMatrix4(boneTransforms.get(hull.boneIndex));
+        }
+        group.add(mesh);
+    }
+    return group;
+}
+function extractEdges(indices) {
+    const edges = [];
+    for (let i = 0; i < indices.length; i += 3) {
+        edges.push(indices[i], indices[i + 1]);
+        edges.push(indices[i + 1], indices[i + 2]);
+        edges.push(indices[i + 2], indices[i]);
+    }
+    return edges;
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@autarkis/chitin-web",
+  "version": "0.1.0",
+  "description": "Load chitin .phys collision sidecars in the browser",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Autarkis/chitin.git",
+    "directory": "integrations/web"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./rapier": {
+      "types": "./dist/rapier.d.ts",
+      "import": "./dist/rapier.js"
+    },
+    "./three": {
+      "types": "./dist/three.d.ts",
+      "import": "./dist/three.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@dimforge/rapier3d-compat": ">=0.13",
+    "three": ">=0.160"
+  },
+  "peerDependenciesMeta": {
+    "three": {
+      "optional": true
+    },
+    "@dimforge/rapier3d-compat": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@dimforge/rapier3d-compat": "^0.19.3",
+    "@types/three": "^0.184.1",
+    "three": "^0.184.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  },
+  "license": "MIT"
+}