Crate tilewright_source

Expand description

Loads and validates a Tilewright world source tree (docs/spec/FORMAT.md) into a typed, game-neutral World.

Loading is bounded and fail-closed: only the files the format defines are read, symbolic links and unexpected files are errors, every document is parsed as strict JSONC under the format’s limits, and every problem is reported as a Diagnostic with its file, byte span and a stable code. A world is returned only when there are no diagnostics at all.

A profile’s terrain transitions (transitions) derive edge, corner and variant tiles from painted terrain; Transitions::resolve_chunk is the one resolver the compiler, editors and other tools share.

load_indexed_in also returns a ReferenceIndex: every reference the loader checks, such as an object’s prototype or a zone’s parent, with what it names, what holds it and its byte span, for finding what names something before it is removed or renamed (index). A World lists the files its revision covers (World::files).

The root path is resolved as the caller gives it and may be a link; nothing beneath it is followed. On Unix every path component beneath the root is opened through its parent directory’s handle without following symbolic links, so a link swapped into the tree during a load is never followed. Other platforms check each component by path before using it; that is a best effort which a local process changing the tree during the load can race. Race-free loading is Unix-only.

let world = tilewright_source::load(std::path::Path::new("content"))
    .map_err(|diagnostics| diagnostics.len())?;
println!("{} planes", world.planes().len());

Re-exports§

pub use index::ReferenceIndex;
pub use transitions::ResolvedChunk;
pub use transitions::TerrainSource;
pub use transitions::Transitions;

Modules§

index: The references of a world: what each one names, from where, and where in which file it is written.
transitions: Terrain transitions (docs/spec/FORMAT.md section 13): the profile’s rules that choose the edge, corner and variant tiles around painted terrain, and the deterministic resolver that applies them.

Structs§

Access: Who may use a file or directory, as publishing keeps it: where there are no modes, a read-only file has none of the write bits.
Anchor
Audience: Who may reach content through a file or directory: for a file who may read it, for a directory who may search it. Publishing requires the entries it compares to have one audience.
Chunk: One chunk of one layer.
Definition
DepthFirst: The objects of a chunk in depth-first order; see Chunk::depth_first.
Diagnostic: One problem in a source tree.
FieldSpec
Grid: A character grid: one palette value per tile.
LoadOptions: Bounds on what a load may read.
Mounts: The mounts of this process, read once to tell the file systems of several directories (SourceDirectory::unchecked_file_system): on Linux from /proc/self/mountinfo, bounded; elsewhere nothing.
Movement: Movement analysis rules for the editor; the format does not interpret them.
Object: A placed object or an inventory entry.
ObjectLocation: Where an object is: its chunk, and its place in the chunk.
Plane: One plane with its zones, anchors, stairwells and chunks.
Profile: The game profile.
Schema: A closed set of fields, in declaration order, indexed by name. A schema document has one, and so does each object field type.
SourceDirectory: A directory beneath the root. Every name is a single entry of it.
SourceFile: A file a load read: its length and SHA-256, as read.
SourceLock: The root’s lock; see SourceRoot::lock.
SourceRoot: A source tree root. The root itself may be a link; nothing beneath it is followed.
Stairwell: One exit spanning several layers: steps on adjacent layers, used end to end in one move.
StairwellStep: One step of a stairwell, in plane coordinates.
World: A validated world source tree.
Zone

Enums§

AccessError: Why a path beneath the root could not be used.
Code: Stable diagnostic codes. JSONC syntax errors use the parser’s own codes.
FieldType
FieldValue: A field value. Arrays and objects, the values of json, list and object fields, are kept as canonical JSON.
PlaneKind
Portal
Projection
StairwellDirection: Which way a stairwell may be used.

Constants§

CHUNK_SIZE: Tiles along each side of a chunk in format 1.
LOCK_NAME: The name of the file in the root that is its lock on Windows. The command line writes no output there on any platform.
MAXIMUM_FIELD_DEPTH: Deepest nesting of list and object field types. A list or object field of a schema is at level 1, a list or object inside it at level 2, and so on.
MAXIMUM_GROUND_LAYERS: Most ground layers a profile may declare.
MAXIMUM_LAYER_HEIGHT: Largest layer_height a profile may declare. A stacked elevation, layer × layer_height + height + z, then stays within the format’s integer range for every 32-bit layer, height and z.
MAXIMUM_LIST_ITEMS: Largest min_items or max_items of a list field: the array limit of the strict JSONC dialect, so the default max_items accepts any array.

Functions§

is_identifier: Whether text is an identifier: it matches ^[a-z0-9][a-z0-9_.-]{0,127}$.
is_jsonc_path: Whether path is a safe relative path ending in .jsonc: at most 1,024 bytes and 32 /-separated components of at most 128 ASCII letters, digits, _, . and -, none starting with . or -.
is_namespace: Whether text is a domain-qualified namespace for custom data, such as example.org or example.org/tool.
load: Loads a source tree with default bounds.
load_edited: Loads a source tree as it would be with overlay applied, without writing anything. Overlay files are read under the same limits and budget as files on disk, and a directory that holds one exists. One that the overlay leaves without a file holds none, and is ignored where the layout ignores such a directory (FORMAT.md section 2). An overlay of more entries than maximum_entries is refused before anything is read.
load_edited_in: Loads the tree of an opened root as load_edited does, through the handle rather than its path, so that what is validated is the directory the caller opened.
load_indexed_in: Loads the tree of an opened root as load_edited_in does, and also returns the index of its references: every reference the loader checks or follows, with its target, role, holder, file and span (see index). The world, and on failure the diagnostics, are those load_edited_in gives, with one exception: a tree whose index would be too large to number is refused (see below).
load_with: Loads a source tree.

Type Aliases§

Overlay: Edits applied over the files of a tree for load_edited, keyed by root-relative /-separated path: Some(text) replaces or creates the file, and None removes it.