> For the complete documentation index, see [llms.txt](https://docs.tempoweave.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tempoweave.com/help-by-menu-tabs/design-menu/block-substitution-authoring-guide.md). # Block Substitution: Authoring Guide A deep-dive companion to the Block Substitution Guide. The first guide is for weavers who want to *use* the bundled templates. This one is for weavers who want to **understand**, **edit**, and **author** templates — the audience the international **Complex Weavers** community has been asking for.\ \&#xNAN;*Note: This document is new and updates will likely be made soon.* You will find: * What block substitution actually does, step by step * The two files that drive every substitution and how they pair up * Exactly where TempoWeave keeps templates on each operating system * The anatomy of a template WIF, including the private `*WarpPattern` / `*TieShafts` markers * The anatomy of a template's row in `blocktemplates.xml` * How each setting (Block Treadles, Warp Tie Count, Pattern Warp Step, Pattern Warp Wrap, Weft Background, Tie-up Pattern Reverse, Huck Style A/B/C/D) drives the output * A walkthrough for editing a bundled template safely * A walkthrough for building a brand-new template from scratch * A catalog of every template TempoWeave ships * A troubleshooting playbook for the most common authoring mistakes *** ### 1. What Block Substitution Actually Does Block substitution takes a small **profile draft** (one shaft per block, one treadle per block activation) and **multiplies** each block out into a real, loomable weave using a **template** that you choose from the library. The result is a fresh draft sized to your loom — full threading, tie-up, and treadling. The classical workflow that this automates is: 1. The weaver designs the *block pattern* at the smallest possible scale — usually 2 to 12 blocks. This stage is purely about layout: which block fires when, where the symmetry breaks, where the borders go. 2. The weaver picks a *weave structure* — Spot Bronson, Summer & Winter, Overshot, Huck, double weave, Satin, Turned Twill — that will give the cloth its hand and surface. 3. The two are combined by hand into a full draft. Each profile block expands to N pattern threads + the structure's shared "tie" threads; each profile treadle expands to N block treadles + the structure's shared "tie" treadles. Step 3 is mechanical and error-prone when done by hand for anything past a few blocks. The block-substitution engine in TempoWeave is exactly that step: given (profile draft, template), produce the full draft. #### What the engine does in six phases 1. **Parse the template WIF.** Read `[THREADING]`, `[TREADLING]`, `[TIEUP]`, plus the private `[TW WARP SECTIONMARKERS]` / `[TW WEFT SECTIONMARKERS]` sections that mark which threads belong to the *pattern* range and which belong to the *tie* range. 2. **Read the profile draft** from the currently open tab. Only the shafts and treadles that are actually used count — a profile project with 8 treadles configured but only 4 used produces a draft sized for 4 blocks, not 8. 3. **Build a shaft map and a treadle map.** These are 2D lookups: "template shaft S inside profile block B becomes output shaft X." The map encodes the chosen Pattern Warp Step / Pattern Warp Wrap behavior. 4. **Expand the profile threading.** For each profile thread, paste in the template's threading pattern at the correct shaft block. 5. **Expand the tie-up.** Walk every (profile shaft, profile treadle) pair; for cells the profile activates, copy the template's tie-up; for cells the profile leaves blank, copy either the template's tabby ground (or a separate Weft Background tie-up if the template provides one). 6. **Expand the profile treadling.** For each profile pick, paste in the template's treadling pattern at the correct treadle block. The result is written to a temporary WIF and opened in a new tab. Your original profile draft is never modified. *** ### 2. The Two Ingredients #### 2.1 The profile draft A profile draft is just a regular TempoWeave draft — but treated as block-level shorthand: * **One shaft = one block.** Shaft 1 is block A, shaft 2 is block B, and so on. * **One treadle = one block activation pattern.** Treadle 1 fires "blocks where treadle 1 is tied"; treadle 2 fires "blocks where treadle 2 is tied"; and so on. * **The tie-up encodes the block-to-block relationships.** A treadle that ties to shafts 1 and 3 fires blocks A and C together. * **Color is preserved.** Whatever warp/weft colors live in the profile carry through into the expanded draft, applied per thread. A 3-block profile draft has 3 shafts, 3 treadles, and a tiny 3×3 tie-up. That is enough to describe a wide-ranging design when expanded through, say, the 18-shaft `HuckHalfUnit-LaceInPattern` template. > The engine measures **used** shafts and **used** treadles, not your project's `Shafts` / `Treadles` settings. If you give yourself 8-treadle headroom but only ever press treadles 1 to 4, the substitution sizes itself for 4 blocks. This is intentional — it stops phantom blank treadles from ballooning the output. #### 2.2 The template A template is a small standalone weave structure stored in two files: * **`Name.wif`** — the structure itself, in standard WIF format, with two TempoWeave-private section-marker blocks that tell the engine which threads are *pattern* and which are *tie*. * **`Name.png`** *(optional)* — the preview image shown in the Block Substitution panel. Any 8-bit PNG works; \~150×150 px is plenty. The template's metadata — its name, type label, the integer flags that control the substitution math, the Huck variant, and so on — lives in the shared catalog file `blocktemplates.xml` alongside the `.wif` and `.png`. The catalog is what the panel reads when it builds the template list; the `.wif` is what the engine parses when you click **Apply**. A template can be tiny. **Spot Bronson**, the simplest bundled template, is a 2-shaft / 2-treadle WIF with a 4-thread pattern range and a 1-thread tie range. The whole `.wif` fits in 130 lines yet expands into a full multi-block draft at any profile size — the size of the output is driven entirely by your profile. *** ### 3. Template Files: Where They Live TempoWeave keeps templates in a **user-writable** folder, NOT inside the install directory. This is deliberate: the Velopack auto-updater replaces the install folder wholesale on every update, so anything inside the install would be wiped. The user folder survives updates, and bundled templates are seeded into it the first time the app runs. | Platform | Path | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Windows** |

%APPDATA%\TempoWeave Studio\_blocktemplates\
= C:\Users\<you>\AppData\Roaming\TempoWeave Studio\_blocktemplates\

| | **macOS** | `~/Library/Application Support/TempoWeave Studio/_blocktemplates/` | | **Linux** | `~/.config/tempoweave/_blocktemplates/` | On macOS the `Library` folder is hidden by default. To see it in Finder, open Finder, press ⌘+⇧+. (Command-Shift-Period). Or in Finder choose **Go → Go to Folder…** and paste the path above. #### What you will find inside ``` _blocktemplates/ ├── blocktemplates.xml ← the catalog (one row per template) ├── SpotBronson.wif ← bundled template structure ├── SpotBronson.png ← bundled preview ├── BronsonLace.wif ├── BronsonLace.png ├── Huck-LaceInPattern.wif ├── Huck-LaceInPattern.png … ├── MyCustom.wif ← something you added └── MyCustom.png ← preview you added (optional) ``` #### How the folder gets populated On first launch, TempoWeave does three things in order: 1. **Seed.** If the user folder is empty, the entire bundled folder (`Data/_blocktemplates/` inside the install) is copied in wholesale. 2. **Bundled-merge.** On every launch, any bundled template missing from the user folder is copied in. When a TempoWeave release adds new bundled templates (say, in v26.700), they show up automatically on the next launch. 3. **Salvage.** Any non-bundled `.wif` that the engine finds in the install folder (or, on Windows, in old `app-*` install dirs left over from prior versions) is copied in. This recovers user customizations that were saved to the install folder by older versions of TempoWeave. User customizations are **never overwritten** by this sync. If you've already got `BronsonLace.wif` in your user folder, the bundled copy is left untouched. The only operation that overwrites is **Reset to Bundled** (see §7). #### How to open the folder quickly The fastest path inside TempoWeave: **Design tab → Block Substitution → Edit Templates → Reveal Folder** opens the user templates folder in Finder / Explorer / your file manager directly — no path-pasting required. (The same button is available from the **Edit** sub-dialog too.) If you'd rather paste the path manually: * **Windows**: Win+R, paste `%APPDATA%\TempoWeave Studio\_blocktemplates`, Enter. * **macOS**: Finder → **Go → Go to Folder…** → paste `~/Library/Application Support/TempoWeave Studio/_blocktemplates`. * **Linux**: open your file manager, paste `~/.config/tempoweave/_blocktemplates`. *** ### 4. Anatomy of a Template WIF *Note: this section may be ignored unless you're integrating / parsing the TempoWeave WIF file.* A template WIF is a standard WIF file — Spot Bronson, for instance, declares `Source Program=TempoWeave Designer` but any WIF-conformant editor (Fiberworks, WeavePoint, pixeLoom) could write one too. The only TempoWeave-specific addition is the **section-marker** blocks. Here are the only sections that actually matter to the block-substitution engine. Everything else (color tables, notes, units) is read but doesn't drive the substitution. #### 4.1 `[WEAVING]` — overall size ``` [WEAVING] Shafts=2 Treadles=2 Rising Shed=true ``` Sets the size of the template's own draft. The engine reads `Shafts` and `Treadles` from this section first; if they're missing, it falls back to the values stored in `blocktemplates.xml` (`templateShafts` / `templateBlockTreadles + templateWeftTieTreadles`). #### 4.2 `[THREADING]` — which template thread sits on which shaft ``` [THREADING] 1=1 2=2 3=1 4=2 6=1 ``` Standard WIF threading. Thread 1 is on shaft 1, thread 2 is on shaft 2, etc. Missing entries (like thread 5 above) become **gaps** — the engine threads nothing there. The threading positions are split into two ranges by the section markers (§4.5): * **Pattern range**: the threads that get repeated *once per profile block*. * **Tie range**: the threads that appear *once total*, shared across all blocks. (These are the ground / tabby threads.) In the Spot Bronson example above, threads 1–4 are pattern (so each profile block produces "1, 2, 1, 2"), thread 5 is a gap, and thread 6 is a tie ("1"). #### 4.3 `[TREADLING]` — the template's own treadling ``` [TREADLING] 1=1 2=2 3=1 4=2 6=1 ``` Same shape as threading, but each row says "pick N uses treadle T". Multiple treadles per pick are comma-separated. The treadling positions are also split by markers into a pattern range and a tie range, plus an optional **weft background** range used by templates like Summer & Winter or Satin. #### 4.4 `[TIEUP]` — the template's own tie-up ``` [TIEUP] 1=1 2=2 ``` Standard WIF tie-up — "treadle 1 lifts shaft 1; treadle 2 lifts shaft 2". For larger templates this is where the structure's signature interlacement lives: shaft pairs of Spot Bronson, tie-down rows of Summer & Winter, the over-3-under-1 of Overshot. #### 4.5 The TempoWeave private markers — `[TW WARP SECTIONMARKERS]` and `[TW WEFT SECTIONMARKERS]` This is the key piece that distinguishes a TempoWeave template WIF from a plain WIF. These blocks declare which thread ranges are *pattern* (per-block) vs *tie* (shared). ``` [TW WARP SECTIONMARKERS] 1=1,4,*WarpPattern 2=6,6,*TieShafts ; [TW WEFT SECTIONMARKERS] 1=1,4,*WeftPattern 2=6,6,*TieTreadles ``` Format: `=,,` — all thread numbers are **1-based, inclusive on both ends**. Recognized marker names: | Marker | Where | Meaning | | ----------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `*WarpPattern` | warp | The thread range that is repeated per profile block. | | `*TieShafts` | warp | The thread range that is shared across all blocks. | | `*WeftPattern` | weft | The pick range that is repeated per profile-treadle activation. | | `*TieTreadles` | weft | The pick range used as shared tie / tabby treadles. | | `*WeftBackground` | weft | An optional second pick range used to fill blocks that are *not* selected by the profile. (Summer & Winter, Satin, Turned Twill use this.) | The marker rows are how a small WIF can encode "the first 4 threads are pattern, then there's a 1-thread gap, then a 1-thread tie" without you having to manually split the file. The `;` character ends a section per the WIF spec. If a template WIF has no markers, the engine assumes the entire template is the pattern range and there is no tie range. That works for templates with no shared ground (like `Overshot1.wif`) but is rare. #### 4.6 The other sections you can ignore `[WARP]`, `[WEFT]`, `[COLOR TABLE]`, `[WARP COLORS]`, `[WEFT COLORS]`, `[TEXT]`, `[NOTES]` are present in any TempoWeave-written WIF but don't influence substitution. They affect how the template *looks* when you open it directly, not how it expands. *** ### 5. Anatomy of a Template XML Row *Note: This information is for integration / parsing only and not needed to create your own Templates.* `blocktemplates.xml` is a DevExpress-flavored `TreeList` XML — one row per template. The full file has a top `` block declaring 16 columns, then a `` block with one `` per template, each containing a `` block of 16 `` entries in column order. Here's a real row (Spot Bronson) with each cell annotated: ```xml Spot Bronson SpotBronson.wif Bronson 17 17 2 1 2 1 false true 0 false ``` #### Column-by-column reference | # | Column | Type | Edit-Template-Dialog label | Notes | | -- | ----------------------------- | ------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | `templateName` | string | **Name** | What the user sees in the catalog. | | 2 | `templateLoc` | string | **File Name** | `.wif` filename, no path. Must live in the user templates folder. | | 3 | `Type` | string | **Type** | A category label only. Since June 2026 this stores a **canonical locale key** (`Bronson`, `Huck`, `Overshot`, `SummerWinter`, `DoubleTwoTie`, `ThreeTie`, `FourTie`, `Bateman`, `Crackle`, `DiversifiedPlain`, `DoubleWeaveBlock`, `Lace`, `Satin`, `Twill`, `Custom`); the dialog renders that key through the active locale, so the panel displays "Summer & Winter" in English, "Spitze" in German, etc. Older XMLs that stored a localized rendered label still load (the dropdown falls back to text match); on save the row is upgraded to the canonical key. | | 4 | `templateShaftsRequired` | int | *(info)* | Display-only "this template needs N shafts in the result". | | 5 | `templateTreadlesRequired` | int | *(info)* | Display-only "this template needs N treadles in the result". | | 6 | `templateBlockTreadles` | int | **Block Treadles** | Pattern treadles per block. Drives `OutputTreadles`. | | 7 | `templateWeftTieTreadles` | int | **Weft Tie Treadles** | Tabby / tie treadles, shared across all blocks. | | 8 | `templateShafts` | int | **Template Shafts** | Total shafts inside the template WIF. Must match `[WEAVING] Shafts`. | | 9 | `templateWarpTieCount` | int | **Warp Tie Count** | Tie shafts inside the template, shared across all blocks. | | 10 | `templateWeftBackground` | bool | **Weft Background** | Template has a second treadling block for non-active blocks. | | 11 | `templateBlockPreview` | object | *(not shown)* | Legacy embedded preview. New templates use the matching `.png`. | | 12 | `templateTieupPatternReverse` | bool | **Tie-up Pattern Reverse** | Treat profile tie-up `0` (not `1`) as "block active". | | 13 | `templatepatWarpStep` | short | **Pattern Warp Step** | Per-block shaft advance. `0` means "no overlap"; `1`/`2`/... step into the previous block. | | 14 | `templatepatWarpWrap` | bool | **Pattern Warp Wrap** | Cap shafts at `profileShafts + tie` and wrap modulo. | | 15 | `templateBlockHuckStyle` | bool | **Huck Style** | Switch the engine into Huck mode. Requires HuckType. | | 16 | `templateBlockHuckType` | string | **Huck Type** | `"A"`, `"B"`, `"C"`, or `"D"`. See §6.7. | You almost never edit `blocktemplates.xml` by hand. The **Edit Templates** dialog reads and writes every column shown above. The most common reasons to peek at the XML are: * Sanity-checking that the catalog matches the on-disk `.wif` (e.g. after editing a template's threading). * Diff-ing across releases to see which templates we added or tweaked. * Recovering from a corrupted catalog — see Troubleshooting (§10). *** ### 6. How the Generator Combines Them This is the section to read when you're trying to *predict* what a template will produce, or to *debug* a result that came out the wrong size. Let: * `profileShafts` = number of shafts used in the profile draft * `profileTreadles` = number of treadles used in the profile draft * `templateShafts` = `[WEAVING] Shafts` in the template (`= TemplateShafts` in the XML) * `tieShafts` = `WarpTieCount` * `patternShafts` = `templateShafts - tieShafts` * `blockTreadles` = treadles in the pattern range = `(templateTreadles - WeftTieTreadles)` (or that divided by 2 if `WeftBackground` is on) * `tieTreadles` = `WeftTieTreadles` #### 6.1 Output size ``` outputShafts = profileShafts + tieShafts if PatWarpWrap (profileShafts - 1) * PatWarpStep + patternShafts + tieShafts if PatWarpStep > 0 profileShafts * patternShafts + tieShafts otherwise outputTreadles = profileTreadles * blockTreadles + tieTreadles ``` The `(profileShafts - 1)` in the stepped branch is deliberate: the shaft-map walks blocks `b = 0..profileShafts-1` and the highest output position written is `(profileShafts - 1) * PatWarpStep + WarpTieCount + (patternShafts - 1)`, so the count is one more than that. An older formula used `profileShafts * PatWarpStep` here and produced a trailing unused shaft on stepped-without-wrap templates (the Bergman row exposed it). Worked example — Spot Bronson (`templateShafts=2`, `tieShafts=1`, `patternShafts=1`, `blockTreadles=1`, `tieTreadles=1`, `PatWarpStep=0`, `PatWarpWrap=false`) applied to a 4-block profile (`profileShafts=4`, `profileTreadles=4`): ``` outputShafts = 4 * 1 + 1 = 5 outputTreadles = 4 * 1 + 1 = 5 ``` > Note: Spot Bronson's catalog dialog *shows* **Block Treadles = 2**, but the engine recomputes `blockTreadles` from the WIF (`[WEAVING] Treadles=2 − WeftTieTreadles=1 = 1`). The XML dialog value is a legacy hint; the WIF wins. See §6.2. Worked example — Overshot1 (`templateShafts=2`, `tieShafts=0`, `patternShafts=2`, `blockTreadles=1`, `tieTreadles=0`, `PatWarpStep=1`, `PatWarpWrap=true`) applied to a 6-block profile: ``` outputShafts = 6 + 0 = 6 (PatWarpWrap caps it) outputTreadles = 6 * 1 + 0 = 6 ``` The engine caps at 128 shafts and 128 treadles; over those caps you get an error message rather than a malformed draft. #### 6.2 `BlockTreadles` — pattern treadles per block How many treadles of treadling does each profile block consume? In Summer & Winter "Singles" it's 1. In Spot Bronson it's 2 (the "1-2" alternation). In Huck full-unit it's 4. Larger structures with longer pattern repeats have larger `BlockTreadles`. The engine recomputes `BlockTreadles` from the WIF data at parse time. The XML value is treated as a hint that can be wrong — if your template's `[WEAVING] Treadles=6` and `WeftTieTreadles=2`, the engine will use `BlockTreadles=4` even if the XML says something different. #### 6.3 `WarpTieCount` — tie shafts in the template Tie shafts are the shafts that are **shared across all blocks** rather than multiplied per block. Summer & Winter has 2 tie shafts (the "1-3, 1-3" tabby ground). Huck full-unit has 2. Overshot has 0 (no shared ground — overshot's plain weave ground is created by the treadling). In the threading expansion, every profile block contributes the template's `patternShafts` worth of pattern threads; the `tieShafts` threads appear exactly once total at the start of the output. #### 6.4 `WeftTieTreadles` — tie treadles in the template Same idea on the weft side. Huck's tabby treadles, Summer & Winter's tabby treadles, Bronson's single tie pick — these are all `WeftTieTreadles`. They get reserved up front in the output treadling and are referenced by *every* profile pick (typically as the alternating tabby between pattern picks). #### 6.5 `PatWarpStep` — progressive shaft assignment (mostly Overshot) Default is `0`, meaning each profile block gets its own fresh `patternShafts` rows. The result has `profileShafts * patternShafts + tieShafts` total shafts. Set to `1` or higher and consecutive blocks share shafts with their neighbors — the classic Overshot trick where block A uses shafts 1+2, block B uses shafts 2+3, block C uses shafts 3+4, and so on. `PatWarpStep=1` produces a Threading that grows by 1 shaft per block instead of by `patternShafts` per block. Spot Bronson keeps `PatWarpStep=0` (each block gets a clean pair). Overshot1 uses `PatWarpStep=1` to get the stepped-twill threading. #### 6.6 `PatWarpWrap` — cap the shaft count When set, the output shafts are capped at `profileShafts + tieShafts` and pattern shafts past the cap wrap around modulo `profileShafts`. This is how Overshot1 produces, e.g., a 4-block design that fits in 4 shafts plus 0 tie shafts — without it the same profile would explode to 8 shafts. `PatWarpWrap` also activates a duplicate-thread filter in the expansion: when two consecutive output threads land on shafts of the same parity (both odd or both even), the second is dropped. That keeps the threading from sitting on the same shaft twice in a row in wrapped/Overshot designs. #### 6.7 `WeftBackground` — separate background tie-up Some templates (Summer & Winter, Satin, Turned Twill, double weave) need a different tie-up for blocks the profile *doesn't* select than for blocks it does. With `WeftBackground=true`, the template's tie-up is interpreted as two side-by-side tie-ups: the pattern columns and the background columns. When the engine expands a non-selected block, it draws from the background half instead of leaving that cell empty. #### 6.8 `TieupPatternReverse` — flip the profile selection logic The engine reads the profile tie-up and treats either `1` cells or `0` cells as "block active". With `TieupPatternReverse=false` (the default), `1` means active. With it set to `true`, `0` means active. Spot Bronson, BronsonLace, the Summer & Winter variants — these all use Reverse=true because the convention in the field is to draw the "off" blocks on profile tie-ups. #### 6.9 `HuckStyle` + `HuckType` (A / B / C / D) When `HuckStyle=true`, the tie-up builder routes every cell through a special Huck path that decides "lace opening here?", "warp float here?", or "weft float here?" based on the cell's shaft / treadle parity and the chosen Huck type. | Huck Type | Selected blocks | Non-selected blocks | | --------- | ------------------------------------ | ------------------- | | **A** | Lace opening | Plain weave ground | | **B** | Warp floats over plain weave | Plain weave ground | | **C** | Weft floats over plain weave | Plain weave ground | | **D** | Lace opening, opposite parity from A | Plain weave ground | Types A and D are mirror images — A puts the lace where the profile says "block on", D puts the lace where the profile says "block off". B and C give you the floats-on-plain-ground variants that are common in towels and table linens. Set `HuckStyle=false` if your template isn't a Huck — the type field is then ignored. #### 6.10 What the panel preview shows The PNG preview is purely cosmetic — the engine doesn't read it. It's there so the catalog list is visually distinguishable at a glance. Any 128×128-ish PNG works. If you don't supply one, the panel shows a blank thumbnail (`blank.png`). *** ### 7. Editing a Bundled Template — Walkthrough The new **Edit Templates** dialog (Design → Block Substitution → **Edit Templates** button) lets you tweak any template's settings *and* open its WIF for direct editing — without ever having to hunt for the user folder yourself. #### 7.1 The two new buttons In the dialog you'll see three small buttons next to the **File Name** field: * **`…`** — Browse for a different `.wif` file. Used to repoint a template at a different structure file (or to import a WIF from outside the templates folder; it auto-copies in). * **`✎`** — **Edit Template WIF.** Opens *this template's* WIF in a new editor tab and closes the dialog. Edit threading / treadling / tie-up like any other draft; **Save** writes the changes back to the same file in the templates folder, so the next substitution sees the edits immediately. * **`↺`** — **Reset to Bundled.** Visible only for templates we ship with the app. Confirms once, then overwrites your user `.wif` (and matching `.png`) with the bundled copy. Use this when you've made changes you regret and want to start over from the version we shipped. #### 7.2 Workflow: tweaking a tie-up Suppose you want to tighten the lace openings in `Huck-LaceInPattern.wif` by changing one tie-up cell. 1. **Design tab → Block Substitution → Edit Templates.** 2. Select **HuckHalfUnit-LaceInPattern** in the list. 3. Click **`✎`** next to the file name. The dialog closes and the WIF opens in a new editor tab named `Huck-LaceInPattern.wif`. 4. Make your tie-up edit. 5. **File → Save** (or Ctrl+S). The save writes directly back to the user folder, overwriting the existing `Huck-LaceInPattern.wif`. 6. Optionally: regenerate the preview PNG. Re-open Block Substitution and apply the template to a small profile to see the new output. #### 7.3 Workflow: undoing your edits 1. **Design tab → Block Substitution → Edit Templates.** 2. Select the template you regret. 3. Click **`↺`**. Confirm in the dialog. 4. The bundled `.wif` (and `.png`) are copied over your user copy, overwriting it. #### 7.4 Workflow: tweaking flags Most of what you'll edit in the dialog itself is the numeric flag fields — `Template Shafts`, `Block Treadles`, `Warp Tie Count`, `Weft Tie Treadles`, `Pattern Warp Step`, `Pattern Warp Wrap`, `Weft Background`, `Tie-up Pattern Reverse`, `Huck Style`. These write back to `blocktemplates.xml`, not to the `.wif`. A safer approach when experimenting: **duplicate the template first** (Add a new entry pointing at the same `.wif`, give it a different Name), then edit the duplicate. That way you can compare side-by-side and you don't have to remember to Reset. #### 7.5 What never gets edited automatically Even though the dialog will let you change the `File Name` field to anything, **changing it does not rename the underlying file**. If you type `MyVersion.wif` into a row whose `.wif` is still on disk as `SpotBronson.wif`, the row will look broken (no WIF, no preview). Use **`…` Browse** (which can also rename / copy) or rename the `.wif` in Finder/Explorer first. *** ### 8. Building a New Template — Walkthrough Suppose you want to author a brand-new template — say, a 4-shaft Huck variant that isn't one of the bundled ones. Here's the end-to-end: #### 8.1 Design the base structure In a fresh TempoWeave project, design the smallest possible unit of the structure you want to express: * For a **non-Huck pattern-on-tabby weave** (Summer & Winter, Overshot, Bronson…), draft the *single-block* version. So for Summer & Winter, threading goes `1, 3, 1, 3` (tie shafts) + `5, 6, 5, 6` (pattern shafts of one block). * For a **Huck variant**, draft one full Huck repeat unit. Usually 6 to 10 threads wide. * For a **double weave or turned twill**, draft one block's worth of layer-swap or twill repeat. Keep the threading minimal. The engine will repeat it once per profile block. #### 8.2 Set the section markers Open the WIF you just saved in a text editor (or use the **Mark Section** tool in TempoWeave to add the named section markers directly in the editor). Add the two private sections at the bottom of the file, **before the final `;`** line: ``` [TW WARP SECTIONMARKERS] 1=,,*WarpPattern 2=,,*TieShafts ; [TW WEFT SECTIONMARKERS] 1=,,*WeftPattern 2=,,*TieTreadles ; ``` Order doesn't matter; if your template has no tie shafts, omit the `*TieShafts` line (don't set its range to 0,0). If your template has a background, add a third row with `*WeftBackground`. #### 8.3 Save the WIF into the user folder Save the file as `MyTemplate.wif` directly into the user templates folder (§3). If you'd rather pick from a browse dialog, save it anywhere and let the **Add → Browse** step copy it for you. #### 8.4 Optional: create a preview PNG In TempoWeave, generate a small drawdown image (View Fabric or Cloth Simulation, then File → Export Image), crop to \~150×150, save as `MyTemplate.png` next to the WIF. The Block Substitution panel will pick it up automatically. #### 8.5 Add the catalog row Open **Design tab → Block Substitution → Edit Templates → Add**. Fill in: * **Name** — what you'll see in the catalog list. * **File Name** — `MyTemplate.wif` (or use **Browse** if the WIF is somewhere else; it'll copy in). * **Type** — pick from the dropdown. As of June 2026 the choices are Bateman, Bronson, Crackle, Diversified Plain, Double Two Tie, 3 Tie, 4 Tie, Summer & Winter (grouped together as the tie-unit family), then Doubleweave, Huck, Lace, Overshot, Satin, Twill, with **Custom** anchored at the bottom for anything that doesn't fit. The Type is a category label only — it doesn't change the substitution math, so when in doubt pick **Custom** and tune the per-template flags. * **Template Shafts** — total shafts in your template WIF. * **Block Treadles** — pattern treadles per block. * **Warp Tie Count** — tie shafts in your template. * **Weft Tie Treadles** — tabby / tie treadles. * **Pattern Warp Step** — almost always `0`. Set to `1`+ only for Overshot-style stepped twill. * The checkboxes — **Pattern Warp Wrap**, **Weft Background**, **Tie-up Pattern Reverse**, **Huck Style** + variant — flip based on what you designed. Click **Save**. The new template appears in the list immediately. #### 8.6 Test it In the same window, create a fresh project with a small profile (3 or 4 shafts, 3 or 4 treadles, a simple tie-up). Then **Design → Block Substitution → select your template → Apply**. The expanded draft opens in a new tab. Check: * Does the output have the right number of shafts? (Compare to §6.1.) * Does the output have the right number of treadles? * Does the tie-up look right where the profile is on? Where the profile is off? * Are there any blank treadles or shafts at the end? If so, the XML `Block Treadles` / `Warp Tie Count` / etc. don't match the WIF — see Troubleshooting. #### 8.7 Iterate Click the **`✎`** button on your new row to reopen the WIF, tweak, save, and run **Apply** again. The cycle is fast. *** ### 9. Reference Catalog (Bundled Templates) These are the templates TempoWeave ships, as of mid-2026. The columns are `Type` (category label), `Shafts` (`templateShafts`), `Block Tr` (`templateBlockTreadles`), `Tie Sh` (`templateWarpTieCount`), `Tie Tr` (`templateWeftTieTreadles`), `Wrap` (`templatepatWarpWrap`), `Step` (`templatepatWarpStep`), `Rev` (`templateTieupPatternReverse`), `WBG` (`templateWeftBackground`), `Huck` (`templateBlockHuckType` if `templateBlockHuckStyle=true`). | Template | Type | Shafts | Block Tr | Tie Sh | Tie Tr | Wrap | Step | Rev | WBG | Huck | | --------------------------------- | --------------- | ------ | -------- | ------ | ------ | ---- | ---- | --- | --- | ---- | | Spot Bronson | Bronson | 2 | 2 | 1 | 1 | – | 0 | yes | – | – | | Bronson Lace | Lace | 3 | 3 | 2 | 2 | – | 0 | – | – | – | | Double Two Tie 1-1-2-2 | Double Two Tie | 6 | 8 | 2 | 0 | – | 0 | – | – | – | | Double Two Tie 1-2-2-1 | Double Two Tie | 4 | 8 | 0 | 0 | – | 0 | – | yes | – | | Doubleweave | Doubleweave | 4 | 8 | 0 | 0 | – | 0 | – | yes | – | | Huck Full Unit – Lace | Huck | 4 | 4 | 2 | 2 | – | 0 | – | – | D | | HuckHalfUnit-LaceInPattern | Huck | 3 | 3 | 2 | 2 | – | 0 | – | – | A | | HuckHalfUnit-WarpFloatsInPattern | Huck | 3 | 3 | 2 | 2 | – | 0 | – | – | B | | HuckHalfUnit-WeftFloatsInPattern | Huck | 3 | 3 | 2 | 2 | – | 0 | yes | – | C | | Overshot1 | Overshot | 2 | 1 | 0 | 0 | yes | 1 | – | – | – | | Overshot Multishaft | Overshot | 2 | 1 | 0 | 0 | – | 0 | – | – | – | | Bergman | Custom | 3 | 3 | 1 | 2 | – | 1 | – | – | – | | Quigley Diamond | 4 Tie | 4 | 4 | 0 | 0 | – | 0 | – | – | – | | Quigley Point | 4 Tie | 4 | 4 | 0 | 0 | – | 0 | – | – | – | | Satin 4 | Satin | 4 | 8 | 0 | 0 | – | 0 | – | yes | – | | Satin 5 | Satin | 5 | 10 | 0 | 0 | – | 0 | – | yes | – | | Satin 6 | Satin | 6 | 12 | 0 | 0 | – | 0 | – | yes | – | | Summer & Winter-Dukagang Fashion | Summer & Winter | 3 | 4 | 2 | 2 | – | 0 | – | – | – | | Summer & Winter-Pairs O's | Summer & Winter | 3 | 4 | 2 | 2 | – | 0 | – | – | – | | Summer & Winter-Pairs X's | Summer & Winter | 3 | 4 | 2 | 2 | – | 0 | – | – | – | | Summer & Winter-Singles Treadling | Summer & Winter | 3 | 4 | 2 | 2 | – | 0 | – | – | – | | Turned Twill | Twill | 8 | 8 | 0 | 0 | – | 0 | – | yes | – | A few observations from the table you can use as design inspiration: * **Bronson family**: 1 tie shaft + 1 tie treadle, small pattern range. Reverse is on for Spot Bronson but off for Bronson Lace. * **Huck family**: same 3-shaft / 3-treadle base, four different "personalities" via Huck Type A/B/C/D. Notice the Weft-Floats variant flips `TieupPatternReverse=true`, which is the field convention. * **Summer & Winter family**: four treadling templates sharing the same threading base (3 template shafts: 2 tie + 1 pattern). Each is a different rhythm of pairs / singles / dukagång across `BlockTreadles=4`; pair them with the same profile to compare. * **Overshot pair**: **Overshot1** uses `PatWarpWrap=true` + `PatWarpStep=1` (the classic 4-block-fits-in-4-shafts combination); **Overshot Multishaft** keeps `PatWarpStep=0` and lets the substitution grow per block, useful when you want every overshot block on its own shaft pair. * **Satin family**: 5-end, 8-end, 12-end satins as block fillers, all with `WeftBackground=true`. * **Turned Twill / Doubleweave / Double Two Tie 1-2-2-1**: notice these also use `WeftBackground=true`. Any block-substituted weave where non-selected blocks need a *different* tie-up than selected ones lives in this group. * **Bergman**: a stepped-twill profile-substitution template (`PatWarpStep=1`, `Custom` type) used in the regression draft that prompted the mid-June 2026 `(profileShafts − 1) * step` off-by-one fix. If you're iterating on stepped templates, drop a profile into Bergman to confirm the trailing-shaft fix is in your build. * **Quigley Diamond / Quigley Point**: 4-tie family templates (`Type=4 Tie`) showing how a tie-unit weave can author cleanly without `WeftBackground` — the diamond and point treadlings differ but share the same threading and tie-up. *** ### 10. Troubleshooting #### "Generated draft is blank / empty" Likely causes, in order: 1. **The template WIF is empty.** `[THREADING]`, `[TREADLING]`, or `[TIEUP]` has no entries (or only entries outside the marker range). Open the WIF directly with the **`✎`** button and confirm it has visible threading, treadling, and tie-up cells. 2. **The section markers are missing or wrong.** If the markers say `*WarpPattern` is threads 1–4 but your `[THREADING]` only has entries 5–8, the engine sees an empty pattern range. Either move the threading entries or fix the markers. 3. **`Template Shafts` in the XML doesn't match `[WEAVING] Shafts`.** When the engine falls back to the XML value because `[WEAVING]` is missing `Shafts`, the wrong number truncates the threading. 4. **`Pattern Warp Step` is set wrong for a non-Overshot template.** Setting `PatWarpStep` to something like 2 on a template that wants 0 can size the output past the engine's 128-shaft cap (you'll see an error), or push every threading entry off-grid. #### "Generated draft has trailing blank treadles or shafts" This was a real bug in versions prior to mid-June 2026 and is now fixed — the engine sizes by **used** profile shafts/treadles, not configured. If you still see trailing blanks: * Check your **profile** project: do you have configured shafts/treadles past your actual use? (e.g., 8 treadles configured, 4 used). Versions before the fix multiplied the unused 4 through. Updating to the latest TempoWeave fixes this without changes to your profile. * If the trailing blanks are on the **shaft** side and your template has `PatWarpStep>0`, remember the formula is `profileShafts * step + patternShafts + tieShafts` — that intentionally produces some extra shafts past the highest-used pattern position to allow the step to complete. #### "Tie-up looks right where blocks are on, wrong where blocks are off" This is the **TieupPatternReverse** decision. If your profile drafts the *active* blocks as `1` cells in the tie-up (common in pixeLoom-style profiles), set `TieupPatternReverse=false`. If your profile drafts the *active* blocks as `0` cells (common in textbook-Bronson notation), set it to `true`. Flipping the checkbox between **Apply** runs is the fastest way to confirm. #### "Apply does nothing / shows an error" Open the bottom **error log** strip of the Block Substitution panel after clicking Apply. The engine writes one of these: * `No profile data in source canvas.` — your profile draft has zero used shafts or zero threads. * `Template file not found: …` — the catalog row's `File Name` points at a `.wif` that isn't in the user templates folder. Use **`…` Browse** to repoint, or rename the file. * `Template has no pattern shafts (all shafts are tie shafts).` — `WarpTieCount >= TemplateShafts`. Reduce the tie count. * `Output requires N shafts (max 128).` / `Output requires N treadles (max 128).` — your profile is too big for this template, OR your `PatWarpStep` is too aggressive. Lower one or the other; or enable `PatWarpWrap`. #### "Edit Templates ✎ button does nothing" If clicking the **`✎`** Edit button doesn't open a tab, the WIF file the row points at isn't where the row says it is. Common causes: a `.wif` was renamed in Finder/Explorer without updating the row, or the WIF was deleted. The dialog will toast `"WIF file isn't in the templates folder. Browse to it first."` — use **`…` Browse** to repoint to wherever the file actually is. #### "Reset to Bundled button isn't showing" The button only appears for templates whose `File Name` matches one of the filenames we shipped with the app. If you've renamed the `.wif` on disk (e.g., from `SpotBronson.wif` to `SpotBronson-tweaked.wif`) the button hides because there's no bundled source to revert to. Rename the file back, or use **Add** to import the bundled version under a new name and copy-paste your tweaks. #### "I edited the WIF directly but Apply still shows the old result" The engine reads the WIF fresh on every **Apply** click, so this shouldn't happen — but check: 1. You saved to the **user** templates folder (§3), not to the bundled `Data/_blocktemplates/` inside the install. 2. The file you saved matches the `File Name` in the catalog row (case-insensitive on Windows, case-sensitive on macOS/Linux). 3. You don't have two copies of the file under slightly different names. Use **`✎`** Edit, which always opens the file the row is actually pointing at. #### "My XML catalog got corrupted" If `blocktemplates.xml` no longer parses, TempoWeave will fall back to loading the embedded copy (the bundled snapshot) on next launch — so the app keeps working but your custom rows disappear. To recover: 1. **Back up the bad XML** to a safe location (it may still contain salvageable rows). 2. **Delete** `blocktemplates.xml` from the user templates folder. 3. **Launch TempoWeave.** It will seed a fresh catalog from the bundled set. 4. **Re-add your custom rows** via **Add** in the Edit Templates dialog. You don't need to recopy the `.wif` files — they're already in the folder. #### "I added a new template but it doesn't appear in the list" Three things to check: 1. The `.wif` is in the user templates folder. (Open the folder; confirm it's there.) 2. You clicked **Save** at the bottom of the **Add** form, not Cancel. 3. The Block Substitution panel is showing the latest list. Reopen the panel (or restart TempoWeave) to force a reload. *** ### Appendix: a Minimal Template You Can Use as a Skeleton Save the following as `MyMinimal.wif` in your user templates folder. It's a 2-shaft / 2-treadle plain-weave template with the markers set so the engine recognizes a 2-thread pattern range and no tie range. From here, edit the threading, treadling, tie-up, and markers to whatever structure you're prototyping. ``` [WIF] Version=1.1 Date=2026-06-11 Developers=YourName Source Program=TempoWeave Source Version=1.0 ; [CONTENTS] WEAVING=true THREADING=true TIEUP=true TREADLING=true ; [WEAVING] Shafts=2 Treadles=2 Rising Shed=true ; [THREADING] 1=1 2=2 ; [TREADLING] 1=1 2=2 ; [TIEUP] 1=1 2=2 ; [TW WARP SECTIONMARKERS] 1=1,2,*WarpPattern ; [TW WEFT SECTIONMARKERS] 1=1,2,*WeftPattern ; ``` Then add a catalog row for it in **Edit Templates → Add** with: * **Template Shafts** = 2, **Block Treadles** = 2, **Warp Tie Count** = 0, **Weft Tie Treadles** = 0 * **Pattern Warp Step** = 0, **Pattern Warp Wrap** = off, **Weft Background** = off, **Tie-up Pattern Reverse** = off, **Huck Style** = off Applied to a 3-block profile (`profileShafts=3`, `profileTreadles=3`), this template will produce `3 × 2 = 6` output shafts and `3 × 2 = 6` output treadles — confirming the math from §6.1. From there you can extend the WIF and rerun Apply to see exactly how each flag and marker changes the result.