Skip to main content

bt.module.json (BT module definition)

bt.module.json gives a folder of BT code a module name and lists the other modules it uses. That is what makes include "my-game/ui"; find the right folder. Put it in the module's root folder.

A game usually doesn't need this file: the module section of game.json does the same job. Use bt.module.json for a shared library of BT code that isn't a game.

Example​

{
  "name": "example/game",
  "dependencies": {
    "example/widgets": "../widgets",
    "physics": "/opt/bt/physics"
  }
}

With this file in /src/game/:

  • include "example/game/ui"; loads the scripts in /src/game/ui/;
  • include "example/widgets/buttons"; loads /src/widgets/buttons/.

Fields​

FieldTypeDefaultDescription
namestring—Required. The module's name. Its root is the folder containing this file.
dependenciesobject{}Other modules, as name → folder. Relative folders are relative to this file; absolute paths are allowed.

Other keys are ignored.

Module names​

A name is one or more parts separated by /, for example cturtle, example/game or dont-pee-in-your-spaceship. Each part uses only letters, digits, ., _ and -, and can't be . or ...

The names of the BT standard library's packages (io, time, files, sync, string, math, buffer, json, regex, socket, process) are reserved. A module can't be named after one, or start with one followed by / (io/tools); see Packages.

How includes resolve​

  • An include names a package: a folder, written as module/sub/folder. include "my-game"; names the module's root folder.
  • A package is every .bt file directly in that folder (not subfolders). Files whose names start with . are skipped.
  • If several module names match, the longest one wins.
  • A standard library name (such as io) always means that standard package.
  • An include that matches no module is looked up among the engine's built-in packages (such as cturtle/events). If it isn't one, it's reported as missing.
  • You can't include a file path ("ui/menu.bt", "./ui", "../x" or an absolute path): include '…' names a file; include a package by its module path.
  • An include can't leave its module's folder with ..: include '…' escapes its BT module root.

How tools find the module​

For each script, the compiler, Studio and bt-lsp look in the script's folder and every parent folder for bt.module.json or a game.json with a module section. The nearest one wins. Module names defined further up are still available if the nearer one doesn't define them, so a game inside another module's folder can include that module's packages.

A script with no module definition above it can still compile, but it can only include the engine's built-in packages.

ctbt also accepts --module-file FILE to name the definition explicitly (ctbt).

Errors​

These fail with invalid or conflicting BT module definition (in game.json: has invalid settings):

  • the file isn't a JSON object, or name is missing or not a string;
  • a module name breaks the naming rules;
  • dependencies isn't an object, or a folder value is empty;
  • the same module name points to two different folders (conflicting roots for BT module '…').

A module named after a standard library package fails with BT module name '…' is reserved: "…" is a standard library package; choose another module name.

See also​