diff --git a/mcp_server.md b/mcp_server.md index 723cdba..f0ab616 100644 --- a/mcp_server.md +++ b/mcp_server.md @@ -284,6 +284,13 @@ Across the shipped examples: 3190 conductors, not one with a cable value. take `"conductor": "{uuid}"` (as `qet_conductors` reports it) in place of `element` + `terminal`, which works where two conductors meet at a terminal, as long as one of the conductor's two terminals carries only it. +- **A terminal can be given by its uuid.** *Pending, + [PR #1126](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1126):* + `terminal`, `from_terminal` and `to_terminal` will also take the + terminal's uuid (as `qet_element_info` lists it) in place of its index, on + the op's own element — for `add_conductor`, each end's own. Unlike the + index, it tells apart two terminals at the same point. A uuid the element + does not have stops the run, with a note naming the argument. - **`link_elements` takes a folio for each end**, because a master and its slave are normally on different folios. Whether a pair may be linked is decided by QElectroTech's own `isLinkable()`, so a script cannot make a diff --git a/project_database.md b/project_database.md index 7d998b5..b85d707 100644 --- a/project_database.md +++ b/project_database.md @@ -197,16 +197,13 @@ stored symbols had no terminal uuid. How that is handled: ([PR #1116](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1116)), and a wire that still cannot be reattached is listed in a warning when the project opens, instead of disappearing silently. - -> **Status: pending.** This point describes -> [PR #1122](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1122), -> not yet merged. Nothing here works until that lands — check the PR -> before trying any of this against your own build. This point will drop -> this notice once it does. -> -> - The symbol editor gives the terminals of an old symbol file the same -> worked-out uuids when it opens it, instead of random ones, so every -> copy of that symbol agrees with the projects that use it. +- Since + [PR #1122](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1122), + the symbol editor gives the terminals of an old symbol file the same + worked-out uuids when it opens it, instead of random ones, so every copy + of that symbol agrees with the projects that use it. The collection's + last three symbols without terminal uuids got these values too + ([elements #83](https://github.com/qelectrotech/qelectrotech-elements/pull/83)). `projectDataBase::excludedConductorCount()` reports how many conductors could not be keyed at all, counted from the live scene rather than the database — diff --git a/scripting.md b/scripting.md index c0538d9..b927702 100644 --- a/scripting.md +++ b/scripting.md @@ -164,8 +164,43 @@ var e = ends[0].split(" terminal "); qet.setConductorProperty(0, e[0], parseInt(e[1], 10), "num", "W12"); ``` -Wires in a project saved by an older QElectroTech have no saved uuid yet, so -theirs are different each time the project opens until that changes (see +Wires in a project saved by an older QElectroTech get a uuid worked out from +what they connect when the project opens, the same every time, and saved +from the next save on (see [the project database](project_database), +section 4). + +### Find a terminal by its uuid + +> **Status: pending.** This section describes +> [PR #1125](https://github.com/qelectrotech/qelectrotech-source-mirror/pull/1125), +> not yet merged. Nothing here works until that lands — check the PR +> before trying any of this against your own build. This section will drop +> this notice once it does. + +`qet.addConductor()` and the conductor calls take a terminal as an element +uuid and a terminal **index**. The index is the terminal's place in a list +sorted top to bottom, then left to right — not the order the symbol file +lists them in, and undefined between two terminals at the same point. +`qet.elementTerminals()` shows that numbering, and ends each line with the +terminal's uuid: + +```js +qet.elementTerminals(0, elementUuid) +// -> ["0: A1 (1 conductor(s)) {5c1e…}", "1: A2 (0 conductor(s)) {9d04…}"] +qet.terminalIndex(0, elementUuid, "{9d04…}") // -> 1, or -1 if not found +``` + +A terminal's uuid comes from its symbol, so every placed copy of one symbol +has the same ones: it names a terminal only together with its element. Hold +the uuid, and turn it into the index when calling: + +```js +var a2 = qet.terminalIndex(0, coil, "{9d04…}"); +qet.addConductor(0, coil, a2, lamp, qet.terminalIndex(0, lamp, "{77aa…}")); +``` + +`qet_element_info` in the [MCP server](mcp_server) lists the uuids of a +symbol file's terminals. Every terminal of an opened project has one (see [the project database](project_database), section 4). ### Navigate and message