bt-lsp

bt-lsp is the BT language server: the program behind error highlighting, completion, hover documentation, go-to-definition, rename and formatting for BT code. Studio, the VS Code extension and the JetBrains plugin start it for you (see Editor integrations). You run it yourself to check scripts in CI, or to connect an editor that supports the Language Server Protocol (LSP), such as Neovim, Helix, Emacs or Sublime Text.

Check scripts in CI

bt-lsp --check scripts/main.bt

This checks the program that starts at that file, including everything it includes, prints each problem as FILE:LINE:COLUMN: MESSAGE, and exits:

Status	Meaning
0	No errors (warnings may be printed).
1	One or more errors.
2	The file could not be read.

Run it from your project folder so it finds your game.json.

Connect another editor

Configure your editor to start bt-lsp for .bt files, talking over standard input and output:

bt-lsp --stdlib-root /path/to/cturtle/stdlib

Use the stdlib folder that ships with the VS Code extension or JetBrains plugin, or the root folder of an engine source checkout that has been built at least once.

Options

Option	Default	Description
--check FILE		Check one program and exit (see above).
--stdlib-root DIR	none	Folder with the engine's BT libraries. Lets the server resolve include "cturtle/..." and find the engine's API declarations.
--manifest FILE	The nearest game.json above each open file	Game manifest that defines your include roots and source files.
--virtual-document-root DIR	none	For editors that can only open real files: writes the engine's API declarations as files under DIR, so go-to-definition on an engine function opens a file.
--trace	off	Log every request to standard error, for troubleshooting.
--help		Print usage.

Engine and game APIs

The server knows the BT standard library and every BT file in your project. Engine functions written in C (rendering, physics, input and so on) are known from a declarations file that ships with the editor extensions and with Studio.

If your game has its own native (C) packages, their declarations are written to .ctbuild/bt-catalog/ in your project when you press Play in Studio or build with ctgame in a compiled code mode. Until then the editor reports those functions as unknown. To write the declarations without Studio, run the game compiler that ships with ctgame:

ct-game-compile --catalog-module build/my_game_module.so --dump-catalog .ctbuild/bt-catalog

The server picks up the new declarations automatically. Deleting .ctbuild/bt-catalog/ is safe.

Errors

Problem	What to do
bt-lsp: cannot analyze FILE	The --check file is missing or unreadable.
Every cturtle/... include is unresolved	Pass --stdlib-root, or open the folder that contains your game.json.
Engine functions are unknown	The declarations file is missing: use the stdlib folder from an editor package or Studio, or pass --stdlib-root from a built engine checkout.
Your game's native functions are unknown	Write the game's declarations as shown above.
bt-lsp: could not materialize declaration module NAME	The --virtual-document-root folder is not writable.