diff --git a/src/content/docs/docs/development/python.md b/src/content/docs/docs/development/python.md index 16e3d4c7..e2083e68 100644 --- a/src/content/docs/docs/development/python.md +++ b/src/content/docs/docs/development/python.md @@ -159,7 +159,7 @@ It is schema-dist's own [folder checker](/docs/schema/folders#rules-for-tools), ## What it covers - **World folders**: `read_folder` and `write_folder` implement the folder format (v0.3.24 since 0.126.0, `FORMAT_VERSION`; a folder's existing stamp is kept, older stamps read as before). A world's `origin` is carried as given, from `GET /world` or a read `world.json`, and never derived. An export writes the [`producer` line](/docs/schema/folders#worldjson) as the folder's maker (`{"tool": "onlyworlds", "version", "input": "server"}`); a tool that runs the export in its own name passes `producer=` with its own line. A folder written from another folder keeps the line it carries. Since 0.37.0 `push` sends nothing for an element whose folder copy carries `hidden: true` while the server's does not, and names it in `PushResult.hidden`: the server takes the hidden mark only through its own route, so a patch would edit an element every reader still sees. `patch_world` never sends the folder-only keys (`format_version`, `source`, `exported_as`, `producer`, `writable`, `api`, `snapshot_*`) and pass its shared conformance fixture. Since 0.9.0 a [known-of](/docs/schema/folders#known-of-elements) stub is written without its unset fields (since 0.10.0 with every field it was served with a value, such as a Character's public fields; `PUBLIC_FIELDS` lists them per type), flagged on read (`folder.known_of`, `is_known_of`), never pushed (`PushPlan.known_of` lists it), and refused by the client's writes before anything is sent. The reader never changes a folder. It skips a file that is not JSON, not an object or has no `id`, and since 0.5.1 a dot-prefixed file in a type folder (a tool's litter, not an element); `folder.skipped` lists each with the reason. An element found in both the current `elements/` layout and Atlas's older `spatial/` one is served from `elements/`, and `folder.in_both_layouts` lists it (since 0.5.0). -- **Archives** (since 0.17.0): `read_world_file(path_or_bytes)` opens a `.owworld` file as the [folder format](/docs/schema/folders#folders-and-onlyworldscom)'s archive rules say (the directory checked before anything is inflated; a refusal is `WorldFileError` with `reason` one of the twelve causes, under the same names as the TypeScript SDK's; since 0.45.1 two names that are one after NFC and simple case folding are compared at Unicode 15.1, built from Unicode's own files rather than the interpreter's, and the NFC is exported as `onlyworlds.worldfile.nfc`) and `.to_folder(dest)` writes it out as a folder; `write_world_file(folder, path, top_dir=None, private_dir=None)` and `world_file_bytes(folder)` write one: the `mimetype` marker first and stored, every entry stamped 1980-01-01 in UTF-8 byte order, only `world.json`, `elements/`, `spatial/`, `media/`, `records/` and the one dot-folder named in `private_dir`, the same folder giving the same bytes (within one zlib build). From 0.32.0 the records a producer marks `"private": true` in `records/RECORDS.json` stay home: left out whole, `RECORDS.json` kept as it is, unless `include_private_records=True`; a manifest it cannot read raises `ValueError` unless you pass that ([private records](/docs/schema/folders#folders-and-onlyworldscom)). From 0.43.0 both take `include_hidden=True`: a world file is a copy, and a [hidden](/docs/development/api/hidden) element's file travels byte for byte. For a file made to hand to someone else, `include_hidden=False` leaves every element file (one directly in a type folder of `elements/` or `spatial/`, since 0.90.1 only those) whose JSON object carries the mark out whole, nothing else rewritten (a link to it keeps the id, which dangles); a list passed as `hidden_left_out=` receives the left-out files' paths, sorted, so its length is the count. From 0.90.0 a world file leaves out who wrote each element: `created_by`, `changed_by`, `changed_via`, `changed_client` and `doors` leave every element file that holds them, which is written in the folder's own form (two-space indent, a trailing newline, its other keys in their order); `include_author_fields=True` writes every file byte for byte, for an archive of your own world. The package's own test runs the 99-case conformance set from its schema pin; the directory it writes matches the TypeScript writer's entry for entry. +- **Archives** (since 0.17.0): `read_world_file(path_or_bytes)` opens a `.owworld` file as the [folder format](/docs/schema/folders#folders-and-onlyworldscom)'s archive rules say (the directory checked before anything is inflated; a refusal is `WorldFileError` with `reason` one of the twelve causes, under the same names as the TypeScript SDK's; since 0.45.1 two names that are one after NFC and simple case folding are compared at Unicode 15.1, built from Unicode's own files rather than the interpreter's, and the NFC is exported as `onlyworlds.worldfile.nfc`) and `.to_folder(dest)` writes it out as a folder; `write_world_file(folder, path, top_dir=None, private_dir=None)` and `world_file_bytes(folder)` write one: the `mimetype` marker first and stored, every entry stamped 1980-01-01 in UTF-8 byte order, only `world.json`, `elements/`, `spatial/`, `media/`, `records/` and the one dot-folder named in `private_dir`, the same folder giving the same bytes (within one zlib build). From 0.32.0 the records a producer marks `"private": true` in `records/RECORDS.json` stay home: left out whole, `RECORDS.json` kept as it is, unless `include_private_records=True`; a manifest it cannot read raises `ValueError` unless you pass that ([private records](/docs/schema/folders#folders-and-onlyworldscom)). From 0.43.0 both take `include_hidden=True`: a world file is a copy, and a [hidden](/docs/development/api/hidden) element's file travels byte for byte. For a file made to hand to someone else, `include_hidden=False` leaves every element file (one directly in a type folder of `elements/` or `spatial/`, since 0.90.1 only those) whose JSON object carries the mark out whole, nothing else rewritten (a link to it keeps the id, which dangles); a list passed as `hidden_left_out=` receives the left-out files' paths, sorted, so its length is the count. From 0.90.0 a world file leaves out who wrote each element: `created_by`, `changed_by`, `changed_via`, `changed_client` and `doors` leave every element file that holds them, which is written in the folder's own form (two-space indent, a trailing newline, its other keys in their order); `include_author_fields=True` writes every file byte for byte, for an archive of your own world. The package's own test runs the conformance set from its schema pin; the directory it writes matches the TypeScript writer's entry for entry. - **Import from other apps**: importers for Campfire, Kanka, LegendKeeper, Notion and World Anvil read each app's export into a world folder (LegendKeeper's also through its API), as `python -m onlyworlds.` or from Python as `import_campfire`, `import_kanka`, `import_legendkeeper`, `import_notion` and `import_worldanvil`. Each has its own section on [Import from other apps](/docs/development/python-import). - **The calendar profile** (since 0.68.0): `onlyworlds.calendar` reads a world's own calendars as the [calendar profile](https://github.com/OnlyWorlds/schema-dist/blob/main/profiles/calendar.md) defines them. `read_calendar_value(raw)` reads an `atlas_calendar` value (an object, or the same object as a JSON string) and gives `None` for anything the profile refuses; `world_calendars(elements)` finds every calendar in a world by the field, and `resolve_calendar` picks the one to read dates through (named `resolve_calendar_lens` before 0.69.0; the old name still answers, with a deprecation warning). `breakdown_step(cfg, step)` and `format_step(cfg, step)` turn an integer step into the calendar's date (months, days outside the months, weekdays, eras, and version 2's leap exceptions and offset), and `parse_date(cfg, text)` reads written words back to a step. It is the [TypeScript SDK](/docs/development/typescript)'s calendar reader under snake_case names, gives the same answers (both replay the profile's fixture, and the two were compared on 175,705 inputs before the release), and reads the calendars the LegendKeeper door writes. - **The lens profile** (since 0.74.0): `resolve_lens(world, lens, reader, as_of=, clock=)` reads a world through a lens for one reader (the kept elements in order, the cut by reason, the mail part), with `is_lens`, `is_template` and `lenses_in_use`, as [Lenses](/docs/lenses) describes. Since 0.77.0, `world_graph(world, reader, *, lens=None, as_of=None, clock=None, rooms=False, hidden=False, proposed=False, map_space=False, reading_aids=False)` (`reading_aids` since 0.103.0: the charter, its guide and its domains back in a graph without a lens, each marked `reading_aid`) reads the same snapshot as nodes and edges, with `edges_cut` counting by reason the links it leaves out; a refused flag raises `ValueError` naming it. Since 0.78.0, `degree_of(graph)` gives each node's count of edges, in or out: rank by it for "most linked". Since 0.79.0, `DATE_FIELD` is the profile's date table and `date_of(el)` an element's date as that table reads it (the whole number in its type's date field, else `None`), so a timeline dates elements exactly as the lens's fence does. Since 0.82.0 a lens's rows for a reader below the owner are the bodies the API serves that reader, the owner's the bodies as stored; since 0.82.1 a contributor's or a guest's row keeps a link to a proposed element it sees, and a lens's note keyed to one, the public rung loses both, and no row carries a stored `x_served_trimmed`. diff --git a/src/content/docs/docs/development/unity.md b/src/content/docs/docs/development/unity.md index 3ddd5ef4..d8594c46 100644 --- a/src/content/docs/docs/development/unity.md +++ b/src/content/docs/docs/development/unity.md @@ -80,7 +80,7 @@ public class ReadWorld : MonoBehaviour **Open with, and `ow://` links** (since v0.26.0). `OWOpeners.For(tools, kind, address, surface)` gives the rows of an **Open with** menu for a world or one of its elements, as the [TypeScript SDK](/docs/development/typescript-readers#addresses)'s `openersFor` does and on the same shared fixture: onlyworlds.com first, then each [listed tool](/docs/development/list-your-tool#open-with) with a link for that kind, in the list's order. Since v0.31.0, `OWOpeners.For(..., surface, new OWOpenersOptions { Element = body })` leaves out a tool that cannot open that element: the list's `element_skips` names what a tool's element door skips (`room`, `hidden`, `proposed`, `map_space`, `reading_aid`), each read as `OWGraph.Read` reads it. Since v0.34.0 a tool that opens one kind of element is offered only on that kind: the list's `element_types` (`OWToolOpen.ElementTypes`, null for every type), read from the address's type word, so Tactical Tangle is offered on a Character and on no other type. Since v0.33.0 a signed-out visitor (the `public` audience) is given the tools that need an account, each a row with `OWOpenerState.NeedsAnAccount` ("Needs an account") that opens nothing: draw it disabled. Since v0.35.0 a row whose list entry carries `open.opens_public` (`OWToolOpen.OpensPublic`) is live there instead, since such a tool opens a public world with no account; anywhere else it reads as its `needs` says. `OWTools.All` is the tools list baked in at the release, so a tool listed later is offered from the next one. `OWLinkListener` listens only on the machine's loopback address for a link clicked outside Unity, reads it with `OWAddress.TryParseLink`, and hands the reading to your callback on the main thread (or through a dispatch you pass); since v0.29.0 a second constructor also hands the link as received, for a reading that cannot be written back as an address (a site address naming its world by slug), and a dispatch declines by returning false; a taken port is reported as `port_taken`, so two Editors can run side by side. `Tools~/ow-link` is an opt-in forwarder for Windows that the system runs for `ow://` links: it offers the link to the ports in its config, in order (a running Editor, then a running player), and starts the configured player with it when none takes it. Its `install.ps1` registers it for the current user only, with no administrator rights, and nothing is registered unless you run it. Since v0.30.0 `install.ps1 -Scheme mygame` registers your game's own scheme instead (`mygame:` links, the config's `scheme` naming the same); such a link reaches the listener as the `ow:` address it carries, and `ow:` stays the default. -**A world's own words for the types.** `OWNames.TypeWord(world, type, supertype, many)` reads the World's `x_names` (the [names profile](https://github.com/OnlyWorlds/schema-dist/blob/main/profiles/names.md)) and returns the word to show for a type, *Employee* for a Character in a work world, or `null` for the standard's name; the supertype's word comes first, and `many` asks for the plural. A display lookup only: routes, folders and field names keep the standard's. Since v0.14.0, on the profile's 23-case fixture. +**A world's own words for the types.** `OWNames.TypeWord(world, type, supertype, many)` reads the World's `x_names` (the [names profile](https://github.com/OnlyWorlds/schema-dist/blob/main/profiles/names.md)) and returns the word to show for a type, *Employee* for a Character in a work world, or `null` for the standard's name; the supertype's word comes first, and `many` asks for the plural. A display lookup only: routes, folders and field names keep the standard's. Since v0.14.0, on the profile's shared fixture. **The strand** (since v0.27.0). `OWStrand.Of(world, elements, reader)` reads a world's story in miniature by the [strand profile](/docs/schema/profiles#strand), through the lens reader's own view: the story the World's `x_strand` names (`Narrative`), one of its events (`Event`), that event's place (`Location`), the story's protagonist (`Character`), where the hero is now (`Now`), and whether then and now are one place (`Same`), each slot `{id, name}` or null, as the [TypeScript SDK](/docs/development/typescript-readers#the-strand)'s `strandOf` reads it. `OWReadingAids.Strand` is the strand keel serves on the front door (`GET /me` and an agent's join answer), read as served. @@ -116,7 +116,7 @@ The same steps run from code. `OWSync.BaselineAsync(client, cache)` fetches the **A downloaded world file.** `OWEnvelopeLoader.LoadInto(cache, path)` fills a cache from the one-file export an owner downloads from their world's page (`format: onlyworlds-world-export`), read-only: the file is a capture, with nothing to sync and no folder to write back to. `OWEnvelopeReader.Read(path)` returns what a folder read returns, plus the file's `SchemaVersion` and `ExportedAt`. A file whose `format` is anything else is refused whole. The file carries no images, members or time settings. `OWFolderExport.ExportFileAsync(path, folder)` writes the same file out as a world folder. Since v0.7.0. -**A world as one file, `.owworld`.** A world folder zipped under its own extension. Drop one into `Assets/` and it imports as a read-only cache; **Assets → OnlyWorlds → Pack World Folder…** packs a folder from anywhere on disk into the project, and `OWWorldArchive.Pack(folder, archive)` does the same from code. Packing writes only the archive, leaves out dot-folders and `.meta` files, carries `records/` byte for byte, drops `world.json`'s `api` block (it holds a key) unless you ask to keep it, and gives the same bytes for the same folder. The archive is read in memory and never extracted, and an entry name that climbs out of the world refuses the whole archive. Pictures in `media/` travel but are not imported yet. Since v0.8.0. From v0.11.0 the archive follows the [folder format](/docs/schema/folders)'s archive rules and agrees with its 78-case conformance set: a refusal names its cause (`OWFolderFormatException.Reason`, one of the twelve `OWWorldArchiveReason` values, the same names the [TypeScript SDK](/docs/development/typescript#world-files) uses), a `mimetype` marker is read when present, the default budget is the spec's floor (500,000 entries, 2 GiB), names are strict and case-fold collisions refuse (Unicode simple case folding, pinned at 15.1.0), the `api` block is stripped on read, and `Pack` writes entries in code point order. From v0.12.1 `Pack` places the marker first and stored, as the other two writers do; a reader still must not require one, since older files have none. From v0.12.0 an entry whose bytes fail its CRC-32 refuses the archive (every file, media and records included), and the conformance set runs as the package's own test (79 of 79 at schema-dist serial 40). From v0.15.0 `Pack` leaves out a producer's records marked private in `records/RECORDS.json` unless you pass `includePrivateRecords: true`, keeping `RECORDS.json` byte for byte (folder format 0.3.15, [private records](/docs/schema/folders#folders-and-onlyworldscom)); the set is at 85 on serial 49. From v0.19.0 a world file is a copy and keeps [hidden](/docs/development/api/hidden) elements; `Pack(..., includeHidden: false)` makes one to hand to someone else, leaving every element file that carries the mark (or a doubt about it: anything but absent, `null` or `false`, `OWPayload.IsHidden`) out whole and listing the left-out paths in `hiddenLeftOut` (folder format 0.3.18, the hidden mark). From v0.19.1 the reader agrees with every other: a deflate stream that does not end at its declared size refuses the archive, and names are folded with Unicode 15.1's NFC built from Unicode's own files, never the runtime's; it reads all 96 cases of the set at schema-dist serial 60. From v0.35.0 `OWWorldArchive.Pack(folder, path, OWWorldArchivePackOptions)` takes every choice the other overloads take, and one more, `StoreForWebPlayers`: every entry is written stored instead of deflated, so reading the file never needs an inflater (a web player built with DiskSizeLTO reads only such a file). The file is larger by about what deflate saves; a web server's own response compression wins most of it back. Every read rule still holds, and the defaults write the bytes the other overloads write. +**A world as one file, `.owworld`.** A world folder zipped under its own extension. Drop one into `Assets/` and it imports as a read-only cache; **Assets → OnlyWorlds → Pack World Folder…** packs a folder from anywhere on disk into the project, and `OWWorldArchive.Pack(folder, archive)` does the same from code. Packing writes only the archive, leaves out dot-folders and `.meta` files, carries `records/` byte for byte, drops `world.json`'s `api` block (it holds a key) unless you ask to keep it, and gives the same bytes for the same folder. The archive is read in memory and never extracted, and an entry name that climbs out of the world refuses the whole archive. Pictures in `media/` travel but are not imported yet. Since v0.8.0. From v0.11.0 the archive follows the [folder format](/docs/schema/folders)'s archive rules and agrees with its conformance set: a refusal names its cause (`OWFolderFormatException.Reason`, one of the twelve `OWWorldArchiveReason` values, the same names the [TypeScript SDK](/docs/development/typescript#world-files) uses), a `mimetype` marker is read when present, the default budget is the spec's floor (500,000 entries, 2 GiB), names are strict and case-fold collisions refuse (Unicode simple case folding, pinned at 15.1.0), the `api` block is stripped on read, and `Pack` writes entries in code point order. From v0.12.1 `Pack` places the marker first and stored, as the other two writers do; a reader still must not require one, since older files have none. From v0.12.0 an entry whose bytes fail its CRC-32 refuses the archive (every file, media and records included), and the conformance set runs as the package's own test (79 of 79 at schema-dist serial 40). From v0.15.0 `Pack` leaves out a producer's records marked private in `records/RECORDS.json` unless you pass `includePrivateRecords: true`, keeping `RECORDS.json` byte for byte (folder format 0.3.15, [private records](/docs/schema/folders#folders-and-onlyworldscom)); the set is at 85 on serial 49. From v0.19.0 a world file is a copy and keeps [hidden](/docs/development/api/hidden) elements; `Pack(..., includeHidden: false)` makes one to hand to someone else, leaving every element file that carries the mark (or a doubt about it: anything but absent, `null` or `false`, `OWPayload.IsHidden`) out whole and listing the left-out paths in `hiddenLeftOut` (folder format 0.3.18, the hidden mark). From v0.19.1 the reader agrees with every other: a deflate stream that does not end at its declared size refuses the archive, and names are folded with Unicode 15.1's NFC built from Unicode's own files, never the runtime's; it reads all 96 cases of the set at schema-dist serial 60. From v0.35.0 `OWWorldArchive.Pack(folder, path, OWWorldArchivePackOptions)` takes every choice the other overloads take, and one more, `StoreForWebPlayers`: every entry is written stored instead of deflated, so reading the file never needs an inflater (a web player built with DiskSizeLTO reads only such a file). The file is larger by about what deflate saves; a web server's own response compression wins most of it back. Every read rule still holds, and the defaults write the bytes the other overloads write. ## Join by a link