Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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. 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

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

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

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

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

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).

Format: <index>=<startThread>,<endThread>,<name> — 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 <Columns> block declaring 16 columns, then a <Nodes> block with one <Node> per template, each containing a <NodeData> block of 16 <Cell> entries in column order.

Here's a real row (Spot Bronson) with each cell annotated:

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

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):

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:

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:

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 <Name> 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.

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.

PreviousBlock SubstitutionNextDesign Repeats

Last updated

Was this helpful?