@axpecter/lync 2.3.3 → 3.0.0

package/shape/Order.luau

@@ -0,0 +1,64 @@
+--!strict
+--!optimize 2
+-- What the canonical ordering decides: the order of names, and which fields vary.
+
+local Base = require (script.Parent.Parent.codec.Base)
+
+local Order = {}
+
+-- Constants -----------------------------------------------------------
+
+-- The kinds that vary whatever they are made of.
+const ALWAYS = table.freeze ({
+    vlq = true,
+    vli = true,
+    tagged = true,
+    optional = true,
+    inst = true,
+}) :: { [string]: boolean }
+
+-- The kinds that carry a count, which vary exactly when the two ends of that count differ.
+const COUNTED = table.freeze ({
+    str = true,
+    buffer = true,
+    array = true,
+    map = true,
+}) :: { [string]: boolean }
+
+-- Public --------------------------------------------------------------
+
+-- The names a declaration carries, in the one order two machines can both arrive at.
+function Order.names <V>(of: { [string]: V }): { string }
+    local out: { string } = {}
+    for name in of do
+        table.insert (out, name)
+    end
+
+    table.sort (out)
+    return out
+end
+
+--[[
+    Whether a declaration's size depends on the value it carries, which is what decides the region a
+    field is written in and nothing else.
+]]
+function Order.varies (of: Base.Cell): boolean
+    local kind = of.kind
+    if ALWAYS[kind] then return true end
+
+    if COUNTED[kind] then
+        local params = of.params
+        if params.min ~= params.max then return true end
+    end
+
+    local children = of.children
+    if children == nil then return false end
+
+    for _, child in children do
+        if Order.varies (child) then return true end
+    end
+
+    return false
+end
+
+return table.freeze (Order)

package/shape/Regions.luau

@@ -0,0 +1,113 @@
+--!strict
+--!optimize 2
+-- Which of the four regions every field of a record is written in, and in what order.
+
+local Base = require (script.Parent.Parent.codec.Base)
+local Folds = require (script.Parent.Folds)
+local Grid = require (script.Parent.Grid)
+local Joins = require (script.Parent.Joins)
+local Order = require (script.Parent.Order)
+local Protocol = require (script.Parent.Parent.wire.Protocol)
+
+local Regions = {}
+
+-- Constants -----------------------------------------------------------
+
+-- The widest a leaf can be and still flow with its neighbours rather than take whole bytes.
+const CEILING = Protocol.BIT_CEILING
+
+-- Types ---------------------------------------------------------------
+
+-- One field, at the path it is reached by from the record being partitioned.
+export type Entry = {
+    read at: { string },
+    read of: Base.Cell,
+}
+
+-- The four regions, each in the order it is written, and the records that dissolved on the way.
+export type Split = {
+    read presence: { Entry },
+    read bits: { Entry },
+    read bytes: { Entry },
+    read vars: { Entry },
+    read nests: { Entry },
+}
+
+-- Private -------------------------------------------------------------
+
+-- The leaves a declaration takes where it is a region field, and nothing where it is not.
+local function held (of: Base.Cell): { Grid.Grid }?
+    local named = Joins.leaves (of)
+    if named ~= nil then return named end
+
+    local fold = Folds.fold (of)
+    return if fold == nil then nil else fold.leaves
+end
+
+-- Every field of a record into the region it is written in, and the fixed records under it too.
+local function walk (of: { [string]: Base.Cell }, at: { string }, into: Split)
+    for _, name in Order.names (of) do
+        local child = of[name]
+
+        local path = table.clone (at)
+        table.insert (path, name)
+
+        local entry: Entry = table.freeze ({ at = table.freeze (path), of = child })
+
+        --[[
+            Both lists, because the two ask different things. A presence bit says whether the field
+            is there at all, and the value behind it is still one whose width is not known ahead.
+        ]]
+        if child.kind == "optional" then
+            table.insert (into.presence, entry)
+            table.insert (into.vars, entry)
+            continue
+        end
+
+        if Order.varies (child) then
+            table.insert (into.vars, entry)
+            continue
+        end
+
+        if child.kind == "struct" then
+            table.insert (into.nests, entry)
+            walk (child.children :: { [string]: Base.Cell }, path, into)
+            continue
+        end
+
+        if Regions.packs (child) then
+            table.insert (into.bits, entry)
+            continue
+        end
+
+        table.insert (into.bytes, entry)
+    end
+end
+
+-- Public --------------------------------------------------------------
+
+-- Whether a declaration flows in a bit run, which is one question asked of every leaf it takes.
+function Regions.packs (of: Base.Cell): boolean
+    local leaves = held (of)
+    if leaves == nil then return false end
+
+    for _, grid in leaves do
+        if grid.width > CEILING then return false end
+    end
+    return true
+end
+
+-- A record's fields, partitioned.
+function Regions.of (of: { [string]: Base.Cell }): Split
+    local into: Split = { presence = {}, bits = {}, bytes = {}, vars = {}, nests = {} }
+    walk (of, {}, into)
+
+    table.freeze (into.presence)
+    table.freeze (into.bits)
+    table.freeze (into.bytes)
+    table.freeze (into.vars)
+    table.freeze (into.nests)
+    return table.freeze (into)
+end
+
+return table.freeze (Regions)

