aether-physics 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# Aether
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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

@@ -0,0 +1,88 @@
+import { a as e, i as t, n, o as r, r as i, s as a, t as o } from "./math-DrI-pge3.js";
+//#region src/engine/loop.ts
+var s = .25, c = class {
+	timeScale = 1;
+	paused = !1;
+	maxStepsPerFrame = 8;
+	#e;
+	#t = 0;
+	#n = null;
+	#r = 0;
+	#i = 0;
+	constructor(e = 60) {
+		this.#e = 1 / e;
+	}
+	get dt() {
+		return this.#e;
+	}
+	get hz() {
+		return 1 / this.#e;
+	}
+	set hz(e) {
+		if (!(e > 0)) throw RangeError(`hz must be positive, got ${e}`);
+		this.#e = 1 / e;
+	}
+	get simTime() {
+		return this.#r;
+	}
+	stepOnce() {
+		this.#i++;
+	}
+	reset() {
+		this.#t = 0, this.#n = null, this.#r = 0, this.#i = 0;
+	}
+	advance(e, t) {
+		let n = this.#n;
+		this.#n = e;
+		let r = n === null ? 0 : Math.min((e - n) / 1e3, s), i = 0, a = () => {
+			t(this.#e), this.#r += this.#e, i++;
+		};
+		for (; this.#i > 0; this.#i--) a();
+		if (this.paused) return {
+			steps: i,
+			alpha: 1,
+			droppedTime: !1
+		};
+		for (this.#t += r * this.timeScale; this.#t >= this.#e && i < this.maxStepsPerFrame;) a(), this.#t -= this.#e;
+		let o = !1;
+		return this.#t >= this.#e && (this.#t %= this.#e, o = !0), {
+			steps: i,
+			alpha: this.#t / this.#e,
+			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, l as Particle, u as ParticleWorld, o as Quaternion, t as Vec3, r as approxEqual, a as clamp };