User Manual    [Previous]   [Next]   

VSCode

Umple for VS Code

A VS Code extension for the Umple modeling language. Provides IDE features for .ump files.

Umple enables textual description of data models (class diagrams) and state models (finite state machines) with embedded code in Java, Python, C++ and other languages, along with generation of high quality code in those languages. Umple enables extensive analysis of models, as well as generation of diagrams, example data and many other outputs. Special features of Umple include specification of product lines (using mixsets), code injection (aspects), code snippet management (traits) and so on. Umple can scale to systems of any size, but its codebase will always be much smaller than software written directly in target languages due to Umple eliminating much boilerplate code. Umple can complement LLM-generation of code: You can arrange for your AI to generate Umple.

This plugin is listed in the VSCode Marketplace

Features of the Umple Plugin

Language Intelligence (via LSP)

• Diagnostics — Real-time error and warning detection via the Umple compiler
• Go-to-definition — Jump to classes, interfaces, traits, enums, attributes, methods, state machines, states, associations, mixsets, and requirements
• Find references — Semantic reference search across all reachable files
• Rename — Safe rename of symbols across all references
• Hover — Contextual information for symbols
• Inlay hints — Editor-only inferred type annotations for untyped attributes when VS Code inlay hints are enabled
• Document symbols — Hierarchical outline of classes, state machines, states, attributes, methods
• Code completion — Context-aware keyword and symbol suggestions
• Formatting — AST-driven indent correction, arrow spacing, declaration assignment spacing, structural comma spacing, blank-line normalization
• Syntax highlighting — TextMate grammar baseline plus LSP semantic tokens generated by umple-lsp
• Cross-file support — Transitive use statement resolution and cross-file diagnostics
• Import error reporting — Errors in imported files shown on the use statement line
• Runtime bootstrap — Automatically downloads umplesync.jar on activation and offers a one-click recovery download if it is missing later

Compile

Generate target language code from Umple source.

• Command: Umple: Compile (also accessible from the Umple menu button)
• Target languages: Java, PHP, Ruby, Python, C++, RT-C++, SQL
• Status bar: Shows the current target language (e.g., Umple: Java) — click to switch. Only visible when editing .ump files.
• Output: Results appear in the “Umple” output channel with parsed errors and warnings

Diagrams

View diagrams (UML and others) generated from your Umple model.

• Command: Umple: Show Diagram or Cmd+Shift+U (Ctrl+Shift+U on Windows/Linux)
• 10 diagram / view types in a dropdown selector:
  • UML Class Diagram
  • Class + Trait Diagram
  • Entity-Relationship Diagram (equivalent to the class diagram)
  • UML State Machine Diagram (if any state machines are present)
  • Feature Diagram (if any mixsets are specified and activated with a require statement)
  • UML Instance Diagram (random; each time it is generated, different instances appear)
  • State Tables (equivalent content to the state machine diagram, but different format)
  • Event Sequence (random; each time it is generated a new sequence is created)
  • Metrics
  • Plain Requirements Doc (HTML view — structured rendering of req declarations and useCase blocks; degenerate placeholder for class-only models)
• Click-to-select: Click classes, traits, interfaces, states, or transitions in the diagram to jump to their source location
• Layout engine: Choose between dot, circo, neato, fdp, and osage (configurable via umple.diagramLayout setting or the in-panel dropdown)
• Diagram filter: Filter diagram content by class/trait name, matching UmpleOnline filter syntax
• Zoom controls: +/−/Fit/1:1 buttons and Ctrl/Cmd+scroll wheel (20%–500%)
• Export: Save as SVG or PNG
• Live auto-refresh: Diagrams update automatically as you edit (1.5s debounce)
• Theme-aware: Diagram colors adapt to your VS Code light/dark theme
• Cross-file support: Diagrams resolve use imports to include referenced files

Snippets

Code snippets for common Umple patterns. Type the prefix and press Tab:

Umple Menu Button

An Umple logo button appears in the editor title bar when editing .ump files. Click it to access:

• Compile (with current target language)
• Show Diagram
• Change Target Language

Requirements

• Node.js 20+ (tested on 20 and 23)
• Java 11+ (optional — only needed for diagnostics, compilation, and diagrams)

Installation

Install from the VS Code Marketplace, or build from source:

