Downloading this VSIX file.
Use "Install from VSIX…" menu item in VS Code to install it:
Once done, you will see "Pascal Language Server" extension installed. Make sure it is enabled.
Visual Studio Code is a powerful, free and open-source, cross-platform text editor for programmers.
Below we describe how to configure it to be a perfect code editor for Pascal, and in particular for your Castle Game Engine projects. We’re proud to provide an LSP server that will make VS Code do intelligent code completion that works great with Pascal and automatically completes all Castle Game Engine API.
|The configuration described here also works with VSCodium, a version of VS Code built using 100% open-source code (without e.g. Microsoft telemetry).|
Go to Castle Game Engine editor preferences, "Code Editor" tab, and select the "Visual Studio Code".
This will make CGE automatically open VS Code when you open Pascal file
by double-clicking Pascal unit from CGE editor "Files" panel,
by double-clicking a message in the "Output" window referencing some Pascal file,
using menu item "Code → Open Project in Code Editor",
and in all other cases when CGE wants to open Pascal file.
There are multiple VS Code extensions that provide Pascal code highlighting.
We recommend Pascal Language Basics. It’s available in the VS Code marketplace, so you can just search for it and install right inside the VS Code "Extensions" panel.
Searching extensions' marketplace for "Pascal" will yield a number of solid alternatives. They will likely work just as well for your Pascal and CGE editing, go ahead and try them. We just recommend choosing any "simple" extension that adds Pascal highlighting but doesn’t do code completion and parsing (because the LSP server will already take care of it).
For VS Codium users, the Pascal magic extension may be the easiest to install, as is available in the VS Codium (and VS Code too) extensions' marketplace.
We provide an LSP server that implements an intelligent code completion for Pascal and is aware of Castle Game Engine units and default syntax options (e.g. FPC ObjFpc mode).
|Our LSP server is based on Philip Zander's LSP server which in turn relies on Lazarus CodeTools to do the code completion. So inside there is really a lot of work and testing from many people in the Pascal ecosystem to make it powerful.|
To use it with VS Code:
Install the Pascal Language Server Extension for Visual Studio Code. It’s easiest to do this by:
Configure the extension, pointing it to your FPC, Lazarus, and
pasls (our LSP server).
Open the extension settings.
Env: FPCDIR to point to the FPC source code. If you use FPC bundled with CGE, this should look like
Env: FPCTARGET to your OS, like
Env: FPCTARGETCPU to your CPU, like
Env: LAZARUSDIR to your Lazarus (source) directory. This is optional, fill it if you have Lazarus installed. It will enable to find LCL units and do the code completion for LCL components too.
Env: PP to your FPC executable. If you use FPC bundled with CGE, this should look like
.exe extension on Windows. If you use regular FPC, this is a path to your regular FPC executable (
Executable to point to our LSP server, inside CGE
bin subdirectory. This should look like
.exe extension on Windows.
Open any Castle Game Engine project.
You can open it from Castle Game Engine editor (e.g. by "Code → Open Project in Code Editor" menu item).
Or you can open it from VS Code, using "File → Open Folder".
Place your cursor somewhere, hit Ctrl + Space and enjoy a proper code completion.
Right click on any Pascal item and use "Go To Definition", "Go To Declaration" or just Ctrl + click on it to move around. You can also peek at definition and declaration using "Peek → …".
|There are more VS Code extension settings, but most of them are not handled (and not necessary) for our LSP server, they are only handled by the alternative Ryan Joseph's Pascal LSP server.|
If you have installed FPC yourself using fpcupdeluxe on Unix, remember to point
In general, the
It is easiest to just run from Castle Game Engine editor using F9 ("Run → Compile And Run").
If you really want to run and debug from VS Code:
CGE applications compiled in debug mode contain debug symbols compatible with GDB. Any debugger extension in VS Code based on GDB should work.
To build and run CGE applications without leaving VS Code, you can utilize our command-line build tool.
CASTLE_ENGINE_PATH environment variable to point to your CGE directory.
PATH environment variable to contain the
bin subdirectory of your CGE directory.
Make sure that FPC is also on
PATH, so that our build tool can find it.
Configure the VS Code tasks to build using
castle-engine compile --mode=debug and run using
castle-engine run. Remember to restart all applications (like VS Code) that need to be aware of new environment variables' values.
The LSP server we use is based on Philip Zander's Pascal LSP server.
Our fork of the LSP server is here: LSP server for Pascal and Castle Game Engine.
VS Code extension is developed by Ryan Joseph.
Both LSP servers are based on initial work of Arjan Adriaanse. They both use latest Lazarus CodeTools to do the actual code completion, so we can enjoy in every editor the same power as Lazarus users.
The LSP server is fully useful with any text editor that supports LSP, not only VS Code.
You can use it with Emacs. See Michalis Kamburelis notes about LSP + Pascal + CGE + Emacs.
The short version is:
company Emacs packages,
Configure it like this in your
(require 'lsp-pascal) ;; choose LSP server binary (setq lsp-pascal-command "/home/michalis/sources/castle-engine/castle-engine/bin/pasls") ;; pass basic info to LSP server, all LSP Pascal servers above support these: (setq lsp-pascal-fpcdir "/home/michalis/cge/tools/contrib/fpc/src") (setq lsp-pascal-lazarusdir "/home/michalis/lazarus") (setq lsp-pascal-pp "/home/michalis/cge/tools/contrib/fpc/bin/fpc-cge") (setq lsp-pascal-fpctarget "linux") (setq lsp-pascal-fpctargetcpu "x86_64")
The big plan is to bundle CGE with VS Code at some point in 2023. If you just install (unpack) CGE you should have a ready setup with CGE + VS Code, and VS Code should automatically have Pascal syntax highlighting and code completion.
Of course we will still make everything such that you don’t have to use this "bundled" VS Code and instead can use your existing VS Code installation, or really any other text editor / IDE, like Lazarus, Emacs, NeoVim etc.
The LSP server should require less (or even zero) configuration. All the parameters required now by LSP configuration are things that CGE editor knows, after all.
Can we have "Code Completion" (that happens in Lazarus when you Ctrl + Shift + C) that can automatically insert e.g. method declarations or complete property declarations?
Have a recommended and perfectly working approach to running and debugging. If you open a directory with CGE project (
CastleEngineManifest.xml) then running and debugging it in VS Code should be just a keystroke (like F9) away. We should use CGE build tool with all parameters that CGE editor already knows.
There is DAP (Debug Adapter Protocol) with similar goals as LSP, but for debuggers. Maybe someone will wrap Lazarus debugger (GDB with Pascal specific interpretations) in DAP?
To improve this documentation just edit the source of this page in AsciiDoctor (simple wiki-like syntax) and create a pull request to Castle Game Engine WWW (cge-www) repository.