ParaShape

Objects and components

Objects

ObjectNode = { key, label?, method: createObject | createBlock, args? (always empty),
               properties?, behaviors?, steps? | objects? }

createObject has a body of steps and produces geometry. createBlock is a nest: its body is objects, it shares the parent's scope, and it exists to carry a placement, copies, paint, visible, a click action or behaviors for the objects under it. key is required and unique in the document. Record kinds such as dimensions, leaders, hatches, images and sections are producer steps. clone(source) and placeComponent(component, parameters) are producer steps that yield a block and carry no placement argument.

Names: an object is one objects[] entry, a nest is a createBlock, a component is a components[] entry placed by placeComponent, and a block is an evaluated nest or placed component.

Components

A components[] entry is a function: isolated, values enter through arguments, and it evaluates to a whole ModelJson. createComponent takes the document inline as data; loadComponent takes an https url, always resolving to the latest published version. placeComponent(component, parameters) places one by the key of the enclosing lane.

  • parameters may be an arrow (copy) => ({ sizeX: widths[copy] }), called with the copy index, so one placement can vary per copy.
  • A key in parameters that names an object of the placed document routes to that object's own overrides, at any depth.
  • A placed document's own components lane is private. Its materials, layers and patterns join the host's lanes after the host's own; views and settings are ignored.
  • A component is read-only to the host: lib.objects is an error, and a host reads only the records and options rows a part publishes.
  • Resources resolve lazily: an unresolved url is reported in Changes.pending and the step reports 'is loading' until the host delivers the document through engine_add_components. The engine never performs IO.
  • A url placed inside itself fails by name, and nesting is bounded by the document depth limit.

Materials, layers and patterns

materials, layers and patterns are node lanes. A record's key is its identity; a reference argument (material, layer, pattern) is an expression that evaluates to the record's key, and deleting a record that is still referenced is refused. A material resolves with catalog defaults for every field (base color, tile size, roughness, metallic, opacity), so a reader never substitutes its own. A layer carries properties.visible; a pattern is a hatch pattern, and the .pat text codec is available as an engine door.

A library document holds only materials or only patterns. A library placed as a component joins the host's records first-wins after the host's own, and a chooser can list a library's records with options: 'library.materials'.

Views

A view is one node, method view, with position, target, up, projection, field of view and height. The active view is session state and never a document field. Objects and layers choose what a view shows through their own visible property (All, a list of view keys, or a camera arrow).

Where each concept is specified

ConceptSource in the repository
Laws and the settled model JSONAGENTS.md
Concepts: expressions, components, objects, behaviorsspec/architecture/concepts.md
Persisted schemacrates/model/src/document
Per-method behaviorspec/requirements/catalog-geometry.md, spec/requirements/catalog-data.md
Expression grammarspec/requirements/expression.md

Edit on GitHub