Home » Documentation » Manual » Pascal IDEs
Previous: Delphi for Linux
Next: Miscellaneous
Manual

Visual Studio Code

1. Introduction

Visual Studio Code is a powerful, free and open-source, cross-platform text editor for programmers.

We provide a VS Code extension for Castle Game Engine that makes it easy to use VS Code with CGE:

  • Allows to build, run, debug (and more) CGE projects from VS Code.

  • Provides Pascal syntax highlighting and code completion.

Moreover, installing CGE will give you our LSP server useful with VS Code or various other text editors (like Emacs or Vim) to make intelligent code completion that works great with Pascal and automatically completes all Castle Game Engine API.

Visual Studio Code completing CGE code Visual Studio Code - symbols in workspace Visual Studio Code - symbols in file

2. Video Overview

3. Make Castle Game Engine invoke VS Code

Go to Castle Game Engine editor preferences, "Code Editor" tab, and select the "Visual Studio Code".

Configure VS Code in CGE Preferences

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.

4. Install Castle Game Engine extension in VS Code

Install Castle Game Engine in VS Code.

You can follow the above link. Or just search for "Castle Game Engine" in the VS Code extensions sidebar.

5. Extension Settings and Pascal code completion

After installing Castle Game Engine in VS Code extension, go to the extension settings and configure it:

VS Code Extension configuration

Details about the extension settings:

Engine Path

Set this to Castle Game Engine directory. This is the only thing you really need to configure. If you installed the engine from our official downloads, then everything else will be auto-detected correctly.

Inside this directory we expect to find bin subdirectory with our tools, like pasls (pasls.exe on Windows), build tool and editor.

PP

FPC executable. Add .exe extension on Windows. If you use regular FPC, this is a path to your regular FPC executable (fpc, fpc.exe, fpc.sh).

If you use FPC bundled with CGE, the correct path looks like <cge-path>/tools/contrib/fpc/bin/fpc-cge. But actually, you can also leave it blank in this case — we will autodetect it.

If you have installed FPC yourself using fpcupdeluxe on Unix, remember to point PP to the fpc.sh script (and not to the fpc binary) that should always be used to execute FPC managed by fpcupdeluxe on Unix.

In general, the PP executable may be run by CodeTools, which may assume this FPC version "knows" standard RTL paths. That’s why it’s important to pass fpc.sh (in case of fpcupdeluxe) or fpc-cge (in case of FPC bundled with CGE) and not the "bare" fpc executable.

FPCDIR

FPC source code.

If you use FPC bundled with CGE, this should look like <cge-path>/tools/contrib/fpc/src/. But actually, you can also leave it blank in this case — we will autodetect it.

LAZARUSDIR

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.

FPCTARGET

Your OS, like linux or win64.

Use operating system names that match FPC and CGE. You can see valid OS names:

  • In CGE editor menu "Run → Platform (To Compile And Run) → …​".

  • If you execute on the command-line build tool as castle-engine --help. Look for possible arguments for the --os option.

You can also leave it empty, our LSP will autodetect it.

FPCTARGETCPU

Your CPU, like x86_64.

Use processor names that match FPC and CGE. You can see valid CPU names:

  • In CGE editor menu "Run → Platform (To Compile And Run) → …​".

  • If you execute on the command-line build tool as castle-engine --help. Look for possible arguments for the --cpu option.

You can also leave it empty, our LSP will autodetect it.

Note
 Our LSP server is based on Philip Zander’s LSP server which in turn uses 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.

5.1. Test Code Completion

  • 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.

    VS Code Extension configuration

  • 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 → …​".

6. Compiling and Running

Simply open in VS Code a directory with CastleEngineManifest.xml. Our extension will automatically detect it is a CGE project, and will show appropriate buttons on the status bar to compile, run and debug the project.

6.1. Alternative ways to compile and run (for other text editors or custom needs)

