ZedScripts LSP

ZedScripts LSP is a language server protocol implemented in Python for the scripting format of Project Zomboid. Previously a VSCode extension, it is now reimplemented as a standalone LSP.

It is powered by the pz-scripts-data to provide up-to-date information about the Scripts format. See configuration to learn how to specify the dataset version.

Installation

Releases

Python package

ZedScripts LSP is available directly as a Python package if you ever need to use its functionality outside of an IDE.

pip install ZedScripts

pip install git+https://github.com/PZ-Wiki-Modding/ZedScripts-LSP.git

pip install -e .

Cache directory

A cache directory is used on your system to cache the pz-scripts-data and logs, as well as global configuration. You can find it here:

~/.zedscripts

%USERPROFILE%\.zedscripts

Configuration

The LSP uses configurations files .zedscripts.json which provide information to the LSP about various settings.

Example of configuration file content:

{
    "$schema": "https://raw.githubusercontent.com/PZ-Wiki-Modding/ZedScripts-LSP/refs/heads/main/schema/zedscripts.json",
    "dataset": {
        "latest": true
    },
    "libraries": [
        "~/.steam/debian-installation/steamapps/common/ProjectZomboid/projectzomboid/media",
    ]
}

They are optional and should be placed at the root of your workspaces or in the cache directory. The local configuration (root of your workspaces) will override the global configuration (cache directory).

📁 workspace1
    📁 Contents/mods/YourMod/42/media/scripts
        📄 example_script.txt
    📄 .zedscripts.json
📁 workspace2
    📄 .zedscripts.json

📁 ~
    📁 .zedscripts
        📄 .zedscripts.json

A schema is available to validate the configuration files and can be found in the schema directory.

See the following sections for detailed explanation of each parameters.

Dataset

You can configure the version of the pz-scripts-data dataset.

{
    "dataset": {
        ...
    }
}

The key-values which can be set in the dataset section are the following:

• latest: a boolean indicating the LSP to use the latest available version for the dataset (latest game version and dataset version)
• stable: a boolean indicating the LSP to use the latest stable version of the dataset
• release: used to indicate a specific release version of the dataset with the following arguments:
  • major: major build version (e.g. 42, 43)
  • minor: minor build version (e.g. 0, 1)
  • patch: patch build version (e.g. 0, 1)
  • version (optional): the dataset version (e.g. 0, 1, 2)
  • for example, version 42.21.0 of the game would be specified as:

{
    "release": {
        "major": 42,
        "minor": 21,
        "patch": 0
    }
}

It's suggested to use the stable option.

Libraries

A list of paths that should include the base game path, as well as other games that your mod depends on for its scripts. This will provide LSP the ability to find other blocks definitions that you may reference inside your mod's scripts.

{
    "libraries": [
        "path/to/base/game",
        "path/to/other/dependent/game"
    ]
}

Ignored

A list of regex patterns tested on file paths that should be ignored by the LSP, by default this includes large script files that can slow down the LSP.

{
    "ignored": [
        "path/to/large/script/file"
    ]
}

Diagnostics

A list of diagnostics with modifiers to change the diagnostic behavior of the LSP. The following parameters:

• type: the type of the diagnostic, that is the ID shown in the diagnostics hover tooltip (for example, BLOCK_UNKNOWN_BLOCK)
• enable (optional): boolean to disable the diagnostic
• severity (optional): the severity level of the diagnostic (accepted values: Error, Warning, Information, Hint)
• tags (optional): an array of tags which an IDE may use to provide additional context or behavior for the diagnostic (accepted values: Unnecessary, Deprecated)

Each diagnostic by default have a specific set of modifiers that can be overridden in the configuration.

{
    "diagnostics": [
        {
            "type": "BLOCK_UNKNOWN_BLOCK",
            "enable": true,
            "severity": "Warning",
            "tags": ["Unnecessary"]
        }
    ]
}

Server

A list of server-related configurations for the LSP. The following parameters are available:

• logging_level (optional, default: INFO): specifies the logging level for the server. This option is only available in the global configuration and accepts values such as NOTSET, DEBUG, INFO, WARNING, ERROR, and CRITICAL.

IDE configuration

Based on the IDE you use, you may need to install the ZedScripts LSP application for your OS in the releases (Linux, Windows).

Visual Studio Code

Install the ZedScripts extension from the Visual Studio Code marketplace. The extension will handle the downloading and setup of the ZedScripts LSP server for you.

VIM

Using yegappan/lsp, setup the ZedScripts LSP server as follows:

let lspServers = [
      \ #{
      \   name: 'zedscripts',
      \   filetype: ['text', 'zedscripts'],
      \   path: 'path/to/ZedScripts',
      \   args: []
      \ }
      \ ]

autocmd User LspSetup call LspAddServer(lspServers)

Pygments

The ZedScripts LSP provides a Pygments lexer for syntax highlighting of ZedScripts code. It is available in the ZedScripts.structure.pygments_lexer module. You can notably use the command-line wrapper to highlight any file's content as ZedScripts:

uv pip install ZedScripts[pygments]
highlight-zedscripts path/to/file.txt

To use the lexer in Sphinx docs, you can add the following to your conf.py:

from ZedScripts.structure.pygments_lexer import ZedScriptsLexer
from sphinx.highlighting import lexers
lexers['zedscripts'] = ZedScriptsLexer()

License and contribution

This project is licensed under a MIT license. Before contributing to the project, please see CONTRIBUTING.