8.4 KiB
Projects
A project describes the application the engine runs: its name and window title, the content packs it is built on, the permissions granted to it, and the scripts that drive it.
Content packs add content (blocks, items, generators, scripts, assets, etc.). A project controls the application at the top level: what is loaded by default, what the main menu looks like, which engine capabilities are available.
Project location
The project folder is selected at startup:
- The path passed via
--project <path>, if specified. - Otherwise
project/in the user files folder (user:project), if it exists. - Otherwise
project/in the resources folder (res/project/) - the default project shipped with the engine. - Otherwise the resources folder itself.
That is, a user can replace the default project without command line arguments by creating a project/ folder in the user files folder (the one set via --dir).
VoxelCore --project path/to/project_name
The selected folder is mounted as the project entry point and is read-only for scripts:
print(file.read("project:project.toml"))
Project structure
project_name/project.toml- project descriptionstart.lua- application script (optional)project_client.lua- client script (optional)content/- project content packs (optional)
Project configuration - project.toml
name = "project_name"
title = "Project Name"
base_packs = ["base"]
permissions = [
"network",
"record-audio",
]
| Field | Type | Description |
|---|---|---|
name |
string | Project identifier. Used in logs. |
title |
string | Shown in the window title as <title> - VoxelCore v<version>. Optional. |
base_packs |
list[string] | Packs that are always loaded and cannot be removed in the content menu. |
permissions |
list[string] | Engine capabilities available to the project. See Permissions. |
Base packs are loaded together with the core content on every content reset (e.g., in the main menu), so their resources (textures, layouts, scripts) are available outside of worlds as well.
The default project (res/project/project.toml):
name = "default"
base_packs = ["base"]
permissions = [
"network",
"record-audio",
"sub-instances",
]
Permissions
Capabilities not listed in permissions are disabled for the project.
| Permission | Grants access to |
|---|---|
network |
The network subsystem and the network library. Without it, the library functions throw an error. |
record-audio |
Audio input devices (microphone). |
write-to-user |
Writing to the user entry point via the file library. By default only world, config and export are writable. |
sub-instances |
app.start_background_instance - starting background (headless) engine instances. |
debugging |
app.start_debug_instance - starting engine instances with a debug server. |
Note
The
--dbg-servercommand line argument works even without thenetworkpermission.
start.lua
start.lua is the project's controlling script. It is started after engine initialization as a coroutine
running in parallel with the main loop, and has access to the app library.
-- wait for the main menu to be ready
app.tick()
app.config_packs({"base", "my_pack"})
app.load_content()
app.new_world("demo", "42", "core:default")
Rules:
- The script runs in its own coroutine.
app.tick(),app.sleep(...)andapp.sleep_until(...)yield control to the engine for one or more frames. - Content reload functions (
app.load_content,app.reset_content,app.reconfig_packs,app.config_packs) must be called from this coroutine. - The script has its own global environment: all global functions and tables are available, as well as the
applibrary. - If the engine is started with
--script <file>or--test <file>, that script replacesstart.lua: only one application script runs at a time. - In headless mode (
--headless) only the script passed via--script/--testruns. Without it the engine has nothing to do and exits immediately. - In test mode (
--test) the engine stops when the script finishes. Otherwise the engine keeps running afterstart.luafinishes.
project_client.lua
project_client.lua is loaded once at startup and only in client mode (it is not loaded with --headless).
It controls the client-side presentation of the project - primarily screens.
The script has its own environment with access to global functions, libraries and app. The engine calls the following functions if they are defined:
-- Called after the screen is opened.
function on_<screen>_setup() end
-- Called before the screen is closed (when switching to another one).
function on_<screen>_clear() end
Screen names:
| Screen | Description |
|---|---|
menu |
Main menu screen. |
level |
In-world screen (world open). |
When switching screens, on_<old>_clear is called first, then the new screen is opened, then on_<new>_setup is called. Errors in these functions are logged and do not stop the engine.
The engine resets the menu when the menu screen is opened; opening a page is the project's job. The default project's client script sets the menu background and opens the main page (simplified):
function on_menu_setup()
setup_background()
menu.page = "main"
menu.visible = true
end
function on_menu_clear()
if menubg then
menubg:destruct()
menubg = nil
end
end
Note
A project does not have to use the standard
menu.
Pages are looked up as layouts/pages/<name>.xml in the core and loaded packs, so a project can ship its own main menu page in one of its base packs:
-- opens layouts/pages/title.xml from a base pack
function on_menu_setup()
menu.page = "title"
menu.visible = true
end
project:content
The project's content/ folder is a content source. Packs placed in it are available to the project the same way as packs in res/content/:
my_project/content/pack_name/package.json
Content sources in descending order of priority:
world:contentuser:contentproject:contentres:content
Project arguments
Arguments after a standalone -- are passed to the project rather than the engine:
VoxelCore --project my_project -- --mode server --port 6000 --verbose
Each argument must have the form --name, optionally followed by a value. An argument without a value gets an empty string.
Project arguments are available to all scripts:
vc.get_project_arg(name: str) -> str | nil
local port = tonumber(vc.get_project_arg("port") or "6000")
local verbose = vc.get_project_arg("verbose") ~= nil
Child instances
Engine instances started from scripts use projects too:
app.start_background_instance(script, output_file, project_args)starts a headless instance with the current project and passesproject_argsas project arguments. Requires thesub-instancespermission.app.start_debug_instance(port, project_path, output_file)starts an instance with a debug server. Ifproject_pathis specified, the instance runs that project; otherwise the project is selected the usual way. Requires thedebuggingpermission.
Child instances use the same resources and user files folders as the parent. Nesting depth is limited to two levels.
See the app library.