Reference

Configuration

Lithos configs can be written in YAML or JSON. This page covers file discovery, path resolution, outputs defaults, and schema tooling.

Looking for every supported key? Jump straight to the Configuration Reference.

Configuration file

Lithos uses a single config file in your project root.

./lithos.yml

All Lithos commands accept a PROJECT argument and resolve it in this order:

If PROJECT is omitted, the current directory is the project.
If PROJECT is a directory, Lithos searches it for one of: lithos.yml, lithos.yaml, lithos.json, then legacy mantle.yml, mantle.yaml.
If PROJECT is a file, Lithos uses it directly. Explicit paths can point to YAML or JSON.

When more than one discovered file exists, lithos.* always wins over the legacy Mantle names.

File path resolution

All paths and globs in your config resolve relative to the config file, not the shell working directory.

For the layout:

lithos.yml
game.rbxl
- game-icon.png
- thumbnail-1.png
- thumbnail-2.png

You would write:

project/lithos.yml

target:
  experience:
    configuration:
      icon: marketing/game-icon.png
      thumbnails:
        - marketing/thumbnail-1.png
        - marketing/thumbnail-2.png
    places:
      start:
        file: game.rbxl

The same rule applies to .env: Lithos loads the file next to the resolved config, plus any .env in the current working directory.

Outputs defaults

lithos outputs can read defaults from the project file with either the outputs block (camelCase) or the codegen alias (snake_case).

project/lithos.yml

outputs:
  writeDir: src/shared/generated
  outputName: lithosOutputs
  format: luau
  robloxTs: true

Supported properties

Property	Type	Description
`path`	string	Full output file path. Mutually exclusive with `writeDir` + `outputName`.
`writeDir`	string	Project-relative directory. Used with `outputName`.
`outputName`	string	File name. Extension is added from `format` if missing.
`format`	`json` \| `yaml` \| `yml` \| `lua` \| `luau`	Output format.
`robloxTs`	boolean	Write a `.d.ts` sidecar when the output is Luau.

CLI flags such as --output, --format, and --roblox-ts always override the values in outputs. When robloxTs is true and no format is set, Lithos defaults to .luau.

YAML and JSON

Lithos accepts YAML and JSON interchangeably. Auto-discovery prefers lithos.yml → lithos.yaml → lithos.json, then the legacy Mantle names. JSONC and YAML anchors-in-comments are not supported.

If you need a YAML refresher, see Learn YAML in Y Minutes (opens in a new tab) or the examples repo (opens in a new tab).

Editor schemas

The published JSON schema powers autocomplete and validation in VS Code, JetBrains IDEs, and anywhere else with YAML/JSON schema support.

In VS Code, install the YAML extension (opens in a new tab) for YAML files and add the snippet below to your settings:

VS Code YAML files

"yaml.schemas": {
  "https://siriuslatte.github.io/lithos/schemas/v0.3.0/schema.json": ["lithos.yml", "mantle.yml"]
}

VS Code JSON files

"json.schemas": [
  {
    "fileMatch": ["lithos.json"],
    "url": "https://siriuslatte.github.io/lithos/schemas/v0.3.0/schema.json"
  }
]

v0.3.0 v0.2.0

Next steps

CLI Commands Reference