docs.json

[{"name":"Physics","comment":"\n\n\n# Coordinates\n\n@docs WorldCoordinates, BodyCoordinates\n\n\n# Bodies\n\n@docs Body\n\n@docs block, plane, sphere, cylinder, pointMass\n\n\n# Positioning\n\n@docs moveTo, translateBy, rotateAround, place\n\n\n# Simulation\n\n@docs simulate, onEarth, Config\n\n@docs Contacts, emptyContacts, contactPoints\n\n\n# Properties\n\n@docs frame, originPoint, velocity, angularVelocity, velocityAt\n\n@docs centerOfMass, mass\n\n\n# Interaction\n\n@docs raycast, applyForce, applyImpulse\n\n\n# Composite bodies\n\n@docs dynamic, static\n\n\n# Overrides\n\nChange body state directly, bypassing the simulation.\n\n@docs setVelocityTo, setAngularVelocityTo, scaleMassTo\n\n\n# Advanced\n\n@docs damp, lock, applyInverseInertia, angularAccelerationFromTorque, angularVelocityDeltaFromAngularImpulse\n\n","unions":[],"aliases":[{"name":"Body","comment":" A body is pure physics state — position, velocity, orientation.\nAll bodies start out centered on the origin; use [moveTo](#moveTo) to set the position.\n\nUse [block](#block), [plane](#plane), [sphere](#sphere), or [cylinder](#cylinder)\nfor simple bodies, or [dynamic](#dynamic) and [static](#static) for bodies\nmade of multiple [shapes](Physics-Shape#Shape).\n\n","args":[],"type":"Physics.Types.Body"},{"name":"BodyCoordinates","comment":" Coordinate system of a body, used for defining\n[shapes](Physics-Shape#Shape) and [constraints](Physics-Constraint#Constraint)\nrelative to the body’s origin.\n","args":[],"type":"Internal.Coordinates.BodyCoordinates"},{"name":"Config","comment":" Configures a simulation.\n\n    onEarth =\n        { gravity = Vector3d.gees 0 0 -1\n        , duration = Duration.seconds (1 / 60)\n        , solverIterations = 20\n        , contacts = emptyContacts\n        , constrain = \\_ -> Nothing\n        , collide = \\_ _ -> True\n        }\n\n  - `gravity` — set the gravity vector, or `Vector3d.zero` for no gravity\n\n  - `duration` — set to `Duration.seconds (1 / 60)` for 60 fps\n\n  - `solverIterations` — balance between precision and performance, 20 is a sweet spot\n\n  - `contacts` — pass [Contacts](#Contacts) from the previous frame for warm starting, or leave as default for cold start\n\n  - `constrain` — limit body movement relative to each other, see [Constraint](Physics-Constraint#Constraint)\n\n  - `collide` — decide which bodies can collide with each other.\n\n","args":["id"],"type":"{ gravity : Vector3d.Vector3d Acceleration.MetersPerSecondSquared Physics.WorldCoordinates, duration : Duration.Duration, solverIterations : Basics.Int, contacts : Physics.Contacts id, constrain : id -> Maybe.Maybe (id -> List.List Physics.Constraint.Constraint), collide : id -> id -> Basics.Bool }"},{"name":"Contacts","comment":" Contacts from the most recent simulation frame. Contains contact points\nand solver state for warm starting.\n","args":["id"],"type":"Physics.Types.Contacts id"},{"name":"WorldCoordinates","comment":" Coordinate system of the simulation, used for positions and velocities\nof bodies.\n","args":[],"type":"Internal.Coordinates.WorldCoordinates"}],"values":[{"name":"angularAccelerationFromTorque","comment":" Compute angular acceleration from torque: α = I⁻¹τ\n\nHow fast will this torque make the body spin up?\n\n","type":"Physics.Body -> Vector3d.Vector3d Torque.NewtonMeters Physics.WorldCoordinates -> Vector3d.Vector3d AngularAcceleration.RadiansPerSecondSquared Physics.WorldCoordinates"},{"name":"angularVelocity","comment":" Get the current angular velocity of a body.\n","type":"Physics.Body -> Vector3d.Vector3d AngularSpeed.RadiansPerSecond Physics.WorldCoordinates"},{"name":"angularVelocityDeltaFromAngularImpulse","comment":" Compute angular velocity change from an angular impulse: Δω = I⁻¹L\n\nHow much does this impulse add to my current spin?\n\n","type":"Physics.Body -> Vector3d.Vector3d (Quantity.Product Torque.NewtonMeters Duration.Seconds) Physics.WorldCoordinates -> Vector3d.Vector3d AngularSpeed.RadiansPerSecond Physics.WorldCoordinates"},{"name":"applyForce","comment":" Apply a force at a point on a body.\n\nKeep applying the force every simulation step to accelerate.\n\n    force =\n        Vector3d.withLength (Force.newtons 50)\n            Direction3d.positiveY\n\n    pushedBox =\n        box\n            |> applyForce force pointOnBox\n\n","type":"Vector3d.Vector3d Force.Newtons Physics.WorldCoordinates -> Point3d.Point3d Length.Meters Physics.WorldCoordinates -> Physics.Body -> Physics.Body"},{"name":"applyImpulse","comment":" Apply an impulse at a point on a body, adding to its velocity and angular velocity.\n\n    impulse =\n        Vector3d.withLength\n            (Quantity.times (Duration.seconds 0.005)\n                (Force.newtons 50)\n            )\n            Direction3d.positiveY\n\n    hitCueBall =\n        cueBall\n            |> applyImpulse impulse hitPoint\n\n","type":"Vector3d.Vector3d (Quantity.Product Force.Newtons Duration.Seconds) Physics.WorldCoordinates -> Point3d.Point3d Length.Meters Physics.WorldCoordinates -> Physics.Body -> Physics.Body"},{"name":"applyInverseInertia","comment":" Apply the inverse inertia tensor of a body to a vector.\nReturns Vector3d.zero for static bodies.\nFor common cases, see [angularAccelerationFromTorque](#angularAccelerationFromTorque)\nand [angularVelocityDeltaFromAngularImpulse](#angularVelocityDeltaFromAngularImpulse).\n","type":"Physics.Body -> Vector3d.Vector3d units Physics.WorldCoordinates -> Vector3d.Vector3d (Quantity.Rate units (Quantity.Product Mass.Kilograms Area.SquareMeters)) Physics.WorldCoordinates"},{"name":"block","comment":" ","type":"Block3d.Block3d Length.Meters Physics.BodyCoordinates -> Physics.Material.Material Physics.Material.Dense -> Physics.Body"},{"name":"centerOfMass","comment":" Get the center of mass of a body. Returns Nothing for static bodies.\n","type":"Physics.Body -> Maybe.Maybe (Point3d.Point3d Length.Meters Physics.WorldCoordinates)"},{"name":"contactPoints","comment":" Get contact points from the most recent simulation frame, filtered by a predicate.\nEach entry is a pair of body ids and a list of world-space contact points between them.\n\n    crash =\n        Physics.contactPoints\n            (\\a b -> a == \"jeep\" && b == \"wall\")\n            contacts\n\n","type":"(id -> id -> Basics.Bool) -> Physics.Contacts id -> List.List ( id, id, List.List (Point3d.Point3d Length.Meters Physics.WorldCoordinates) )"},{"name":"cylinder","comment":" Create a cylinder, approximated with 12 side faces.\nFor more subdivisions, use [dynamic](#dynamic) with [Shape.cylinder](Physics-Shape#cylinder).\n","type":"Cylinder3d.Cylinder3d Length.Meters Physics.BodyCoordinates -> Physics.Material.Material Physics.Material.Dense -> Physics.Body"},{"name":"damp","comment":" Set linear and angular damping, in order to decrease velocity over time.\nThese parameters specify the proportion of velocity lost per second.\nInputs are clamped between 0 and 1, the defaults are 0.01.\n","type":"{ linear : Basics.Float, angular : Basics.Float } -> Physics.Body -> Physics.Body"},{"name":"dynamic","comment":" Create a dynamic body from shapes and materials. Mass and center of mass\nare derived from geometry and density.\n","type":"List.List ( Physics.Shape.Shape, Physics.Material.Material Physics.Material.Dense ) -> Physics.Body"},{"name":"emptyContacts","comment":" Empty contacts for the first simulation frame (no warm starting).\n","type":"Physics.Contacts id"},{"name":"frame","comment":" Get the position and orientation of the body in the world as Frame3d.\nUseful to transform points and directions between world and body coordinates,\ne.g. for rendering.\n","type":"Physics.Body -> Frame3d.Frame3d Length.Meters Physics.WorldCoordinates { defines : Physics.BodyCoordinates }"},{"name":"lock","comment":" Restrict a body’s degrees of freedom along world axes. The list fully\ndescribes the lock state — calling `lock` again replaces the previous\nmasks. An empty list clears all locks.\n\n    -- 2D-in-3D gameplay on the XY plane\n    body |> lock [ Lock.translateZ, Lock.rotateX, Lock.rotateY ]\n\n    -- character controller: slides freely, never tips\n    body |> lock Lock.allRotation\n\nSee [Physics.Lock](Physics-Lock) for the available tokens. Has no effect on static bodies.\n\n","type":"List.List Physics.Lock.Lock -> Physics.Body -> Physics.Body"},{"name":"mass","comment":" Get the mass of a body. Returns Nothing for static bodies.\n","type":"Physics.Body -> Maybe.Maybe Mass.Mass"},{"name":"moveTo","comment":" Set the position of the body in the world,\ne.g. to raise a body 5 meters above the origin:\n\n    movedBody =\n        body\n            |> moveTo (Point3d.meters 0 0 5)\n\n","type":"Point3d.Point3d Length.Meters Physics.WorldCoordinates -> Physics.Body -> Physics.Body"},{"name":"onEarth","comment":" A ready-to-use simulation config with Earth gravity pointing down (-Z)\nat 60 fps. Customize it by updating individual fields,\nsee [Config](#Config) for available options.\n","type":"Physics.Config id"},{"name":"originPoint","comment":" Get the origin point of a body in the world.\n","type":"Physics.Body -> Point3d.Point3d Length.Meters Physics.WorldCoordinates"},{"name":"place","comment":" Set the position and orientation of a body. Like [moveTo](#moveTo)\nbut also sets the orientation.\n\n    placedBody =\n        body\n            |> place\n                (Frame3d.atPoint (Point3d.meters 2 0 1)\n                    |> Frame3d.rotateAround Axis3d.z (Angle.degrees 45)\n                )\n\nLeft-handed frames are not supported — Z is recomputed from X and Y.\n\n","type":"Frame3d.Frame3d Length.Meters Physics.WorldCoordinates { defines : Physics.BodyCoordinates } -> Physics.Body -> Physics.Body"},{"name":"plane","comment":" Create a static plane, collidable only from the direction of the normal,\ne.g. for +Z:\n\n    floor =\n        Physics.plane Plane3d.xy Material.wood\n\n","type":"Plane3d.Plane3d Length.Meters Physics.BodyCoordinates -> Physics.Material.Material any -> Physics.Body"},{"name":"pointMass","comment":" Create a point mass — infinitely small, so it doesn’t collide with other point masses.\n","type":"Point3d.Point3d Length.Meters Physics.WorldCoordinates -> Mass.Mass -> Physics.Material.Material any -> Physics.Body"},{"name":"raycast","comment":" Find the closest intersection of a ray against a list of bodies.\n\n  - point masses are always excluded because they are infinitely small\n  - a plane only intersects when the ray is facing the plane’s normal\n\n","type":"Axis3d.Axis3d Length.Meters Physics.WorldCoordinates -> List.List ( id, Physics.Body ) -> Maybe.Maybe ( id, Physics.Body, { point : Point3d.Point3d Length.Meters Physics.WorldCoordinates, normal : Direction3d.Direction3d Physics.WorldCoordinates } )"},{"name":"rotateAround","comment":" Rotate the body around an axis in the world,\ne.g. to rotate a body 45 degrees around the Z axis:\n\n    rotatedBody =\n        body\n            |> rotateAround Axis3d.z (Angle.degrees 45)\n\n","type":"Axis3d.Axis3d Length.Meters Physics.WorldCoordinates -> Angle.Angle -> Physics.Body -> Physics.Body"},{"name":"scaleMassTo","comment":" Scale a body to the given mass. The volume and center of mass\nare preserved. Has no effect on static bodies.\n","type":"Mass.Mass -> Physics.Body -> Physics.Body"},{"name":"setAngularVelocityTo","comment":" Replace the angular velocity of a body. See [setVelocityTo](#setVelocityTo)\nfor guidance. Has no effect on static bodies.\n","type":"Vector3d.Vector3d AngularSpeed.RadiansPerSecond Physics.WorldCoordinates -> Physics.Body -> Physics.Body"},{"name":"setVelocityTo","comment":" Replace the linear velocity of a body.\n\nFor physics-correct changes, prefer [applyImpulse](#applyImpulse). Using\n`setVelocityTo` after `applyImpulse` silently discards the impulse:\n\n    body\n        |> applyImpulse impulse point\n        -- erased by the next line\n        |> setVelocityTo newVelocity\n\nHas no effect on static bodies.\n\n","type":"Vector3d.Vector3d Speed.MetersPerSecond Physics.WorldCoordinates -> Physics.Body -> Physics.Body"},{"name":"simulate","comment":" Simulates one frame. Returns updated bodies and contacts.\nCall this on a message from the `onAnimationFrame` subscription\nwith [onEarth](#onEarth) to simulate 1/60th of a second in Earth gravity:\n\n    ( simulated, contacts ) =\n        simulate onEarth model.bodies\n\nTo improve solver stability for stacked objects, pass contacts\nfrom the previous frame back via the config’s `contacts` field:\n\n    ( simulated, contacts ) =\n        simulate { onEarth | contacts = model.contacts }\n            model.bodies\n\n","type":"Physics.Config id -> List.List ( id, Physics.Body ) -> ( List.List ( id, Physics.Body ), Physics.Contacts id )"},{"name":"sphere","comment":" ","type":"Sphere3d.Sphere3d Length.Meters Physics.BodyCoordinates -> Physics.Material.Material Physics.Material.Dense -> Physics.Body"},{"name":"static","comment":" Create a static body from shapes and materials.\nStatic bodies only collide with dynamic bodies, not other static bodies.\n","type":"List.List ( Physics.Shape.Shape, Physics.Material.Material any ) -> Physics.Body"},{"name":"translateBy","comment":" Move the body relative to its current position,\ne.g. to translate a body down by 5 meters:\n\n    translatedBody =\n        body\n            |> translateBy (Vector3d.meters 0 0 -5)\n\n","type":"Vector3d.Vector3d Length.Meters Physics.WorldCoordinates -> Physics.Body -> Physics.Body"},{"name":"velocity","comment":" Get the current linear velocity of a body.\n","type":"Physics.Body -> Vector3d.Vector3d Speed.MetersPerSecond Physics.WorldCoordinates"},{"name":"velocityAt","comment":" Get the linear velocity of a point on a body.\nTakes into account both linear and angular velocities.\n","type":"Point3d.Point3d Length.Meters Physics.WorldCoordinates -> Physics.Body -> Vector3d.Vector3d Speed.MetersPerSecond Physics.WorldCoordinates"}],"binops":[]},{"name":"Physics.Constraint","comment":"\n\n@docs Constraint\n\n@docs pointToPoint, hinge, distance, lock\n\n","unions":[],"aliases":[{"name":"Constraint","comment":" Limit the freedom of movement of two bodies relative to each other.\n\nPass a `constrain` function in the [simulation config](Physics#Config). For example, to drag\na body with the mouse, connect a mouse to a point on the box with\n[pointToPoint](#pointToPoint):\n\n    constrain id =\n        if id == \"mouse\" then\n            Just\n                (\\otherId ->\n                    if otherId == \"box\" then\n                        [ pointToPoint Point3d.origin pointOnBox ]\n\n                    else\n                        []\n                )\n\n        else\n            Nothing\n\n","args":[],"type":"Physics.Types.Constraint"}],"values":[{"name":"distance","comment":" Keep the centers of mass of two bodies at the constant distance\nfrom each other.\n","type":"Length.Length -> Physics.Constraint.Constraint"},{"name":"hinge","comment":" Keep two bodies connected with each other and limit the freedom of rotation.\nUseful for e.g. connecting a window to a window frame, or to connect a wheel to a car.\n","type":"Axis3d.Axis3d Length.Meters Internal.Coordinates.BodyCoordinates -> Axis3d.Axis3d Length.Meters Internal.Coordinates.BodyCoordinates -> Physics.Constraint.Constraint"},{"name":"lock","comment":" Keep two bodies connected with each other and remove all degrees of freedom between bodies.\n","type":"Frame3d.Frame3d Length.Meters Internal.Coordinates.BodyCoordinates {} -> Frame3d.Frame3d Length.Meters Internal.Coordinates.BodyCoordinates {} -> Physics.Constraint.Constraint"},{"name":"pointToPoint","comment":" Connect a point on the first body with a point on the second body.\nThis doesn’t limit the freedom of rotation of two bodies.\n","type":"Point3d.Point3d Length.Meters Internal.Coordinates.BodyCoordinates -> Point3d.Point3d Length.Meters Internal.Coordinates.BodyCoordinates -> Physics.Constraint.Constraint"}],"binops":[]},{"name":"Physics.Lock","comment":" Restrict a body’s degrees of freedom along world axes.\n\nPass a list of `Lock` tokens to [Physics.lock](Physics#lock). Each entry\nremoves one degree of freedom from the body. The list fully describes the\nbody’s lock state — calling `lock` again with a different list replaces the\nprevious one. An empty list clears all locks.\n\n@docs Lock\n\n\n# Translation\n\n@docs translateX, translateY, translateZ\n\n\n# Rotation\n\n@docs rotateX, rotateY, rotateZ\n\n\n# Presets\n\n@docs allTranslation, allRotation\n\n","unions":[],"aliases":[{"name":"Lock","comment":" A single degree of freedom to lock.\n","args":[],"type":"Physics.Types.Lock"}],"values":[{"name":"allRotation","comment":" All three rotation axes locked. The body cannot tip or spin.\nUseful for character capsules whose orientation is driven outside\nof physics.\n","type":"List.List Physics.Lock.Lock"},{"name":"allTranslation","comment":" All three translation axes locked. The body cannot move.\n","type":"List.List Physics.Lock.Lock"},{"name":"rotateX","comment":" Lock rotation about the world X axis.\n","type":"Physics.Lock.Lock"},{"name":"rotateY","comment":" Lock rotation about the world Y axis.\n","type":"Physics.Lock.Lock"},{"name":"rotateZ","comment":" Lock rotation about the world Z axis.\n","type":"Physics.Lock.Lock"},{"name":"translateX","comment":" Lock translation along the world X axis.\n","type":"Physics.Lock.Lock"},{"name":"translateY","comment":" Lock translation along the world Y axis.\n","type":"Physics.Lock.Lock"},{"name":"translateZ","comment":" Lock translation along the world Z axis.\n","type":"Physics.Lock.Lock"}],"binops":[]},{"name":"Physics.Material","comment":"\n\n@docs Material\n\n@docs wood, rubber, steel, ice\n\n\n# Custom materials\n\n@docs Dense, dense, Surface, surface\n\n","unions":[{"name":"Dense","comment":" Material with density, required for dynamic bodies\nwhere mass is computed from geometry.\n","args":[],"cases":[]},{"name":"Surface","comment":" Material with surface properties only — friction and bounciness,\nno density. Used for static bodies and point masses.\n","args":[],"cases":[]}],"aliases":[{"name":"Material","comment":" Material encodes friction, bounciness, and optionally density.\n\nThe type parameter tracks capabilities:\n\n  - `Material Dense` — carries density (required for volumetric bodies)\n  - `Material Surface` — surface properties only (for static bodies and point masses)\n\n**Friction** controls how much a body resists sliding against another.\n0 means frictionless (like ice), 1 means maximum grip (like rubber).\n\n**Bounciness** (coefficient of restitution) controls how much kinetic energy\nis preserved after a collision. 0 means no bounce (the body absorbs the impact),\n1 means a perfectly elastic bounce.\n\nWhen two shapes collide, their friction values are combined using the geometric\nmean √(f1 · f2), so a slippery surface dominates. Bounciness uses the\nmaximum of the two values, so the bouncier surface wins.\n\n","args":["kind"],"type":"Physics.Types.Material kind"}],"values":[{"name":"dense","comment":" Create a dense material.\n\nDensity is clamped to at least 1 kg/m³. Friction and bounciness are clamped to [0, 1].\n\n","type":"{ density : Density.Density, friction : Basics.Float, bounciness : Basics.Float } -> Physics.Material.Material Physics.Material.Dense"},{"name":"ice","comment":" Density 900 kg/m³, friction 0.03, bounciness 0.1.\n","type":"Physics.Material.Material any"},{"name":"rubber","comment":" Density 1100 kg/m³, friction 0.8, bounciness 0.7.\n","type":"Physics.Material.Material any"},{"name":"steel","comment":" Density 7800 kg/m³, friction 0.3, bounciness 0.2.\n","type":"Physics.Material.Material any"},{"name":"surface","comment":" Create a surface material.\n\nFriction and bounciness are clamped to [0, 1].\n\n","type":"{ friction : Basics.Float, bounciness : Basics.Float } -> Physics.Material.Material Physics.Material.Surface"},{"name":"wood","comment":" Density 700 kg/m³, friction 0.4, bounciness 0.3.\n","type":"Physics.Material.Material any"}],"binops":[]},{"name":"Physics.Shape","comment":"\n\n@docs Shape, block, sphere, cylinder\n\n\n# Complex shapes\n\n@docs minus, plus, sum, unsafeConvex\n\n","unions":[],"aliases":[{"name":"Shape","comment":" Shapes are needed for creating compound [dynamic](Physics#dynamic)\nand [static](Physics#static) bodies.\n\nThe supported primitive shapes are [block](#block), [sphere](#sphere),\nand [cylinder](#cylinder). For complex geometry use [unsafeConvex](#unsafeConvex).\n\nShapes within a body **should not overlap** — composing shapes only affects physical\nproperties like mass, inertia, and center of mass. Use [plus](#plus) and\n[minus](#minus) to combine shapes, for example to create hollow bodies.\n\n","args":[],"type":"Physics.Types.Shape"}],"values":[{"name":"block","comment":" ","type":"Block3d.Block3d Length.Meters Internal.Coordinates.BodyCoordinates -> Physics.Shape.Shape"},{"name":"cylinder","comment":" Create a cylinder shape with the given number of side faces, clamped to at least 3.\nEven numbers are more efficient, because collision performance depends\non the number of unique non-parallel faces and edges.\n","type":"Basics.Int -> Cylinder3d.Cylinder3d Length.Meters Internal.Coordinates.BodyCoordinates -> Physics.Shape.Shape"},{"name":"minus","comment":" Subtract the first shape from the second. The subtracted shape must be\nfully contained within the other. It reduces volume, mass, and inertia,\nand is excluded from collision detection.\n\nUseful for hollow bodies.\n\n    crate =\n        Shape.block outer\n            |> Shape.minus (Shape.block inner)\n\n","type":"Physics.Shape.Shape -> Physics.Shape.Shape -> Physics.Shape.Shape"},{"name":"plus","comment":" Add a shape to another.\n\n    snowman =\n        Shape.sphere bottom\n            |> Shape.plus (Shape.sphere top)\n\n","type":"Physics.Shape.Shape -> Physics.Shape.Shape -> Physics.Shape.Shape"},{"name":"sphere","comment":" ","type":"Sphere3d.Sphere3d Length.Meters Internal.Coordinates.BodyCoordinates -> Physics.Shape.Shape"},{"name":"sum","comment":" Combine a list of shapes.\n\n    dumbbell =\n        Shape.sum\n            [ Shape.cylinder 12 leftWeight\n            , Shape.cylinder 12 bar\n            , Shape.cylinder 12 rightWeight\n            ]\n\n","type":"List.List Physics.Shape.Shape -> Physics.Shape.Shape"},{"name":"unsafeConvex","comment":" Create a shape from a triangular mesh. This is useful if you want\nto import from Blender using [elm-obj-file](https://package.elm-lang.org/packages/w0rm/elm-obj-file/latest).\n\n**Note:** this may cause unexpected behavior, unless you make sure that:\n\n  - the mesh is a [convex polyhedron](https://en.wikipedia.org/wiki/Convex_polytope);\n  - the mesh is watertight, consisting of one closed surface;\n  - all faces have counterclockwise [winding order](https://cmichel.io/understanding-front-faces-winding-order-and-normals).\n\n","type":"TriangularMesh.TriangularMesh (Point3d.Point3d Length.Meters Internal.Coordinates.BodyCoordinates) -> Physics.Shape.Shape"}],"binops":[]}]