Implement stable Sable gravity frame physics

README.md

@@ -1,12 +1,51 @@
-# Sable Gravity 0.6.0 test16
+# Sable Gravity 0.7.4
 
-Built on the working test13 Sable OBB collision path.
+Sable Gravity is a multidimensional gravity-frame kernel for moving and arbitrarily rotated
+Sable ships. A frame owns a dimension-qualified identity, a local coordinate system, a rigid
+pose and a local `-Y` gravity direction.
 
-Changes from test15:
-- never imports Sable-mutated world deltaMovement back into local velocity; removes tilted-floor drift;
-- uses Sable local floor contact as the authoritative ground state;
-- keeps creative flight independent from stale world-axis onGround state;
-- captures flight ascend/descend against the exact previous post-tick velocity, so ship rotation cannot become fake acceleration;
-- updates walk animation directly from the actual local displacement because cancelled Player.travel never reaches vanilla calculateEntityAnimation;
-- replaces Sable/vanilla sneak edge backoff with a full local plot-space floor query;
-- leaves Entity.bb axis-aligned only for Minecraft broadphase. It is no longer used as the source of local ground, flight or sneak behaviour.
+## Physics model
+
+- Players use an oriented body and plot-local feet anchor. Crouching, standing, jumping,
+  creative flight, edge sneaking and wall sliding are resolved in the ship frame without using
+  the parent-world AABB as the source of truth.
+- Entities always remain in physical parent-world coordinates. Sable is the only owner of their
+  OBB collision, tracking and packet conversion; Sable Gravity rotates gravity, locomotion and
+  drag into the selected frame without exposing the hidden plot grid to entity networking.
+- Non-player entities keep their ordinary parent-world/network position. Their oriented body is
+  foot-anchored only inside Sable's collision transform, so items and mobs do not need a spawn-time
+  coordinate rebase and cannot leak plot coordinates into packets.
+- Client particle attachment and packet conversion remain on Sable's native path. This mod does
+  not install a second universal particle lifecycle on top of Sable's particle mixins.
+- For the local player, plot-local feet position and relative velocity are authoritative. A
+  translating or rotating ship is reconstructed from them every tick instead of accumulating pose
+  deltas.
+
+## Dimensions and Cosmonautics
+
+`GravityFrameId` contains provider, dimension and local UUID. Frame lookup is always performed in
+the entity's current `Level`, so an identical SubLevel UUID in another dimension cannot alias the
+old ship. A recreated destination frame is resolved again from that level's Sable container.
+
+Gravity magnitude comes from the final parent-world `Entity#getGravity()` result while the entity
+stays physical. Dimension/altitude modifiers such as Cosmonautics therefore compose with Sable
+direction and never evaluate against the plot's synthetic Y coordinate.
+
+There is no hardcoded list of planets, dimensions or entity types. The built-in provider accepts
+Sable SubLevels from any `Level`, including Cosmonautics dimensions. Other mods can register a
+higher-priority `GravityFrameProvider` through `SableGravityApi` for directional gravity and frame
+consumers; arbitrary-orientation ship collision additionally requires a Sable-backed frame.
+
+## Development
+
+The development client loads Create, Aeronautics, Cosmonautics and the local Minecraft MCP bridge.
+The bridge is configured for `127.0.0.1:8765` only; it is not packaged into the release jar.
+
+Build with:
+
+```powershell
+.\gradlew.bat build
+```
+
+Player controls remain available through `/sablegravity enable|disable`,
+`/sablegravity strength <value>` and `/sablegravity test <state|frame|support|all>`.