Log inGet started
Package

fabricsMaterials.package

Newest version

This package holds more than this page lists. See all of its files in its world.

README.md

fabricsMaterials: Warp and Weft

25 real-scale fabric and soft-goods materials for the Swatchbook material library: woven cloth, pile and knits, leathers, rope and quilting, and toon looks, all behind one name each.

Version 1.0.1. Depends on materialLibraryKit 1.3.1 (Swatchbook), which installing this package brings with it. Nothing else is installed, and there is no setup code: once installed, every fabric is in the library's list, picker and swatch gallery on every player's machine.

Velvet, satin, silk and suede glow at grazing angles with the engine's sheen lobe. Satin and silk stretch their highlight across the floating threads with its anisotropic lobe, and faux fur carries the paired strand highlights of its fibre lobe. Every fabric is two-sided, so a sheet that drapes physically shows its fabric from both faces. Swapping denim for velvet, or for toon velvet in a cartoon world, is a change of one name.

Texture memory: 23.9 MB for all 25 (GPU, mipmaps included, every texture counted once), 32.3 MB with the 25 reference pictures the gallery shows. The largest fabric is 3.0 MB.

Install and use

Install fabricsMaterials from ZeroMind (search "fabricsMaterials" or "Warp and Weft"). It lands at /source/fabricsMaterials.package, with materialLibraryKit 1.3.1 under /source/deps/. Then, in a brand-new world, run this from a script or the console (execute):

local Materials = require("~materialLibraryKit.Materials")
local cushion = entity.spawn("cushion", { synced = true, components = { Model = { model = "cube" } } })
cushion.localPosition = { 0, 0.5, 3 }
assert(Materials.apply(cushion, "velvet"))        -- every player sees velvet
assert(Materials.apply(cushion, "toonVelvet"))    -- the same cushion for a cartoon world: only the name changes
for _, m in Materials.list({ collection = "fabrics", kind = "denim" }) do
    print(m.id, m.style, m.tileSize, m.textureKB)  -- denimIndigo, denimStonewash, toonDenim
end
Materials.clear(cushion)                           -- take the fabric off again, for everyone
entity.despawn(cushion.id)                         -- and the cushion

Materials.apply(object, name) puts a fabric on any Model and shares the choice with every player. Materials.get(name).material is the material itself, for any Model of your own. Materials.list({ collection = "fabrics", ... }) filters by kind, style, tag or search, for example tag = "sheen", style = "toon" or search = "carpet".

To walk round every fabric, make the world's start scene the gallery: copy this world's scenes/main.scene, or stand the gallery in a scene of your own (build.luau, with the spawn near the origin):

local g = entity.spawn("Gallery")
g.component.add("SwatchGallery", { view = "all", lighting = "studio" })
g.component.add("FabricShowcase", {})

A fabric on a draped cloth

