What to build
Add support for Lua and Luau-backed project configs so Lithos can load lithos.luau and lithos.lua in addition to the existing YAML and JSON formats.
Lithos now supports static lithos.yml and lithos.json files, which is a strong baseline, but both formats are still declarative data only. A Lua/Luau config format would open up a much more flexible workflow for larger Roblox projects: sharing helper functions, composing common fragments, generating repetitive resource definitions, branching on environment variables, and building the final desired state without introducing a separate prebuild step.
This should be a real Luau execution path, not a restricted table-only decoder. Users should be able to write normal Luau code, define their own helper functions, and expose hook-style functions that Lithos can execute as part of config evaluation or related config lifecycle steps. Since Lithos is a Roblox tool, the runtime should use an external Luau-capable tool rather than trying to approximate Luau internally; Lune is the most obvious candidate here.
The important part here is not just accepting another file extension. Lua/Luau configs should participate in the same project-loading flow as YAML and JSON today: discovery from a project directory, explicit PROJECT path support, validation against the same Config shape, and clear failure modes when evaluation or decoding fails.
Acceptance criteria
- Lithos can load explicit
.luau and .lua config file paths and decode their resulting data into the same config structure used by YAML and JSON.
- Directory-based project discovery has a documented precedence rule for YAML, JSON,
.luau, .lua, and legacy Mantle config files.
- Lua/Luau config evaluation runs through an external Luau runtime, ideally Lune or an equivalent Roblox-oriented runtime, instead of a custom partial interpreter.
- The execution model behaves like normal Luau: users can define helper functions and hook-style functions, and Lithos documents when and how those hooks are invoked.
- Lua/Luau config validation uses the same schema and field rules as the existing config formats, including useful errors for missing or invalid fields.
- Runtime errors from config or hook execution surface clearly, with the config path and enough context to debug the failure.
- The execution model is documented: available runtime features, expected environment-variable access, determinism expectations, and any side-effect boundaries Lithos imposes.
- Docs include at least one example showing how a Lua/Luau config can reduce repetition compared with static YAML/JSON, plus one example of user-defined hooks or helper-driven generation.
- Tests cover discovery, successful load, invalid returned shapes, runtime-evaluation failures, and hook execution behavior.
Out of scope
- Running config code inside Roblox Studio or inside the game runtime.
- A plugin marketplace or remote code-loading model for config execution.
- Solving every advanced metaprogramming use case in the first pass.
- Replacing YAML or JSON as the default config formats.
What to build
Add support for Lua and Luau-backed project configs so Lithos can load
lithos.luauandlithos.luain addition to the existing YAML and JSON formats.Lithos now supports static
lithos.ymlandlithos.jsonfiles, which is a strong baseline, but both formats are still declarative data only. A Lua/Luau config format would open up a much more flexible workflow for larger Roblox projects: sharing helper functions, composing common fragments, generating repetitive resource definitions, branching on environment variables, and building the final desired state without introducing a separate prebuild step.This should be a real Luau execution path, not a restricted table-only decoder. Users should be able to write normal Luau code, define their own helper functions, and expose hook-style functions that Lithos can execute as part of config evaluation or related config lifecycle steps. Since Lithos is a Roblox tool, the runtime should use an external Luau-capable tool rather than trying to approximate Luau internally; Lune is the most obvious candidate here.
The important part here is not just accepting another file extension. Lua/Luau configs should participate in the same project-loading flow as YAML and JSON today: discovery from a project directory, explicit
PROJECTpath support, validation against the sameConfigshape, and clear failure modes when evaluation or decoding fails.Acceptance criteria
.luauand.luaconfig file paths and decode their resulting data into the same config structure used by YAML and JSON..luau,.lua, and legacy Mantle config files.Out of scope