Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand Down
1 change: 1 addition & 0 deletions src/content/docs/docs/changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
1 change: 1 addition & 0 deletions src/content/docs/docs/development/python.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
31 changes: 31 additions & 0 deletions src/content/docs/docs/development/typescript-readers.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/docs/development/typescript.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading