Skip to main content
Glama

align_faces

Realigns texture on selected VMF faces to world, face, fit, or arc modes, recomputing offsets from a face corner to avoid stale-offset misplacement.

Instructions

Realigns the texture on selected faces: to the world axes, to the face's own plane, or stretched to fit the face. Hammer's three alignment modes. 'world' derives the axes from the face's dominant normal using vbsp's own base-axis table, which is what a face gets at creation; 'face' projects them into the face's plane so the texture runs along a slope instead of being squashed onto it; 'fit' spans the face exactly. The offsets are always recomputed from a corner of the face rather than carried over -- an axis pair with a stale offset puts the texture somewhere else entirely, which is the most common way an alignment tool produces a map that compiles and looks wrong.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "path": "<path>",
      "mode": "<mode>"
    },
    "name": "align_faces"
  }
}

Input Schema

NameRequiredDescriptionDefault
allNoEvery face of the map. Required when no other criterion is given.
modeYes'arc' is 'face' plus continuity: facets that touch without turning a corner are one run, and each carries its texture on from where the last one stopped. It is what a curve needs and what neither of the others gives -- a ring aligned to 'face' restarts the brick at every seam, which reads as flat plates however well the smoothing groups are set.
pathYesPath to the .vmf, absolute or relative to the repo root.
scaleNoMultiply both texture scales by this afterwards. Zero is refused.
shiftNoAdd to the u and v offsets, in texels.
backupNoCopy the file to <file>.bak before writing. Nothing is copied on a no-op.
dryRunNoCheck and report without writing. Every verification runs either way.
facingNoOnly faces pointing this way. 'up' is a floor, 'down' a ceiling, 'side' a wall; the cut is at 45 degrees, so a ramp counts as what it is closer to being.
repeatNoFor 'fit': how many times the texture repeats across the face. Default once.
rotateNoTurn the axis pair in the face's plane, degrees.
confirmNoRequired (true) to run this tool: it writes or executes.
minAreaNoOnly faces at least this large, in square units.
materialNoOnly faces already carrying this. Substring, case-insensitive.
solidIdsNoOnly faces of these solids.

Output Schema

NameRequiredDescriptionDefault
pathYes
changedYes
matchedYes
writtenYes
nextStepYes
warningsYes
unchangedYes
backupPathYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.0.24-alpha

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With only a title in annotations, the description carries the full disclosure burden, and it does surface a real behavioral trait: offsets are always recomputed from a face corner rather than carried over, with the consequence of stale offsets spelled out. However, for a tool that mutates map files it never states that it writes to disk, that confirm is required, or that a backup is made and dryRun verifies — all left to the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core operation and mode semantics are front-loaded and every clause is doing work until the final rhetorical flourish about maps that "compile and look wrong," which adds flavor rather than information. One dense paragraph rather than a scan-friendly structure, but no filler sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-parameter mutation tool with an output schema and no destructive-safety annotations, the description conveys the conceptual model an agent needs to choose a mode correctly, and the output schema covers returns. The remaining gap is that the write path (confirm, backup, dryRun) and the selection filters are only documented in the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema does not: it explains how 'world' derives axes from the dominant normal via vbsp's base-axis table, what 'face' projection does to slopes, and that 'fit' spans the face exactly, while the schema's mode description only covers 'arc'. It also clarifies that offsets are not preserved, which affects how shift and rotate interact.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Realigns the texture on selected faces" gives a specific verb and resource, and the sentence that follows immediately partitions the operation into its distinct modes. An agent knows exactly what domain of change this tool performs without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description thoroughly explains when to pick each alignment mode and why 'face' avoids the squashing that 'world' produces on slopes, which is genuine usage guidance within the tool. It never says when to reach for this tool rather than a sibling like edit_vmf or paint_displacement, and it omits any mention of the face-selection filters or the confirm/write guard, so tool-level selection remains implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.