# Voussoir — buyer quickstart

Voussoir is a **source-included Roblox Model/API, not a toolbar plugin**. It generates an arch as a Folder of ordinary, editable rectangular Parts. You supply the opening dimensions; Ring and Arc calculate the layout.

The central keystone is an **odd-count visual convention** used by this generator. It is not proof that real arches require an odd stone count, and no load-bearing or structural behavior is calculated. The current buyer states this in its source comments and refusal text.

## 1. Insert and identify the product

Insert the purchased Voussoir Model into Workspace. In Explorer, its contents should be:

    Workspace
      Voussoir (Model)
        Ring (ModuleScript)
          Arc (ModuleScript)
        Raise (Script)

Keep Arc inside Ring: Ring requires `script.Arc`. The separate test package is not part of the buyer workflow. Save a local copy of your place before making changes.

## 2. Preview with Raise — temporary

1. While Studio is in **Edit mode**, open `Workspace.Voussoir.Raise`.
2. Change values in its `SETTINGS` table, such as `span`, `rise`, `ring` and `maxStone`.
3. Press Play. Raise builds a sample at the world origin; the generated Folder is named `Arch` in Workspace by default. Read Output if it refuses the settings.
4. Press Stop. **The generated Play-session arch disappears.** This is a preview, not saved geometry.

Edits made to Raise in Edit mode can be saved, but running Raise in Play does not bake its output into the saved place. For a static build, disable the Raise Script in Properties after previewing so it will not generate another sample every time the game runs. Ring and Arc remain usable.

## 3. Generate geometry that can be saved

Stop any running test first. Use the **Studio Multi-line Command Bar in Edit mode**, not a game Script and not the Play-session Command Bar. This workflow targets the multi-line bar with its Run button; do not assume that the older single-line bar has the same history behavior.

The following synchronous example creates `Workspace.MyVoussoirArch`. It requires the installed module and refuses to overwrite an existing output of that name. Roblox documents that the Multi-line Command Bar records its commands for Undo/Redo, so this example does **not** begin or finish a nested recording. Voussoir itself has no built-in Undo button or recording logic. Validate the actual Undo/Redo result below before relying on that history or saving over existing work.

```lua
do
    local RunService = game:GetService("RunService")
    assert(not RunService:IsRunning(), "Stop the test; run this in Edit mode")

    local voussoir = workspace:FindFirstChild("Voussoir")
    assert(voussoir and voussoir:IsA("Model"), "Insert Voussoir into Workspace first")
    local ringModule = voussoir:FindFirstChild("Ring")
    assert(ringModule and ringModule:IsA("ModuleScript"), "Voussoir.Ring is missing")
    local Ring = require(ringModule)

    local outputName = "MyVoussoirArch"
    assert(not workspace:FindFirstChild(outputName),
        "That output name already exists; choose a new name or Undo your previous build")

    local ok, arch, reason = pcall(function()
        return Ring.build({
            span = 40, rise = 20, ring = 4, width = 6,
            maxStone = 6, keystoneProud = 0.5, abutment = 6,
            name = outputName, parent = workspace,
            cframe = CFrame.new(0, 12, 0),
        })
    end)

    if not ok or not arch then
        error(ok and tostring(reason) or tostring(arch), 0)
    end

    print("Voussoir created", arch:GetFullName(),
        arch:GetAttribute("stones"), "stones;", arch:GetAttribute("parts"), "Parts")
end
```

The example puts the springing line 12 studs above the origin; `rise` is measured above that line. The Parts are anchored by default. `Ring.build()` returns the new Folder, or `nil, reason` when refused.

Run the whole block once and let it finish; do not wrap it in a background task, persistent event connection or never-ending loop. Do not call `FinishRecording`, `ResetWaypoints`, `SetEnabled` or `SetWaypoint` to take over or repair the Command Bar's recording. If any step errors, inspect the place before saving over your known-good copy; do not assume an error rolled everything back.

If you integrate Ring into your **own plugin**, that plugin must manage its own `TryBeginRecording`/`FinishRecording` lifecycle and handle a refused recording before changing the place. That is a separate context from this Command Bar example, not a feature supplied by the Voussoir Model.

## 4. Fit an existing opening instead

Create or identify a BasePart named `Doorway` directly in Workspace to represent the opening. Its **local X size** supplies the span, **local Z size** supplies the arch's front-to-back width, and its **top local-Y face** supplies the springing line. The arch inherits the Part's rotation.