package/shape/Rotation.luau

@@ -0,0 +1,472 @@
+--!strict
+--!optimize 2
+-- The two orientation mappings: a direction as a pair on a square, a turn as three of its four.
+
+local Grid = require (script.Parent.Grid)
+local Protocol = require (script.Parent.Parent.wire.Protocol)
+
+local Rotation = {}
+
+-- Constants -----------------------------------------------------------
+
+-- Hoisted so the tag a branch writes is a capture rather than a read through two tables.
+const AT_X = Protocol.QUAT_X
+const AT_Y = Protocol.QUAT_Y
+const AT_Z = Protocol.QUAT_Z
+const AT_W = Protocol.QUAT_W
+
+-- How near two of the four have to be before the first of them wins.
+const LEVEL = 1e-9
+
+-- How much better one spelling of a rotation has to score before it is taken as better at all.
+const TIGHTER = 0.999999999
+-- How near a component has to sit to a grid point before it is called one.
+
+const NEARLY = 1e-9
+
+-- Types ---------------------------------------------------------------
+
+--[[
+    A direction, either way. `plane` answers the two grid indices the wire carries, and nil for a
+    reading that is no direction at all. `sphere` takes those indices back to a unit vector.
+]]
+export type Octahedral = {
+    read plane: (x: number, y: number, z: number) -> (number?, number?),
+    read sphere: (u: number, v: number) -> (number, number, number),
+}
+
+--[[
+    A turn, either way, and a pair that is a matrix in and a quaternion out. The platform builds a
+    CFrame from four numbers and hands none of them back, so the way in is off the rotation matrix
+    and the way out is the four the constructor takes.
+]]
+export type Smallest = {
+    read parts: (
+        _x: number,
+        _y: number,
+        _z: number,
+        r00: number,
+        r01: number,
+        r02: number,
+        r10: number,
+        r11: number,
+        r12: number,
+        r20: number,
+        r21: number,
+        r22: number
+    ) -> (number, number?, number?, number?),
+    read whole: (
+        largest: number,
+        a: number,
+        b: number,
+        c: number
+    ) -> (number, number, number, number),
+}
+
+--[[
+    A turn about one declared axis, either way. `parts` answers the grid index of the angle and
+    nothing for a matrix that is no rotation at all, and `whole` answers the quaternion at that
+    index. Both speak the twelve components a frame is read with, for the reason the smallest three
+    does: that is one call at the boundary and nothing here then names a datatype.
+]]
+export type Axial = {
+    read parts: (
+        _x: number,
+        _y: number,
+        _z: number,
+        r00: number,
+        r01: number,
+        r02: number,
+        r10: number,
+        r11: number,
+        r12: number,
+        r20: number,
+        r21: number,
+        r22: number
+    ) -> number?,
+    read whole: (at: number) -> (number, number, number, number),
+}
+
+-- A look direction, either way, as the same square a unit vector folds onto.
+export type Facing = {
+    read parts: (
+        _x: number,
+        _y: number,
+        _z: number,
+        r00: number,
+        r01: number,
+        r02: number,
+        r10: number,
+        r11: number,
+        r12: number,
+        r20: number,
+        r21: number,
+        r22: number
+    ) -> (number?, number?),
+    read whole: (u: number, v: number) -> (number, number, number, number),
+}
+
+-- Private -------------------------------------------------------------
+
+--[[
+    Zero counts as positive. That is what makes the fold total: a component sitting exactly on an
+    axis has to go the same way on both machines, and it is why neither `math.sign` nor
+    `vector.sign` can stand here, since both answer zero for zero and one of the two folds is then a
+    reflection through nothing.
+]]
+local function sign (value: number): number return if value >= 0 then 1 else -1 end
+
+--[[
+    The fold, which is its own inverse. The far half of the sphere reflects across the square's two
+    diagonals, and the same two lines carry it back, so both directions of the mapping share this
+    rather than each spelling a reflection out and one of them wearing a sign the other does not.
+]]
+local function folded (u: number, v: number): (number, number)
+    return (1 - math.abs (v)) * sign (u), (1 - math.abs (u)) * sign (v)
+end
+
+-- The one of the two names a point on the square's outer edge has.
+local function only (span: number, atU: number, atV: number): (number, number)
+    local edgeU = atU == 0 or atU == span
+    local edgeV = atV == 0 or atV == span
+
+    if edgeU and span - atV > atV then atV = span - atV end
+    if edgeV and span - atU > atU then atU = span - atU end
+    return atU, atV
+end
+
+--[[
+    The lower index of the two the value lies between, which is where a search of a grid cell
+    starts. Read off the nearest rather than by dividing, so the grid keeps its own arithmetic and a
+    reading that is on no grid at all arrives here as the nil that grid already answers.
+]]
+local function under (of: Grid.Grid, value: number): number?
+    local at = of.toIndex (value)
+    if at == nil then return nil end
+    return if of.fromIndex (at) > value then at - 1 else at
+end
+
+-- Public --------------------------------------------------------------
+
+--[[
+    The octahedral mapping over one grid, which is `vec3.unit`, the direction half of
+    `vec3.bounded`, and `rotation.direction`.
+]]
+function Rotation.octahedral (of: Grid.Grid): Octahedral
+    local span, fromIndex = of.span, of.fromIndex
+
+    local function sphere (u: number, v: number): (number, number, number)
+        local x, y = fromIndex (u), fromIndex (v)
+        local z = 1 - math.abs (x) - math.abs (y)
+        if z < 0 then
+            x, y = folded (x, y)
+        end
+
+        local length = math.sqrt (x * x + y * y + z * z)
+        return x / length, y / length, z / length
+    end
+
+    --[[
+        The pair whose direction is nearest, rather than the pair nearest the projection. The
+        projection is no isometry, so rounding each coordinate lands as much as a sixth of a step
+        past the arc the precision promises, and one of the cell's four corners always does better.
+        A corner is scored by how far along the vector it points, which needs no length.
+    ]]
+    local function plane (x: number, y: number, z: number): (number?, number?)
+        local reach = math.abs (x) + math.abs (y) + math.abs (z)
+        local u, v = x / reach, y / reach
+        if z < 0 then
+            u, v = folded (u, v)
+        end
+
+        local lowU, lowV = under (of, u), under (of, v)
+        if lowU == nil or lowV == nil then return nil, nil end
+
+        local best, atU, atV = -math.huge, lowU, lowV
+        for stepU = 0, 1 do
+            for stepV = 0, 1 do
+                local tryU = math.clamp (lowU + stepU, 0, span)
+                local tryV = math.clamp (lowV + stepV, 0, span)
+
+                local ax, ay, az = sphere (tryU, tryV)
+                local along = ax * x + ay * y + az * z
+                if along > best then
+                    best, atU, atV = along, tryU, tryV
+                end
+            end
+        end
+        return only (span, atU, atV)
+    end
+
+    return table.freeze ({ plane = plane, sphere = sphere })
+end
+
+-- The smallest-three mapping over one grid, which is `rotation.quat` alone.
+function Rotation.smallest (of: Grid.Grid): Smallest
+    local span, fromIndex = of.span, of.fromIndex
+
+    -- The three a tag sends and the one it leaves behind, which is `laid` the other way about.
+    local function apart (
+        tag: number,
+        x: number,
+        y: number,
+        z: number,
+        w: number
+    ): (number, number, number, number)
+        -- The one of the pair whose named component is already positive.
+        local named = w
+        if tag == AT_X then
+            named = x
+        elseif tag == AT_Y then
+            named = y
+        elseif tag == AT_Z then
+            named = z
+        end
+
+        if named < 0 then
+            x, y, z, w = -x, -y, -z, -w
+        end
+
+        if tag == AT_X then return y, z, w, x end
+        if tag == AT_Y then return x, z, w, y end
+        if tag == AT_Z then return x, y, w, z end
+        return x, y, z, w
+    end
+
+    -- The three that travelled and the one rebuilt from them, back in component order.
+    local function laid (
+        largest: number,
+        a: number,
+        b: number,
+        c: number,
+        d: number
+    ): (number, number, number, number)
+        if largest == AT_X then return d, a, b, c end
+        if largest == AT_Y then return a, d, b, c end
+        if largest == AT_Z then return a, b, d, c end
+        return a, b, c, d
+    end
+
+    --[[
+        The dropped component is positive and is whatever is left of a unit quaternion, so a frame
+        claiming three that already overrun one leaves nothing for it rather than a root of a
+        negative. Every index pair a frame can carry answers a quaternion here, and none of them
+        answers a zero one, because three zeros leave the fourth at one.
+    ]]
+    local function whole (
+        largest: number,
+        a: number,
+        b: number,
+        c: number
+    ): (number, number, number, number)
+        local ka, kb, kc = fromIndex (a), fromIndex (b), fromIndex (c)
+        local x, y, z, w =
+            laid (largest, ka, kb, kc, math.sqrt (math.max (0, 1 - ka * ka - kb * kb - kc * kc)))
+
+        local length = math.sqrt (x * x + y * y + z * z + w * w)
+        return x / length, y / length, z / length, w / length
+    end
+
+    --[[
+        The three indices whose quaternion is nearest, for the reason the direction search gives:
+        the rebuilt component moves with all three others, so the triple nearest component by
+        component is not the triple nearest as a rotation. One of the cell's eight corners is always
+        the answer.
+    ]]
+    local function parts (
+        _x: number,
+        _y: number,
+        _z: number,
+        r00: number,
+        r01: number,
+        r02: number,
+        r10: number,
+        r11: number,
+        r12: number,
+        r20: number,
+        r21: number,
+        r22: number
+    ): (number, number?, number?, number?)
+        local trace = r00 + r11 + r22
+
+        --[[
+            Which of the four is largest, and the first of them where they are level. The branch
+            decides which component is dropped, so it decides the bytes, and a quarter turn makes
+            two of them equal to within a last bit rather than exactly. A strict comparison let that
+            bit choose, and the two took turns forever.
+        ]]
+        local top = math.max (trace, r00, r11, r22) - LEVEL
+
+        local largest, a, b, c, d
+        if trace >= top then
+            local s = math.sqrt (trace + 1) * 2
+            largest, d = AT_W, 0.25 * s
+            a, b, c = (r21 - r12) / s, (r02 - r20) / s, (r10 - r01) / s
+        elseif r00 >= top then
+            local s = math.sqrt (1 + r00 - r11 - r22) * 2
+            largest, d = AT_X, 0.25 * s
+            a, b, c = (r01 + r10) / s, (r02 + r20) / s, (r21 - r12) / s
+        elseif r11 >= top then
+            local s = math.sqrt (1 + r11 - r00 - r22) * 2
+            largest, d = AT_Y, 0.25 * s
+            a, b, c = (r01 + r10) / s, (r12 + r21) / s, (r02 - r20) / s
+        else
+            local s = math.sqrt (1 + r22 - r00 - r11) * 2
+            largest, d = AT_Z, 0.25 * s
+            a, b, c = (r02 + r20) / s, (r12 + r21) / s, (r10 - r01) / s
+        end
+
+        --[[
+            Held to unit length before anything is placed on a grid. A matrix carried in float32
+            spells a quaternion a last bit of that width off one, and a CFrame carries its matrix in
+            float32.
+        ]]
+        local x, y, z, w = laid (largest, a, b, c, d)
+
+        local length = math.sqrt (x * x + y * y + z * z + w * w)
+        x, y, z, w = x / length, y / length, z / length, w / length
+
+        --[[
+            Every tag tried, and the nearest answer taken. The branch above names the largest of the
+            exact quaternion, which cannot be the whole choice: the three that travel are rounded,
+            so the bytes name one tag while the value they rebuild wants another.
+        ]]
+        local best, took, atA, atB, atC = math.huge, largest, nil, nil, nil
+        for tag = AT_X, AT_W do
+            local pa, pb, pc, pd = apart (tag, x, y, z, w)
+
+            local lowA, lowB, lowC = under (of, pa), under (of, pb), under (of, pc)
+            if lowA == nil or lowB == nil or lowC == nil then continue end
+
+            for stepA = 0, 1 do
+                for stepB = 0, 1 do
+                    for stepC = 0, 1 do
+                        local tryA = math.clamp (lowA + stepA, 0, span)
+                        local tryB = math.clamp (lowB + stepB, 0, span)
+                        local tryC = math.clamp (lowC + stepC, 0, span)
+
+                        local ka, kb, kc = fromIndex (tryA), fromIndex (tryB), fromIndex (tryC)
+
+                        --[[
+                            A triple that overruns the unit quaternion, which is not a spelling of
+                            anything.
+                        ]]
+                        local over = ka * ka + kb * kb + kc * kc
+                        if over > 1 then continue end
+
+                        local kd = math.sqrt (math.max (0, 1 - over))
+                        local away = (ka - pa) ^ 2 + (kb - pb) ^ 2 + (kc - pc) ^ 2 + (kd - pd) ^ 2
+
+                        -- Nearer wins, and where two are level the smaller spelling does.
+                        if away < best * TIGHTER then
+                            best, took, atA, atB, atC = away, tag, tryA, tryB, tryC
+                        end
+                    end
+                end
+            end
+        end
+
+        if atA == nil or atB == nil or atC == nil then return largest, nil, nil, nil end
+
+        local heldA, heldB, heldC = atA :: number, atB :: number, atC :: number
+
+        --[[
+            The same rotation, spelled by the lowest tag that can spell it exactly. Nearest is not a
+            choice a rotation can be held to, since which of two tags is nearer depends on the value
+            asked about and the bytes then take turns.
+        ]]
+        local qx, qy, qz, qw = whole (took, heldA, heldB, heldC)
+        for tag = AT_X, took - 1 do
+            local pa, pb, pc, pd = apart (tag, qx, qy, qz, qw)
+
+            local ia, ib, ic = of.toIndex (pa), of.toIndex (pb), of.toIndex (pc)
+            if ia == nil or ib == nil or ic == nil then continue end
+
+            local ka, kb, kc = fromIndex (ia), fromIndex (ib), fromIndex (ic)
+            local over = ka * ka + kb * kb + kc * kc
+            if over > 1 then continue end
+
+            local kd = math.sqrt (math.max (0, 1 - over))
+            local off = math.abs (ka - pa) + math.abs (kb - pb) + math.abs (kc - pc)
+            if off + math.abs (kd - pd) > NEARLY then continue end
+
+            return tag, ia, ib, ic
+        end
+
+        return took, heldA, heldB, heldC
+    end
+
+    return table.freeze ({ parts = parts, whole = whole })
+end
+
+-- A turn about one axis the declaration named, over the cyclic grid its precision cuts.
+function Rotation.axial (of: Grid.Grid, ax: number, ay: number, az: number): Axial
+    local length = math.sqrt (ax * ax + ay * ay + az * az)
+    local nx, ny, nz = ax / length, ay / length, az / length
+
+    local toIndex, fromIndex = of.toIndex, of.fromIndex
+
+    local function parts (
+        _x: number,
+        _y: number,
+        _z: number,
+        r00: number,
+        r01: number,
+        r02: number,
+        r10: number,
+        r11: number,
+        r12: number,
+        r20: number,
+        r21: number,
+        r22: number
+    ): number?
+        local along = (r21 - r12) * nx + (r02 - r20) * ny + (r10 - r01) * nz
+        return toIndex (math.deg (math.atan2 (along / 2, (r00 + r11 + r22 - 1) / 2)))
+    end
+
+    local function whole (at: number): (number, number, number, number)
+        local half = math.rad (fromIndex (at)) / 2
+        local turned = math.sin (half)
+
+        return nx * turned, ny * turned, nz * turned, math.cos (half)
+    end
+
+    return table.freeze ({ parts = parts, whole = whole })
+end
+
+-- A look direction on the octahedral square, and the shortest turn back onto it.
+function Rotation.facing (of: Grid.Grid): Facing
+    local mapping = Rotation.octahedral (of)
+    local plane, sphere = mapping.plane, mapping.sphere
+
+    local function parts (
+        _x: number,
+        _y: number,
+        _z: number,
+        r00: number,
+        r01: number,
+        r02: number,
+        r10: number,
+        r11: number,
+        r12: number,
+        r20: number,
+        r21: number,
+        r22: number
+    ): (number?, number?)
+        return plane (-r02, -r12, -r22)
+    end
+
+    local function whole (u: number, v: number): (number, number, number, number)
+        local tx, ty, tz = sphere (u, v)
+        local w = 1 - tz
+
+        if w <= 0 then return 0, 1, 0, 0 end
+
+        local length = math.sqrt (ty * ty + tx * tx + w * w)
+        return ty / length, -tx / length, 0, w / length
+    end
+
+    return table.freeze ({ parts = parts, whole = whole })
+end
+
+return table.freeze (Rotation)