greybel-vs

This toolkit provides essential tools for developing in GreyScript, the scripting language used in Grey Hack. The extension offers syntax highlighting, code execution, bundling, minification, and more to streamline GreyScript development in VSCode.

Prefer a different editor? The GreyScript Language Server is also available and compatible with IDEs like Sublime Text, IntelliJ, nvim and more. Examples for setting up these editors are included in the repository.

Links

Project Resources

• Changelog: View the latest changes and updates.
• greybel-js CLI: Command-line interface for Greybel.
• GreyScript Documentation: API documentation for GreyScript.

Projects Using Greybel

• gsse: GreyScript Script Extender is a modular library that aims to expand the current scripting framework of greyscript.
• minizod: A lightweight, Zod-inspired validation library for MiniScript.
• Minesweeper: A Minesweeper game created in GreyScript. (Demo project)
• JSON Parser: JSON parsing functionality. (Demo project)
• TEdit: Text editor built with GreyScript. (Demo project)

Do you have a project that uses Greybel? If so, feel free to create a pull request to showcase it here.

Grey Hack Tools

• Image Transformer: Tool for transforming images in Grey Hack.
• Website Image Generator: Tool for generating Grey Hack website images.

Community

• awesome-greyhack: List with several resources related to Grey Hack.
• Greybel Discord: Join the community on Discord for support and discussion.

Usage

This extension automatically detects .gs, .src, and .ms files and provides convenient commands to streamline your workflow.

Commands available (CTRL+SHIFT+P):

• Greybel: Build - Transpile your GreyScript code. More info
• Greybel: Share - Share your code with others easily. More info
• Greybel: API - Open the API browser for quick reference. More info
• Greybel: Snippets - Insert GreyScript snippets into your code. More info
• Greybel: Preview output – View a preview of the ingame like output. More info
• Greybel: Import file into the game – Upload files into the game. More info

You can also access these commands through the context menu for quick right-click access:

Tip: Make sure to configure settings to customize Greybel to your preferences.

Settings

• General
  • Autocomplete: Activate/Deactivate
  • Diagnostic: Activate/Deactivate
  • Hoverdocs: Activate/Deactivate
  • Formatter: Activate/Deactivate
  • File Extensions: Define allowed file extension
  • Root File: Define the root project file. If not set, the extension will rely on the given context to built or execute files
• Create in-game
  • Active: Activate/Deactivate
  • Auto Compile: Auto compile and delete source files
  • Allow Import: Enable allowImport on auto compile
  • Port: Select the port of the message-hook server
• Interpreter
  • Default Args: Default call arguments
  • Environment Variables: JSON used to define environment variables (ENVs)
  • Environment Variables File: Define .env file from which environment variables should be loaded from
  • Hide Unsupported Text Mesh Pro Rich Text Tags: Hides unsupported rich tags in the pseudo-terminal
  • Seed: Seed used to generate the testing environment
  • Silence Error Popups: Silences error popups due to execution failure
  • Port: Select the port of the message-hook server
  • Environment type: Interpreter environment type
  • Program name: Defines program name in runtime
• Transpiler
  • Build Type: Default, Uglify, Beautify
  • Beautify
    • Indentation: Tab or whitespace. What should be used for indentation?
    • Indentation Spaces: In case whitespace is used this will determine the amount of whitespaces
    • Keep Parentheses: Will always use parentheses
  • Literals Optimizations: Activate/Deactivate
  • Namespaces Optimizations: Activate/Deactivate
  • Environment Variables: JSON used to define environment variables (ENVs)
  • Environment Variables File: Define .env file from which environment variables should be loaded from
  • Excluded Namespaces: List of namespaces that should not be optimized
  • In-game Directory: Destination folder used in the game
  • Installer
    • Active: Activate/Deactivate
    • Auto Compile: Adds boilerplate code to the installer for auto-deletion of the script after execution
    • Allow Import: Enable allowImport when performing auto compile in installer
    • Max Chars: Define the maximum number of characters at which the installer should split the code
  • Obfuscation: Enables minification of namespaces using special characters
  • Watch: Watch project files for changes and run build automatically
  • Output Filename: Specify the name of the main output file.