In the preceding example, replace only the `return Ring.build({...})` call inside the `pcall` with:

```lua
return Ring.over(workspace:FindFirstChild("Doorway"), {
    rise = 10, ring = 3, maxStone = 6, abutment = 6,
    name = outputName, parent = workspace,
})
```

Keep the module lookup, output-name check and error handling. Run the complete synchronous block in the same Multi-line Command Bar context. Use dimensions appropriate to your opening. Omitting `rise` requests a semicircle by default.

Do not supply `span`, `width` or `cframe` to `Ring.over()`: it derives them from the Part and refuses overrides. It does not delete the placeholder, cut a hole in a wall, or synchronize the arch when the opening later changes. Each successful call builds a new Folder; it is not an update-in-place API.

## 5. Check Undo, then save and reopen

1. Still in Edit mode, select `Workspace.MyVoussoirArch`. Check its Parts, crown keystone, two seats and the Folder attributes.
2. Before making another edit or executing another command, move focus out of the Command Bar and use the Studio scene Undo action from its menu or toolbar. This build's Folder should disappear while the Voussoir generator remains. Use scene Redo and check that it returns; do not run another command between Undo and Redo. This is a required verification of Studio's command history, not a claim that Voussoir implements Undo. If history does not behave as expected, stop and keep your original saved copy; do not assume that saving repairs history.
3. Leave the generated Folder present in Edit mode. Keep Raise disabled if you want only the static geometry.
4. Save the **whole place** to a new local `.rbxl` or `.rbxlx` file, with a name and location you can identify. Saving only the generator Model will not include a separate output Folder in Workspace.
5. Close that place and reopen the same saved file. **Do not press Play yet.** Confirm `Workspace.MyVoussoirArch`, its child Parts, transforms and stone/part attributes are already present. That is the persistence check; seeing a newly generated arch after pressing Play is not equivalent.
6. Keep the earlier copy until the reopened result is correct. Place-file persistence is separate from publishing your experience or updating the Creator Store asset.

## Settings and limits

- `span` is the springing-to-springing opening; `rise` is the crown height above it. Rise below half the span gives a segmental arch, half gives a semicircle, and above half gives a horseshoe. Pointed/Gothic arches are not supported.
- `ring` is radial stonework thickness; `width` is front-to-back depth. `maxStone` is the automatic stone-width cap. Automatic mode chooses the smallest valid odd count under that cap. An explicit `stones` count must also satisfy validation.
- `keystoneProud` controls the crown's extra projection. `abutment = 0` omits the two seats. `stoneVariation = 0` removes per-index tint variation; the keystone and seats still have their distinct base colors.
- Hard ceilings are **201 stones / 203 Parts**. Requested geometry must also fit the product's 0.05–2048-stud Part-size and conservative 100,000-stud coordinate bounds. These are guardrails, not performance guarantees. Do not attempt to bypass a refusal with `maxStones` or by mutating the frozen module/default tables.
- Rectangular blocks intentionally overlap inward. They are not tapered wedge meshes. Generated geometry is not a masonry, structural-engineering or physics simulation; unanchoring it does not make it a tested load-bearing arch.
- Both public build routes validate inputs and return a reason for a refused build. Read that reason before changing parameters. The generator has no toolbar, live-opening tracking, networking or telemetry.

## If something seems wrong

- **The arch vanished after Stop:** use the Edit-mode generation and save/reopen workflow above.
- **The arch appears twice during Play:** Raise is still running in addition to geometry you already saved; disable the sample Script for a static scene.
- **Ring cannot be required:** check the Model name, the Ring ModuleScript, and Arc nested inside Ring.
- **An opening is not followed after moving it:** call `over()` again deliberately; it does not track the Part.
- **A second call is refused by the example's name guard:** choose another output name or Undo the previous build. Do not overwrite an unrelated object.

For support, include the exact refusal text, settings, which route you used (`build` or `over`), and whether Studio was in Edit or Play mode. Never send passwords or session credentials.

## History behavior reference

Roblox's [Studio plugin documentation](https://create.roblox.com/docs/studio/plugins#support-undo-and-redo) explains recording ownership. Voussoir has no built-in Undo. Test the complete workflow in a saved copy of your own project before relying on it.