Terminology

Bundle

A bundle is a directory that contains a bundle.json manifest and any Lua, JSON, assets, or runtime-specific files referenced by that manifest. Selene treats the manifest name as the bundle identifier.

On the server, the bundle directory is discovered at bundles_path/<bundle-name>.

On the client, the bundle directory is discovered from a --bundle <name> <path> mapping.

Manifest

bundle.json defines the bundle metadata. Selene currently recognizes:

• name: required bundle identifier
• description: optional human-readable label, defaulting to name
• entrypoints: ordered list of Lua files the runtime may execute
• dependencies: bundle names that must resolve before this bundle loads
• preloads: Lua module names mapped to files that should be pre-registered in package.preload

Dependency

A dependency is another bundle listed in dependencies. Selene resolves declared dependencies before enabling the bundle. Missing dependencies stop the load instead of partially enabling the bundle.

Dependencies are also loaded before the bundles that depend on them.

Entrypoint

An entrypoint is a Lua file path listed in entrypoints. Selene does not infer entrypoints from directory names alone. If a file should run automatically, it must be present in the manifest.

Each runtime filters entrypoints by prefix:

• Server runtime: common/, server/, and top-level init.lua
• Client runtime: common/, client/, and top-level init.lua

If an entrypoint does not match the active runtime filters, Selene skips it.

Preload

A preload is a Lua module registration defined in preloads. The manifest accepts either:

• A string file path
• An object with file and optional encoding

At load time, Selene registers the module name in the Lua package system before bundle execution. This is separate from entrypoints: preloads make a module importable, while entrypoints execute code directly.

Active bundle

An active bundle is one that the current runtime has loaded and enabled. Lua module resolution only serves modules from bundles that are currently active.

That distinction matters during reloads: files can exist on disk without being available to Lua until the runtime has enabled the bundle.