# Project parameters

Every project has one parameter table: sizes that several of its documents must agree on (a spindle's center height, rail spacing, a bolt circle, a sheet thickness) are set there once, and parts and assemblies read them as `project.<name>`. When the table changes, every document that reads it follows, without a new revision of its own.

Read [Working with plans](working.md) first.

## When to use it

- Put a size in the table when two documents must agree on it; never repeat a number another document owns. A size only one part uses stays a parameter of that part.
- A bought part's length in one assembly is not a project parameter: set it on the component (see [Assemblies](assemblies.md), component parameters).

## The table

`list_projects` and `create_project` give each project's `parametersId`: the table is a document like any other. On it, `inspect_document` lists the parameters with their values, kinds, groups and `usedBy` (the documents that read each, also through other parameters of the table, `through`, and assemblies and drawings by the documents they use, `via`), and `preview_plan` changes it:

```json plan:project-table
{
  "summary": "Machine sizes the headstock, tool post and bed share",
  "steps": [
    {
      "label": "Machine",
      "commands": [
        {
          "type": "parameter.create",
          "name": "railHeight",
          "expression": "15 mm",
          "group": "Machine"
        },
        {
          "type": "parameter.create",
          "name": "centerHeight",
          "expression": "80 mm",
          "group": "Machine"
        },
        {
          "type": "parameter.create",
          "name": "axisZ",
          "expression": "railHeight + centerHeight",
          "group": "Machine",
          "comment": "The spindle's axis above the bed"
        }
      ]
    }
  ]
}
```

- Expressions in the table use the table's own names and units, never `project.` and never a document's parameters.
- `parameter.update` changes an expression, comment, group or aliases by id; `parameter.delete` is refused while another parameter or a document reads the name; `parameter.move` orders them.
- Renaming a name documents read is refused for now: add a parameter with the new name, move the documents to it, then delete the old one.

## Reading it

In a part or an assembly, any expression can read the table: `{"type":"parameter.create","name":"axisH","expression":"project.axisZ - 10 mm"}`, a feature value `"project.wall * 2"`, a joint offset, a configuration cell, `{project.partNumber}` in sketch text. `inspect_document` on a part lists the table's names under `project`, with the values and whether this document uses each; a parameter that reads the project says so (`readsProject`).

## Changing it

A change of the table reaches every document that reads a changed name. `preview_plan` on the table rebuilds them with the new values before anything is saved and lists them in `affected`: each document with `ok`, the failing feature or joint and its message, and an assembly's degrees of freedom. The plan applies at once when they all rebuild (unless the user approves changes); when one fails it waits for **Apply**, and the user decides. Tell the user which documents the change reached or would break.

A library version keeps the values it was published with; changing the table does not change parts inserted from the library.