• Type Analyzer
  • Strategy: Specifies which files are used for type resolution. The "Dependency" strategy resolves types from all files imported into the current file. Alternatively, the "Workspace" strategy resolves types from all files within the workspace
  • Exclude: Specifies files to ignore based on matching glob patterns

Features

• Transform
• Build
• Upload
• Interpreter
• Message Hook
• API Browser
• Comment Docs
• Snippets
• Share
• Goto Error
• Preview output
• Providers

Transform

Transpiles your code into a specific format. Be sure to select your desired output in the settings. By default, the "Default" build type is selected.

Output modes

There are three different modes: "Default", "Uglify", and "Beautify". The output will vary depending on the mode selected.

• Default: No special behavior like optimization or formatting. This format is the best all-rounder if you're unsure.

• Uglify: Minifies your code and optimizes literals and namespaces. You can disable these features if necessary, especially if namespaces must remain unchanged for your code to function properly. You can also exclude specific namespaces from optimization.

  

• Beautify: Formats your code to improve readability. There is currently no customizability available in this mode, which might limit its use case.

Imports (Transform)

Important: Unlike the build function, transforms will ignore any #include, #import, or import_code lines. Use the build functionality instead.

Environment (Transform)

Greybel allows you to inject environment variables during transformation. These can be configured in the extension settings.

Build

Building transforms and bundles your scripts in a way that makes them easy to import into Grey Hack. As mentioned in the transform section, building also provides three different output modes: "Default", "Uglify", and "Beautify". For more details, check out the output-modes section.

Auto create files in-game

You can automatically create transpiled files in the game by enabling the "create-ingame" option. To use it, you must have message-hook installed.

Imports on building

Scripting in Grey Hack can be challenging, especially when you have files that import each other or are working on a larger project where you have to copy-paste each file manually into the game every time. Greybel aims to reduce this hassle, allowing you to spend more time coding and playing rather than copy-pasting files repeatedly.

Dependency Management (Transpiler)

Greybel enables you to split your code into different files, which helps maintain readability and also makes your code reusable.

It is recommended to use include and import for small or medium-sized projects.

For larger projects, import_code should be used instead, as the transpiler will bundle your files in a way that maximizes the use of import_code in the game, helping to avoid exceeding the maximum character limit of 160,000.

Cyclic dependencies will also be detected. If a cyclic dependency is found, an error will be thrown, indicating which file is causing it.

A step-by-step guide is available here.

Import

Used to import exported namespaces from a file. Features:

• Supports relative imports
• Loads code only when required
• Does not pollute global scope
• Only imports once, no matter how many times it’s referenced
• Exports only what you want
• Code is appended to the root file, which may exceed the character limit in GreyHack. If that's an issue, use import_code instead

You can check out the example code for a better understanding of how to use this feature.

Include

Used to import the content of a file. Features:

• Supports relative includes
• Easy to use
• Pollutes global scope
• Includes the content every time, which may lead to redundant code
• May exceed the character limit of GreyHack, so use import_code instead if this is a concern

You can review the example code for more details.

import_code

Used to import code from a file. Features:

• Keeps files separate in-game, helping to avoid the character limit
• Supports nested import_code
• Supports relative imports

Here’s some example code.

When the installer option is enabled, Greybel will create one or more installer files depending on the size of your project. These installer files will contain all the code files and logic to create the files in the game. Essentially, you just need to copy and paste the installer code into the game, then compile and execute it. Using the --auto-compile flag adds logic to automatically compile the project and remove all source files.

By setting up the in-game directory in the settings, you can define where you want the files to be imported in the game. By default, /root/ is used.

Additionally, nested import_code is supported. This is achieved by moving all imports into the entry file based on their usage throughout the project. It’s recommended to only use import_code at the head of the file, as the import locations of nested files cannot be guaranteed.

Syntax

Any valid MiniScript or GreyScript syntax is supported. Additionally, some minor syntax sugar is added to these languages. If you use these features, keep in mind to transpile your code first. Using these is completely optional.

No trailing comma is required in maps or lists

myList = [
	false,
	null
]