Using our VS Code extension commands is just one way to build and run CGE application. Some alternatives:

  • Use editor, menu item "Run → Compile And Run" (F9).

  • Use Lazarus IDE or Delphi IDE. You can open CGE project in them.

  • Use command-line build tool. Like this: castle-engine compile && castle-engine run.

    This approach is also how you can build and run CGE projects from any text editor.

    You can also define VS Code tasks.json file to allow to run the project indicated by the currently open file (so you don’t need to open the exact project directory in VS Code). Place in your tasks.json this (use raw version for easy copy-paste).

    This file defines a few CGE tasks and makes the task "(CGE) Compile And Run" the default.

    Use this sample as:

    • your personal (user-specific, apply to all projects) tasks. Use command "Tasks: Open User Tasks" from the palette (Ctrl + Shift + P) to edit this file.

    • or place these tasks inside the .vscode folder of your project. Use menu item "Terminal → Configure Tasks" to edit this file.

    The above sample tasks.json assumes that the CGE build tool called castle-engine can be found on environment variable PATH.

    Make sure your environment is set correctly to make it work:

    • Extend the PATH environment variable to contain the bin subdirectory of your CGE directory. This is where castle-engine[.exe] file should be. If you don’t know how to set the environment variable, search the Internet (e.g. these are quick instructions how to do it on various Windows versions).

      Alternative: Edit the sample tasks.json to provide full path to the build tool exe, like /home/example/castle_game_engine/bin/castle-engine instead of just castle-engine.

    • (Optional) Make sure that compiler (FPC or Delphi) is on PATH, so that our build tool can find it.

      This is not necessary in the common case, when you use FPC bundled with CGE.

    • (Optional) Set CASTLE_ENGINE_PATH environment variable to point to the root of CGE.

      This is not necessary if you run the build tool from CGE subdirectory bin/, it will auto-detect CGE path then correctly.

    • Remember to restart all applications (like VS Code) that need to be aware of new environment variables' values.

7. Keybindings

Our VS Code extension for Castle Game Engine defines a few useful keybindings:

  • Compile using Ctrl + F9 (or Cmd + F9 on macOS).

  • Run using Shift + F9.

  • Search API reference using Ctrl + F1 (or Cmd + F1 on macOS).

  • Go to declaration using Ctrl + F12 (or Cmd + F12 on macOS).

You can change the bindings as you see fit, naturally, using VS Code.

8. Debugging

Our VS Code extension for Castle Game Engine defines a ready debugger called castleDebug based on fpDebug. Just start debugging in VS Code and choose castleDebug as a debugger.

8.1. Alternative debuggers

Any debugger extension in VS Code able to debug native applications should work.

8.1.1. GDB

You can use Native Debug with GDB.

This is a sample launch.json you can use (edit app_name as necessary):

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug",
            "type": "gdb",
            "request": "launch",
            "target": "./app_name",
            "cwd": "${workspaceFolder}",
            "valuesFormatting": "parseText"
        }
    ]
}

For debugging code compiled with FPC, it’s very useful to set a breakpoint at fpc_raiseexception. Just define a breakpoint at such function name (don’t worry that it may seem like it doesn’t work — it will actually work once you run the project).

8.1.2. fpDebug (directly)

While CGE extension runs fpDebug for you (our castleDebug is only a shortcut for preconfigured fpDebug), you can also set up and tweak fpDebug yourself in the launch.json. Here’s an example:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug",
            "type": "fpDebug",
            "request": "launch",
            "program": "${workspaceRoot}/ui_batching",
            "workingdirectory": "${workspaceRoot}"
        }
    ]
}

9. More Information and Credits

10. Other text editors

The LSP server is fully useful with any text editor that supports LSP, not only VS Code.

10.1. Emacs

You can use it with Emacs. See Michalis Kamburelis notes about LSP + Pascal + CGE + Emacs.

