Document format
A model you can read, edit and re-evaluate
A blacksmith document is one JSON file that holds a parametric model: named parameters, and a list of nodes, each one kernel operation whose fields are numbers, expressions or other nodes. The file is the model, not a picture of it. Change a parameter and the nodes that read it are evaluated again; nothing else is.
The Loom, the Forge and the robot bench save their work in this format. In code the same files go through cadaclysm_blacksmith_document_load, _save, _apply, _evaluate and _value in the C ABI (see Documents), the Document class in each wrapper (Python, for one), and the web package. This page says what each part of a file means, so you can read one, write one by hand, or generate one.
The file
Nine keys, in a fixed order
The smallest file the reader accepts: no parameters, no nodes, and the one empty commit every history starts from.
{
"format": "cadaclysm-blacksmith",
"version": 1,
"units": "mm",
"params": {},
"nodes": [],
"commits": [
{"id": "c0", "parents": [], "ops": [], "inverses": []}
],
"branches": {"main": "c0"},
"branch": "main",
"head": "c0"
}
| Key | Holds |
format | Always "cadaclysm-blacksmith". |
version | The format's version, a whole number: 1. A file of a newer version is refused in words — version 2 is newer than this reader (1) — before the rest of it is checked. |
units | The length unit bare numbers are counted in: mm (the default when the key is left out), cm, m, in or ft. Angles are always degrees. |
params | An object, parameter name to value. Optional; empty when left out. |
nodes | The model as it stands at head, one object per node. A file opens from this list without replaying any history. |
commits | The whole commit tree: every edit ever applied and the edit that undoes it, undone tails and other branches included. At least one commit, the root. |
branches | Each named branch and the commit at its tip. |
branch | The branch head is on, or null when it is on none. |
head | The commit the document stands at. |
Any other top-level key is refused (unknown key `colour`), and so is a head or branch tip that names no commit. The reader never half-loads: a file is read whole or refused with a message naming the item at fault.
The writer is canonical. Saving always writes the keys in the order above, two-space indentation, one node and one commit per line, params and branches sorted by name, each node's keys in a fixed order, and every number in its shortest round-trip form (1.50 is written 1.5). So save, load, save gives the same bytes, and a diff of two saved files shows only what changed. A file you write by hand loads in any order and layout; it comes back canonical the first time it is saved.
Parameters
Named values every node can read
A parameter's name is an identifier (letters, digits and _, not starting with a digit). It may not be a unit name, a function name or a keyword (see reserved names), nor the id of a node. Its value is any of these, and lists and objects of them, nested:
| Written | Is |
120 | A number. A bare number takes the meaning of wherever it is used: a length in a length field, a count in a count field. |
"6 mm", "-45 deg", "1.2 rad" | A quantity: a number with a unit, converted to document units (lengths) or degrees (angles). |
"=width / 2" | An expression: any string that begins with =. |
true, false | A boolean. |
[40.7, 19.7, "3 mm"] | A list. Lists nest. |
{"M4": 4.5, "M5": 5.5} | A record: named fields, in the order written. |
"M5" | Text: any other string. |
The rule that decides what a parameter string is: one that begins with = is an expression; one that reads as a single number with a unit is a quantity; any other string is text. So "M5" is text, and so are "12" (no unit) and "3 mmm" (no such unit). A misspelt unit therefore does not fail where it is written but where it is used, and the message names the parameter: `t` is the text '3 mmm', not a number.
Nodes
One operation each, by kind
A node is an object with an id, a kind, and the fields that kind declares.
{"id": "plate", "kind": "solid.cuboid", "name": "Base plate", "x": "=width", "y": "=depth", "z": "6 mm"}
{"id": "part", "kind": "solid.cut", "target": "plate", "tool": "tool"}
| Key | Meaning |
id | A non-empty string, unique in the document. It never changes; a renamed node keeps its id. Give it the shape of an identifier if expressions are to read it by name. |
kind | What the node does, as namespace.verb: profile.rect, solid.extrude, measure.mass, or a plain word such as value and check. An unknown kind is refused at load, naming it. |
name | Optional display name. |
hidden | Optional, true or false; written only when true. |
meta | Optional object the document stores and never reads: an application's own data about the node, such as a colour. Edits set it and undo restores it, but it never causes re-evaluation. |
lacing | Optional, "longest" (the default) or "cross": how the node pairs lists (see lacing). |
| the kind's fields | Everything else. A field the kind does not declare is refused (c: `colour` is not a field of solid.cuboid); a field with no default that is left out is refused (c: `z` is missing). A field with a default, or an optional one, may be left out. |
What a field takes depends on its kind. cadaclysm_blacksmith_document_kinds returns every kind as JSON — its fields with their types, defaults, units and ranges, its inputs, its output and a line of help — and the editors build their panels from it. The forms a field value comes in:
| Field type | Written as |
| A number (length, angle, count) | A bare number in document units or degrees, a unit literal such as "3 cm", or an expression. The unit must fit: a length field given "30 deg" is refused with expected a length, got an angle. A range is checked too: c: `x` must be within 0 and 1e9, not -1. A bare number in quotes ("3") is not accepted. |
| A point or a vector | A list of numbers, each one of the forms above, or one expression giving the whole list. |
| An input | The id of another node, whose output must be of the type the field wants: c: `target` names no node `a` otherwise. Some inputs take a list of ids. |
| A frame | "xy", "xz" or "yz", the id of a node that gives a frame, or {"origin": [...], "x": [...], "y": [...]}. |
| Text | A string, or an expression giving text (see text fields). |
| A choice | One of the words the kind lists. |
Every input and every name an expression reads is a dependency, and a cycle — through parameters, expressions or inputs — is refused at load and at every edit, naming it: cycle: x -> y -> x.
Three kinds hold no kernel call. value holds one expression (field value), so a number, a list or a condition can be a node of its own that others read by id. check states a condition the document must satisfy (see checks). value.unresolved (fields type and why) stands in for a node an app holds but cannot build: whatever reads it is blocked by it, and its error is why. Bench and building documents open through their own load calls (cadaclysm_parts_document_load, cadaclysm_bim_document_load), which add those apps' kinds to the same format.
Expressions
A string that starts with =
Any field that takes a number, a point, a boolean or text, and any parameter, may hold an expression instead: a string beginning with =. Expressions read parameters by name and node outputs by path, and are evaluated in 64-bit floating point, left to right, with the same functions on every platform, so two copies of a document give the same bits.
| Expression | Gives | Note |
=w / 2 | 100 | with w = 200 |
=t * 2 | 6 (mm) | with t = "3 mm" |
=m1.volume | 6000 | a field of a node's output; m1 a measure.mass of a 10 × 20 × 30 box |
=m1.centroid.z | a length | paths go as deep as the output does |
=v1 | node v1's whole output | a bare name is a parameter, or a node when no parameter has the name |
Units and dimensions
A number may carry a unit, with or without a space: mm, cm, m, in, ft for lengths, deg and rad for angles. Lengths are converted to the document's unit as the expression is read and angles to degrees, so in a millimetre document =1 in is 25.4, =25.4 mm + 1 in is 50.8 and =1.2 rad is about 68.75.
Every value keeps its dimension, a power of length and a power of angle, and arithmetic checks it. A plain number has none and takes on the dimension of what it meets, so =t + 2 is a length.
| Expression | Gives |
=t * t | an area, 9 |
=t * t / t | a length, 3 |
=t / 1 mm | a plain number, 3 |
=sqrt(t * t) | a length, 3 |
=t + a | error: cannot add a length to an angle |
=sqrt(t) | error: cannot take the square root of a length |
=t ^ 0.5 | error: a length can only be raised to a whole power |
The result must fit the field: a length field takes a length or a plain number, and an angle there is the node's error, `x` expected a length, got an angle.
Operators and precedence
| From lowest to highest | Meaning |
or | Either is true. |
and | Both are true. |
not | The opposite. |
< <= == != >= > | Compare. They do not chain: 1 < 2 < 3 is refused, write a < b and b < c. Ordering compares numbers only; == and != also compare booleans and texts. |
+ - | Add and subtract; + also joins texts. |
* / | Multiply and divide. Dividing by zero is an error. |
unary - | Negate. |
^ | Power, right associative. |
f(...), [...], {...}, x[i], ( ) | A call, a list, a record, an index, a group. |
So =2 + 3 * 4 is 14, =-2 ^ 2 is -4 and =2 ^ 3 ^ 2 is 512. true and false are the booleans. A lone = or ! inside an expression is refused with a hint: `=` alone is not an operator; compare with `==`, `!` alone is not an operator; write `not`.
Text
Text is written in single or double quotes; single quotes are the comfortable ones inside a JSON string. Inside, \\, \' and \" are the only escapes. + joins two texts; text plus a number is an error that says what to do, and text(x) writes a number as text in the same shortest form the file uses, a length in document units with no unit name.
| Expression | Gives |
='hole.' + hole | "hole.M4", with hole = "M4" |
="a" + 'b' | "ab" |
='n' + 3 | error: cannot add a number to text: use text(x) |
='n' + text(3) | "n3" |
=text(t) | "3", with t = "3 mm" |
=text(1 / 3) | "0.3333333333333333" |
=len('héllo') | 5, characters |
='a' == 'a' | true |
='a' < 'b' | error: text compares only by `==` and `!=` |
='a' == 1 | error: cannot compare text with a number |
Records and indexing
A record literal is {key: value, ...}, keys bare identifiers or quoted text, values any expression; the order is kept and a repeated key is refused. A JSON object given as a parameter is the same record. x[i] reads item i of a list, counting from 0, a negative index counting from the end; x['k'] reads field k of a record. An index that is itself a list gives a list. A dot path such as m1.centroid reads into a node's output; a parameter's record is read by indexing.
| Expression | Gives |
={a: 1, 'b c': 2} | {"a": 1, "b c": 2} |
=c[hole] | 4.5, with c = {"M3": 3.4, "M4": 4.5} and hole = "M4" |
=c['M3'] | 3.4 |
=c['M5'] | error: no key 'M5' in a record of M3, M4 |
=xs[0], =xs[-1] | 10, 30, with xs = [10, 20, 30] |
=xs[[0, 2]] | [10, 30] |
=xs[5] | error: item 5 of a list of 3 |
Lists
[a, b, c] is a list; lists nest. A list's items must agree: =[1 mm, 2 deg] is refused with a list mixes a length and an angle. Every operator and every function of numbers works item by item: a single value meets a list as if repeated, and two lists of different lengths are paired with the shorter padded by its last item. An empty list on either side gives an empty list.
| Expression | Gives |
=xs + 1 | [11, 21, 31] |
=xs * [1, 2] | [10, 40, 60], the 2 repeated |
=[1, 2] + [10, 20, 30] | [11, 22, 32] |
=xs == [10, 0, 30] | [true, false, true] |
=[1, 2] + [] | [] |
Functions
The whole set; there are no others, and no way to define one. A function of numbers applied to a list works item by item. A list function makes at most 100,000 items.
| Function | Gives | Example |
| Numbers |
abs(x) | The magnitude, same dimension. | abs(-2 mm) → 2 |
round(x) floor(x) ceil(x) | To a whole number; round takes halves away from zero. | round(2.5) → 3, floor(-2.5) → -3 |
sqrt(x) | The square root; halves the dimension (an area gives a length). A negative number is an error. | sqrt(t * t) → 3 |
min(a, b) max(a, b) | With two arguments, item by item over lists. With one list, its least or greatest item; with three or more arguments, the least or greatest of them. | min(xs) → 10, max(4, 9, 2) → 9 |
clamp(x, lo, hi) | x held between lo and hi. | clamp(15, 0, 10) → 10 |
sum(list) | The items added; 0 for an empty list. | sum(xs) → 60 |
| Angles |
sin(a) cos(a) tan(a) | Of an angle; a plain number counts as degrees. | sin(30) → 0.49999999999999994 |
asin(x) acos(x) atan(x) | An angle in degrees, of a plain number. | asin(2) → error, not a finite number |
atan2(y, x) | The angle of the point (x, y), in degrees; y and x of one kind. | atan2(1, 1) → 45 |
| Making and reading lists |
range(stop) range(start, stop) range(start, stop, step) | From start (default 0) up to but not including stop, by step (default 1, never 0). | range(0, 10 mm, 2.5 mm) → [0, 2.5, 5, 7.5] |
repeat(v, n) | n copies of v. | repeat(5, 3) → [5, 5, 5] |
item(list, i) | Item i, as list[i]; a list of indices gives a list. | item(xs, 1) → 20 |
slice(list, from) slice(list, from, to) | The items from from up to to; negative counts from the end, and both ends are clamped to the list. | slice(xs, -2, 3) → [20, 30] |
merge(a, b, ...) | The lists one after another; a single value is one item. | merge(xs, 40, [50]) → [10, 20, 30, 40, 50] |
flatten(list) | Every nested item in one flat list. | flatten([[1, [2]], 3]) → [1, 2, 3] |
reverse(list) | The items in the other order. | reverse(xs) → [30, 20, 10] |
len(x) | A list's items, or a text's characters. | len(xs) → 3 |
column(rows, i) | Item i of every item of a list of lists. | column([[1, 2], [3, 4]], 0) → [1, 3] |
zip(a, b, ...) | Lists to rows, item by item, the shorter padded with its last item; a single value repeats. | zip(xs, [1, 2], 0) → [[10, 1, 0], [20, 2, 0], [30, 2, 0]] |
polar(n, r) | n points [x, y] evenly round a circle of radius r, the first at angle 0. | polar(4, 10) → [10, 0], about [0, 10], ... |
| Choosing and text |
if(c, a, b) | a when c is true, else b; only the branch taken is evaluated. A list of conditions chooses item by item. | if([true, false], 1, 2) → [1, 2] |
text(x) | A number written as text. | text(2.5) → "2.5" |
column and zip split points into coordinates and put them back: zip(column(xy, 0), column(xy, 1), 5) lifts a list of 2D points to z = 5.
Reserved names
The function names above — text, sum, column, len, if, range and the rest — and the keywords and, or, not, true, false are never parameter names (`sum` is a function name or keyword, not a parameter name), and neither are the unit words mm, cm, m, in, ft, deg, rad (`in` is a unit name, not a parameter name). A node may have such an id, but an expression cannot read it: =sum + 1 is refused with `sum` is a function; write `sum(...)`. Call a box sum_ instead. A name that is no parameter and no node is refused at load: unknown name `nope`.
Text fields
A leading = makes an expression
A field of type text — a check's message, a label — takes a string as it is, or an expression when the string begins with =, as every other field does. The expression must give text. To write text that itself begins with =, write it as an expression holding a text literal.
| Field value | Text |
"plain words" | plain words |
"='l is ' + text(l)" | l is 40, with l = 40 |
"='=5'" | =5 |
"=5" | error: `message` must be text, not a number |
Lacing
A list where one value is wanted makes the node a list
Give a field that takes one number a list, or an input that takes one node a node whose output is a list, and the node runs once per item; its output is the list of those runs. Several such fields are paired longest: the run count is the longest list's length, shorter lists padded with their last item, single values repeated. With "lacing": "cross" the node runs once for every combination instead, the first field varying fastest. An empty list makes no runs and an empty output.
{"id": "b", "kind": "solid.cuboid", "x": "=[10, 20, 30]", "y": "=[5, 6]", "z": 1}
{"id": "c", "kind": "solid.cuboid", "x": "=[10, 20, 30]", "y": "=[5, 6]", "z": 1, "lacing": "cross"}
b is three boxes, 10 × 5, 20 × 6 and 30 × 6; c is six. A node reading b through an input that takes one solid laces in turn (a measure.mass of b is three records), while an input that takes a list of nodes, such as solid.join's solids, takes b's items as they are. A point field laces per slot: each of its numbers may be a list. When one run fails, the node fails and its error names the item, counting from 0 as id#i does (item 1: ... is the second run).
Checks
Conditions the document states about itself
A check node has two fields: condition, an expression giving true or false, and message, text. True, and its output is true. False, and the node fails with the message as its error, so any node reading it is blocked. A list condition fails at its first false item and the message names that item's index, counting from 0. A condition that is not a boolean is the node's error: `condition` must be true or false, not a number.
{"id": "fits", "kind": "check", "condition": "=clearance[bolt] < 2 * margin",
"message": "='a ' + bolt + ' hole does not fit a ' + text(margin) + ' mm margin'"}
{"id": "each", "kind": "check", "condition": "=xs < 25", "message": "too big"}
With xs = [10, 20, 30], each fails with too big (item 2).
Evaluation
Every node ends ok, in error, or blocked
Evaluation runs the nodes in dependency order, ties broken by their order in the file, so the order is a function of the document alone. Each node ends in one state:
| State | Meaning |
ok | It has a value. |
error | It failed, with a message: `x` division by zero. A kernel failure inside a node is that node's error. A failed parameter fails the nodes reading it with the parameter's name and message: `q`: division by zero. |
blocked | It reads a node that failed or is itself blocked, and is not evaluated. It names the first failed ancestor: blocked by b. |
pending | Only in a cheap-only pass: a heavy kind (a kernel build) not yet computed, and everything that reads one. |
The rest of the document evaluates around a failure. cadaclysm_blacksmith_document_evaluate returns every node's status, [{"id", "state", "key", "error"?, "by"?, "hash"?}]; _errors lists only the failed and blocked ones.
Re-evaluation is incremental. Each node has a key: a hash of the document's units, its kind, its fields as written, and the keys of everything it reads. A node is computed again only when its key changes, so an edit re-evaluates the edited node and what depends on it, and nothing else; a units edit changes every key. An editor can use the cheap-only pass to follow a drag: cheap kinds (profiles, values, checks) evaluate at once, heavy ones stay pending until a full pass.
Edits
Eight ops, each undoable
A document changes only through ops, JSON objects passed to cadaclysm_blacksmith_document_apply. Each op is checked against the whole document — types, ranges, references, cycles — and a refused op leaves the document as it was, returning the reason. Each applied op is one commit, with an optional message.
| Op | Effect |
{"op": "add", "node": {...}, "at": 0} | Inserts a node, at a position or (without at) at the end. A node with no id is given a fresh one that was never used, reported in the changed set. |
{"op": "set", "id": "b", "fields": {"x": 10, "at": null}} | Replaces the named fields; null removes one, back to its default. name, hidden and meta are set the same way; id and kind never change. |
{"op": "remove", "id": "a", "cascade": true} | Removes a node. Refused while another node reads it (a is read by b) unless cascade removes the readers too. |
{"op": "rename", "id": "b", "name": "Box"} | Changes the display name. |
{"op": "param", "name": "w", "value": "=2 * 3"} | Adds or changes a parameter; "value": null removes it. |
{"op": "units", "units": "cm"} | Changes the document's unit. Bare numbers are not rescaled: 10 was ten millimetres and is now ten centimetres. Unit literals such as "10 mm" keep their meaning. |
{"op": "meta", "app": "forge", "value": {"grid": 5}} | Sets an app's own data about the document, kept beside the nodes and saved with them: a viewer's camera, a grid, a selection. Evaluation never reads it; undo takes it back like any other op. "value": null removes it, and cadaclysm_blacksmith_document_meta(doc, app) reads it back. |
{"op": "batch", "ops": [...], "message": "..."} | All or none, one commit and one undo step. Inside a batch a node may be added before the node it reads; the document is checked once at the end. |
Apply returns the changed set, {"added": [ids], "changed": [ids], "removed": [ids], "params": [names], "variants": bool, "components": [names], "meta": [apps]}. Ops are deterministic: two copies of a document that apply the same ops in the same order save the same bytes.
History lives in the file. Each commit holds its id, its parents, its ops and the inverses that undo them, and optionally an author, a time and a message. Undo applies the inverses of the head commit and redo its ops again. An edit after an undo keeps the undone commits as an unnamed tip rather than discarding them, so nothing is lost; branches can be made, switched to by name or commit id, renamed and deleted. Undo, redo and every branch survive a save and a reload. Two more calls keep edits out of the history: a preview applies and evaluates ops without recording them (a drag), and a batch opened with _batch_begin records everything up to _batch_end as one commit.
Results
Values as JSON, geometry as handles
cadaclysm_blacksmith_document_value(doc, id) gives a node's value as JSON: a number (lengths in document units, angles in degrees), a boolean, text, a list or a record. Geometry appears there as a summary such as {"type": "solid", "faces": 6}. For a node in error it fails with the node's message; for a blocked one with blocked by b.
_result_kind says what a node holds — "solid", "sheet", "profile", "profiles", "nurbs", "subd", "curve", "list", "value" or "none" — and _result_solid, _result_profile and the other result calls return a new handle of that type, the caller's to free.
Curves as Béziers. _result_bezier_count and _result_beziers give a curve node, a profile, a list of profiles or a sketch as rational cubic Béziers, sixteen numbers each (x y z w per control point), carried onto a frame if one is given: what a page draws without asking for the profile's handle.
An item of a list node is id#i. A laced node or a kind that outputs a list gives a list; every result call reads its items as holes#0, holes#1, ..., counting from 0, and id#i#j reads an item of an item. Asked for the whole list, a result call refuses and says how: `c` is a list of 2: read an item as `c#0`. _value on the list node shows every item; on an item past the end it fails with `b#7`: no such item.
Reading the graph
What changed, what reads what, and what if
cadaclysm_blacksmith_document_revision(doc) is a counter that moves once with every change to the document's state: an apply, an undo or redo, a branch made, switched to or deleted, a preview frame, a batch's end. An evaluation, a save or a read never moves it, so a page keys what it has read on it and asks again only when it moved. _nodes(doc, ids) gives the nodes as the file holds them, all of them or the ones a JSON list of ids names, including an open batch's or preview's edits.
_inputs(doc, id, transitive) lists the nodes a node reads, and _readers the nodes that read it: directly, or with transitive however far. The readers are what removing a node would break; the inputs are what a node needs before it can be built.
A probe asks "what if" without an edit. _probe(doc, op, ids) applies an op to a scratch copy and evaluates only the nodes ids names and what they read, returning their statuses. Until _probe_end, every result call answers those nodes from the probe; the document's nodes, history and revision stay as they were, and any call that would change the document is refused. A snapping tool tries a placement this way and keeps it only if it fits.
A whole document
A plate with four bolt holes
A 120 × 80 × 6 mm plate with a clearance hole near each corner, the hole size looked up from the bolt named in a text parameter. Every node evaluates ok, and the file is exactly as the writer saves it.
{
"format": "cadaclysm-blacksmith",
"version": 1,
"units": "mm",
"params": {"bolt": "M5", "clearance": {"M4": 4.5, "M5": 5.5, "M6": 6.6}, "depth": 80, "margin": 10, "t": "6 mm", "width": 120},
"nodes": [
{"id": "fits", "kind": "check", "condition": "=clearance[bolt] < 2 * margin", "message": "='a ' + bolt + ' hole does not fit a ' + text(margin) + ' mm margin'"},
{"id": "plate", "kind": "solid.cuboid", "x": "=width", "y": "=depth", "z": "=t"},
{"id": "holes", "kind": "solid.cylinder", "r": "=clearance[bolt] / 2", "h": "=t + 2", "at": ["=[-1, 1, 1, -1] * (width / 2 - margin)", "=[-1, -1, 1, 1] * (depth / 2 - margin)", "=-t / 2 - 1"]},
{"id": "tool", "kind": "solid.join", "solids": ["holes"]},
{"id": "part", "kind": "solid.cut", "target": "plate", "tool": "tool"},
{"id": "mass", "kind": "measure.mass", "solid": "part"},
{"id": "label", "kind": "value", "value": "='Plate ' + text(width) + ' x ' + text(depth) + ', ' + text(len(holes)) + ' x ' + bolt"}
],
"commits": [
{"id": "c0", "parents": [], "ops": [], "inverses": []}
],
"branches": {"main": "c0"},
"branch": "main",
"head": "c0"
}
| Node | What it does |
fits | Checks that the hole leaves material inside the margin; its message is an expression, so it names the bolt and the margin. |
plate | A box centred on the origin, t thick. |
holes | One cylinder per corner. The at point's x and y are lists of four, so the node laces and gives four solids, holes#0 to holes#3; the radius comes from the record, indexed by the text parameter. |
tool | The four cylinders joined: a list input takes a laced node's items. |
part | The plate with the holes cut away. |
mass | Volume, area, centroid and inertia of the part, readable as mass.volume. |
label | "Plate 120 x 80, 4 x M5": text built from numbers and a list's length. |
Change "bolt" to "M6" and the check, the holes, the tool, the part, the mass and the label are evaluated again; the plate is not.
From code
Load, evaluate, read
// C: the document above, its part as a solid, the label as JSON
struct CadaclysmBlacksmithDocument *doc = cadaclysm_blacksmith_document_load(text);
char *status = cadaclysm_blacksmith_document_evaluate(doc, false);
struct CadaclysmBlacksmithSolid *part = cadaclysm_blacksmith_document_result_solid(doc, "part");
struct CadaclysmBlacksmithSolid *hole = cadaclysm_blacksmith_document_result_solid(doc, "holes#0");
char *label = cadaclysm_blacksmith_document_value(doc, "label"); // "Plate 120 x 80, 4 x M5"
char *edit = cadaclysm_blacksmith_document_apply(doc, "{\"op\": \"param\", \"name\": \"bolt\", \"value\": \"M6\"}", "bigger bolts");
# Python: the same calls on the Document class
from cadaclysm_blacksmith import Document
doc = Document.load(text)
part = doc.result("part") # a Solid
label = doc.value("label") # 'Plate 120 x 80, 4 x M5'
doc.apply({"op": "param", "name": "bolt", "value": "M6"}, "bigger bolts")
text = doc.save()
Status
The library ships in four flavours, from the whole kernel and every format down to the readers alone, and every license covers all four: the SDK at github.com/rdeioris/cadaclysm-sdk fetches the one you pick for your machine, free to build and test with, licensed per product, server or website when it runs in production. The Unreal plugin and the Unity package are not on their marketplaces yet; the Rust wrapper is on crates.io as cadaclysm-sdk, over the same proprietary library.
What you can do today: build a document node by node in the Loom or the Forge, save it, and open the file in a text editor; write to us at info@blitter.studio about the plugins or a kernel licence.