@autarkis/chitin-web 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,81 @@
+# @autarkis/chitin-web
+
+Load chitin `.phys` collision sidecars in the browser. Parses the binary format
+and turns it into Rapier colliders or Three.js debug meshes.
+
+## Setup
+
+```bash
+npm install @autarkis/chitin-web
+```
+
+The package uses subpath exports. The root is dependency-free -- just the `.phys`
+parser and validator. The Rapier and Three.js bindings live under `/rapier` and
+`/three` and pull their engines in as optional peer dependencies:
+
+```bash
+npm install @dimforge/rapier3d-compat   # for /rapier
+npm install three                        # for /three
+```
+
+## Usage
+
+### Parse a .phys file
+
+```typescript
+import { parsePhys } from "@autarkis/chitin-web";
+
+const buffer = await fetch("/assets/scene.phys").then((r) => r.arrayBuffer());
+const phys = parsePhys(buffer); // throws on malformed input
+
+for (const hull of phys.hulls) {
+  console.log(hull.vertices, hull.indices); // Float32Array, Uint16Array
+}
+```
+
+### Add colliders to a Rapier world
+
+```typescript
+import RAPIER from "@dimforge/rapier3d-compat";
+import { parsePhys } from "@autarkis/chitin-web";
+import { addToWorld } from "@autarkis/chitin-web/rapier";
+
+const phys = parsePhys(await fetch("/scene.phys").then((r) => r.arrayBuffer()));
+addToWorld(RAPIER, world, phys);
+```
+
+Use `createColliders(rapier, phys)` if you want the `ColliderDesc`s without
+attaching them to a body.
+
+### Pick a LOD tier
+
+For a `.phys` with LOD tiers, select the set nearest a target concavity:
+
+```typescript
+import { selectLodHulls } from "@autarkis/chitin-web";
+import { createColliders } from "@autarkis/chitin-web/rapier";
+
+const coarseHulls = selectLodHulls(phys, 0.3); // hull data only
+const { colliders } = createColliders(rapier, phys, { lodConcavity: 0.3 });
+```
+
+Readers with no target pick default to LOD 0 (highest detail).
+
+### Debug meshes
+
+```typescript
+import { createDebugMeshes } from "@autarkis/chitin-web/three";
+
+scene.add(createDebugMeshes(phys)); // wireframe hull visualization
+```
+
+## Other engines
+
+`parsePhys` returns plain `Float32Array` / `Uint16Array` hull data. If you use a
+physics engine other than Rapier, read the hulls directly and pass each one's
+vertices and indices to your engine's convex-collider API -- no `/rapier` import
+needed.
+
+Colliders are generated by the [chitin](https://github.com/Autarkis/chitin)
+compiler (or `@autarkis/chitin-lite` in the browser); this package only reads
+their `.phys` output.

package/package.json

@@ -1,55 +1,71 @@
-{
-  "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"
-}
+{
+  "name": "@autarkis/chitin-web",
+  "version": "0.1.2",
+  "description": "Load chitin .phys collision sidecars in the browser",
+  "keywords": [
+    "physics",
+    "collision",
+    "collider",
+    "convex-hull",
+    "three",
+    "threejs",
+    "rapier",
+    "gltf",
+    "glb",
+    "robotics",
+    "webgl",
+    "phys"
+  ],
+  "homepage": "https://github.com/Autarkis/chitin#readme",
+  "bugs": "https://github.com/Autarkis/chitin/issues",
+  "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"
+}