From 539e459a9f5f7dafb22d8424d2d1bc5fe14d3f24 Mon Sep 17 00:00:00 2001 From: Titus Date: Mon, 16 Nov 2026 10:47:33 +0100 Subject: [PATCH] A world laid out in 3D: TypeScript SDK 4.171.0's layoutByLinks3d and Python 0.130.0's layout_by_links_3d The readers page gains a section for the 3D layout (what it places, the answer's keys, held points, that its word by-links-3d is the tool's own until its page in the standard is published); the Python page names the same function; the changelog says so. The SDK pin moves to 4.171.0 and the generated reference with it. Co-Authored-By: Claude Fable 5.2 --- package-lock.json | 8 ++--- package.json | 2 +- src/content/docs/docs/changelog.md | 1 + src/content/docs/docs/development/python.md | 1 + .../docs/development/typescript-readers.md | 31 +++++++++++++++++++ .../docs/docs/development/typescript.md | 2 +- 6 files changed, 39 insertions(+), 6 deletions(-) diff --git a/package-lock.json b/package-lock.json index 5e44aafb..535145f7 100644 --- a/package-lock.json +++ b/package-lock.json @@ -14,7 +14,7 @@ "starlight-page-actions": "0.7.1" }, "devDependencies": { - "@onlyworlds/sdk": "4.170.1", + "@onlyworlds/sdk": "4.171.0", "typescript": "5.9.3" } }, @@ -1685,9 +1685,9 @@ } }, "node_modules/@onlyworlds/sdk": { - "version": "4.170.1", - "resolved": "https://registry.npmjs.org/@onlyworlds/sdk/-/sdk-4.170.1.tgz", - "integrity": "sha512-56MEKjHylTRI0Y8Bkp9ubpNdLhLCHNKo62FLa6Tg/aapwiaArA+3dpqatZ7wvCs9dblFNkPJqId8JNfTt5brQg==", + "version": "4.171.0", + "resolved": "https://registry.npmjs.org/@onlyworlds/sdk/-/sdk-4.171.0.tgz", + "integrity": "sha512-IxSW9BbIfKDCIpPcf96IuCI7kk/1QRflVAzDmIrEP8j5uZ77QBXNpM8bHmQJjupmIw8RBDw8s/wV3YOTUHdmAQ==", "dev": true, "license": "MIT", "dependencies": { diff --git a/package.json b/package.json index 069d042b..63880dcf 100644 --- a/package.json +++ b/package.json @@ -17,7 +17,7 @@ "starlight-page-actions": "0.7.1" }, "devDependencies": { - "@onlyworlds/sdk": "4.170.1", + "@onlyworlds/sdk": "4.171.0", "typescript": "5.9.3" }, "overrides": { diff --git a/src/content/docs/docs/changelog.md b/src/content/docs/docs/changelog.md index 403806d6..66fb34e0 100644 --- a/src/content/docs/docs/changelog.md +++ b/src/content/docs/docs/changelog.md @@ -9,6 +9,7 @@ What changed on onlyworlds.com for everyone is on its own [Changelog](https://ww ## 2026-11-16 +- **[A world laid out in 3D](/docs/development/typescript-readers#a-world-laid-out-in-3d): TypeScript SDK 4.171.0's `layoutByLinks3d` and [Python](/docs/development/python) 0.130.0's `layout_by_links_3d`.** One method in both packages lays a whole graph out in three dimensions by its links, with the world's map as a flat plate, and held points keep a picture still as the world grows. Its word, `by-links-3d`, is the tool's own until its page in the standard is published. - **[The default layouts are a profile](/docs/schema/profiles#default-layouts) (serial 132).** The two methods that draw a world nobody has laid out, `by-kind` and `around`, are written out in the standard, with a fixture of 17, 10 and 15 cases: the same graph gives the same points in every tool and language. A method's word is its version. The [map-space profile](/docs/schema/profiles#map-space)'s rule on layout maps now ends on what reading may do: reading or drawing a layout map changes none of its Pins, and laying it out again is a write like any other. - **[What a saved layout does not place](/docs/development/typescript-readers#a-worlds-default-picture): TypeScript SDK 4.170.0's `unplacedByKind` and `unplacedAround`, and [Python](/docs/development/python) 0.129.0's `unplaced_by_kind` and `unplaced_around`**, answer the ids a layout method would place that a saved layout Map has no Pin for, so a tool can say how many elements a world has gained since the layout was saved. Both packages now replay the profile's own fixture from the standard's distribution. - **[Unity SDK](/docs/development/unity) v0.43.1** follows serials 130 and 131: the pin and the fixtures move (the room page's exact case fold, a value that is no object read as no element, a body that is not a message never unknown). No reader changes; a folder it writes names 0.43.1 on its producer line. diff --git a/src/content/docs/docs/development/python.md b/src/content/docs/docs/development/python.md index 2cddb892..67a81da9 100644 --- a/src/content/docs/docs/development/python.md +++ b/src/content/docs/docs/development/python.md @@ -176,6 +176,7 @@ It is schema-dist's own [folder checker](/docs/schema/folders#rules-for-tools), - **The map-space profile** (since 0.104.0): `map_space(elements)` reads a world's Maps, Zones, Markers and Pins as the [map-space profile](/docs/schema/profiles#map-space) defines, from the elements as the reader is served them. It returns `{maps, zones, pins, out}`: each Map's frame (`width`, `height`, `depth`, `z_max`, `scale` in metres per pixel from `x_metres_per_pixel`, `location`, `parent_map`; a missing `width` or `height` is measured from the Map's own placed points, with `extent: "points"`), one outline per Map a Zone has Markers on (its points in `order`, then by id, with `shape` `polygon` or `line`), each Pin's point with its element as `element_type` and `element_id`, and `out`, what the reading left aside counted by `no_point`, `no_markers`, `dangling` and `no_map`, a reason with nothing counted absent. `z` is an elevation, never a height. A number counts when it is whole by value (`2.0` reads as 2; a boolean or a fraction is no point), and a row without an id is ignored; since 0.104.1 (serial 106) two rows of one type with one id read as the last one served. Types `MapSpace`, `MapSpaceMap`, `MapSpaceOutline` and `MapSpacePin`. The npm SDK's `mapSpace` answers the same. - **The layout of a map** (since 0.110.0): `layout_of(map, maps, pins)` answers `{"layout", "ground", "hand"}` from a Map's `x_layout` and its Pins' `x_hand`, the TypeScript SDK's [`layoutOf`](/docs/development/typescript-readers#the-layout-of-a-map) with the same answer: the method or `None`, the served ground Map's id or `None`, and the ids of the Pins a new lay-out keeps (`x_hand` exactly `True`, never `1`; every Pin of a `"hand"` board), in code point order. - **A world's default picture** (since 0.127.0): `layout_by_kind(graph)` and `layout_around(graph, focus, steps=1)`, the TypeScript SDK's [`layoutByKind` and `layoutAround`](/docs/development/typescript-readers#a-worlds-default-picture), the same points to the bit. Since 0.129.0, `unplaced_by_kind(graph, placed)` and `unplaced_around(graph, focus, placed, steps=1)` answer the ids a saved layout Map has no Pin for, the same lists as the SDK's; the methods and that reading are the standard's [default layouts profile](/docs/schema/profiles#default-layouts), whose fixture both packages replay. +- **A world laid out in 3D** (since 0.130.0): `layout_by_links_3d(graph, elements=None, *, held=None, held_unit=None)`, the TypeScript SDK's [`layoutByLinks3d`](/docs/development/typescript-readers#a-world-laid-out-in-3d) with the same answer: the same points to the bit for a centre, a grouped element and a pinned one, within a billionth of a rest for the rest. `points` is one flat list, x, y, z a node. It is plain Python, so a world of several thousand elements takes minutes. - **A layout along a route** (since 0.108.0): `trail_by_place(input)` lays a world out along a route on a ground map, the TypeScript SDK's [`trailByPlace`](/docs/development/typescript-readers#a-layout-along-a-route) with the same input and the same answer: a Map frame and one Pin per element in the standard's own fields (so `map_space` reads it back), the route, and the recipe it ran with. You hand it the places in travel order and what hangs where; it places them. `TRAIL_TIERS` is the default floors. - **A world's own words** (since 0.30.0): `type_word(world, element_type, supertype=None, many=False)` gives the word a world's `x_names` map prints for a type (*Employee* for Character in a work world), or `None` for the standard's name; a supertype's own word wins over the type's. The [names profile](https://github.com/OnlyWorlds/schema-dist/blob/main/profiles/names.md), schema-dist serial 48; its 29 shared test cases (the fixture every reader of the profile passes) are the package's test. - **The spine profile** (since 0.44.0): `read_spine_element(element_type, element)` reads one element of a world that maps a software ecosystem and returns a `SpineRead`: its kind (the closed list's spelling, `off-list`, or `free` for a Character, Institution or Collective), each `x_spine_*` key as read or `None`, the audience's primary, the probe's verb or `unsupported`, and `dropped`, every value it left out, each as `{"key", "value"}` with the value as the element held it (since 0.44.1), and `retires`, the retired row's id from `x_spine_retires` as given, on whatever element carries it (since 0.50.0; whether it sits on a Retirement Event and names a row is the doctor's to check). Trimmed and case-blind as the room profile defines it. `SPINE_KINDS` is the closed list. The [spine profile](https://github.com/OnlyWorlds/schema-dist/blob/main/profiles/spine.md), schema-dist serial 61; its 46 fixture cases are the package's test. The calendar the profile ships is checked with `onlyworlds.calendar` (since 0.68.0). diff --git a/src/content/docs/docs/development/typescript-readers.md b/src/content/docs/docs/development/typescript-readers.md index e5361852..60cd99de 100644 --- a/src/content/docs/docs/development/typescript-readers.md +++ b/src/content/docs/docs/development/typescript-readers.md @@ -198,6 +198,37 @@ const graph = worldGraph({ elements }, { rung: 'owner' }); const { points } = layoutByKind(graph); // [{ id, x, y }, ...], each x and y within -1..1 ``` +## A world laid out in 3D + +`layoutByLinks3d(graph, elements?, { held, heldUnit })` (since 4.171.0) lays a whole graph out in three dimensions by its links. The most linked elements become centres, each with its group round it. The groups are packed apart and settled by 300 seeded steps, what hangs off the body fans out from it, and what is not joined to the main piece stands on a shelf under the picture. Pass the world's elements as the second argument and its maps join in: the Map that holds the most of the graph's elements by a Pin, three or more, becomes a flat plate with each pinned element at its Pin. Maps and Pins are read through `mapSpace` and `layoutOf`. A Pin's `z` is not read, and a layout map is never the plate. + +It answers one row per node, in the order you passed them: + +| Key | What it holds | +|---|---| +| `ids` | The nodes' ids. | +| `points` | A `Float64Array`: x, y, z of `ids[i]` at `3 * i`, in units where a link at rest is `BY_LINKS_3D_REST` (60) long. | +| `how` | How each was placed: `centre`, `with` (in a centre's group), `arm` or `link` (hanging off the body), `shelf`, `map` (at its Pin). | +| `group` | The id of the centre the element stands with, or null. | +| `part` | For an element with no centre: `map`, `one-link` or `no-link`. Null where `group` is an id. | +| `centres` | The centres' ids, in the method's rank order. | +| `held` | True where the point is one you handed back. | + +The same input gives the same points in every browser and in the Python package's `layout_by_links_3d`: to the last bit for a centre, a grouped element and a pinned one, and within a billionth of a rest for the rest. The package's tests replay a fixture both packages hold. + +To keep a picture still as a world grows, hand an earlier answer's points back as `held` (element id to `[x, y, z]`), with `heldUnit: 1` when you saved them as whole numbers. A held element stays where it was, and what is new is placed round it. Nothing is saved: to keep a picture, save it as a layout Map yourself. A saved layout keeps points only; the groups are read again from the world. + +The method's word, `by-links-3d`, is the tool's own until its page in the standard is published. Until then a release may move its points. + +```typescript +import { worldGraph, layoutByLinks3d } from '@onlyworlds/sdk'; + +const graph = worldGraph({ elements }, { rung: 'owner' }); +const layout = layoutByLinks3d(graph, elements); +layout.points; // Float64Array: x, y, z of layout.ids[i] at 3 * i +layout.centres; // the ids of the most linked elements, each the centre of a group +``` + ## A layout along a route `trailByPlace(input)` lays a world out along a route on a ground map and answers a layout in the standard's own fields: a Map frame (`width`, `height`, `depth`) and one Pin per element, whole numbers in the Map's pixels, so `mapSpace` reads it back. It places and does not read: you hand it which elements are in, the order of travel and what hangs where, and it answers the same points for the same input. diff --git a/src/content/docs/docs/development/typescript.md b/src/content/docs/docs/development/typescript.md index 92625e09..baffbd4e 100644 --- a/src/content/docs/docs/development/typescript.md +++ b/src/content/docs/docs/development/typescript.md @@ -395,7 +395,7 @@ The package also ships `SCHEMA.md` (every field and its meaning, generated) and ## Reference -Generated from the types of `@onlyworlds/sdk` 4.170.1, the version these docs pin. The full declarations ship in the package (`dist/index.d.ts`), with `SCHEMA.md` and `AGENTS.md` beside them. +Generated from the types of `@onlyworlds/sdk` 4.171.0, the version these docs pin. The full declarations ship in the package (`dist/index.d.ts`), with `SCHEMA.md` and `AGENTS.md` beside them. ### Client options