myMap = {
	"test": {
		"level2": {
			"bar": true
		}
	}
}

Math - shorthand

a /= b
a *= b
a -= b
a += b

Bitwise - shorthand

a = b << c
a = b >> c
a = b >>> c
a = b | c
a = b & c

Block comment

/*
	My block comment
*/
print("test")

Filename expression

print(#filename)

The filename expression will be replaced with the string literal containing the name of the file before transpiling. This can be useful for debugging.

Line expression

print(#line)

The line expression will be replaced with the number literal containing the line of the expression before transpiling. This can be useful for debugging.

Envar expression

print(#envar MY_TEST_VAR)

The envar expression will be replaced with the value of the provided environment variable. Make sure you define an environment variable for the provided namespace. If no value is found, it will instead use null.

Inject expression

print(#inject "path/to/file")

The inject expression will be replaced with the content of whatever file exists at the provided path. If the file does not exist, it will be replaced with null. Content injected will automatically be escaped.

Upload

If you're not interested in the build functionality or need to upload many files into the game, you can use the "Import files into game" command. This will behave similarly to the create-in-game build feature, but without the building step.

This feature will also use the transpiler's "Ingame directory" setting as the in-game destination.

IMPORTANT: Please keep in mind that you first need to setup the message-hook agent.

Interpreter

Greybel comes with its own GreyScript interpreter, allowing you to test and debug your code outside of the game. This is partly due to the test environment that gets generated on the fly, attempting to emulate the game's API.

Dependency Management (Interpreter)

Dependencies are dynamically loaded into the execution without any limitations. Cyclic dependencies are also supported.

Environment Variables (Interpreter)

Greybel supports the injection of environment variables into the interpreter. These environment variables can be configured in the extension settings.

Mock Environment

When using this environment, Greybel will automatically generate a local setup, including simulated computers, networks, filesystems and more, on the fly. By default, generation is based on a seed value called test. You can modify this seed using the appropriate option. Using the same seed consistently will ensure that the generated entities remain stable across sessions.

The local computer configuration is hardcoded, with admin credentials set to root:test. Additionally, your local machine will have crypto.so and metaxploit.so available by default.

Note that the mock environment runs locally and is independent from the actual game. As a result, some intrinsic game behaviors may not be fully supported. If you need highly accurate debugging, consider using the In-game Environment instead.

Examples:

metax = include_lib("/lib/metaxploit.so") //returns metaxploit interface
print(metax) //prints metaxploit

myShell = get_shell("root", "test") //get local root shell

Ingame Environment

This environment uses the actual in-game setup. To use it, you must have message-hook installed and the game running in singleplayer mode.

The key advantage of the in-game environment is that it mirrors real gameplay behavior exactly, unlike the mock environment, which is an approximation.

TextMesh Pro Rich Text Support

TextMesh Pro Rich Text is partially supported.

Note: For the pseudo-terminal, Greybel will attempt to transform TextMesh Pro Rich-Text tags into ANSI codes. Due to the nature of TextMesh Pro Rich-Text tags, some formatting may be lost. If you're looking for a proper preview of your output in Grey Hack, please check out the Preview Output feature.

Debugger

The debugger allows you to set breakpoints, run code in a breakpoint context, and jump to the next line of execution. It's helpful for debugging your code.

Note: Make sure to set the breakpoint on a non-empty line, or it will be skipped.

A REPL is also available while executing the script or having an active breakpoint.

Message Hook

The Message Hook enables Greybel to communicate with the game server via the game client, extending its functionality. Features such as in-game auto-create (used for building) and the in-game interpreter environment rely on this capability. Installing it is entirely optional and not required for basic use.

To use the Message Hook, you must first install BepInEx, followed by the appropriate plugin. Instructions are provided below for both BepInEx 5.x.x and 6.x.x versions.

BepInEx 5.x.x

1. Download BepInEx 5.x.x: BepInEx v5.4.23.2
   • Install by extracting BepInEx files into your Grey Hack game folder (location of the game executable). See the Installation Guide if needed.
2. Add the Plugin: Download GreyHackMessageHook5.dll and move it to the plugins folder in BepInEx.
3. Configure Launch Options (macOS/Linux Only):
   • Go to Steam Library > Grey Hack > Properties > Launch Options.
     • macOS: "/path/to/Steam/steamapps/common/Grey Hack/run_bepinex.sh" %command%
     • Linux: "/path/to/.steam/steam/steamapps/common/Grey Hack/run_bepinex.sh" || %command%
4. Launch Grey Hack via Steam to load BepInEx 5 with the plugin.

BepInEx 6.x.x

1. Download BepInEx 6.x.x: BepInEx version 6.0.0-pre.2 Unity.Mono
   • Install by extracting BepInEx files into your Grey Hack game folder (location of the game executable). See the Installation Guide if needed.
2. Add the Plugin: Download GreyHackMessageHook.dll and move it to the plugins folder in BepInEx.
3. Configure Launch Options (macOS/Linux Only):
   • Go to Steam Library > Grey Hack > Properties > Launch Options.
     • macOS: "/path/to/Steam/steamapps/common/Grey Hack/run_bepinex.sh" %command%
     • Linux: "/path/to/.steam/steam/steamapps/common/Grey Hack/run_bepinex.sh" || %command%
4. Launch Grey Hack via Steam to load BepInEx 6 with the plugin.

Note: BepInEx 6.x.x is in a pre-release state and may be less stable than 5.x.x. If you experience frequent crashes, consider switching back to version 5.x.x.

Reminder: Grey Hack must be running for this agent to function properly.

Preview Output

This feature creates a web view that renders actual TextMesh Pro Rich-Text tags within VSCode. Its main purpose is to emulate the actual output of the game, making it useful for drawing images or creating fancy prompts.

API Browser

The API Browser for GreyScript brings the GreyScript API Documentation directly into Visual Studio Code.

Comment Docs

Provide signatures for your functions to show better hover tooltips. Additionally, the provided return value will be recognized by the implemented type system, resulting in context-sensitive auto-complete suggestions.

// Hello world
// I am **bold**
// @description Alternative description
// @example test("title", 123)
// @param {string} title - The title of the book.
// @param {string|number} author - The author of the book.
// @return {crypto} - Some info about return
test = function(test, abc)
  print(test)
end function

There is also the possibility of custom types. Here an example:

// @type Bar
// @property {string} virtualMoo
// @property {string} nested.virtalMoo
Bar = {}
Bar.moo = ""

// Hello world
// I am **bold**
// @description Alternative description
// @example test("title", 123)
// @param {string} title - The title of the book.
// @param {string|number} author - The author of the book.
// @return {Bar} - Some info about return
Bar.test = function(test, abc)
	print("test")
	return self
end function

// @type Foo
Foo = new Bar
// @return {Foo}
Foo.New = function(message)
	result = new Foo
	return result
end function

myVar = Foo.New

myVar.test // shows defined signature of Bar.test on hover
myVar.virtualMoo // shows virtual property of type string on hover
myVar.nested.virtalMoo // shows nested virtual property of type string on hover

Share

Shares your code via editor.greyscript.org. The related link will be copied to your clipboard.

Snippets

Provides a list of available GreyHack snippets, such as ls, mkdir, and more.

Goto Error

Jumps to the next existing syntax error.

Supporting Providers

This extension includes several IntelliSense providers to enhance your coding experience with GreyScript:

• Autocompletion Provider
  Offers context-aware suggestions based on your current position in the code.

• Signature Helper Provider
  Displays function signatures with parameter types and return values as you type, helping you use functions correctly and efficiently without needing to reference documentation.

• Hover Tooltips Provider
  Displays helpful information about functions and types when you hover over them.

• Diagnostics Provider
  Identifies and highlights syntax errors in your code for easier debugging.

• Symbol Provider
  Lists all symbols available in the active file for easy navigation.
  

• Definition Provider
  Locates and displays definitions within the active file and its dependencies.
  

• Color Picker Provider
  Shows a color picker when you use color or mark tags in your code.

Copyright

Sloth icons created by Freepik - Flaticon

Contact

For questions, feature requests, or support, feel free to join the dedicated Greybel Discord.