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
2 changes: 2 additions & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@ tests/fixtures/doors.fixture.json -text
tests/fixtures/author-fields.fixture.json -text
# The tools list, vendored byte for byte as GitHub serves it at the pinned commit (codegen/tools-pin.json holds its sha256).
codegen/tools/tools.json -text
# The by-links-3d layout's directions table, the same bytes as the npm SDK's copy (the method's fixture holds its sha256).
codegen/layout/directions.json -text
# The layout methods' shared cases, the same bytes as the npm SDK's copy (both tests hold its sha256).
tests/fixtures/layout/** -text
# The address-in-prose cases (serial 123), the same bytes as the npm SDK's copy (the test holds its sha256).
Expand Down
1 change: 1 addition & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ jobs:
- run: uv run python codegen/generate_schema.py --check
- run: uv run python codegen/generate_tools.py --check
- run: uv run python codegen/generate_anchors.py --check
- run: uv run python codegen/generate_directions.py --check
# Published text names no one inside the team and points at no internal room or tracker.
- run: uv run python scripts/public_words.py

Expand Down
5 changes: 4 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,10 @@

The package version runs on its own semver; the schema it is generated from is `SCHEMA_DIST_TAG`.

## Unreleased
## 0.130.0 (2026-11-16)

- **`layout_by_links_3d`: a 3D layout of a whole graph by its links (`by-links-3d`).** Given the graph as `world_graph` answers it and, optionally, the world's elements as served, it answers a point `[x, y, z]` for every node, in the order handed in (one flat `points` list), and how each was placed: a group's centre, with a centre, hanging off the body, on the shelf, or at its Pin. The body of the graph is cut into groups round its centres, the groups are packed apart in directions read from a table baked into the package, and 300 seeded force steps settle it; what hangs off the body is fanned out from it, and what is not joined to the main piece stands on a shelf under the picture. When a Map holds three or more of the graph's elements by a Pin, the Map that holds the most is a flat plate with each of its elements at its Pin, and a Map over a place on it a small plate above that place; a Pin's z is not read, and a layout map is never the plate. Maps and Pins are read through `map_space` and `layout_of`, nothing else. The same input gives the same points as the npm SDK's `layoutByLinks3d`: to the last bit for elements placed at a centre, with a centre or at a Pin, within a billionth of a rest (the unit `BY_LINKS_3D_REST`, 60) for the rest, which are placed with the runtime's cosine and sine. Two keyword options: `held`, points an earlier answer gave (element id to three finite numbers), so the picture keeps still as the world changes, and `held_unit`, the step those points were rounded to. A bad `held` or `held_unit` is refused before anything runs, each error with a `code` (`held-not-object`, `held-not-point`, `held-box`, `held-unit`). It is pure Python, so a world of several thousand elements takes minutes. The word `by-links-3d` is the tool's own until the method's page is published, and until then a release may move its points.
- Tests: the method's shared fixture, the same bytes as the npm SDK's copy, replayed whole by its own compare rules; the baked directions table (`codegen/generate_directions.py`, its `--check` in CI) held to the table the fixture names by sha256.

## 0.129.1 (2026-11-16)

Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -400,6 +400,7 @@ uv run ruff check . && uv run ruff format --check . && uv run mypy --strict src
uv run python codegen/generate_schema.py --check
uv run python codegen/generate_tools.py --check
uv run python codegen/generate_anchors.py --check
uv run python codegen/generate_directions.py --check
uv run python codegen/generate_casefold.py --check
uv run python codegen/generate_nfc.py --check
```
Expand Down
97 changes: 97 additions & 0 deletions codegen/generate_directions.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
#!/usr/bin/env python3
"""Generate src/onlyworlds/_directions.py: the by-links-3d layout's directions table.

``layout_by_links_3d`` packs the groups of a graph apart in directions read from a table: for each count of parts k
from 1 to 37, k unit vectors [x, y, z] spread over the sphere. They are computed once and kept as numbers, so no
runtime's own cosine, sine or cube root is ever called for them and every runtime reads the same doubles. The table is
codegen/layout/directions.json, the same bytes as the npm SDK's copy; the method's shared fixture names it by its
sha256 (``table_sha256``). Each number is written in the shortest form that reads back the same bits (``repr``), a
negative zero as ``-0.0``.

Usage:
python codegen/generate_directions.py write the module
python codegen/generate_directions.py --check exit 1 if the committed module is stale
"""

from __future__ import annotations

import argparse
import hashlib
import json
import math
import struct
import sys
from pathlib import Path

HERE = Path(__file__).resolve().parent
SOURCE = HERE / "layout" / "directions.json"
OUT = HERE.parent / "src" / "onlyworlds" / "_directions.py"
K_MAX = 37


def _number(text: str) -> float:
"""A JSON number as a double, a ``-0`` written without a point kept as -0.0 (``int("-0")`` would lose the sign)."""
return float(text)


def build() -> str:
"""The module's text, from the table's ``directions``."""
raw = SOURCE.read_bytes()
table = json.loads(raw.decode("utf-8"), parse_int=_number, parse_float=_number)
if table.get("k_max") != K_MAX:
raise ValueError(f"directions.json: k_max is {table.get('k_max')!r}, not {K_MAX}")
dirs = table["directions"]
if sorted(dirs, key=int) != [str(k) for k in range(1, K_MAX + 1)]:
raise ValueError(f"directions.json holds k = 1 to {K_MAX}, each once")
lines = [
'"""The by-links-3d layout\'s directions table.',
"",
"GENERATED by codegen/generate_directions.py from codegen/layout/directions.json (sha256",
f"{hashlib.sha256(raw).hexdigest()}). Do not edit by hand. DIRECTIONS[str(k)]: for k parts",
"(1 to 37), k unit vectors (x, y, z), float64 written in the shortest form that reads back the same bits.",
'"""',
"",
"DIRECTIONS: dict[str, tuple[tuple[float, float, float], ...]] = {",
]
for k in range(1, K_MAX + 1):
row = dirs[str(k)]
if len(row) != k or any(len(p) != 3 for p in row):
raise ValueError(f"directions.json: k = {k} does not hold {k} directions of three numbers")
cells = []
for p in row:
for v in p:
if not isinstance(v, float) or not math.isfinite(v):
raise ValueError(f"directions.json: k = {k} holds a number that is not finite")
if struct.pack("<d", float(repr(v))) != struct.pack("<d", v):
raise ValueError(f"directions.json: k = {k} holds a number that does not read back")
cells.append(f"({p[0]!r}, {p[1]!r}, {p[2]!r}),")
if k == 1: # the shape ruff format gives a one-point tuple
lines.append(f' "{k}": ({cells[0]}),')
continue
lines.append(f' "{k}": (')
lines.extend(f" {cell}" for cell in cells)
lines.append(" ),")
lines.append("}")
return "\n".join(lines) + "\n"


def main() -> int:
parser = argparse.ArgumentParser(description=(__doc__ or "").splitlines()[0])
parser.add_argument("--check", action="store_true", help="exit 1 if the committed module is stale")
args = parser.parse_args()
text = build()
if args.check:
if not OUT.exists() or OUT.read_bytes() != text.encode("utf-8"):
print(
f"{OUT.relative_to(HERE.parent)} is stale: run python codegen/generate_directions.py", file=sys.stderr
)
return 1
print(f"{OUT.relative_to(HERE.parent)} is current")
return 0
OUT.write_bytes(text.encode("utf-8"))
print(f"wrote {OUT.relative_to(HERE.parent)}")
return 0


if __name__ == "__main__":
sys.exit(main())
1 change: 1 addition & 0 deletions codegen/layout/directions.json

Large diffs are not rendered by default.

4 changes: 4 additions & 0 deletions src/onlyworlds/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,7 @@
unplaced_around,
unplaced_by_kind,
)
from .layout_links_3d import BY_LINKS_3D_REST, LayoutByLinks3d, layout_by_links_3d
from .layout_trail import (
TRAIL_TIERS,
TrailHanger,
Expand Down Expand Up @@ -152,6 +153,7 @@

__all__ = [
"API_BASE",
"BY_LINKS_3D_REST",
"CHECKS_FIELD",
"CREATE_FIELDS",
"DATE_FIELD",
Expand Down Expand Up @@ -208,6 +210,7 @@
"LandingCluster",
"LandingGap",
"LandingMember",
"LayoutByLinks3d",
"LensMail",
"LensReading",
"MapLayout",
Expand Down Expand Up @@ -286,6 +289,7 @@
"landing_of",
"layout_around",
"layout_by_kind",
"layout_by_links_3d",
"layout_of",
"lenses_in_use",
"map_space",
Expand Down
Loading
Loading