A language server/client for the Tads3/Tads2 programming language and tailored made for Visual Studio Code.
Prioritized to work on linux and mac platform but also supported on windows.
Install the extension via the marketplace by opening the extension tab within vscode and search for its partial/full name, select it and install.
Specific instructions for windows can be found here.
Once installed open up a tads3 project folder (use the open folder feature of vscode), or create a new project with the "Tads3 command: Create a new Tads3 template project" found in the general command menu (CTRL-SHIFT-P). (See the movie below).
Opening up a folder and/or saving a tads3 source code within an opened project will trigger a symbol parsing of that current file (or the whole project, if it hasn't already parsed all files).
Please observe: The extension relies heavily on the project's Makefile (.t3m) file, so be sure it points to the correct includes and/or libraries. If you can compile it with the "t3make" command in a command line tool, it should be good to go with the extension too. Provided the default command "t3make" can be found. (This is otherwise configurable in the setting "tads3.compiler.path".)
First time using the extension within a valid project, all the current library files will be parsed (adv3 or adv3Lite). This is done with several threads running in parallel (default is 6 and configurable), but even so the time for indexing all of it will take some time. It's been timed to be around 1 minute, 30 seconds on a 2013 macbook pro, and around 20 seconds on a desktop running linux/windows i7 3.70GHz.
After this initial parse, all library files will be cached and persisted, and only the project files will be parsed, which will reduce the parsing time to barely noticable. So expect a slightly longer initial parse the first time and then a immediate one the next time you open any project using the same libraries.
The requirements for Tads2 support is having access to the "t3make" compiler, the tads2 compiler ("tadsc" on linux/mac or tc32.exe on windows) as well as the library path.
Modify if needed the following settings:
-
"tads.preprocessor.path"
(default value: "t3make") -
"tads2.compiler.path"
(default value: "tadsc" for usage with frobtads, use tc32.exe for windows) -
"tads2.library.path" (default value: "/usr/local/share/frobtads/tads2/")
When opening up a folder containing a tads2 project the extension will automatially try to find the "main" file in order to preprocess all the other files. If it can't find a single such file it will give a quickpick menu showing the candidates. When a main file is found all the files are preprocessed and parsed.
Compilation happens automatically on every save in the editor on files part of the project. In that process a new *.t3 or *.gam (if using Tads2) game image is built if no errors are found and placed according to the specification of the project's Makefile. (Default is in the root of the project folder and can be overriden with the -o argument). If errors on the other hand were found, no new image will produced and diagnostics are shown with markers in the editor and detailed in the View/Problems section.
Running the game file in an interpreter can be toggled to happen automatically using the (CTRL-SHIFT-P) command: ”Tads3 command: Toggles on/off if the game should restarted as soon as the t3 image game file changes” The extension monitors any t3 file within the project folder for changes and with this setting enabled launches the game with the frob interpreter in a terminal within vscode. (This is a feature primarily working on mac/linux right now.)
Subsequent launching can be made to keep track of last player position by installing a game tracker with the command “Tads3 command: Install a tracker...”. This will persist the player’s position and restore it on each new game run. It is simply a tads3 extension being added to the directory and the makefile that can be removed anytime.
See all the movies in here for a quick introduction in how to use this extension.
vscode-tads3tools has the following features:
Symbol outliner:
outliner.mp4
Symbol definitions:
definitions.mp4
Hover over keywords to see documentation for classes, methods and properties:
hoverdoc.mp4
Create new projects easily:
createNewProject.mp4
Use an interactive map editor for a visual experience while creating the game world:
"Tads3 command: Open current tads3 source code *.{t,h} in Tads3 Visual Editor"
Opens the project in a special web view that displays a map of the game and also allows for some interactivity in changing the exits and adding room.
mapeditor.mp4
See diagnostics on each save:
diagnostics.mp4
Completions as you type and save time:
completions.mp4
Documentation while using Text Completion:
completiondoc.mp4
Snippets for boilerplate code:
snippets.mp4
snippets2.mp4
Be lazy and automatically create props for each room:
"Tads3 command: Analyze the text at the current position and offer code actions. "
Analyzes a room description (using NLP pos tagger technique) and identifies nouns in the text. Then displays a quickpick modal allowing you to select which one should be made a decoration for the current object. The levelling will be kept automatic, so in case the room starts with '+' the decoration objects will be set to '++'.
propGenerator.mp4
Examine how preprocessed documents look like for better understanding during debugging:
"Tads3 command: Toggle CodeLens for preprocessed text of the current Tads3 command: Create a new Tads3 template project"
Toggles a codelens for any preprocessed differences in the original game source code. If clicking the codelens text it will open the preprocessed text and focus in on the divergent text.
"Tads3 command: Choose a preprocessed file to show in a separate window"
Let's you choose any of the preprocessed files available in the project in a separate window next to the source code.
"Tads3 command: Open any project file in a separate window"
Let's you choose any one of the project files (including library files that are included in the project) available in the project in a separate window next ot the source code.
"Tads3 command: Show preprocessed text for the current file"
Opens up the preprocessed version of the file next to the source code in a separate window.
preprocessedDocCmds.mp4
Extract all single or double quoted strings in the project or current file:
stringExtractor.mp4
"Tads3 command: Toggles on/off if the game should restarted as soon as the t3 image game file changes"
If toggled to be enabled, the game will be restarted with the default interpreter in a terminal, on any saved changes in the project that will lead to a new game image file.
The interpreter can be changed in the setting called "Tads3: Game Runner Interpreter to change", the default is set to "frob", but can for instance be set to "t3run.exe -plain", "htmlt3.exe" to make it run on windows if those interpreters are installed.
"Tads3 command: Clear cache for standard libraries adv3/adv3Lite."
This command will clear all the cache that's been built up since last parsing. This hopefully will only be useful for rare circumstances and edge cases. By default using cache for the library files will speed up parsing immensly.
"Tads3 command: Download and install extension(s)"
Will open a quickpick dialog showing all the extensions for tads3 in the ifarchive contribution folder. It will let you multi-select which extension to download and install. At the moment, installment is only unzipping an archive to the project folder. This, because there might be non-uniformity in how extensions are installed and used. A downloaded file will also be cached in the same folder parent folder of the standard library cache. (globalStorageUri)
"Tads3 command: Install a tracker game file in the project so the game will remember player position between sessions"
This command will install a "gametracker" tads source code file into the project and add itself to the makefile. (Both the makefile and this source code will be opened on the command run, so the effect can be seen right away.) Installing the game tracker allows for continuous game development, meaning the player position will be persisted ony any room change and whenever the game is restarted the tracker extension will move the player to the last persisted position and start the game from there. This along with the command for toggling a game restart on each t3 image file change this, will fire up the frob interpreter in a terminal on each incremental change that are saved with the latest change.
"Tads3 command: Set which makefile (.t3m) to use for this project (in case there are several)"
Select which makefile to use (this will be set automatically when opening the project but can be overriden with this command)
- A debugger implementation (via DAP)
- Go to references
- Call Hierarchy
- Document/Selection Formatting
-
Microsoft - This language server is based on the example found in (https://github.com/microsoft/vscode-extension-samples/tree/main/lsp-sample) MIT License
-
Antlr4 was used to generate a parser for the Tads3 programming Language (https://github.com/antlr/antlr4) BSD 3-clause license
-
Antlr4ts was used to produce a specific typescript target of the antlr4 grammar (https://github.com/tunnelvisionlabs/antlr4ts) BSD
-
Litegraph (https://github.com/jagenjo/litegraph.js) MIT License
-
RxJS (https://github.com/ReactiveX/rxjs) Apache-2.0 License
-
Fuzzysort (https://github.com/farzher/fuzzysort) MIT License
-
Wink pos-tagger (https://github.com/winkjs/wink-pos-tagger) MIT License
-
Threads (https://github.com/andywer/threads.js) by Andy Wermke(andywer) MIT License
-
Axios (https://github.com/axios/axios) MIT License
-
The Tads3 tmLanguage definition (for syntax highlighting) is copied from Sam Win-Mason (repo here: https://github.com/Or4c/vscode-tads3), and originally ported from the Sublime Text plugin by VoidPhantom (https://github.com/VoidPhantom/sublime-tads3) (Both distributed under the UNLICENSE license
This is a work in progress and is considered at the moment an early alpha. It has probably a ton of bugs left to fix. Use at your own risk. The aim is to provide a robust language server available to several text editors beginning with vscode.
Please add an issue if you encounter any bugs or proposals. This is a project I hope there will be a lot of collaboration on.
The vscode-tads3tools is licensed under the MIT License
@Copyright Tomas Öberg 2021