# Side-by-side checkout: this repo currently pins umple-lsp-server to a local
# tarball produced by `npm pack` in the umple-lsp monorepo. So you also need
# umple-lsp cloned as a sibling.
git clone https://github.com/umple/umple-lsp.git
git clone https://github.com/umple/umple.vscode.git

# Build the server first and pack it
cd umple-lsp
npm install
npm run compile
cd packages/server
npm pack            # produces umple-lsp-server-X.Y.Z.tgz

# Then build the extension. package.json's `umple-lsp-server` dep points at
# the .tgz path; if you packed a new version, edit package.json to match.
cd ../../../umple.vscode
npm install
npm run compile

To package as .vsix:

npx @vscode/vsce package

Alternative: change the umple-lsp-server dep in package.json from the file: tarball path to a registry version like ^0.4.3, then npm install pulls from npm. Cleaner long-term; requires the matching server version already published.

Configuration

Keyboard Shortcuts

Development

To test local changes to the LSP server:

1. Clone both repos side by side:

workspace/
├── umple-lsp/       # LSP server monorepo
└── umple.vscode/    # This extension

2. Build the server:

cd umple-lsp
npm install
npm run compile

3. Link the local server into the extension:

cd umple.vscode
npm install
npm link ../umple-lsp/packages/server
npm run compile

4. Press F5 in VS Code to launch the Extension Development Host.

5. After making changes to the server, recompile and reload:

cd umple-lsp
npm run compile

Then in the dev host: Cmd+Shift+P (or Ctrl+Shift+P) → Developer: Reload Window

Where to make language-feature changes

This extension is mostly VS Code glue. Features such as diagnostics, completion, hover, inlay hints, go-to-definition, references, rename, formatting, workspace symbols, code actions, and LSP semantic tokens live in umple-lsp/packages/server.

Inlay hints are handled by VS Code’s standard LSP client. No extension code is needed when the server advertises textDocument/inlayHint; users only need VS Code’s editor.inlayHints.enabled setting to be on.

Formatting is provided by the LSP server. It is conservative: it formats parse-clean Umple structure, parser-visible structural commas, and already split multi-line list indentation. It does not format embedded target-language method or action bodies. Formatter behavior should be changed in umple-lsp/packages/server, not in this VS Code wrapper.

For highlighting:

• VS Code uses this repo’s TextMate grammar as the baseline coloring path.
• The LSP server also advertises semantic tokens. Those are derived from umple-lsp/packages/tree-sitter-umple/queries/highlights.scm and mapped in umple-lsp/packages/server/src/semanticTokens.ts.
• If a token is parsed correctly but colored incorrectly across editors, update highlights.scm and/or semanticTokens.ts in umple-lsp, then rebuild the server and reload the Extension Development Host.
• Change this repo only when the VS Code wrapper needs different activation, commands, snippets, TextMate fallback scopes, settings, packaging, or server-launch wiring. Current TextMate fallback scopes intentionally cover common LSP semantic-token gaps such as tracer directives, port declarations/connectors, test sequences, and UmpleOnline layout directives.

Useful checks:

cd umple-lsp
npm run compile
npm test -w packages/server

cd ../umple.vscode
npm run compile

In VS Code, run Developer: Inspect Editor Tokens and Scopes to distinguish TextMate scopes from LSP semantic token classifications.

Architecture

This extension is a thin client that launches the Umple LSP server. The server handles all language intelligence (diagnostics, completion, go-to-definition, references, rename, hover, inlay hints, formatting, workspace symbols, code actions, and semantic tokens). The extension adds VS Code-specific features: compile command, diagram panel, snippets, and UI chrome.

VS Code Extension (this repo)
  |
  +-- (stdio) --> umple-lsp-server --> umplesync.jar (diagnostics)
  |                 |
  |                 +-- tree-sitter (go-to-def, completion, references,
  |                                  rename, hover, formatting, symbols,
  |                                  semantic tokens, inlay hints)
  |
  +-- Compile command --> umplesync.jar -generate <lang>
  |
  +-- Diagram panel --> umplesync.jar -generate GvClassDiagram/...
  |                       |
  |                       +-- @viz-js/viz (DOT → SVG rendering)
  |
  +-- Click-to-select --> umple/resolveStateLocation (custom LSP request)
                          umple/resolveTransitionLocation

Original markdown source for this page: https://github.com/umple/umple.vscode/blob/master/README.md