aether-physics 0.1.0 → 0.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Brandon Berisford
-
-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.
+MIT License
+
+Copyright (c) 2026 Brandon Berisford
+
+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

@@ -1,79 +1,95 @@
-# Aether
-
-A 3D rigid-body physics engine written from scratch in TypeScript, with a browser playground built on Lit and Three.js.
-
-This is a learning project. The engine is built in phases, from vectors to stacking boxes to ragdolls, following Ian Millington's *Game Physics Engine Development*, Erin Catto's solver talks, and the resources collected at [brm.io/game-physics-for-beginners](https://brm.io/game-physics-for-beginners/).
-
-- **[docs/PLAN.md](docs/PLAN.md):** the phased build plan, with goals, checklists, tests and demos for each phase
-- **[docs/RESOURCES.md](docs/RESOURCES.md):** books, articles, talks and reference engines for each phase
-- **[docs/DEMOS.md](docs/DEMOS.md):** how to build a demo: templates, using the engine from Three.js, demo controls and UI style
-
-**[Try the playground](https://beyondbelief96.github.io/aether/)**. Each push to `main` deploys it to GitHub Pages.
-
-## Using the package
-
-```sh
-npm install aether-physics
-```
-
-```ts
-import { Quaternion, Vec3 } from 'aether-physics';
-
-const q = new Quaternion().setFromAxisAngle({ x: 0, y: 1, z: 0 }, Math.PI / 2);
-q.rotateVec3({ x: 1, y: 0, z: 0 }, new Vec3()); // about (0, 0, -1)
-```
-
-It's early: so far the package has the math library and a fixed-timestep loop. Physics arrives with the later phases below, and the API can change in any 0.x release.
-
-## Running it
-
-```sh
-npm install
-npm run dev        # playground at http://localhost:5173
-npm test           # Vitest in watch mode
-npm run test:run   # Vitest once
-npm run typecheck  # tsc, no emit
-npm run build      # typecheck, then production build of the playground to dist-playground/
-npm run build:lib  # build the npm package to dist/
-```
-
-Keyboard: **Space** pauses, **.** steps once while paused, **R** resets the demo.
-
-## Layout
-
-```
-src/
-  math/         Vec3, Mat3, Mat4, Quat                     Phase 1
-  engine/       game loop, Particle, RigidBody, World      Phases 0, 2, 4, 7
-  forces/       force generators                           Phases 3, 4
-  collision/    shapes, broadphase, narrowphase            Phase 5
-  constraints/  contact solver, joints                     Phases 6, 7
-  playground/   the app in the browser, which uses the engine only through "aether-physics"
-    demos/      one file per demo (the only engine + Three.js code)
-    ui/         Lit components
-```
-
-## Rules
-
-- The engine (`math`, `engine`, `forces`, `collision`, `constraints`) never imports `three` or touches the DOM. Demos are the bridge.
-- Physics runs on a fixed timestep; rendering interpolates between steps.
-- TypeScript runs with `erasableSyntaxOnly`: no `enum`, `namespace` or parameter properties.
-- Lit components use `static properties` with `declare` fields and `customElements.define`, never decorators.
-
-## Progress
-
-| Phase | Topic | Status |
-|---|---|---|
-| 0 | Scaffold and game loop | ✅ |
-| 1 | Math library | ✅ |
-| 2 | Particles and integration | |
-| 3 | Forces, springs and mass aggregates | |
-| 4 | Rigid bodies | |
-| 5 | Collision detection | |
-| 6 | Collision response and friction | |
-| 7 | Joints, sleeping and stability | |
-| 8 | Stretch goals | |
-
-## License
-
-[MIT](LICENSE)
+# Aether
+
+A 3D rigid-body physics engine written from scratch in TypeScript, with a browser playground built on Lit and Three.js.
+
+This is a learning project. The engine is built in phases, from vectors to stacking boxes to ragdolls, following Ian Millington's *Game Physics Engine Development*, Erin Catto's solver talks, and the resources collected at [brm.io/game-physics-for-beginners](https://brm.io/game-physics-for-beginners/).
+
+- **[docs/PLAN.md](docs/PLAN.md):** the phased build plan, with goals, checklists, tests and demos for each phase
+- **[docs/RESOURCES.md](docs/RESOURCES.md):** books, articles, talks and reference engines for each phase
+- **[docs/DEMOS.md](docs/DEMOS.md):** how to build a demo: templates, using the engine from Three.js, demo controls and UI style
+
+**[Try the playground](https://beyondbelief96.github.io/aether/)**. Each push to `main` deploys it to GitHub Pages.
+
+## Using the package
+
+```sh
+npm install aether-physics
+```
+
+```ts
+import { Quaternion, Vec3 } from 'aether-physics';
+
+const q = new Quaternion().setFromAxisAngle({ x: 0, y: 1, z: 0 }, Math.PI / 2);
+q.rotateVec3({ x: 1, y: 0, z: 0 }, new Vec3()); // about (0, 0, -1)
+```
+
+Point masses move under forces in a fixed-timestep world:
+
+```ts
+import { Particle, ParticleWorld } from 'aether-physics';
+
+const ball = new Particle();
+ball.position.set(0, 10, 0);
+ball.velocity.set(3, 4, 0);
+ball.acceleration.set(0, -9.81, 0);
+
+const world = new ParticleWorld();
+world.particles.push(ball);
+for (let i = 0; i < 60; i++) world.step(1 / 60); // one simulated second
+```
+
+It's early: so far the package has the math library, a fixed-timestep loop and particles. Rigid bodies and collisions arrive with the later phases below, and the API can change in any 0.x release. See the [engine API guide](src/engine/README.md) and the [math API guide](src/math/README.md).
+
+## Running it
+
+```sh
+npm install
+npm run dev        # playground at http://localhost:5173
+npm test           # Vitest in watch mode
+npm run test:run   # Vitest once
+npm run test:smoke # load the built playground in Chrome (run npm run build first)
+npm run typecheck  # tsc, no emit
+npm run build      # typecheck, then production build of the playground to dist-playground/
+npm run build:lib  # build the npm package to dist/
+```
+
+Keyboard: **Space** pauses, **.** steps once while paused, **R** resets the demo.
+
+## Layout
+
+```
+src/
+  math/         Vec3, Mat3, Mat4, Quat                     Phase 1
+  engine/       game loop, Particle, RigidBody, World      Phases 0, 2, 4, 7
+  forces/       force generators                           Phases 3, 4
+  collision/    shapes, broadphase, narrowphase            Phase 5
+  constraints/  contact solver, joints                     Phases 6, 7
+  playground/   the app in the browser, which uses the engine only through "aether-physics"
+    demos/      one file per demo (the only engine + Three.js code)
+    ui/         Lit components
+```
+
+## Rules
+
+- The engine (`math`, `engine`, `forces`, `collision`, `constraints`) never imports `three` or touches the DOM. Demos are the bridge.
+- Physics runs on a fixed timestep; rendering interpolates between steps.
+- TypeScript runs with `erasableSyntaxOnly`: no `enum`, `namespace` or parameter properties.
+- Lit components use `static properties` with `declare` fields and `customElements.define`, never decorators.
+
+## Progress
+
+| Phase | Topic | Status |
+|---|---|---|
+| 0 | Scaffold and game loop | ✅ |
+| 1 | Math library | ✅ |
+| 2 | Particles and integration | ✅ |
+| 3 | Forces, springs and mass aggregates | |
+| 4 | Rigid bodies | |
+| 5 | Collision detection | |
+| 6 | Collision response and friction | |
+| 7 | Joints, sleeping and stability | |
+| 8 | Stretch goals | |
+
+## License
+
+[MIT](LICENSE)

package/dist/index.js

@@ -51,6 +51,38 @@ var s = .25, c = class {
 			droppedTime: o
 		};
 	}
+}, l = class {
+	position = new t();
+	velocity = new t();
+	acceleration = new t();
+	forceAccum = new t();
+	damping = .99;
+	inverseMass = 1;
+	get mass() {
+		return this.inverseMass === 0 ? Infinity : 1 / this.inverseMass;
+	}
+	setMass(e) {
+		if (!(e > 0)) throw RangeError(`mass must be positive, got ${e}`);
+		this.inverseMass = 1 / e;
+	}
+	hasFiniteMass() {
+		return this.inverseMass > 0;
+	}
+	addForce(e) {
+		this.forceAccum.add(e);
+	}
+	clearAccumulator() {
+		this.forceAccum.set(0, 0, 0);
+	}
+	integrate(e) {
+		if (!(e > 0)) throw RangeError(`dt must be positive, got ${e}`);
+		this.inverseMass > 0 && (this.velocity.addScaled(this.acceleration, e).addScaled(this.forceAccum, this.inverseMass * e).scale(this.damping ** +e), this.position.addScaled(this.velocity, e)), this.clearAccumulator();
+	}
+}, u = class {
+	particles = [];
+	step(e) {
+		for (let t of this.particles) t.integrate(e);
+	}
 };
 //#endregion
-export { e as EPSILON, c as FixedStepLoop, i as Mat3x3, n as Mat3x4, o as Quaternion, t as Vec3, r as approxEqual, a as clamp };
+export { e as EPSILON, c as FixedStepLoop, i as Mat3x3, n as Mat3x4, l as Particle, u as ParticleWorld, o as Quaternion, t as Vec3, r as approxEqual, a as clamp };

package/dist/types/engine/index.d.ts

@@ -0,0 +1,4 @@
+export { FixedStepLoop } from "./loop.js";
+export type { FrameResult } from "./loop.js";
+export { Particle } from "./particle.js";
+export { ParticleWorld } from "./particle-world.js";

package/dist/types/engine/particle-world.d.ts

@@ -0,0 +1,13 @@
+import type { Particle } from "./particle.js";
+/** A collection of particles stepped together. */
+export declare class ParticleWorld {
+    /** Particles in this world, integrated in array order. Add and remove them directly. */
+    readonly particles: Particle[];
+    /**
+     * Integrates every particle by one step.
+     *
+     * @param dt Step length in seconds.
+     * @throws RangeError If `dt` is not positive and the world has particles.
+     */
+    step(dt: number): void;
+}

package/dist/types/engine/particle.d.ts

@@ -0,0 +1,51 @@
+import { Vec3, type Vec3Like } from "../math/index.js";
+/**
+ * A point mass integrated with semi-implicit Euler.
+ *
+ * Mass is stored as its inverse, so `inverseMass = 0` represents an immovable particle.
+ * Vector fields are `readonly` references: change them in place, e.g.
+ * `particle.position.set(0, 1, 0)`.
+ */
+export declare class Particle {
+    /** Position in meters. */
+    readonly position: Vec3;
+    /** Velocity in meters per second. */
+    readonly velocity: Vec3;
+    /** Constant acceleration in m/s², independent of mass. Typically gravity. */
+    readonly acceleration: Vec3;
+    /** Sum of forces in newtons applied since the last `integrate`. */
+    readonly forceAccum: Vec3;
+    /** Fraction of velocity kept per second, in [0, 1]. `1` disables damping. */
+    damping: number;
+    /** Reciprocal of mass in 1/kg. `0` makes the particle immovable. */
+    inverseMass: number;
+    /** Mass in kilograms. `Infinity` when `inverseMass` is `0`. */
+    get mass(): number;
+    /**
+     * Sets the mass.
+     *
+     * @param mass Mass in kilograms. `Infinity` makes the particle immovable.
+     * @throws RangeError If `mass` is not positive.
+     */
+    setMass(mass: number): void;
+    /** Whether forces and integration can move this particle. */
+    hasFiniteMass(): boolean;
+    /**
+     * Adds a force for the next `integrate`.
+     *
+     * @param force Force in newtons.
+     */
+    addForce(force: Vec3Like): void;
+    /** Discards all accumulated forces. */
+    clearAccumulator(): void;
+    /**
+     * Advances the particle by one step and clears the force accumulator.
+     *
+     * Velocity is updated first and the new velocity moves the position. A particle with
+     * `inverseMass = 0` does not move, whatever its velocity.
+     *
+     * @param dt Step length in seconds.
+     * @throws RangeError If `dt` is not positive.
+     */
+    integrate(dt: number): void;
+}

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
-export { FixedStepLoop } from './engine/loop.js';
-export type { FrameResult } from './engine/loop.js';
+export { FixedStepLoop, Particle, ParticleWorld } from './engine/index.js';
+export type { FrameResult } from './engine/index.js';
 export { EPSILON, approxEqual, clamp, Vec3, Mat3x3, Mat3x4, Quaternion } from './math/index.js';
 export type { QuatLike, Vec3Like } from './math/index.js';

package/package.json

@@ -1,48 +1,60 @@
-{
-    "name": "aether-physics",
-    "version": "0.1.0",
-    "description": "A 3D rigid-body physics engine built from scratch in TypeScript, with a Lit + Three.js playground.",
-    "license": "MIT",
-    "author": "Brandon Berisford",
-    "keywords": ["physics", "physics-engine", "rigid-body", "quaternion", "typescript"],
-    "homepage": "https://beyondbelief96.github.io/aether/",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/BeyondBelief96/aether.git"
-    },
-    "bugs": "https://github.com/BeyondBelief96/aether/issues",
-    "type": "module",
-    "sideEffects": ["./src/playground/**"],
-    "files": ["dist"],
-    "types": "./dist/types/index.d.ts",
-    "exports": {
-        ".": {
-            "types": "./dist/types/index.d.ts",
-            "default": "./dist/index.js"
-        },
-        "./math": {
-            "types": "./dist/types/math/index.d.ts",
-            "default": "./dist/math.js"
-        }
-    },
-    "scripts": {
-        "dev": "vite",
-        "build": "tsc && vite build",
-        "preview": "vite preview",
-        "build:lib": "vite build --config vite.lib.config.ts && tsc -p tsconfig.build.json",
-        "prepublishOnly": "npm run typecheck && npm run test:run && npm run build:lib",
-        "typecheck": "tsc",
-        "test": "vitest",
-        "test:run": "vitest run"
-    },
-    "devEngines": {},
-    "devDependencies": {
-        "@types/three": "^0.186.0",
-        "fast-check": "^4.10.2",
-        "lit": "^3.3.3",
-        "three": "^0.186.1",
-        "typescript": "^7.0.2",
-        "vite": "^8.3.4",
-        "vitest": "^5.0.3"
-    }
-}
+{
+    "name": "aether-physics",
+    "version": "0.2.0",
+    "description": "A 3D rigid-body physics engine built from scratch in TypeScript, with a Lit + Three.js playground.",
+    "license": "MIT",
+    "author": "Brandon Berisford",
+    "keywords": [
+        "physics",
+        "physics-engine",
+        "rigid-body",
+        "quaternion",
+        "typescript"
+    ],
+    "homepage": "https://beyondbelief96.github.io/aether/",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/BeyondBelief96/aether.git"
+    },
+    "bugs": "https://github.com/BeyondBelief96/aether/issues",
+    "type": "module",
+    "sideEffects": [
+        "./src/playground/**"
+    ],
+    "files": [
+        "dist"
+    ],
+    "types": "./dist/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/types/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./math": {
+            "types": "./dist/types/math/index.d.ts",
+            "default": "./dist/math.js"
+        }
+    },
+    "scripts": {
+        "dev": "vite",
+        "build": "tsc && vite build",
+        "preview": "vite preview",
+        "build:lib": "vite build --config vite.lib.config.ts && tsc -p tsconfig.build.json",
+        "prepublishOnly": "npm run typecheck && npm run test:run && npm run build:lib",
+        "typecheck": "tsc",
+        "test": "vitest",
+        "test:run": "vitest run",
+        "test:smoke": "node scripts/smoke-test.mjs"
+    },
+    "devEngines": {},
+    "devDependencies": {
+        "@types/three": "^0.186.0",
+        "fast-check": "^4.10.2",
+        "lit": "^3.3.3",
+        "playwright-core": "^1.58.0",
+        "three": "^0.186.1",
+        "typescript": "^7.0.2",
+        "vite": "^8.3.4",
+        "vitest": "^5.0.3"
+    }
+}