The short version is:

  • Install lsp-pascal, lsp-mode, company Emacs packages,

  • Configure it like this in your ~/.emacs:

    (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")

10.2. NeoVim

The LSP server can be used with NeoVim. See the client/nvim subdirectory of Philip Zander's repository.

11. Plans, TODOs

  • Upload our extension also to VS Codium marketplace. Note that fpDebug is not in VS Codium as of now, we’ll likely fallback on different debuggger.

  • Make the status bar shorter, following VS Code status bar guidelines. We know that current buttons may be "too much", esp. if you have already a number of other extensions filling the status bar. Ideally, we move (and add more) CGE functionality to a view (sidebar) of VS Code, and in exchange make the status bar shorter.

  • Show our API docs using VS Code popup, and available offline. This will replace the current approach to use a separate Webview (with pre-filled search).

  • Bundle CGE with VS Code?

    If you just install (unpack) CGE you should have a ready setup with CGE + VS Code. This is practically just VS Code with automatically enabled (or suggested?) "Castle Game Engine" extension mentioned above.

    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.

  • 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?

  • Debugging on macOS doesn’t work yet.

To improve this documentation just edit this page and create a pull request to cge-www repository.

Previous: Delphi for Linux
Next: Miscellaneous
Manual
Documentation
  1. Tutorial: 3D physics fun
    1. Manual
      1. Install
      2. Build your first application
      3. Designing user interface and handling events (press, update) within the view
        1. Managing Views
      4. Viewport with scenes, camera, navigation
        1. Tutorial: Designing a 3D world
        2. Tutorial: Designing a 2D world
        3. Camera
        4. Navigation
        5. Writing code to modify scenes and transformations
        6. Behaviors
        7. Multiple viewports to display one world
        8. Expose scene elements, like children transformations, as TCastleScene children
      5. User interface
        1. Text and fonts
        2. Localization (translating your application)
        3. Customize loading image
        4. Advanced: custom drawn 2D controls
      6. Editor
        1. Custom Components in Editor
        2. Components to reuse a design in other designs
      7. URLs, loading (downloading) and saving resources
        1. Data directory and castle-data:/ URL protocol
        2. Multi-player
      8. 2D games
        1. Sprite sheets
        2. Images
        3. Tiled maps
        4. How to render 2D games with images and sprites
      9. Physics
      10. Sound
        1. OpenAL
        2. FMOD
      11. Persistent data (user preferences, savegames)
      12. Save screen (screenshot)
      13. Logging
      14. Cross-platform (desktop, mobile, consoles...) projects
        1. CastleEngineManifest​.xml
        2. Customize UI scaling, font, warmup cache by CastleSettings.xml
        3. Build Tool
        4. Touch Input
      15. Platforms details
        1. Android
        2. Android FAQ
        3. Android Services (Google Play Games and many more...)
        4. Adding New Android Services
        5. iOS
        6. iOS Services (Apple Game Center and many more...)
        7. In-App Purchases (Android, iOS)
        8. Nintendo Switch
        9. macOS
        10. Web
      16. Optimization
        1. Occlusion Culling
        2. Profiling Using Valgrind
        3. Detecting Memory Leaks
      17. Making rendering prettier
        1. Bump Mapping (Normal Maps)
        2. Shadow Volumes
        3. Background (skybox, sky and ground)
        4. Fog
        5. Blending
        6. Color Space (Gamma Correction)
        7. Alpha Bleeding
        8. Sketchfab
      18. Engine on a form (VCL, FMX, LCL) using TCastleControl
      19. Automatic Builds (Continuous Integration and Delivery)
        1. GitHub Actions (automatic builds for GitHub projects)
        2. GitLab CI/CD (automatic builds for GitLab projects)
        3. Docker (easily get CGE, compilers, texture compression tools)
        4. Jenkins (automatic builds by your Jenkins server)
      20. Pascal IDEs
        1. Lazarus
        2. Delphi
          1. Delphi packages
          2. Delphi for Linux
        3. Visual Studio Code
      21. Miscellaneous
        1. Steam
        2. Which way is up?
        3. Transformation hierarchy
        4. CastleWindow Backends
        5. Threads
        6. Compiling from source
        7. Supported compilers and IDEs
        8. Coding Traps
        9. Units Map
        10. Dedicated GPU
        11. fpcupdeluxe
        12. FpMake and FpPkg
        13. License
      22. Helping in engine development
        1. Donate
        2. Roadmap
        3. Coding Conventions
    2. Creating Game Data
      1. API Reference
      2. Why Pascal?
      3. Modern Object Pascal Introduction
        1. Overview for Unity Developers
        2. Scene Graph: X3D nodes
          1. Conferences

            Copyright Michalis Kamburelis and Castle Game Engine Contributors.

            This webpage is also open-source and we welcome pull requests to improve it.

            We use cookies for analytics. See our privacy policy. Scarf Analytics