Fabrics repeat once per UV unit (the library's convention; tileSize says how many metres that is), so cloth that moves needs UVs laid in metres ÷ tileSize. The package ships those as meshes: a 1.6 × 1.6 m sheet and a 0.45 × 0.14 × 0.45 m cushion, for every fabric's tile size. FabricCloth swaps to the right one whenever a player applies another fabric. Something to drape over, and a sheet that falls onto it in play:

local Materials = require("~materialLibraryKit.Materials")
local stand = entity.spawn("stand", { components = { Model = { model = "cube" }, BoxCollider = {} } })
stand.localPosition = { 3, 0.4, 3 }
stand.localScale = { 0.8, 0.8, 0.8 }
local sheet = entity.spawn("tablecloth", { synced = true, components = { Model = { model = "fabricsMaterials.meshes.drapeSheet_72" } } })
sheet.localPosition = { 3, 1.4, 3 }
sheet.localScale = { 1.6, 1, 1.6 }                 -- the baked sheet is 1.6 m square
sheet.component.add("FabricCloth", { shape = "sheet", fabric = "linen" })
sheet.component.add("SoftBody", { shape = "cloth", resolution = 24 })
assert(Materials.apply(sheet, "velvet"))           -- FabricCloth moves it to the 250 mm layout
  • Cushions: use meshes.cushion_<mm> and scale { 0.45, 0.14, 0.45 }, with FabricCloth { shape = "cushion" } and SoftBody { shape = "box", resolution = 6, stiffness = 120, shapeMatching = 6 }. This world's bench does exactly that.
  • Both sides: every fabric is two-sided (cull: none, and double_sided on the pbr fabrics flips the shading normal on the back face), so the underside of a hanging flap is lit as fabric, not as the inside of a mesh.
  • Measured in play: the sheet above fell from 1.4 m and draped over the stand (its bounds 0.26 to 0.86 m). Velvet went on through the shared channel, and the mesh changed to drapeSheet_250 with the body still built. Once settled, cloth sleeps: four of five bodies asleep after 6 s, 0.9 ms of soft-body time per step.
  • Other sizes: FabricDrape.sheetGeometry(width, depth, segments, tile) and FabricDrape.bakeMesh(name, geometry) make a sheet of any size (tool code).

The fabrics

Every fabric is tagged category = fabric, with its kind, its style, tileSize (metres one repeat covers), roughness and metallic ranges (measured from its textures; metallic is 0 everywhere), textureKB (GPU memory, mipmaps included), and animated = false. Its tags add the lobes it uses (sheen, anisotropic, fibre highlights, clearcoat, cel-shaded), two-sided, a finish (glossy, satin, rough), non-metallic, a texture weight (textures-tiny / -light / -medium / -heavy), tile-<metres>m, not-animated, and search words.

Textures lists albedo / normal / mask sizes in pixels (the mask packs occlusion, roughness and metalness; - means none). Seam is Checks.seams' score at 4 × 4 and shimmer Checks.shimmer's score at 30 m (fails above 6). Both were measured on 2026-10-25 with materialLibraryKit 1.3.1 on the desktop engine; see "Checked".

NameFabricKind, styleTile (m)Real sizesRoughnessLobesTextures (memory)Seam / shimmer
Woven cloth
cottonCalicoCotton calicocotton, realistic0.064plain weave, 0.5 mm yarns; 128 × 128 per repeat0.84–0.95sheen512 / 512 / 512 (1.0 MB)1.77 / 0.13
denimIndigoIndigo denimdenim, realistic0.0643/1 right-hand twill, 0.5 mm ends and picks0.78–0.91sheen512 / 512 / 512 (1.0 MB)1.63 / 0.29
denimStonewashStonewashed denimdenim, realistic0.064the same twill, stonewashed0.76–0.89sheen512 / 512 / 512 (1.0 MB)1.55 / 0.33
linenNatural linenlinen, realistic0.072plain weave, 0.75 mm slubbed yarns; 96 × 960.73–0.84sheen512 / 512 / 512 (1.0 MB)0.93 / 0.30
canvasHeavyHeavy canvascanvas, realistic0.096cotton duck, plain weave, 1.0 mm plied yarns0.84–0.92sheen512 / 512 / 512 (1.0 MB)1.58 / 0.28
burlapBurlap sackclothburlap, realistic0.12open jute weave, 3.33 mm pitch, 2.1 mm yarns0.85–0.97sheen512 / 512 / 512 (1.0 MB)2.06 / 0.86
silkDupioniShot silk dupionisilk, realistic0.0640.33 mm crimson warp × 0.5 mm slubbed gold weft0.31–0.44sheen, anisotropic512 / 512 / 512 (1.0 MB)1.47 / 0.11
satinCharmeuseSatin charmeusesatin, realistic0.0645-end warp-faced satin, 0.4 mm, floats 1.6 mm0.22–0.25sheen, anisotropic512 / 512 / 512 (1.0 MB)1.40 / 0.03
tartanWoolWool tartantartan, realistic0.1282/2 twill, 1.0 mm; one 128-thread Black Watch style sett0.84–0.88sheen512 / 512 / 512 (1.0 MB)1.36 / 0.52
Pile, knit and fluffy
woolKnitChunkyChunky wool knitknit, realistic0.096stockinette, 12 mm stitches, 9.6 mm rows; 8 × 100.86–0.92sheen512 / 512 / 512 (1.0 MB)1.83 / 0.15
feltWool feltfelt, realistic0.2nonwoven, matted fibres 10 to 30 mm long0.94–0.96sheen512 / 512 / 512 (1.0 MB)0.70 / 0.20
velvetVelvetvelvet, realistic0.252 mm cut pile with soft drifts0.90–0.96sheen512 / 512 / 512 (1.0 MB)0.46 / 0.15
carpetCutPileCut-pile carpetcarpet, realistic0.2saxony tufts about 3 mm across on a 4 mm gauge0.80–0.95sheen512 / 512 / 512 (1.0 MB)1.14 / 0.26
carpetLoopBerber loop carpetcarpet, realistic0.2loops 4 mm across in rows 5 mm apart; 50 × 400.84–0.96sheen512 / 512 / 512 (1.0 MB)1.59 / 0.79
fauxFurFaux furfur, realistic0.2530 to 50 mm pile lying along U0.52–0.74sheen, fibre highlights512 / 512 / 512 (1.0 MB)0.97 / 0.75
Leather
leatherSmoothSmooth leatherleather, realistic0.2grain cells 1 to 2 mm, pores 0.1 to 0.3 mm0.44–0.63clearcoat512 / 1024 / 512 (2.0 MB)0.99 / 0.38
leatherWornWorn cracked leatherleather, realistic0.3crack cells 10 to 40 mm, scuffed through0.51–0.78clearcoat1024 / 1024 / 512 (3.0 MB)0.95 / 0.94
suedeSuedesuede, realistic0.25brushed nap with brush marks 10 to 60 mm long0.92–0.97sheen512 / 512 / 512 (1.0 MB)1.32 / 0.37
Soft goods
ropeManila roperope, realistic0.1four 25 mm three-strand ropes, 100 mm lay0.78–0.90sheen512 / 512 / 512 (1.0 MB)1.00 / 0.79
quiltedCushionQuilted cushionquilted, realistic0.3diamonds 100 mm point to point, 3 mm stitches0.50–0.85sheen, anisotropic512 / 512 / 512 (1.0 MB)0.99 / 2.59
Stylised
toonCottonToon cottoncotton, toon0.2cross-hatch 12.5 mm apart0.9cel-shaded256 / - / - (85 KB)0.01 / 0.15
toonDenimToon denimdenim, toon0.2twill diagonals 10 mm apart0.85cel-shaded, rim256 / - / - (85 KB)1.22 / 0.22
toonVelvetToon velvetvelvet, toon0.4painted pile swirls; hard pale rim band0.95cel-shaded, sheen rim256 / - / - (85 KB)1.72 / 2.32
handPaintedKnitHand-painted knitknit, stylised0.2painted stitches 25 mm wide0.9(none)512 / 512 / - (683 KB)2.05 / 0.39
feltFlatFlat-colour feltfelt, toon0.4one flat tomato red1.0cel-shaded64 / - / - (5 KB)1.28 / 0.06

Texture memory

  • All 25 fabrics: 23.9 MB of GPU texture memory (24,495 KB), mipmaps included, each texture counted once. That is 18 fabrics at 1.0 MB (18,432 KB), leatherSmooth at 2.0 MB, leatherWorn at 3.0 MB, handPaintedKnit at 683 KB, the three toons at 85 KB each and feltFlat at 5 KB: 18 + 1 + 1 + 1 + 3 + 1 = 25 fabrics, and 18,432 + 2,048 + 3,072 + 683 + 255 + 5 = 24,495 KB.
  • Reference pictures: 8.3 MB (25 at 512 px). They load only where the gallery hangs them.
  • Everything together: 32.3 MB, about a twelfth of the library's 384 MiB budget for low-end devices.
  • Within the web limits: every fabric passes Checks.budget with no warnings. Each binds at most 5 sampled textures (the web limit is 9) and no storage buffers, nothing is over 1024 px, and every texture is UASTC (BC7 on desktop, ASTC on phones).
  • The mask is one texture in two slots: the pbr fabrics bind their ORM mask to both occlusion_texture and roughness_metallic_texture. The library's Materials.measureTextures counts it per slot, so the catalog takes the second copy off; textureKB is the real figure.
  • Meshes: the 20 drape and cushion meshes (2,401 and 1,734 vertices each) are geometry, not texture: 1.6 MB on disk for all 20. A scene loads only the ones its cloth wears.

How they were made

  • Reference pictures first. Every fabric has references/<id>, generated from the prompt in its catalog entry before the fabric was drawn, at its stated real width. Each fabric was then compared with its picture side by side under the library's Studio look (its reference look for judging materials), and its mean colour was matched to the picture's.
  • Baked procedurally in Luau by FabricBaker, FabricWeaves and FabricRecipes (require("~fabricsMaterials.FabricRecipes").bakeAll() re-bakes all 25 in about a minute).
    • FabricBaker is masonryMaterials' MasonryBaker (Brick and Mortar, MIT), itself from Bedrock's StoneBaker and Heartwood's WoodBaker. Every field covers one repeat and every generator is periodic, so the maps tile by construction.
    • Weaves are real weave structures: which yarn is on top at each crossing (plain, 2/2 and 3/1 twill, 5-end satin), round yarns that rise along each float and dip under, slubs and ply twist rounded to whole numbers per repeat.
    • Knits are V stitches with two-ply legs. Carpets are twisted tufts and loops. Fur is long soft fibre streaks lying along U. Leathers are Voronoi grain, pores and a warped crack network. Rope is a real three-strand lay, and the quilt is seamed diamonds with running stitches.
  • The engine's own lighting model. The realistic fabrics are the engine's pbr shader with its own lobes, so every capture pass reads real material data:
    • sheen (sheen_color, sheen_roughness) for cloth and pile;
    • anisotropy along the UV tangent for satin, silk and the quilted sateen;
    • the fibre lobe for fur;
    • a thin clearcoat for waxed leather.
  • A small cel shader for the toons. toonFabric is adapted from metalsMaterials' toonMetal (MIT): cel bands, lifted shadows and a hard pale rim band for toon velvet. It is two-sided.
  • Physically based. Colour carries no painted-in light; gaps, pits and seams darken through the occlusion channel and the normal map. Metallic is 0. Roughness follows the fibre: satin 0.22–0.25, silk 0.31–0.44, waxed leather from 0.44, wool, jute, felt and suede 0.84 and up. Normal maps are green-up, the convention the engine reads; the test suite proves the direction on a synthetic bump.
  • Real size. Each repeat holds a whole number of threads, stitches, loops, ropes or seams at their real dimensions (the "Real sizes" column).

What was reused, and what was not

  • Used: the library's collection contract, gallery, picker, lighting looks and checks (materialLibraryKit 1.3.1); masonry's baker, catalog pattern and showcase (MIT); metals' toon shader (MIT); the engine's pbr lobes and SoftBody cloth.
  • Not used: the older "Cloth and fabric" world's fabric_surface shader. Its sheen is a rim added after lighting, and its weave is a sin × sin pattern that moirés at distance; the engine's pbr now does both properly. Its GPU cloth module was also left out: it collides only with analytic spheres and planes, where SoftBody drapes over real colliders and is shared with every player.
  • Not used: one-off velvet, leather and denim materials in other games, which are flat colours or photos with no stated scale.

Checked

On 2026-10-25, desktop engine, materialLibraryKit 1.3.1, for all 25 fabrics:

  • Seamless tiled 4 × 4: Checks.seams renders a 4 × 4-repeat plane in the albedo pass (the toons, whose shader lights itself, in the final pass) and checks every texture's opposite edges. All 25 pass both. The worst scores, burlap 2.06 and handPaintedKnit 2.05, pass on the library's rule that the edge is no stronger than the fabric's own strongest yarn edges.
    • The library's seam check assumes one repeat per UV unit, which is exactly how fabrics map, so it is used as it ships.
    • Getting here fixed three real wrap bugs: twist ridges and slubs that did not divide the repeat, and knit legs cut at stitch columns. The baker also rolls each periodic texture so its edge falls on the calmest row and column.
  • No shimmer or moiré at 30 m: Checks.shimmer moves a grazing 30 m view by half a pixel and measures the change. The worst are quiltedCushion 2.59 and toonVelvet 2.32, against a limit of 6; every other fabric is under 1.
  • Web budget: Checks.budget reports no warnings for any fabric.
  • On moving cloth: the scene's linen sheet and the README's draped sheet both drape over a collider in play. Swapping the fabric changes the mesh to the new tile size without disturbing the body, and the underside shows the same fabric.

The test suite reruns the quick parts in about a minute:

asset.resolve("fabricsMaterials.tests.fabricsMaterials", "testSuite"):run()

It covers the 25 names and every tag, the filters, the costs and budget, the physical values and normal direction, and seams and shimmer on one fabric per shader path (denim, velvet, fur, toon velvet). It also covers apply, swap and clear, FabricCloth on a sheet and a cushion, the references, the picker, all 25 on one gallery ring, and this README. Each test runs inside the library's Sync.isolate(), so nothing it does reaches other players.

Multiplayer

  • Applied fabrics are shared. Materials.apply and the picker go through the library's shared channel: every player sees the fabric on any object every machine holds (a synced object, a scene's own objects, the gallery's swatches), and players who join later get it too.
  • Draped cloth is shared. The sheet and cushions are synced soft bodies: one machine simulates each, every player sees the same drape, and FabricCloth makes the same mesh swap on every machine from the shared material.
  • Lighting looks are shared. The gallery's toolbar switches them for everyone.
  • Gallery pieces are local. Swatches and reference boards are built on each machine.

Known limits

Every limit here is tracked in an issue. gh#N is issue N at github.com/OrigoZero/zero.

  • The gallery is heavy in the desktop editor (gh#20750; also filed on ZeroMind as 01M5SQ91GAF4MTJNHD2VTYC1V8).
    • Measured with the library's own Sync.perf() in the desktop editor (2097 × 1409 viewport): 9.9 fps with the 25-bay gallery standing (280 local entities), 26.9 fps with it cleared.
    • The difference, about 63 ms a frame, is the engine's gather_and_send_deltas.settle_loans working through the gallery's local swatch entities. The fabrics themselves cost nothing per frame, and settled cloth sleeps.
    • The same cost is reported against materialLibraryKit 1.3.1 ("gallery swatches replicate in editor play"), and masonryMaterials 2.0.0 describes it too.
    • The ring is kept whole so every fabric is visible from the spawn.
  • The library's checking tools log errors about .shared in a browser (gh#7789). materialLibraryKit's materialChecks tools each require(".shared"), and its Checks module and test suites load the engine's .shared helpers. In a browser these report errors. The fabrics, the picker, the gallery and Materials.* don't load them; the checking tools and this package's test suite do. Reported from a browser; not reproduced on the desktop engine, where they run.
  • Not measured in a browser (gh#20946). An agent on the desktop engine has no way to check its world in a browser, and this release was prepared there, with no browser player in the world to measure. Whether the gallery holds 30 fps in a browser has not been confirmed. With a browser player in the world, require("~materialLibraryKit.Gallery").requestTour() measures their machine; the result arrives in require("~materialLibraryKit.Sync").heard().
  • The same gallery in a browser (gh#20822, reported by masonryMaterials; not checked here): the gallery can stay unbuilt for about 30 seconds after the world opens.
  • Two-player behaviour can't be tested inside one engine (gh#19114). Sharing is checked through the library's shared channel.
  • No asset.materialCollection.* namespace yet (gh#1889): fabrics are reached through Materials.*.
  • The engine's normal-map green convention is undocumented (gh#19414). These maps are green-up, and the tests prove it.

Design notes

How the package behaves by design; none of these is a defect, so none has an issue.

  • One repeat per primitive face. The engine's cube, sphere and cylinder carry UVs 0..1 per face, so a fabric shows at real size on them only when the object is its tileSize across. The gallery's floor tiles and walls, the drape and cushion meshes, and any mesh with UVs laid in metres ÷ tileSize show real size.
  • Fur lies along U, and anisotropy follows the UV tangent. Turn the mesh's UVs to turn the nap.
  • Draped meshes come in two sizes: a 1.6 m sheet and a 0.45 m cushion. Other sizes are baked with FabricDrape.
  • Toon fabrics have no diagnostic channels. toonFabric lights itself, so the capture tool's albedo, roughness and metallic passes draw it magenta. Its final and normal views are normal.

Version history

  • 1.0.0 (2026-10-25): the 25 fabrics above, their reference pictures, the drape and cushion meshes with FabricCloth, the toonFabric shader, FabricShowcase, this world's gallery scene with a draped sheet and three cushions, and the test suite. Depends on materialLibraryKit 1.3.1.
  • 1.0.1 (2026-10-25): documentation only. Every known limit now cites its issue: gh#20750 for the gallery's frame cost, gh#20946 for the browser check, and gh#7789 added for the .shared errors in a browser. The design notes have a section of their own, and the memory breakdown is corrected to 18 fabrics at 1.0 MB (the 23.9 MB total was right). This world's main scene README now describes the gallery. No fabric, texture, mesh, shader or code changed beyond version stamps and comments, so 1.0.1 draws exactly as 1.0.0 does.