Skip to content

feat(config): support Lua and Luau-backed project configs #8

@siriuslatte

Description

@siriuslatte

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestscope:configConfiguration loading, schema, and project file formats

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions