Farming Simulator IDE Support - VS Code Extension

Full IDE support for Farming Simulator development — Lua IntelliSense with engine API completion, XML schema validation, GSL shader support, in-game Lua debugging, script hot-reload, and density map viewing.

Table of Contents

• Features
  • Lua Language Server (IntelliSense)
  • Engine Stubs and Auto-Completion
  • LuaLS Plugin for GIANTS Conventions
  • Lua Hex Color Preview
  • Image Hover Preview
  • Callback Generation
  • String Format Validation
  • LuaDoc Generation
  • XML Schema Support
  • XML Color Preview
  • File Path Validation and Completion
  • XML Editing Helpers
  • GIM File Support
  • Brand Material Template Preview
  • Moving Parts Validation
  • Shader Language Support
  • Lua Debugger
  • Script Hot-Reload
  • Density Map Viewer
  • Luadoc Viewer
  • Game Log Viewer
  • Getting Started: Debugging a Mod or Editor Script
• Commands
• Settings
• Keybindings
• File Associations

Features

Lua Language Server (IntelliSense)

The extension bundles LuaLS (Lua Language Server) configured specifically for GIANTS Engine development.

Auto-completion and hover documentation for engine API functions

• Auto-completion for all Lua symbols, engine globals, and class methods
• Hover documentation showing function signatures, parameter types, and descriptions
• Go to Definition / Peek Definition for Lua symbols
• Find All References across the workspace
• Signature Help showing parameter info as you type
• Diagnostics for syntax errors, type mismatches, and undefined globals
• Semantic highlighting with GIANTS-specific token scopes
• Inlay hints for parameter names and types (configurable)

Command: FS Lua: Restart Language Server — Restarts LuaLS if it gets stuck or after configuration changes.

Engine Stubs and Auto-Completion

IntelliSense for the GIANTS Engine API — engine functions, globals, classes, and enums — is generated automatically when the workspace activates and refreshed when the engine binding files change.

For engine functions with multiple return values, the completion list offers an extra snippet entry that assigns all return values to local variables at once — e.g. accepting it for getRigidBodyAABB inserts local minX, maxX, minY, maxY, minZ, maxZ = getRigidBodyAABB() with the cursor placed between the parentheses. The entry only appears at the start of a statement; picking the regular completion entry behaves as usual.

LuaLS Plugin for GIANTS Conventions

GIANTS-specific Lua patterns are understood automatically: the project's -- @param doc style, Class(Child, Parent) inheritance, self.xmlFile / self.xmlSchema field types, superClass() return types, and engine-style class definitions all participate in IntelliSense, hover, and Go-to-Definition just like native LuaLS annotations.

Lua Hex Color Preview

Inline color swatches for hex color values in Lua code (e.g. constants in Color.lua).

Inline color swatches with the native color picker

• Detects 0xRRGGBB / 0xRRGGBBAA literals and {r, g, b[, a]} table values used as color constants
• Click the swatch to open the native VS Code color picker and edit the value in place

Image Hover Preview

Hover over an image path in a Lua or XML file to see an inline thumbnail preview.

Thumbnail preview when hovering an image path

• Supports .png, .jpg, and .dds previews — including textures referenced by their .png name but shipped as a .dds on disk
• Resolves $data/, $dataS/, and mod-relative paths
• Useful for verifying texture, icon, and UI asset references without leaving the editor

Callback Generation

When an engine async function is passed a callback name that doesn't exist yet, the missing function gets a warning diagnostic and a Quick Fix (Ctrl+.) that generates the callback stub with the correct signature, inserted next to the calling function.

String Format Validation

Validates string.format, string.namedFormat, and the Logging.* wrapper calls (Logging.info, Logging.warning, Logging.xmlError, …) against the placeholders in the format string.

• Argument count mismatch — Warns when the call supplies fewer or more arguments than the format string's % placeholders expect
• Type mismatch — Warns when a literal argument can't satisfy its placeholder, e.g. passing "str" to %d
• Named format pairing — For string.namedFormat, warns when the name-value arguments don't pair up, when a %{name} placeholder has no matching value argument, or when a placeholder name is empty

Warnings for mismatched format placeholders and arguments

LuaDoc Generation

Generate the GIANTS-style -- @param / -- @return doc block for a Lua function with one command.

• Single function — FS Lua: Generate Lua Function Documentation (Ctrl+Shift+D on a .lua file) inserts a doc block above the function under the cursor with inferred parameter and return types
• Whole file — FS Lua: Generate All Lua Function Documentations regenerates doc blocks for every function in the current file, preserving existing descriptions

XML Schema Support

Full XSD-based support for GIANTS Engine XML files (vehicle XMLs, map XMLs, mod descriptors, etc.).

• Auto-completion for XML element names, attribute names, and attribute values
• Hover documentation showing element descriptions, types, and default values from XSD
• Diagnostics for missing required attributes, unknown elements, and type mismatches
• Quick-fix code actions for broken or missing schema references, unknown element/attribute names, missing required attributes, and outdated $data/ paths
• GDN schema URL — Broken schema paths can be fixed to the GIANTS validation URL with the right game version
• i3D mapping completions — g_node_index attributes get completion items from the <i3dMapping> entries in the current document

Completion and validation of node attributes against the document's <i3dMapping> entries

Schema validation requires the XML header to reference the correct GDN schema URL for the file's root element.

XML Color Preview

Inline color swatches and an interactive color picker for color attributes in XML files.

• Detected attributes — color, uiColor, colorScale, rgb, and any attribute typed as g_color in the schema
• Color picker — Click the swatch to open VS Code's native color picker
• Alpha support — 3-component (R G B) and 4-component (R G B A) values both work

File Path Validation and Completion

XML attribute values and Lua string literals that reference files on disk get path completion and an existence check.

• Auto-completion for paths in attributes the schema marks as file references (textures, i3d, lua, xml, sounds, etc.) and for known string contexts in Lua
• Diagnostics when a referenced file does not exist on disk
• Case-sensitivity check — Warns when a reference matches a file only by ignoring letter case (works on Windows, fails in the game at runtime); auto-completion itself stays case-insensitive
• Mod-relative resolution — Paths in modDesc.xml / dlcDesc.xml are resolved relative to the mod root
• Path prefix resolution — $data/, $dataS/, $dataS2/, shared, and profile-template prefixes are mapped to actual directories
• File-extension aliases — Tolerates .png ↔ .dds ↔ .grle mismatches where the engine accepts either
• File-existence checks are skipped inside commented-out lines

Path auto-completion for file-reference attributes

Referenced files become clickable links (Ctrl+Click to open)

XML Editing Helpers

A set of context-menu actions and commands for common XML editing operations on GIANTS Engine config files. All are available from the editor right-click menu in .xml files.

• Toggle Line Comment (Ctrl+/) — Toggles <!-- … --> on each selected line individually. Selecting an already-commented block uncomments each line; otherwise comments each non-blank line.
• Toggle Block Comment (Shift+Alt+A) — Wraps the selection in <!-- … -->. Any nested <!-- / --> inside the selection is automatically neutralized to <!- - / - -> so the outer wrapper stays well-formed, and restored on uncomment.
• Invert Animation — Swaps startTime ↔ endTime (and matching start/end attribute pairs) on every <part> of the animation under the cursor.
• Mirror Left/Right — Duplicates the selected XML block and rewrites …Left… ↔ …Right… (and 01..N index pairs) so a mirrored side can be generated from one authored side.
• Copy Path — Copies the engine-style path of the element or attribute under the cursor to the clipboard, e.g. vehicle.foldable.foldingConfigurations.foldingConfiguration(0).foldingParts#allowUnfoldingByAI — the same key you pass to xmlFile:getString(...) in Lua. A (N) index is included only where an element has multiple same-tag siblings.

Invert Animation swaps the start/end attribute pairs of an animation

Jump directly to an animation definition

XML Formatting

Format Document (Shift+Alt+F) tidies a GIANTS XML file: consistent indentation and attribute spacing, and attribute columns aligned across consecutive elements of the same tag (and matching nested elements such as each wheel's <physics>) so related rows line up into readable columns. Comments, text, and attribute order are preserved.

Enable fsLua.xmlFormat.formatOnSave to apply the same formatting automatically every time you save an XML file.

GIM File Support

Syntax highlighting and schema-driven autocompletion for .gim files (GIANTS Image Metadata format that is XML-based).

• Treated as XML for syntax and structure
• Element and attribute completion + hover documentation from the bundled .gim XSD schema
• Same diagnostics infrastructure as regular XML files

Brand Material Template Preview

Hover over a materialTemplateName attribute to see the brand name, title, and an inline color swatch for that template.

Brand color and title preview on material template hover

Moving Parts Validation

Validates moving parts and tool configurations in vehicle XML files.

• Detects missing dependency declarations between moving parts
• Validates i3D node references against <i3dMapping> entries
• Produces diagnostics for missing or invalid reference nodes
• Tracks moving node hierarchy with influence zones

Shader Language Support

Support for GIANTS Engine shader files (.xml shader definitions and .gsl shader source).

Shader XML:

• Syntax highlighting for GIANTS shader XML format
• Auto-associated for files in data/shaders/ directories

GSL (GIANTS Shader Language):

• Syntax highlighting with HLSL/GLSL-like token scopes
• Language configuration for brackets, comments, and auto-closing pairs

Shader Builtins:

• Auto-completion for built-in shader functions and shared helper functions, with parameter info
• Hover documentation for shader functions, parameters, and structs
• Signature help while typing function calls

Syntax highlighting and completion for GSL shader source

Lua Debugger

Full interactive debugger for GIANTS Engine Lua scripts. Attaches to a running game instance over TCP.

• Breakpoints — Set, remove, and toggle breakpoints in .lua files
• Step Over / Step Into / Step Out / Continue — Standard debugger controls
• Call Stack — View the full Lua call stack with source locations
• Variables — Inspect local variables and the global table with full tree expansion
• Variable sorting — Values are sorted alphabetically with functions grouped at the bottom
• FS Variables panel — A dedicated Variables view in the Debug sidebar with a built-in search box that filters Locals and Globals live as you type, without collapsing tables you have expanded
• Watch Expressions — Evaluate arbitrary Lua expressions
• Debug Console autocompletion — Typing in the Debug Console suggests globals, locals, and table members (type . or : after a value to see its fields and methods). While paused, suggestions reflect the live game state; while the game is running, they come from the engine API and known script classes
• Debug Console auto-print — Type a bare value like myVar or type(getChildAt) in the Debug Console and its result is printed automatically — no need to wrap it in print(). Tables and enums print their contents recursively instead of just a table reference; statements and assignments still run as-is
• Hover Evaluation — Hover over variables in the editor to see their values
• Conditional Breakpoints — Break only when a condition is true
• Auto-attach — When the game starts with Lua debugging enabled, a debug session connects automatically; no need to press F5 first

Inspecting live game variables while paused at a breakpoint

Auto-completion for globals and table members in the Debug Console

Press F5 to launch the game using a workspace launch configuration.

Sample launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug - Sample",
            "type": "fsLua",
            "request": "launch",
            "program": "PATH_TO_GAME/x64/FarmingSimulator2025Game.exe",
            "cwd": "PATH_TO_GAME/x64",
            "args": ["-yourArgs"]
        }
    ]
}

Commands:

• FS Lua: Reload Script in Game — Hot-reload the current .lua file (see below)

Script Hot-Reload

Reload the current Lua file in the running game without restarting. Only available while a debug session is active.

Command: FS Lua: Reload Script in Game Keybinding: Ctrl+R (when editing a .lua file)

Density Map Viewer

Built-in viewer for GIANTS density map files (.grle and .gdm).

Viewing a density map with pan, zoom, and pixel inspection

Supported formats:

• GRLE (Giants RLE) — Run-length encoded grayscale images. Used for info layers (field ownership, terrain types, etc.)
• GDM (Giants Density Map) — Chunk-based palette-compressed density maps. Used for crop density, weed density, etc.

Viewer features:

• Pan and zoom — Mouse wheel to zoom (up to 1000%), click-drag to pan
• Pixel inspection — Hover cursor shows exact pixel coordinates and raw value as a tooltip
• Low-depth highlighting — Files with fewer than 8 bits (e.g. stone or weed density) render non-zero pixels in red with a brightness floor, so even single-value differences are clearly visible; the tooltip still shows the real value
• Selection box — Click-drag with selection tool to measure rectangular areas
• Multi-channel rendering — GDM files with >8 channels render as RGB; ≤8 render as a single channel (low bit depths use the red low-depth highlight above, otherwise grayscale)

Export:

• Export the open density map to PNG using the toolbar button in the viewer

Convert:

• Built-in conversion dialog for changing bit depth with per-bit channel remapping
• Supports target depths from 1-24 bits (multi-channel GRLE output)
• Sequential or custom bit mapping presets
• Saves as .grle file

Luadoc Viewer

Interactive documentation browser for all engine Lua functions and shader builtins. Accessible from the VS Code activity bar (sidebar).

Browsing engine function documentation in the Luadoc Viewer sidebar

• Lua tab — Browse all engine Lua functions organized by category (2800+ functions, 70+ categories, 70+ enums)
• Shader tab — Browse shader functions and struct definitions (190+ functions)
• Search — Filter by function name, description, or parameter/attribute names
• Detail panel — Shows full function signature, arguments table (type, name, description), return values, and overloads
• Enums — Browse engine enums with all their values

The viewer appears as a Lua icon in the VS Code activity bar. Click to open.

Command: FS Lua: Open Luadoc Viewer

Game Log Viewer

Live game log output directly in VS Code, automatically following the latest log file.

• Color-coded output — Errors in red, warnings in yellow, info in default
• Clickable file links — Script paths in log lines open the file at the right line
• Error block collapsing — Repeated identical error + callstack blocks are collapsed with a "repeated N more times" summary
• Auto-restart detection — When the game restarts, the output clears and starts fresh

Output appears in the FS Game Log output channel (View > Output > FS Game Log).

Getting Started: Debugging a Mod or Editor Script

This walks through everything needed to debug Lua running in the game or in the GIANTS Editor for the first time.

1. Open your workspace

Open the folder that contains the scripts you want to debug — your mod folder, or a folder with your scripts — as the VS Code workspace (File > Open Folder…). When the folder is detected as a Farming Simulator project, the language, debugging, and stub features engage automatically. A Farming Simulator installation is required for full functionality — the engine API stubs, path resolution, and debugging all depend on it, so make sure the game is installed (and set fsLua.gamePath if it isn't auto-detected, see step 3).

2. Trust the workspace

VS Code opens unfamiliar folders in Restricted Mode, which blocks the bundled language server, debugger, and stub generation from running. When prompted, choose Yes, I trust the authors, or click the Restricted Mode banner and select Manage > Trust. The extension's features only work in a trusted workspace.

3. Point the extension at your game and editor

The extension auto-detects an installed game and GIANTS Editor on Windows. Set these only if auto-detection can't find your install or you want a specific one:

• fsLua.gamePath — the game installation directory (the folder containing the FarmingSimulator20XX.exe). Use the command FS Lua: Set Game Path to browse for it. Needed to launch the game with F5 and to generate engine stubs.
• fsLua.editorPath — the GIANTS Editor installation directory (e.g. C:/Program Files/GIANTS Software/GIANTS_Editor_XX.X.X). Use the command FS Lua: Set Editor Path to browse for it. Needed to open .i3d files in the editor and to pick up the editor's script bindings for editor-script IntelliSense.

4. Check the status bar

Three status-bar items tell you whether everything is wired up:

• Language server state (left) — shows Starting… / Generating stubs… while initializing and Ready once IntelliSense is live. Click it to open the server log.
• Game info (right) — shows the detected game name and version. Hover for the resolved game path. If this is missing, the game wasn't detected — set fsLua.gamePath.
• Debug listener (left) — shows Listening on :<port> while waiting for a connection and Game Connected once the game or editor attaches. Click it for the listener menu (enable/disable). Only one VS Code instance can listen on the port at a time — if you have multiple windows open, the status shows Port <port> in use in the others; disable the listener in the windows you aren't debugging from.

5. Connect the game or editor to VS Code

The extension listens for an incoming debug connection as soon as the workspace activates, so you don't have to press F5 first. Connect from the running game or GIANTS Editor:

• In the game — press F10 to connect to VS Code.
• In the GIANTS Editor — choose Scripts > Connect to Studio.

When the connection arrives, a debug session named GIANTS Engine (auto) starts automatically, the debug-listener status flips to Game Connected, and your breakpoints become active. You can now step, inspect variables, and use the Debug Console. The Debug sidebar also gains an FS Variables panel (Locals/Globals with a live search box that keeps expanded tables open) and an FS Memory panel (total memory over time plus per-file memory and allocation tables).

To instead launch the game directly from VS Code with debugging attached from startup, press F5 with a launch.json configuration (see the sample in the Lua Debugger section).

Commands

Settings

All settings are under the fsLua namespace. Access via File > Preferences > Settings and search for "fsLua".

Keybindings

File Associations

The extension registers these file type associations:

License

Copyright (C) GIANTS Software GmbH, All Rights Reserved. See the bundled LICENSE file for terms and THIRD_PARTY_NOTICES.md for third-party attributions.